--- title: How-to maintain documentation on Discourse description: Canonical makes open source secure, reliable and easy to use, providing support for Ubuntu and a portfolio of enterprise-grade technologies. Founded in 2004, Canonical operates globally with team members in over 80 countries. url: https://canonical-com-2950.demos.haus/mir/docs/how-to-maintain-mir-documentation?format=md --- *Submit* # How-to maintain documentation on Discourse This document describes how documentation is maintained on Discourse. **Contents:** * [Introduction](https://canonical-com-2950.demos.haus/mir/docs/how-to-maintain-mir-documentation?format=md#heading--introduction) * [Navigation pane](https://canonical-com-2950.demos.haus/mir/docs/how-to-maintain-mir-documentation?format=md#heading--navigation-pane) * [Redirects](https://canonical-com-2950.demos.haus/mir/docs/how-to-maintain-mir-documentation?format=md#heading--redirects) * [Formatting](https://canonical-com-2950.demos.haus/mir/docs/how-to-maintain-mir-documentation?format=md#heading--formatting) + [Headings](https://canonical-com-2950.demos.haus/mir/docs/how-to-maintain-mir-documentation?format=md#heading--formatting-headings) + [Commenting](https://canonical-com-2950.demos.haus/mir/docs/how-to-maintain-mir-documentation?format=md#heading--formatting-commenting) + [Versioning](https://canonical-com-2950.demos.haus/mir/docs/how-to-maintain-mir-documentation?format=md#heading--formatting-versioning) + [Table of Contents](https://canonical-com-2950.demos.haus/mir/docs/how-to-maintain-mir-documentation?format=md#heading--formatting-table-of-contents) * [Converting content](https://canonical-com-2950.demos.haus/mir/docs/how-to-maintain-mir-documentation?format=md#heading--converting-content) + [From Google](https://canonical-com-2950.demos.haus/mir/docs/how-to-maintain-mir-documentation?format=md#heading--converting-content-from-google-docs) + [From Ubuntu Tutorials](https://canonical-com-2950.demos.haus/mir/docs/how-to-maintain-mir-documentation?format=md#heading--converting-content-from-ubuntu-tutorials) * [Resources](https://canonical-com-2950.demos.haus/mir/docs/how-to-maintain-mir-documentation?format=md#heading--resources) --- ## [Introduction](https://canonical-com-2950.demos.haus/mir/docs/how-to-maintain-mir-documentation?format=md#heading--introduction) The [Mir and Ubuntu Frame documentation pages](https://mir-server.io/docs) are maintained on this Ubuntu Discourse. Each page’s content lives in the first post in a separate discussion thread, with subsequent posts serving as space for discussion about the content. The entry point is a thread whose content is used as the home page, but includes extra metadata for navigation and redirects (explained below). You can reach this thread by following the “Help improve this document in the forum” at the bottom of [the rendered version](https://mir-server.io/docs). The “Help improve …” link at the bottom of each page will take you to the thread from which the content is sourced. We maintain a list of tasks to complete in [this GitHub Project](https://github.com/orgs/MirServer/projects/9). ## [Navigation pane](https://canonical-com-2950.demos.haus/mir/docs/how-to-maintain-mir-documentation?format=md#heading--navigation-pane) The *Navigation* table present at the bottom of the home page post describes the navigation structure of the documentation tree. It is rendered as the navigation pane on the documentation site. Its format is a Markdown table: ``` ## Navigation [details=Navigation] |Level|Path|Navlink| |--|--|--| |||[]()| ``` Where: * `` is the indentation level for display; * `` is the path component in `https://mir-server.io/docs/` URLs; * `[]()` is the Markdown-formatted item to be rendered in the navigation pane. It is recommended to use relative, short `/t/` URLs. If an item is not meant to be a link, but rather an organizational heading, omit `` and just use plain text in the *Navlink* column. ## [Redirects](https://canonical-com-2950.demos.haus/mir/docs/how-to-maintain-mir-documentation?format=md#heading--redirects) Similar to Navigation, there is a *Redirects* table, whose purpose is ensuring that once a page is published, its URL will remain valid, even if the content is moved or removed. The format is a simple table: ``` ## Redirects [details=Mapping table] | Location | Path | |--|--| |/docs/|| ``` Whenever you move the content or remove a page from the documentation site, consider whether it could be bookmarked or indexed in search engines, and if so, add an entry to the Redirects table so that users arriving there are not greeted with a `404 Not Found` error. ## [Formatting](https://canonical-com-2950.demos.haus/mir/docs/how-to-maintain-mir-documentation?format=md#heading--formatting) Content is rendered from Markdown just as it is on Discourse [1](https://canonical-com-2950.demos.haus/mir/docs/how-to-maintain-mir-documentation?format=md#footnote-1). There are a few additional notes that help rendering useful documentation from the content here. ### [Headings](https://canonical-com-2950.demos.haus/mir/docs/how-to-maintain-mir-documentation?format=md#heading--formatting-headings) To be able to refer directly to a particular section in documentation, it’s recommended to use HTML headings with an anchor around them, like this: ```

