Skip to content

Contributing to the FSL documentation

Note

This page is intended for the FSL development team and colleagues working at OxCIN. For everbody else, if you see a problem with our documentation, please get in touch!

The FSL documentation pages are stored as markdown files in a repository on Gitlab:

https://fsl.fmrib.ox.ac.uk/fsl/docs/

These files are converted to HTML using a static site generator called mkdocs, and an extension called mkdocs+material.

How to contribute

You can edit files directly through the Gitlab web interface at the fsl/docs repository.

  1. Navigate to the file you want to edit, and click the Edit button at the top right. If you just want to edit the one file, choose Edit single file. If you want to edit multiple files, or add/remove files, you can choose Open in Web IDE. The instructions below assume that you have chosen Edit single file.

  2. Edit the file as needed.

  3. Click the Commit changes button at the top of the page. Enter a descriptive commit message, e.g. Fix typo on BET page, and then click the Commit changes button in the dialog.

  4. You will then be prompted to create a Merge request, which is a request for your edits to be merged into the documentation. Add a title and description if you like, and then click the Create merge request button.

  5. Wait for one of the FSL maintainers to merge your changes.

Follow these instructions if you prefer to edit the documentation on your local computer using your text editor of choice.

  1. Install git and git lfs if you have not already done so. You probably already have git, but git lfs is often not installed by default. On macOS, you can install it from https://git-lfs.com/, or via homebrew or macports. Once you have installed git lfs, open a terminal and run: 

    ngit lfs install

  2. Download a local copy of the FSL documentation git repository: 

    git clone git@git.fmrib.ox.ac.uk:fsl/docs.git
cd docs

  3. Make sure your local repository is up-to-date, and then create a branch for your new changes - give your branch a sensible name, e.g.: 

    git fetch --all
git checkout -b add-fnirt-docs origin/main

  4. Make your changes/add your content (more details on this below).

  5. Add/commit your changes: 

    git add docs/registration/fnirt.md
git commit -m "Added FNIRT page"

  6. Push your changes to the fsl/docs Gitlab repository: 

    git push origin add-fnirt-docs

  7. Open a merge request at https://git.fmrib.ox.ac.uk/fsl/docs/

From a fork

If you wish, you can fork the fsl/docs Gitlab repository into your own Gitlab namespace (e.g. paulmc/docs). Contributing changes from a fork works in much the same manner as described above, except that you will be opening merge requests across repositories (e.g. from your branch on paulmc/docs to the main branch on fsl/docs).

When working locally, you will also need to keep track of two remote repositories - a very common convention is to use the following names:

  • upstream for the main repository (fsl/docs)
  • origin for your fork (paulmc/docs)

