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.
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.
In order to edit the documentation, you need to:
- Clone the documentation repository on your machine
- Navigate to the
docsfolder, 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
Latex/Mathjax, e.g. \(f(x) = x^2\) (enclose the formula between single
$for inline and double
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.
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:
- To link to the Introduction to BHoM_Adapter page, you can provide this link:
- To link to the IsValidDataset page, you can provide this link:
This way of providing URL to pages is required because MkDocs reflects the markdown files starting from the root
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
Alternative (not recommended)
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:
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:
- Have Python and PIP installed on your machine. Install
- You will also need to ensure you have the MkDocs extensions and plugins that we are utilising installed. These can also be installed using
pipby running the following:
- Navigate to your locally cloned
- 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.
The web page can be configured by configuring mkdocs and related dependencies.
On top of mkdocs, we also use:
- an extender theme called Material for Mkdocs, which exposes more customisation and extra functionality.
- a plugin for customising the sorting of the pages: mkdocs awesome pages plugin
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
You can edit the
.page file according to mkdocs awesome pages plugin.
Customising the appearance of the documentation
Github actions configuration
Every time a push to this repository is done, a GitHub action kicks in and calls:
- mkdocs functionality to transform markdown to HTML
- mkdocs-material functionality, which expands the markdown translation of mkdocs with more features
- mkdocs awesome pages plugin functionality, which gives extra configs on top of mkdocs.
The actions are configured as described in https://squidfunk.github.io/mkdocs-material/publishing-your-site/.