Skip to content

Editing the documentation

This documentation is simply a set of Markdown documents, stored and organised in the Documentation repository. The markdown documents are then automatically mapped to a web page every time a Push to the main branch of the Documentation repository is done. See below for technical details on how this is achieved.

Depending on your account permissions, you should be able to commit directly to main, or a Pull Request will be required to perform the changes.

Minor modifications

For small modifications, you can click the pencil ✏️ icon on the top-right of the page. This will bring you to the Github Markdown editor.

Avoid this for non-minor changes. Limit this approach to e.g. correcting typos, rephrasing sentences for clarity, adding short sentences, fixing URLs.

General modifications

In order to edit the documentation, you need to:

  1. Clone the documentation repository on your machine
  2. Navigate to the docs folder, and edit a markdown file or add new markdown files.

The enhanced markdown

The documentation markdown can incorporate non-markdown content. You can embed:

  • HTML blocks with embedded functionality, e.g. (click on details to see!):

  • Latex/Mathjax, e.g. \(f(x) = x^2\) (enclose the formula between single $ for inline and double $$ for block).

Tip

Many more features are available to spice up the look of the documentation and help you convey information. See the available customisations of Material for Mkdocs: setup and Markdocs extra elements.

Using a text editor to edit the documentation

We recommend using either Visual Studio Code or Markdown Monster to edit the documentation.

With Visual Studio Code you can preview the markdown while editing.

Adding pages

If you want to add a page, just add an new markdown document.

The first H1 header (#) of the page will be taken as the title of the corresponding webpage.

Each header will be reflected in the navigation menu on the right hand side of the page.

Linking to other documentation pages

Links to other documentation pages should be relative URLs (starting with a /) where the first slash must be followed with the documentation folder. Some examples:

This section is work in progress -- please refer to https://github.com/BHoM/documentation/issues/84

Note

This way of providing URL to pages is required because MkDocs reflects the markdown files starting from the root documentation.

Tip

If using Visual Studio Code, enable Error Reporting on Markdown files and Link Validation in settings. VS Code will then check the validity of local links and cross referencing across your Markdown files, flagging warnings where links are invalid. VS Code Link Validation

If you are editing a specific nested page you can also use URLs relative to the current page. Some examples: - To link to the Getting started for developers page, relative to this current page (Editing-the-documentation), you can provide: ../Getting-started-for-developers.

Folders

Folders behave as groups for sub-pages and are reflected into the left menu of the website.

A folder may contain one markdown file called index.md; if it exists, that file is taken to be the first page of the folder when viewed from the website.

For information on how to sort the pages, see below.

Previewing the website before pushing to the repository

You may want to preview how your markdown documents will appear in the automatically-generated website. In order to do this, you can use mkdocs from command line.

You need to:

  1. Have Python and PIP installed on your machine. Install mkdocs by running 
    pip install mkdocs
  2. You will also need to ensure you have the MkDocs extensions and plugins that we are utilising installed. These can also be installed using pip by running the following: 
    pip install mkdocs-material 
pip install mkdocs-awesome-pages-plugin
pip install mkdocs-git-revision-date-localized-plugin
  3. Navigate to your locally cloned documentation repository folder.
  4. In that location, invoke from command line:
    python -m mkdocs serve

Mkdocs should spin up a local server and you should be able to connect to http://localhost:8000/ in your browser to display the documentation website. Any change to your local file will be hot-reloaded into the webpage.

Website configurations

As mentioned, the Markdown documents are transformed into a proper web page thanks to mkdocs every time a Push to the main branch of the documentation repository is done.

The web page can be configured by configuring mkdocs and related dependencies.

Dependencies

On top of mkdocs, we also use:

Customising the ordering of the pages in the menu

You just need to add a .pages text file in the specific folder where you want to sort out your pages. For an example, see the .pages file in the docs folder.

You can edit the .page file according to mkdocs awesome pages plugin.

Customising the appearance of the documentation

See the available customisations of Material for Mkdocs: setup and extra elements.

Github actions configuration

Every time a push to this repository is done, a GitHub action kicks in and calls:

The actions are configured as described in https://squidfunk.github.io/mkdocs-material/publishing-your-site/.