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 will need to update the example Getting Started guide that is displayed in your portal.

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 Cloud Identity and Access Management permission or role required to complete the task is provided. For more information about Cloud IAM permissions, see the following:

Prerequisites

The page assumes that you have:

About custom documentation

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

  • A private repository in Cloud Source Repositories that is in the same GCP 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 be in a specific structure. At the root of the repository, there must be a folder with your Cloud Endpoints service name (for example, echo-api.endpoints.example- project-12345.cloud.goog). You can create additional subfolders as needed. The left navigation bar contains links to the folders and files that you have created. 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 Cloud 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 GCP project.
    • Creates a local Git repository in the default-content-repo folder.
    • Creates a folder with the same name as your Cloud 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 navigation.yaml.
    • 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 just need to setup the required directory structure for your custom documentation.

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

Getting the custom documentation starter files

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

Minimum required permissions:

  • Project members with the Project Viewer and the Source > Source Repository Administrator roles can create the repository in Cloud Source Repositories.
  • Project members with the Project Editor role can sync the repository to the portal for your API. See Control Access to the API for information on how to assign these roles.

To get the custom documentation starter files:

  1. Enable the Cloud Source Repositories API:

    1. In the Developers Console, 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 GCP SDK is authorized to access your data and services:

    gcloud auth login
    
  3. Make sure the gcloud command line tool is configured to use the same project that owns 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 Cloud Endpoints service name:

    gcloud endpoints services list
    
  7. Run the script with your Cloud 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 GCP 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. Click the title bar to go back to the API documentation landing page.

    In the left navigation bar, you will see Example Page. Click on it to display the content.

  9. Browse the contents of your newly-created repository. In the GCP Console, go to the Cloud 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 Using the Source Browser for more information.

Modifying the custom documentation

Now that you have custom documentation in Cloud Source Repository, 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.

This section covers some basic modifications to help you get started.

Minimum required permissions:

  • Project members with the Project Viewer and the Source > Source Repository Writer roles can modify the repository in Cloud Source Repositories.
  • Project members with the Project Editor role can sync the repository to the portal for your API. See Granting Access to the API for information on how to assign these roles.

Modifying 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 Cloud Endpoints service. For example:

    cd echo-api.endpoints.example-project-12345.cloud.goog
    
  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 settings.
    3. On the Settings page, click the APIs tab and select your API from the drop-down list.
    4. Click Sync.
    5. Click Save.

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

Removing the Example Page

To remove the Example Page:

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

    cd echo-api.endpoints.example-project-12345.cloud.goog
    
  2. Open navigation.yaml 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 settings.
    3. On the Settings page, click the APIs tab and select your API from the drop-down list.
    4. Click Sync.
    5. Click Save.

The Example Page has been removed from the left navigation bar.

Renaming the Example Page

To rename the Example Page:

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

    cd echo-api.endpoints.example-project-12345.cloud.goog
    
  2. Open navigation.yaml 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 from 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 settings.
    3. On the Settings page, click the APIs tab and select your API from the drop-down list.
    4. Click Sync.
    5. Click Save.

The renamed page is displayed in the left navigation bar.

Required directory structure

For the Cloud 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 Cloud Endpoints service name (for example, echo-api.endpoints.example-project-12345.cloud.goog). 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 Cloud 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.yamlspecifies that the Introduction page should appear first, followed by the Guides section, and so on.

Introduction, API Reference, and Resources are special sections, and you must not 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 will not appear in your portal. For example, in the default navigation.yaml, the folders key contains a subkey named Guides since there is a folder with the same name.

Adding 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 Cloud Endpoints service name, you can reference the images with a relative URL (starting with a "/").

For example, suppose you have the following directory structure:

~/echo-api.endpoints.example-project-12345.cloud.goog/
    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.
Was this page helpful? Let us know how we did:

Send feedback about...

Cloud Endpoints Frameworks for App Engine
Need help? Visit our support page.