Adding custom documentation

In addition to the SmartDocs API reference documentation, you can add custom documentation to your portal that users of your API might need. Even if you don't need to provide your users with additional documentation pages, you need to update the example Getting Started guide that is displayed in your portal to explain how to get started using your API.

This page describes how to change the example Getting Started guide, and how to create and display additional documentation pages for your portal. For each task, the minimum required Identity and Access Management role (or roles) required to complete the task is provided. For more information about IAM permissions, see the following:

Prerequisites

The page assumes that you have:

About custom documentation

To display custom documentation in your portal, you must store the files in a Git repository and configure the URL to the Git repository on the Settings page in your portal. You can add the files for your custom documentation to:

  • A private repository in Cloud Source Repositories that is in the same Google Cloud project as your API.
  • A public repository in GitHub or Bitbucket.

For the Cloud Endpoints Portal to find and display your custom documentation, the files and folders in your repository must have a specific structure. At the root of the repository, you need a folder with your Cloud Endpoints service name. You can create additional subfolders as needed. The left navigation bar contains links to your folders and files. For more information, see Required directory structure

You use Markdown to edit the content in the Getting Started guide and to write the content for additional documentation pages. The Endpoints Portal follows the CommonMark spec as well as the table extension from the GitHub Flavored Markdown spec.

You can also add images to your repository and reference them from your Markdown files.

Getting started updating custom documentation

To help you get started, we recommend that you clone the endpoints-developer-portal-sample-content repository on GitHub, which contains the following files:

  • Getting Started.md: The Markdown file that contains the content of the example Getting Started page that is displayed in your portal.
  • Example Page.md: An example file to help you get started using Markdown.
  • navigation.yaml: A file that describes the ordering of pages and folders in the left navigation bar in your portal.

  • add_example_page: A script that does the following:

    • Creates a Git repository in Cloud Source Repositories in your Google Cloud project.
    • Creates a local Git repository in the default-content-repo folder.
    • Creates a folder with the same name as your Endpoints service name, and creates a subfolder called Guides.
    • Adds files called Example Page.md and Getting Started.md to the Guides folder.
    • Adds Example Page to the navigation.yaml file.
    • Commits and pushes these changes to the newly created Git repository in Cloud Source Repositories.

    There are two versions of the script:

    • For Linux and Mac users, there's add_example_page.sh (Bash shell).
    • For Windows users, there's add_example_page.ps1 (PowerShell).

    Running the script is optional. If you prefer, you can manually create a repository in Cloud Source Repositories or in a public GitHub or Bitbucket repository instead. You need to set up the required directory structure for your custom documentation.

    Before running the script, you might want to review the Pricing and quota documentation for the Cloud Source Repositories. If you run the script and then decide you prefer to use a public GitHub or Bitbucket repository instead, you can delete the repository from Cloud Source Repositories.

Get the custom documentation starter files

This section describes how to get set up so that you can run the add_example_page script.

To get the custom documentation starter files:

  1. Enable the Cloud Source Repositories API:

    1. In APIs & services, go to the API Library page.

      Go to the API Library

    2. From the projects list, select the project that your API is in.

    3. Search for the Cloud Source Repositories API and click its card to display its information page.

    4. Click Enable.

  2. Make sure that the gcloud CLI is authorized to access your data and services:

    gcloud auth login

  3. Set the default project. In the following command, replace YOUR_PROJECT_ID with the Google Cloud project ID in which you created your Endpoints API:

    gcloud config set project YOUR_PROJECT_ID

  4. Download the sample content, configuration, and scripts:

    git clone https://github.com/GoogleCloudPlatform/endpoints-developer-portal-sample-content

  5. Change to the directory that contains the script:

    cd endpoints-developer-portal-sample-content/scripts

  6. Display your Endpoints service name:

    gcloud endpoints services list

  7. Run the script with your Endpoints service name:

    • Linux and Mac users: ./add_example_page.sh SERVICE_NAME
    • Windows users: add_example_page.ps1 SERVICE_NAME

    When the script is finished, it prints URLs to the following locations:

    • Your API's portal settings.

    • Your Git URL. This is the same URL that is displayed in the Clone URL field on the Cloud Source Repositories page.

  8. Sync the repository to your portal:

    1. Highlight and copy the first URL, and paste it in your browser's address bar to go to the Settings page.
    2. Follow the login prompts to continue to the Settings page for your API. If you have more than one account, make sure to choose the account that is in the Google Cloud project that owns the API.
    3. Highlight and copy the clone URL for your Git repository, and paste it in the Custom Content Settings field.
    4. Click Sync.
    5. Click Save.
    6. To go back to the API documentation landing page, click the title bar.

    In the left navigation bar, click Example Page to display the content.

  9. Browse the contents of your newly-created repository. In the Google Cloud console, go to the Source Repositories > Source code page for your project.

    Go to the Source Code Browser

    The source code browser shows a directory view of the repository contents at the most recent commit level. See Browsing repositories for more information.

