This repository contains the documentation for the central NOMAD distribution.

• Typos, corrections, and missing docs can be reported by Creating an Issue

• For internal contributions (write access to the repo required), please open a pull request (PR) with your changes. At least one review from a FAIRmat co-worker is required before merging. If you are not sure who to assign, please ask in the PR conversation by tagging @ahm531 or @JFRudzinski.

• For external contributions, please follow the External Contribution Instructions

When contributing, please check the writing guide for best practices.

If you have a nomad-dev-distro setup, you can follow the day to day development instructions to install nomad-docs as a submodule there.

If you do not have an up-to-date Python installation (3.11 or 3.12), see Help to install Python below.

On macOS and Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

On Windows

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
Or, from PyPI:

pip install uv

pipx install uv

If installed via the standalone installer, uv can update itself to the latest version:

uv self update

Once uv is installed, you can start the MkDocs server with:

uv run mkdocs serve

This will install all requirements in a virtual environment and start the local development server.

💡 Tip: To compare your local docs with the latest version once you start making significant changes, use the DEV Deployment DOCS.

uv run --extra dev pytest

This repository uses GitHub Actions to automatically run a series of tests on every push and pull request to the main branch. These tests ensure the quality and integrity of the documentation.

This test checks for broken links in all markdown files (.md) within the docs and examples directories, as well as in the README.md file. This ensures that all internal and external links are valid and accessible.

This test builds the MkDocs documentation using the --strict flag. This flag treats any warnings as errors, ensuring that the documentation is always in a buildable state.

This test runs the pytest command to execute all the tests in the tests directory. This test runs the pytest command to execute all the tests in the tests directory. These tests include:

• test_assets.py: This test ensures there are no unused assets (e.g., images, data files) in the docs/ directory by checking if they are referenced in any Markdown files.
• test_docs.py: This test verifies that the documentation pages are served correctly, checking for proper HTTP status codes and cache headers.
• test_pydantic.py: This test checks helper functions that extract information from Pydantic models, which are used to automatically generate documentation for these models.
• test_metainfo.py: This test checks helper functions that extract information from NOMAD's Metainfo models, which are used to automatically generate documentation for these models.

Click the Fork button at the top right of this page to create a copy of the repo under your GitHub account.

git clone https://github.com/your-username/nomad-docs.git
cd nomad-docs

git checkout -b my-feature-branch

git push origin my-feature-branch

• Go to your fork on GitHub.
• Click "Compare & pull request".
• Choose the base repo (FAIRmat-NFDI/nomad-docs) and target branch (e.g., main).
• Describe your changes and submit the PR.

✅ Your PR will be reviewed by the maintainers. You don’t need write access to contribute this way.

Note: Replace 3.11 with 3.12 below if you prefer to use Python 3.12.

If Python 3.11 is not installed on your system, use the instructions below based on your OS:

Debian Linux

sudo apt install python3.11

Red Hat Linux

sudo dnf install python3.11

macOS

brew install python@3.11

Windows PowerShell

1. Download the installer from the official Python website.
2. Run the installer.
3. Make sure to check the box "Add Python 3.11 to PATH" during installation.