Each topic page is built using at least one Discourse topic, under the category topic-pages. A topic page on Charmhub can be a single page. Optionally, it can include side navigation linking to different content pages you’d like to include in the topic. For each content page in the navigation, a new Discourse page will be needed.
Creating the navigation and cover page
- Add a title for your topic page.
- The body of this topic contains the cover page and if you want your navigation with a full list of all the pages for your topic page. Each page has to be a topic in Discourse. Here is an example snippet you can start with as an outline. Cut it from here and paste it into your Discourse topic:
The cover page of your docs. This should be some introductory text
which will be displayed on the front page of the Charmhub topic. All the content above the 'Navigation' heading below is part of the cover page.
Optionally, you can include a navigation table with other pages:
# 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>) |
If you want to see a big example, this same system is used to make the Juju.is documentation. 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/topic/<Your topic>/
.
You can use formatting here to create your page, including headings, images, and lists. It is common to have an outline of the topic created, or any limitations such as requiring a particular cloud or hardware.
If you want to keep it simple, this front page can become the entire topic page, without navigation. Do not use # Navigation
as a heading if you do not want to add navigation.
Using # Navigation
as a heading to include navigation in your topic page is covered in 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. Level 1 means a top-level item in the navigation.
Path
This value will be used to transform any discourse URL to a path in your Charmhub topic, as an example:
# Navigation
| Level | Path | Navlink |
| -- | -- | -- |
| 1 | about-kubeflow | [Kubeflow](/t/topic-title/123) |
Will create a path like charmhub.io/topics/about-kubeflow
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 a link to the Discourse 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. To give an example, 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 link 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.