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:
- Understanding roles
- Granting, changing, and revoking access to resources
- Creating and managing custom roles
Prerequisites
The page assumes that you have:
- Created your portal.
- Installed and initialized the Google Cloud CLI.
- Installed Git.
- Set up your Git email and name.
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
andGetting Started.md
to theGuides
folder. - Adds
Example Page
to thenavigation.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:
Enable the Cloud Source Repositories API:
In APIs & services, go to the API Library page.
From the projects list, select the project that your API is in.
Search for the Cloud Source Repositories API and click its card to display its information page.
Click Enable.
Make sure that the gcloud CLI is authorized to access your data and services:
gcloud auth login
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
Download the sample content, configuration, and scripts:
git clone https://github.com/GoogleCloudPlatform/endpoints-developer-portal-sample-content
Change to the directory that contains the script:
cd endpoints-developer-portal-sample-content/scripts
Display your Endpoints service name:
gcloud endpoints services list
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.
- Linux and Mac users:
Sync the repository to your portal:
- Highlight and copy the first URL, and paste it in your browser's address bar to go to the Settings page.
- 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.
- Highlight and copy the clone URL for your Git repository, and paste it in the Custom Content Settings field.
- Click Sync.
- Click Save.
- 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.
Browse the contents of your newly-created repository. In the Google Cloud console, go to the Source Repositories > Source code page for your project.
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:
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
Go to folder that contains
Getting Started.md
:cd Guides
Open
Getting Started.md
in a text editor.Modify the content as needed to help your users get started using your API.
Save the file.
Commit your changes:
git commit -a -m "updated getting started"
Push your changes to your repository in Cloud Source Repositories:
git push
Sync the updated content to your portal:
- Browse to your portal.
- Click Settings .
- On the Settings page, click the APIs tab and select your API from the list.
- Click Sync.
- 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
:
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
Open the
navigation.yaml
file in a text editor.In the
ordering
section, delete the line withExample Page
.Save the file.
Remove the
Example Page.md
file from Git:git rm ‘Guides/Example Page.md'
Commit your changes:
git commit -a -m "removed example page"
Push your changes to your repository in Cloud Source Repositories:
git push
Sync the updated content to your portal:
- Browse to your portal.
- Click Settings .
- On the Settings page, click the APIs tab and select your API from the list.
- Click Sync.
- Click Save.
Example Page
is no longer in the left navigation bar.
Rename Example Page
To rename Example Page
:
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
Open the
navigation.yaml
file in a text editor.In the
ordering
section, change Example Page to the title of your guide. The name here must match the actual filename in theGuides
directory.Save the file.
Rename the
Example Page.md
file in Git.git mv 'Guides/Example Page.md' 'Guides/NEW FILENAME.md'
Modify the contents of the renamed file as needed.
Commit your changes:
git commit -a -m "removed example page"
Push your changes to your repository in Cloud Source Repositories:
git push
Sync the updated content to your portal:
- Browse to your portal.
- Click Settings .
- On the Settings page, click the APIs tab and select your API from the list.
- Click Sync.
- 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:

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

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.