Modifying the custom documentation

Now that you have custom documentation in Cloud Source Repositories, you can modify content and add or delete files and folders as needed. If you are new to using Git, the Git documentation contains reference documentation as well as links to books and videos.

Modify the Getting Started content

To modify the Getting Started content:

  1. Starting at the root of your local Git repository, go to the folder that has the same name as your Endpoints service. For example:

    cd example-api.example.com

  2. Go to folder that contains Getting Started.md:

    cd Guides

  3. Open Getting Started.md in a text editor.

  4. Modify the content as needed to help your users get started using your API.

  5. Save the file.

  6. Commit your changes:

    git commit -a -m "updated getting started"

  7. Push your changes to your repository in Cloud Source Repositories:

    git push

  8. Sync the updated content to your portal:

    1. Browse to your portal.
    2. Click Settings .
    3. On the Settings page, click the APIs tab and select your API from the list.
    4. Click Sync.
    5. Click Save.

    When you click the Getting Started link in the left navigation bar, the Endpoints Portal displays the updated content.

Remove Example Page

To remove Example Page:

  1. Starting at the root of your local Git repository, go to the folder that has the same name as your Endpoints service. For example:

    cd example-api.example.com

  2. Open the navigation.yaml file in a text editor.

  3. In the ordering section, delete the line with Example Page.

  4. Save the file.

  5. Remove the Example Page.md file from Git:

    git rm ‘Guides/Example Page.md'

  6. Commit your changes:

    git commit -a -m "removed example page"

  7. Push your changes to your repository in Cloud Source Repositories:

    git push

  8. Sync the updated content to your portal:

    1. Browse to your portal.
    2. Click Settings .
    3. On the Settings page, click the APIs tab and select your API from the list.
    4. Click Sync.
    5. Click Save.

Example Page is no longer in the left navigation bar.

Rename Example Page

To rename Example Page:

  1. Starting at the root of your local Git repository, go to the folder that has the same name as your Endpoints service. For example:

    cd example-api.example.com

  2. Open the navigation.yaml file in a text editor.

  3. In the ordering section, change Example Page to the title of your guide. The name here must match the actual filename in the Guides directory.

  4. Save the file.

  5. Rename the Example Page.md file in Git.

    git mv 'Guides/Example Page.md' 'Guides/NEW FILENAME.md'

  6. Modify the contents of the renamed file as needed.

  7. Commit your changes:

    git commit -a -m "removed example page"

  8. Push your changes to your repository in Cloud Source Repositories:

    git push

  9. Sync the updated content to your portal:

    1. Browse to your portal.
    2. Click Settings .
    3. On the Settings page, click the APIs tab and select your API from the list.
    4. Click Sync.
    5. Click Save.

The renamed page is displayed in the left navigation bar.

Required directory structure

For the Endpoints Portal to find and display your custom content, the files and folders in your repository must be in a specific structure.

At the root of the repository, there must be a folder with your Endpoints service name. This structure gives you the option of using one repository for multiple APIs by having separate root-level folders for each API.

Subfolders within your service folder let you group related pages under a section, and may contain further subfolders. The title of the folders and filenames are used in navigation. For example, a file named Getting Started.md appears in the left navigation bar as Getting Started. Within the folder named after your Endpoints service name, you must have a file called navigation.yaml. This file indicates how you want your content to appear in the left navigation bar in your portal. The default one looks like this:

ordering:
- Introduction
- Guides
- API Reference
- Resources

folders:
  Guides:
    ordering:
    - Getting Started
    - Example Page

The first ordering list specifies the order in which you want the entries to appear at that level. For example, the default navigation.yaml file specifies that the Introduction page appears first, followed by the Guides section, and so on.

Introduction, API Reference, and Resources are special sections, and you mustn't remove them from navigation.yaml, but you can change their order.

Each folder and page should have a corresponding configuration within its parent's folders configuration in navigation.yaml. If omitted, the page or folder doesn't appear in your portal. For example, in the default navigation.yaml file, the folders key contains a subkey named Guides because there is a folder with the same name.

Add images

You can add images to the custom content Git repository and reference them in your Markdown files. If you put the images and any Markdown file that references them under the same directory as your Endpoints service name, you can reference the images with a relative URL (starting with a /).

For example, suppose you have the following directory structure:

~/example-api.example.com/
    get-started.md
    images/
        example.jpg

You can add the images/example.jpg image to get-started.md with the following markup:

    ![alt-text](/images/example.jpg "Optional title")

You can add images hosted elsewhere using the standard Markdown syntax and the full URL to the image:

    ![alt-text](https://example.com/image.png "Optional title")

The portal supports the following image types:

  • BMP
  • GIF
  • JPEG
  • PNG
  • TIFF
  • WEBP

Custom content limits

The portal has the following limitations on custom content:

  • Maximum of 200 Markdown pages per API.
  • Maximum of 200 images per API.
  • Maximum size of 4 MiB per image.

What's next