Add docs to your charm page

1. Overview

The most-used charms are those with the best documentation! A few great pages help people understand what your charm is capable of and how to use it best.

Charmhub makes it easy to publish and collaborate on documentation for your charm. Your doc pages are managed in the Charmhub Discourse, which means community members can comment on them and help improve them directly.

This tutorial will explain how to publish documentation for your charm.

Prerequisites

  • You must have a charm in Charmhub which we will call <charm>, so that there is a page at https://charmhub.io/<charm>/ for which we will create the docs tab content
  • You should have a basic knowledge of Markdown text structuring

2. Your documentation

Each charm has a Docs tab in Charmhub, with navigation on the left and content pages on the right.

image

Your navigation, and each page of your docs, are separate ‘topics’ in Discourse.

Creating the navigation and cover page

image

  • Call your topic <charm> docs - index. Use your own charm name, not <charm> of course!
  • We recommend you tag it with your charm name, <charm>, and also the docs tag. You may need to make a new tag for your charm name.
  • The body of this topic contains the cover page and your navigation, as well as a full list of all the pages in the docs. Each page is a topic in the Discourse. Here is an example snippet you can start with as an outline. Cut it from here and paste it into your DIscourse docs index topic:
The cover page of your docs. This should be some introductory text
which will be displayed on the front page  of the Docs tab for your
charm. All the content above the 'Navigation' heading below is part
of the cover page.

# Navigation

| Level | Path | Navlink |
| -- | -- | -- |
| 1 |  | [Overview](/t/topic-title/<ID>) |
| 1 | install | [install](/t/topic-title/<ID>) |
| 2 | Subtopic | [Subtopic](/t/topic-title/<ID>) |
| 2 | Subtopic | [Subtopic](/t/topic-title/<ID>) |
| 1 | topic | [install](/t/topic-title/<ID>) |
| 2 | Subtopic | [Subtopic](/t/topic-title/<ID>) |

# Redirects

[details=Mapping table]
| Path | Location |
| -- | -- |
[/details]

If you want to see a big example, this same system is used to make the Snapcraft documentation and the corresponding Discourse topic (which defines that cover page) is linked from the bottom of that page, or you can go straight there.

Let’s go through each section in detail.

Front page content

The text that is above the # Navigation section will appear on the cover page of your docs at charmhub.io/<charm>/docs/.

You can use formatting here, including headings, images, and lists. It is common to have an outline of the main ways to use your charm, or any limitations such as requiring a particular cloud or hardware.

Essentially you can make a whole page. Just don’t use # Navigation as a heading until you want to make your navigation, which is the next section.

Defining the left-hand navigation structure

# Navigation

| Level | Path | Navlink |
| -- | -- | -- |
| 1 | / | [Overview](/t/topic-title/<ID>) |

This is the navigation on the left side of the docs tab.

image

To add a new navigation item:

  • Create a Markdown table and add a row per item
  • Set a level value, you can start with 1
  • Set the path for this topic
  • Add a markdown link: [Title displayed on the navigation](link to any other discourse topic)

Here is an explanation of the different columns:

Level

We use this value to generate a tree structure in the navigation, a level 1 means a top-level item in the navigation.

Path

The value will be used to transform any discourse URL to a path in your charm docs, as an example:

# Navigation

| Level | Path | Navlink |
| -- | -- | -- |
| 1 | install | [Install](/t/topic-title/123) |

Will create a path like charmhub.io/mycharm/docs/install

Navlink

In this column, you need to specify the link to the discourse topic.

For example:

# Navigation

| Level | Path | Navlink |
| -- | -- | -- |
| 1 | install | [Install](/t/example-docs-install/9999) |
| 1 | configure | [Configure](/t/example-docs-configure/9998) |

Note that in Markdown a link is [text](url) so each of those is actually a link straight to the Discourse topic page. If you get this right, you can click the navigation links in your cover page # Navigation section and jump straight to the relevant Discourse topics which define those pages.

The important thing in a DIscourse topic path is the number at the end, which uniquely identifies a topic, even if the title is edited later. So if the topic link is /t/foo-bar-docs/1234 and later you rename the topic to /t/fixed-up-docs/1234 then the old links to /t/foo-bar-docs/1234 will still work because 1234 never changes.

Of course, in order to have topics to link to, you need to create those topics! And we are now just creating the placeholder navigation, so leave it empty. Later you can fill it in with all the actual pages you want.

The navigation items are normally just the high-level pages. Your docs tree can have many pages, not just the pages linked from your navigation.

Redirect

# Redirects

[details=Mapping table]
| Path | Location |
| -- | -- |
| old/path/to/page | new/path/to/page |
[/details]

If you decide to update the URL of a page you can add it directly to this table. The format is:

| previous URL | new URL |

From now on the pages will redirect to the new pages. For example:

# URLs

[details=Mapping table]
| Topic | Path |
| -- | -- |
| /<CHARM NAME>/docs/old-url | /<CHARM NAME>/docs/new-url |
| /<CHARM NAME>/docs/very-old-url | /<CHARM NAME>/docs/very-new-url |
[/details]

3. Add a new page

Feel free to create topics in discourse for your documentation. Don’t forget to jump back into your index topic to add the correct URLs. You might also want to add the new page to the navigation.

Each new topic added should have the tags <charm> and docs.

In these topics, you don’t need to add the navigation, URLs or redirect section since they are already handled by your documentation index topic.

4. Publish

To tell Charmhub which index page to use for your charm docs, you update the metadata of the charm itself to point to the Discourse topic of the index, and release the charm.

  • In your favourite editor open the metadata.yaml of your charm
  • Add the URL to the index topic in Discourse:
docs: https//discourse.charmhub.io/t/charm-docs-index/9999
  • Now build, push and release your updated charm with charmcraft
  • Et voilà, go to your charm page on Charmhub and check the docs tab
  • Don’t forget to celebrate your work on the internets!