Organizing and adding content

Configure your landing page to display custom content.

1. In your API Portal repository, open the landing page file: /content/_index.md.
2. Change the value of the api-list parameter to false.

   

3. Under the closing ---, enter the content that you want to display on the landing page.
   You can also edit the title if needed.
4. Commit your changes.

Configure your portal to define how to display your list of APIs.

1. In your API Portal repository, open the config.toml file.
2. Enter your configuration at the end of the file, under [params].
   The file contains comments with an example of the structure. The list should be structured as follows:

   [params]
     [[params.api-list]]
       "<group_1>" = [ "<api_1>", "<api_2>" ]
     [[params.api-list]]
       "<group_2>" = [ "<api_3>", "<api_4>" ]
     [[params.api-list]]
       "default" = [ "<api_5>", "<api_6>" ]

   You can add as many groups as needed. You can also sort APIs in "default" if they should appear at the beginning of the list, without a specific group.

   The APIs should be referenced using the name of their folder in apis. Group names can contain UTF-8 and Unicode characters.

   Information noteNote: Once the list is created in config.toml, new APIs need to be added to it in order to appear in the portal.
3. Commit your changes.

Results

Once your portal is deployed with this new configuration, your APIs appear in the specified groups.

With the following configuration, the list would be displayed as in the image below:

[params]
  [[params.api-list]]
    "Inventory" = [ "books", "dvds" ]
  [[params.api-list]]
    "Sales" = [ "customers", "orders" ]
  [[params.api-list]]
    "default" = [ "employees"]

Add a Markdown file as a new page in your portal.

1. In your API Portal repository, go to the content folder.
2. Create a new Markdown file.
   The name of the file is used to create the URL of the page. If you create a file named examples.md, the page will be available at <portal-url>/examples.
3. Add metadata for your page
   The metadata is surrounded with --- and defines the title of the page and its position on the header. The header displays pages from lowest to highest weight. If two pages have the same weight, they are sorted alphabetically. By default, the weight of the "Getting started" page is set to 10, and the "APIs" page is set to 20. If you add a new page named "Examples" with weight: 20, it will appear after "APIs" in the header.

   Example

   ---
   title: Examples
   menu:
     main:
       weight: 20
   ---

4. Add your content under the metadata.
   For more information about writing in Markdown, see Markdown Guide.

   Example

   ---
   title: Examples
   menu:
     main:
       weight: 20
   ---
   
   # Examples
   
   ## Fetching a book by title
   
   1. Generate an access token.
   2. Run the following command with the relevant query parameters:
     `curl -X GET -H "Authorization:Basic {userToken}" https://company.com/api/books?title={bookTitle}`
   
   ### Result
   A response containing information about the book is returned. For example, the request `https://company.com/api/books?title=Jane+Eyre` returns the following information:
   ``` json
   [
     {
       "id": "hfp1651869",
       "title": "Jane Eyre",
       "author": "Charlotte Brontë",
       "publisher": "Penguin",
       "isbn": "978-0141441146"
     }
   ]
   ```

   Information noteTip: If your want to add code samples in your content, you can specify the language after the opening ``` to enable syntax highlighting.
5. Commit your changes.

Results

Once your portal is deployed, the new page appears. In this example, it looks like this: