Each charm has a Docs tab in Charmhub, with navigation on the left and content pages on the right.
Your navigation, and each page of your docs, are separate ‘topics’ in Discourse.
Creating the navigation and cover page
- 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.
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]