How to write documentation for the TMF Docusaurus

Intro and setup

Repository

All files that together create this docusaurus are being saved in a git repository. This is done for tracking changes. If you are not familiar with git repositories, don't worry, you don't need to know the ins and outs of a git repository to be able to save your changes.

Committing changes

Everytime you save something into the repository you commit the changes you made. You give the committed changes a name describing the changes you made. For example "added documentation about TMF interal rules". Whenever a commit is added to the repository the docusaurus website is automatically rebuild by a continious integration pipeline so your changes are visible. This rebuilding of the website takes a few minutes. If you are making changes via a text editor on your desktop and not in gitlab don't forget to push the committed changes to the remote.

Gitlab project

The git repository is a project on the TMF Gitlab. In order to make changes you need access to the tmf-docs gitlab project.

Writing documentation

Markdown

Documentation and pages on docusaurus are written in markdown. Markdown is a lightweight markup language for creating formatted text using a plain-text editor. You can find a markdown cheat sheet here. This cheat sheet will help you with how to put text in bold, create headings and insert links and images.

Via Gitlab

You can create and edit documentation on docusaurus without the need of installing any software.

  1. To start go to the tmf-docs gitlab project.
  2. Click the button on the right, Web IDE, IDE stands for integrated development environment. An online editor opens.
  3. On the left you will see all the files that together create the docusaurus. The markdown files that create the documentation are in the docs folder. The subfolders in this folder are the categories in the top navigation bar on the docusaurus.
  4. You can create new files or edit existing ones. You can switch from edit mode to Preview Markdown to verify your markup.
  5. To the left of the folder structure there are 3 buttons. After you are done making your changes you can review your changes and if all is good you can commit your changes to the repository.
  6. Type in a commit message, describing the changes you made, and make sure you have selected commit to master branch
  7. Click the green commit button.

Via text editor on desktop

How to create documentation from your computer goes here.

Common practices and guidelines

Which terms do we often use? What to avoid.

Get started with Docusaurus

Editing an existing docs page

Edit docs by navigating to docs/ and editing the corresponding document:

docs/doc-to-be-edited.md

---
id: page-needs-edit
title: This Doc Needs To Be Edited
---

Edit me...

For more information about docs, click here

Editing an existing blog post

Edit blog posts by navigating to website/blog and editing the corresponding post:

website/blog/post-to-be-edited.md

---
id: post-needs-edit
title: This Blog Post Needs To Be Edited
---

Edit me...

For more information about blog posts, click here

Adding Content

Adding a new docs page to an existing sidebar

  1. Create the doc as a new markdown file in /docs, example docs/newly-created-doc.md:
---
id: newly-created-doc
title: This Doc Needs To Be Edited
---

My new content here..
  1. Refer to that doc's ID in an existing sidebar in website/sidebars.json:
// Add newly-created-doc to the Getting Started category of docs
{
  "docs": {
    "Getting Started": [
      "quick-start",
      "newly-created-doc" // new doc here
    ],
    ...
  },
  ...
}

For more information about adding new docs, click here

Adding a new blog post

  1. Make sure there is a header link to your blog in website/siteConfig.js:

website/siteConfig.js

headerLinks: [
    ...
    { blog: true, label: 'Blog' },
    ...
]
  1. Create the blog post with the format YYYY-MM-DD-My-Blog-Post-Title.md in website/blog:

website/blog/2018-05-21-New-Blog-Post.md

---
author: Frank Li
authorURL: https://twitter.com/foobarbaz
authorFBID: 503283835
title: New Blog Post
---

Lorem Ipsum...

For more information about blog posts, click here

Adding items to your site's top navigation bar

  1. Add links to docs, custom pages or external links by editing the headerLinks field of website/siteConfig.js:

website/siteConfig.js

{
  headerLinks: [
    ...
    /* you can add docs */
    { doc: 'my-examples', label: 'Examples' },
    /* you can add custom pages */
    { page: 'help', label: 'Help' },
    /* you can add external links */
    { href: 'https://github.com/facebook/docusaurus', label: 'GitHub' },
    ...
  ],
  ...
}

For more information about the navigation bar, click here

Adding custom pages

  1. Docusaurus uses React components to build pages. The components are saved as .js files in website/pages/en:
  2. If you want your page to show up in your navigation header, you will need to update website/siteConfig.js to add to the headerLinks element:

website/siteConfig.js

{
  headerLinks: [
    ...
    { page: 'my-new-custom-page', label: 'My New Custom Page' },
    ...
  ],
  ...
}

For more information about custom pages, click here.

Full Docusaurus Documentation

Full documentation can be found on the website.

Next →