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
Gitlab web interface (recommended for small changes)
You can edit files directly through the Gitlab web interface at the fsl/docs
repository.
-
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.
-
Edit the file as needed.
-
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.
-
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.
-
Wait for one of the FSL maintainers to merge your changes.
Working locally (recommended for large changes)
Follow these instructions if you prefer to edit the documentation on your local computer using your text editor of choice.
-
Install
git
andgit lfs
if you have not already done so. You probably already havegit
, butgit 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 installedgit lfs
, open a terminal and run: -
Download a local copy of the FSL documentation git repository:
-
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.:
-
Make your changes/add your content (more details on this below).
-
Add/commit your changes:
-
Push your changes to the
fsl/docs
Gitlab repository: -
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:
-
Locate the markdown (
.md
) file that corresponds to the web page you wish to update. -
Make your changes as described above.
If you wish to create a new page or section:
-
Create the new files/directories inside the
docs/
directory. -
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. -
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.
-
Create a Python environment using any method of your choosing (e.g.
uv
,conda
,python -m venv
, etc) -
Install
mkdocs
,mkdocs-material
, and a few extensions (these packages can also be installed fromconda-forge
if you prefer): -
Run the following command from the root directory of your local clone:
-
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:
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:
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.:
Linking to sections within a page
Every Markdown heading will be turned into a linkable anchor - for example, this Markdown header:
can be linked to with the following syntax:
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:
And link to it elsewhere like so:
These section links work across pages too, e.g.:
Literal URLs
If you want to display a clickable URL, surround the URL with <
and >
, e.g.:
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:
or:
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.:
If you need to set the width or height of an image, you can specify attributes in curly braces, e.g.:
Or you can just use HTML:
Custom block quotes ("admonitions")
You can display important messages using admonitions. For example, this text:
Will be displayed as:
Important message
My hovercraft is full of eels!
And this:
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:
Or for a block equation, use:
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