How do I add my own documentation to Sema?

Sema contains a documentation system that serves as a reference guide to the various aspects of the system. If you add something to sema, such as a widget or language, you may want to document it using the same system. If you choose to do so we have made it easy to add additional pages of documentation, please follow the steps below.

Step 1

All pages of the documentation consume a markdown file, so to add your documentation you need to create a yourfilename.md file in the assets/docs/ folder. You will see existing documentation organized into folders, consisting of markdown files.

Step 2

In order for the new documentation to be served up by the website, we need to add an entry to the file /assets/docs/docs.json which might look as follows:

{
    "container": true,
    "title": "Live coding",
    "children": [
      {
        "container": false,
        "title": "Sample Loading",
        "file": "live-coding/sample-loading",
        "path": "./sample-loading"
      },
      {
        "container": true,
        "title": "Languages",
        "children": [
          {
            "container": false,
            "title": "Default Language",
            "file": "live-coding/languages/default-language",
            "path": "./default-language"
          },
          {
            "container": false,
            "title": "Rubber Duckling",
            "file": "live-coding/languages/rubber-duckling",
            "path": "./rubber-duckling"
          },
          {
            "container": false,
            "title": "Quaverseries",
            "file": "live-coding/languages/quaverseries",
            "path": "./quaverseries"
          },
          {
            "container": false,
            "title": "Nibble",
            "file": "live-coding/languages/nibble",
            "path": "./nibble"
          },
          {
            "container": false,
            "title": "YOUR NEW LIVE CODING LANGUAGE NAME",
            "file": "live-coding/languages/YOUR DOCUMENTATION MARKDOWN FILE",
            "path": "./THE URL THIS SHOULD DISPLAY AT (PROBABLY THE NAME OF YOUR LANGUAGE LOWERCASED)"
          },

        ]
      }
    ]
  }
...
...
and so on

See the last entry of the .json file above for an example of how to add a new page of documentation.

JSON object structure description

container whether the object is a folder in the navigation sidebar and will contain a list of children documentation objects.

path is the URL slug that is used. For example, "path":"./default-language" displays in the URL bar as http://localhost:5001/docs/default-language. It is a good idea to pick a lower cased and hyphenated version of the title of the documentation page it directs to.

title dictates the name of the documentation page as it will be displayed in the navigation sidebar.

file is the name of the markdown file you have created. There is no need to include .md file extension.

Once you have followed steps 1 and 2 the markdown file you made will have been successfully added to your version of sema, take a look!

Markdown formatting

Some important points to make best use of markdown formatting within the documentation system.

• # H1 style headers will be treated as sub sections, and appear as navigable links in the navigation sidebar.
• ``` code blocks ``` will be appear with a copy button on the top right hand corner.

Final Notes

A design and usability choice we have made, is to not allow nesting in our sidebar navigation menus beyond 3 levels.

for example:

live coding✔️
|->languages✔️
    |->my language folder✔️
       ->my first language.md ❌!!

The last entry will not display in the sidebar, as we have hard limits internally.