Add and edit content

Use the Drupal Book module to add documentation about your API, such as how-to guides and API reference documents, to your developer portal. The Book module allows you to create the kind of structured, hierarchical content that typically appears in a book. However, you can also use the Drupal Book module to create less formal documents, such as a brief set of instructions or a list of links to additional content such as videos, screencasts, or code downloads. 

Note: Developers will use apps to access resources in your API products. In general, developers will use your developer portal to add those apps. Ensure that your documentation includes instructions for adding apps though your developer portal. You can use Instructions for adding apps as a starting point. Those instructions cover how to add apps through the default developer portal.

The Documentation page is set up with some initial entries organized in various categories such as "Getting Started" and "Tutorials". The page is a starting point for you to edit. In this way you can add you own content entries and organize those entries in the way you want.

Adding documentation

To add content to your developer portal

1. Log in to your portal as a user with admin or content creation privileges.
2. Select Content > Add content > Book page in the Drupal administration menu.
3. Enter the title of the document and the content of the first page. Click Edit summary to add a Summary.

   

4. Click the Book outline item below the Body section to open the Book drop-down menu. Select <create a new book> in the menu, and click Save.
5. To add a page to the newly-created book, repeat steps 5 and 6. However, when you open the Book drop-down menu, select the name of the document in which you want to add the new page. Repeat this step for each new page you want to add to the document.

Displaying documentation

To display the content of a document

1. Log in to your portal as a user with admin or content creation privileges.
2. Select Content > Books in the Drupal administration menu.
3. Select the document you want to view from the Book list.
   The first page of the document opens. Pages that follow the first page are displayed as topics in the topics list.

Rearranging the order of pages

You can change the sequence of pages in a document . You can also make a page subordinate in level to another page.

To rearrange pages in a document

1. Log in to your portal as a user with admin or content creation privileges.
2. Select Content > Books in the Drupal administration menu.
3. Click "edit order and titles" in the row for the pertinent book.
   A list of titles opens, showing the pages in the book.
4. Click the Title (+) icon that corresponds to the page that you want to move. Drag the icon up or down in the title list. You'll see the sequence of pages change. Drop the icon at the appropriate point in the title list.
5. Move the icon to the right, to make the page a subtopic of the topic above it.
6. Click Save book pages.

Editing the Documentation page

After you add documentation to your developer portal, you can edit the Documentation page that is displayed to developers. This page links to the available documentation about your API. Developers will be able to access the Documentation page by selecting the Documentation menu in the developer portal menu.

To edit the Documentation page

1. Select Documentation in the developer portal navigation menu.
   The Documentation page opens.
2. Select the Edit tab.
3. Open a visual editor by selecting Filtered HTML in the Text Format drop-down menu below the Body section.
   You should see the content of the Documentation page displayed in the editor.

   

4. Change the entries in the editor, as appropriate. Use the link button in the editor to link the entries to the pertinent documentation.
5. Click Save.

Editing the content of footer pages

To edit the content of a footer page, such as the Privacy Policy, Terms of Use, or Contact Us page, in your developer portal

1. Log in to your portal as a user with admin or content creation privileges.
2. Navigate to the page by clicking its link in the footer. For example, click the Privacy Policy link.
3. Click the Edit tab in the page to open the editor.

   

4. Change the contents of the Privacy Policy page as appropriate.
5. Click Save.

Checking for broken links

It's good practice to check your content for broken links. By default, the developer portal is set up to check various types of pages for broken links. For example, links are checked in book pages, articles, blog entries, and forum topics.

To add to or remove page types from the link check

1. In the Drupal administration menu select Configuration > Github Importer > Link checker.
   The Link checker page opens.

   

2. Check the checkboxes for the page types in which you want links checked. Uncheck the checkboxes for the page types in which you don't want links checked.

Disabling Google indexing

It's also good practice to index your content, and make it available to search engines. By default, your content is indexed by the Google indexer. However, you have the option of disabling Google indexing. You might want to do this if your developer portal is not ready for public use and so you don't want your content to be publicly searchable.

To disable Google indexing

1. Log in to your portal as a user with admin or content creation privileges.
2. Select Modules in the Drupal administration menu.
   The Modules page opens.
3. Select the Meta tags section to expand the section.
4. Uncheck the Meta tags checkbox.
5. Click Save configuration.
6. In the Drupal administration menu select Configuration > Search and metadata > Meta tags.
   The Meta tags page opens.
7. Select the Override operation for the Global type.
   The Global page opens.
8. Click the Advanced section to open it.

   

9. Check the checkbox for Prevent search engines from indexing this page.
10. Click Save.

Notice that there are other search-engine related options in the Advanced section of the Global page. For example, you can check a checkbox to prevent search engines from following links on a page. Check one or more of these checkboxes as appropriate.

Instructions for adding apps

As mentioned earlier, it's important that your documentation include instructions on how developers can add their apps though your developer portal. You can use the following instructions as a starting point — these instructions cover how to add apps through the default developer portal.

To add an app through the default developer portal

1. Select  My apps below your username in the login menu. This displays the My apps page.
2. Click the Add  (+)  new app  icon. This displays the Add app page.

   

3. Enter appriopriate values in the Add app page:

   App name	Provide a unique App Name for your app.
   Callback URL	Provide the callback URLto which the OAuth call should return.
   Product	Select the pertinent API product from the drop-down list to gain access to that product.

4. Click Create App. This will create the app and generate keys for the app.

Learning more about the Drupal Book module

The Drupal Book module has more functionality than described here. The Drupal community maintains a Community Documentation page that includes more complete information about using the Book module. There are also some good videos that demonstrate the use of the Book module. One of them is Book Module Demo for Drupal & Drupal Gardens.