Skip to content

How to Update this Documentation

Welcome! This page is part of the documentation itself — and serves as your guide for contributing updates to it.

The documentation is built using Material for MkDocs, a powerful and customisable static site generator for project documentation. Whether you’re fixing typos, updating content, or adding entirely new sections, this guide will walk you through how to do it cleanly and effectively.

Viewing documentation changes

It can take a few minutes for your changes to percolate to the live website and you may need to refresh your browser window to see the changes (e.g. Ctrl-Shift-R on a PC).  

✅ Prerequisites

Before you get started:

  • You must have write access to the TRE-docs repository on GitHub.
  • You do not need to branch or fork. This documentation encourages low-friction updates — just edit the files directly if you have access.
  • If multiple people are working on documentation simultaneously, consider coordinating to avoid merge conflicts.

✏️ Updating Existing Pages

All content lives in Markdown (.md) files within the docs/ directory.

Steps:

  1. In TRE-docs, navigate to the documentation page you want to update.
  2. Click the icon in the top right of the page.
  3. If prompted, sign in as a user with write access to the TRE-docs GitHub repo.
  4. You are now in edit mode (editing the .md file for that documentation page - in a new browser tab or window).
  5. Commit changes… when you are happy with the edits you have made.

Tip

Return to the page in the documentation where the changes were made. Wait a few seconds and then refresh the page in the browser. The changes should appear in place.

🖼️ Adding Images

All image assets should live under the docs/images/ folder of the TRE-docs repo. If an image for use exists elsewhere on the internet then (provided you have permission) make a copy and place it in docs/images/. This protects against referring in the docs to an image which has subsequently been moved or deleted externally.

How to include images:

  1. Upload your image file (e.g., cool-manhattan-plot.png) to docs/images/ in the TRE-docs repo. Or a subfolder therein (e.g. docs/images/regenie/)
  2. refer to the image in your .md file like so:
![Cool Manhattan Plot](images/cool-manhattan-plot.png)

Images will automatically scale in most cases, but you can use Markdown extensions like :width: if needed (with proper plugin support).

🆕 Creating New Pages

Want to add a new topic or guide?

1. Create a new file

Place your new Markdown file into an appropriate location, such as:

docs/[my-new-documentation-feature]/integration.md

You can use an existing page as a template for structure and formatting.

2. Add to Navigation

Edit the mkdocs.yml file at the root of this project to include your new page at the appropriate location in the site nav:

nav:
  - Home: index.md
  - Developer Guide:
      - Integration: developer-guide/integration.md

YAML is whitespace-sensitive — use 2 spaces per indentation, not tabs!

Info

If you don’t add your page to mkdocs.yml, it won’t appear in the sidebar navigation.

🧩 Markdown Extensions and Best Practices

Material for MkDocs includes several powerful extensions:

  • Callout boxes: !!! note, !!! warning, !!! example, etc.

Example: Adding a note box

Material for MkDocs calls these admonitions:

!!! note
    You can add callouts like this to draw attention.

Which renders as:

Note

You can add callouts like this to draw attention.

  • Code syntax highlighting:

Here’s how to display some python with syntax highlighting:

```python
def greet(name: pl.Utf8) -> None:
  print(f"Hello, {name}")
```

Which appears in the documentation as:

def greet(name: pl.Utf8) -> None:
    print(f"Hello, {name}")
  • Internal linking: 
    [Read the Getting Started Guide](getting-started.md)

Use these features to make your contributions clearer and more engaging.

🔒 Permissions

You’ll need access to the following:

  • docs/ – for Markdown pages
  • docs/images/ – for images and diagrams
  • mkdocs.yml – to update navigation structure

If you're missing access, contact a maintainer or administrator.

✅ Final Checklist Before Committing

  • [ ] Proofread for spelling and grammar
  • [ ] Image paths and links verified
  • [ ] New pages added to nav in mkdocs.yml
  • [ ] Content renders correctly in local preview
  • [ ] Used relevant MkDocs features (admonitions, syntax highlighting, etc.)

🛠️ Additional Resources

Happy writing!