Working form a fork has the advantage that, when you push changes to your fork, you will be able to preview your changes online, (e.g. https://pages.fmrib.ox.ac.uk/paulmc/docs/). This is described in more detail below.

Adding content

You can simply edit the markdown (.md) files inside the docs/ sub-directory. The website structure exactly mirrors the file/directory inside docs/ - for example, https://fsl.fmrib.ox.ac.uk/fsl/docs/registration/fnirt/index.html is generated from docs/registration/fnirt/index.md.

If you wish to change an existing page:

  1. Locate the markdown (.md) file that corresponds to the web page you wish to update.

  2. Make your changes as described above.

If you wish to create a new page or section:

  1. Create the new files/directories inside the docs/ directory.

  2. Add a link to your new pages/sections in the relevant _sidebar.md files - the navigation sidebar on the left is generated from these files.

  3. If you have created a new section/directory containing several pages, add a _sidebar.md file inside it, so that each page will appear in the navigation sidebar.

See the Markdown cheat sheet below for more details and suggestions.

Previewing your changes

There are two ways to preview your changes before they are added to the FSL documentation.

Working from a fork

If you are making your changes on a Gitlab fork (e.g. paulmc/docs), a full copy of the documentation, with your changes, will be published via Gitlab pages every time you add or push new commits to any branch.

You will be able to view your changes at https://pages.fmrib.ox.ac.uk/<user>/docs/, e.g. https://pages.fmrib.ox.ac.uk/paulmc/docs/.

Working locally

If you are making your changes locally, you can install mkdocs and build the documentation yourself.

  1. Create a Python environment using any method of your choosing (e.g. uv, conda, python -m venv, etc)

  2. Install mkdocs, mkdocs-material, and a few extensions (these packages can also be installed from conda-forge if you prefer):

    pip install                        \
    mkdocs                         \
    mkdocs-material                \
    mkdocs-literate-nav            \
    mkdocs-section-index           \
    mkdocs-include-markdown-plugin

  3. Run the following command from the root directory of your local clone: 

    mkdocs serve

  4. After a few seconds, you will be able to open http://localhost:8000 in a web browser to view the documentation.

Markdown cheat sheet

The FSL documentation is written in Markdown, which is a simple plain-text format. The official Markdown syntax reference can be found here.

The mkdocs+material framework supports a range of extensions to the Markdown syntax, which you can read about here.

Linking to other pages and content

When linking to other files, images and attachments within the FSL documentation, you may use either relative or absolute links.

A relative link to a file is simply specified as relative to the file you are linking from. For example, in diffusion/eddy/users_guide/index.md, you can link to diffusion/eddy/FAQ/index.md like so:

Check out the [EDDY FAQ](../FAQ/index.md).

An absolute link is specified from the root directory of the documentation (i.e. the docs/ directory), and must start with a forward-slash (/). For example:

Check out the [EDDY FAQ](/diffusion/eddy/FAQ/index.md).

Follow the same rules when linking to attachments/data files within the FSL documentation.

If, for whatever reason, you are using HTML for links, you must use relative URLs, and you must use the .html suffix rather than the .md suffix, e.g.:

Check out the <a href="../FAQ/index.html">EDDY FAQ</a> ...

Linking to sections within a page

Every Markdown heading will be turned into a linkable anchor - for example, this Markdown header:

## Some section

can be linked to with the following syntax:

Refer to [some section](#some-section) for more details.

The link (a.k.a slug) for a header is the same as the header, converted to lower-case, and with all non-alpha-numeric characters replaced with hyphens (e.g. the slug for Some section is some-section).

It is also possible to manually create and link to anchors anywhere in your file - for example, you can create an anchor for a paragraph like so:

<a id="some-paragraph" href="#some-paragraph">This paragraph</a> is a very
good paragraph

And link to it elsewhere like so:

Check out [this paragraph](#some-paragraph) as it is a very good paragraph.

These section links work across pages too, e.g.:

Check out this [other paragraph](other_file.md#other-paragraph) as it is also great.

Literal URLs

If you want to display a clickable URL, surround the URL with < and >, e.g.:

The FSL documentation can be found at <https://fsl.fmrib.ox.ac.uk/fsl/docs/>.

Linking to images

Follow the linking rules described above when using Markdown syntax to display images - i.e. you can use either absolute or relative links, for example:

This diagram depicts single-session ICA:

![single session ICA](melodic_single_session.png)

or:

![single session ICA](/resting_state/melodic_single_session.png)

However, if you are using HTML to display images (i.e. the <img> element), you cannot use absolute links, and must use relative links, e.g.:

<img alt="single session ICA" src="melodic_single_session.png">

If you need to set the width or height of an image, you can specify attributes in curly braces, e.g.:

![Rabbits](rabbits.jpg){ width=30% }

Or you can just use HTML:

<img alt="Rabbits" src="rabbits.jpg" width="30%">

Custom block quotes ("admonitions")

You can display important messages using admonitions. For example, this text:

!!! note "Important message"

    My hovercraft is full of eels!

Will be displayed as:

Important message

My hovercraft is full of eels!

And this:

!!! warning "Warning"

    My limbs are flailing wildly!

will look like:

Warning

My limbs are flailing wildly!

Code highlighting

If you are displaying code snippets, you can apply language-specific syntax highlighting by beginning the snippet with the language name:

```bash
ls -l
```

```python
def some_function():
    print('hello')
```

Latex

We have enabled mathjax for rendering LaTeX mathematical equations. For an inline equation, use:

The equation $e=mc^2$ is a very good equation.

Or for a block equation, use:

The equation:

$$
e=mc^2
$$

is a very good equation.

NIfTI preview with NiiVue

You can display one or more NIfTI images with NiiVue like so:

<div class="niivue-canvas" thumbnail="thumbnail.png">
<vol url="T1.nii.gz"/>
<vol url="T1_brain.nii.gz" colormap="red" opacity="0.5"/>
</div>

Paths to all files must be relative to the docs/ directory. The thumbnail image is used as a preview before the NIfTI images are loaded.

Lists

Lists must be preceded by an empty newline, and nested lists must be indented with four spaces, e.g.:

Check out the following list:

 - Item A
 - Item B
     - Item B.1
     - Item B.2
     - Item B.3
 - Item C

Check out the following list:

  • Item A
  • Item B
    • Item B.1
    • Item B.2
    • Item B.3
  • Item C