Neurobagel Documentation

The neurobagel documentation.

Our docs are built with the Material Theme for MKdocs.

Setup

Create a new virtual environment with python -m venv venv and activate it. Then install the dependencies with pip install -r requirements.txt

Adding new pages to the navigation

We use mkdocs-awesome-nav to define the navigation structure of the docs.

To add a new page, add it to the .nav.yml (structured the same way as the nav section of mkdocs.yml) of the directory the markdown file lives in.

To add an entire subdirectory (section) of pages, you can simply specify the subdirectory name, e.g.:

  - User guide: user_guide

Each subdirectory can then itself contain a .nav.yml to organize the pages within.

Note: Both relative and absolute paths can be used to specify files or directories in .nav.yml.

Build

To spin up the side locally while you edit it, run:

mkdocs serve

More details are in the mkdocs documentation.

Deploy

At the moment we are using mkdocs to deploy directly to gh-pages.

When your local build runs well, commit the changes to the main branch with a PR and then call

mkdocs gh-deploy

See the docs for more details.

Installing tailwind

To install tailwind, run:

npm i

Rebuilding tailwind

If you need to rebuild the tailwind css, run:

npx tailwindcss build docs/stylesheets/tailwind.css -o docs/stylesheets/output.css