Table of Contents

Loading ...

Contributing to the Documentation

Documentation guideline

Here's the guideline/conventions to follow for the Wazo documentation. Wazo documentation is generated with GatbsyJS. The source code is available on GitHub at https://github.com/wazo-platform/wazo-platform.org

Language

The documentation must be written in english, and only in english.

File structure

File and Folders

  • Word should be separate by dashes (ex: /my-folder/my-file.md)
  • Don't use dot (.)

Images

  • Should be stored in /static/images/uc-doc/
  • Should reproduce page path /static/images/uc-doc/page1/subpage2/myimage.jpg

Content

Documentation content should be stored in /content/uc-doc/.

Table of Contents

The table of contents is based on files and folders structure on /content/uc-doc. If you want to create a new level you must :

  • Create a new folder
  • Add an index.md with a list of subpages (Required to generate a clean navigation)
  • Create a new file mypage.md
  • Write your content inside the new file

Headings

  • The top section of each file must be capitalized using the following rule: capitalization of all words, except for articles, prepositions, conjunctions, and forms of to be.

    <!-- Correct -->
    The Vitamins are in My Fresh California Raisins
    
    <!-- Incorrect -->
    The Vitamins Are In My Fresh California Raisins
  • Must use # syntax to create a title

  • Must be H2 or lower. (H1 titles are automatically generated by React)

    ## My Title 1
    
    ### My Subtitle 1.1
    
    ## My Title 2

Anchors and Headings

  • Default: are automatically generated based on the title text
  • Custom: words must be separated by dashes
## My Title {#title-custom-anchor}

Lists

Bullet lists:

- First item
- Second item
- ...

Autonumbered lists:

1. First item
2. Second item
3. ...

Code blocks

To highlight code, you can add the following values at the code block initialization. It's better to specify it because it will improve readability.

  • shell
  • Shell
  • YAML
  • Python
  • Javascript
  • Markdown
  • ini

Others

  • There must be no warning nor error messages when building the documentation with yarn start.
  • There should be one and only one newline character at the end of each file.
  • There should be no trailing whitespace at the end of lines
  • Paragraphs must be wrapped and lines should be at most 100 characters long
  • You must run yarn format:uc-doc when you're done