Name

 Content

Subheading

 ``` When using subheadings, make sure the anchor has the full context, including the parent heading title. You can then link to them using the `#heading--name` anchor. ### [Commenting](https://canonical-com-2950.demos.haus/mir/docs/how-to-maintain-mir-documentation?format=md#heading--formatting-commenting) To hide some content that you don’t want rendered, but don’t want to remove (e.g. when refactoring it), just use HTML comments: ``` ``` ### [Versioning](https://canonical-com-2950.demos.haus/mir/docs/how-to-maintain-mir-documentation?format=md#heading--formatting-versioning) To denote a section of documentation that only applies to a certain version of the software, use a note: ``` [note status="Version 2.7"] This feature is only available from Mir 2.7 onward [/note] ``` Version: This feature is only available from Mir version 2.7 onward ### [Table of Contents](https://canonical-com-2950.demos.haus/mir/docs/how-to-maintain-mir-documentation?format=md#heading--formatting-table-of-contents) At the top of each document, build a Table of Contents. Unfortunately still manual, but is a pretty simple: ``` **Contents:** - [Heading title](#heading--title) - [Subheading title](#heading--title-subheading-title) --- ``` ## [Converting content](https://canonical-com-2950.demos.haus/mir/docs/how-to-maintain-mir-documentation?format=md#heading--converting-content) ### [From Google Docs](https://canonical-com-2950.demos.haus/mir/docs/how-to-maintain-mir-documentation?format=md#heading--converting-content-from-google-docs) The Docs to Markdown extension is a good starting point for content that exists in Google Docs: Since the document may be linked elsewhere, leave the document be and add a link to the new location rather than trashing it. ### [From Ubuntu Tutorials](https://canonical-com-2950.demos.haus/mir/docs/how-to-maintain-mir-documentation?format=md#heading--converting-content-from-ubuntu-tutorials) To convert from content on [tutorials.ubuntu.com](http://tutorials.ubuntu.com): 1. Head on to the tutorial in question, 2. At the bottom there’s a “Suggest changes” link, follow it to a Discourse post, 3. Edit the post and take the contents out, 4. Remove the table at the top and the “Duration:” hints, 5. Place the content in a new topic [under Mir / documentation](https://discourse.ubuntu.com/c/mir/docs/28), 6. Link the new topic to the “How-to guides” section of the navigation. 7. Replace the content of the tutorial with a link to the new location, including a “This content was moved…” comment. **NB**: Most content on there are actually How-to guides in accordance with the Diátaxis Framework[3](https://canonical-com-2950.demos.haus/mir/docs/how-to-maintain-mir-documentation?format=md#footnote-3), so place it there rather than under “Tutorials”. ## [Resources](https://canonical-com-2950.demos.haus/mir/docs/how-to-maintain-mir-documentation?format=md#heading--resources) There’s more content around this topic available, e.g.: * [Creating Discourse-based documentation pages](https://discourse.canonical.com/t/creating-discourse-based-documentation-pages/159) * [Editing MAAS documentation](https://discourse.maas.io/t/editing-maas-documentation-wip/3769) * [Docs moving to maas.io/docs, content to Discourse](https://discourse.maas.io/t/docs-moving-to-maas-io-docs-content-to-discourse/890) If you find problems with how the documentation pages are rendered, report a bug on [the project’s GitHub page](https://github.com/canonical-web-and-design/canonicalwebteam.discourse). --- 1 [Discourse markdown reference](https://meta.discourse.org/t/post-format-reference-documentation/19197#markdown-1) 2 [Vanilla syntax highlighting](https://vanillaframework.io/docs/base/code#syntax-highlighting) 3 [Diátaxis framework](https://diataxis.fr) --- [Previous Migrating from mir-kiosk to Ubuntu Frame](https://canonical-com-2950.demos.haus/mir/docs/how-to-migrate-from-mir-kiosk-to-ubuntu-frame) [Next Running Ubuntu Frame: Run Ubuntu Frame in your Desktop Environment](https://canonical-com-2950.demos.haus/mir/docs/run-ubuntu-frame-on-your-desktop) Last updated 1 year, 11 months ago. [Help improve this document in the forum](https://discourse.ubuntu.com/t/how-to-maintain-documentation-on-discourse/28916).