Adding Documentation¶

Project layout¶

mkdocs.yml    # The configuration file.
docs/
    index.md  # The documentation homepage.
    ...       # Other markdown pages, images and other files.

Adding pages¶

These can be created in any sensible nested folder structure, and linked in the nav section of mkdocs.yml (used to prevent default alphabetical order), e.g.

nav:
  - Intro: index.md
  - Authors:
      - authors/quickstart.md
      - authors/notifications.md
  - Display Components:
      - components/audio.md
  - Developers:
      - developers/quickstart.md
      - developers/documentation.md
      - developers/device-testing.md

Styling¶

A full set of styling options can be found from the theme documentation at https://squidfunk.github.io/mkdocs-material/reference/

Info

This includes how to add things like call-outs (admonitions), buttons, tables and more!

View Theme Docs :fontawesome-solid-external-link-alt:

Screenshots and Images¶

Images can be linked from local files, ideally in a nested images folder or similar.

If editing in VSCode and adding screenshots, a handy extension to use is Paste Image which allows copy/paste directly into markdown files (using ctrl + alt + v) and will create the required image file (like how things work in github)

If using the extension it is recommended to enable the VSCode setting pasteImage.showFilePathConfirmInputBox, which will prompt a filepath for saving images

Tip

When adding screenshots the recommended device width is 425px. This is the size available in google chrome as Mobile L configuration. If the screenshot is unclear at this sizing the next recommendation would be 768px

Component Docs¶

Individual component documentation can be found in the ./components folder, ideally each document should contain the following information:

Example syntax for use in google sheet template
Example google sheet linked
Example live preview linked
List of available parameters, with description and defaults
Link in sidebar (added in mkdocs.yml)