Source for the documentation located at https://docs.alcf.anl.gov/
Using Git's SSH protocol. Make sure you add your SSH public key to your GitHub account:
git clone git@github.com:argonne-lcf/user-guides.git
cd user-guides
git submodule init; git submodule updateTo build the documentation locally, you need a Python 3.10+ environment with mkdocs and the
plugins listed in requirements.txt installed. Use either of the two options
below.
uv manages the Python interpreter and the virtual environment for
you, and is considerably faster than pip. If you do not already have it:
curl -LsSf https://astral.sh/uv/install.sh | sh # macOS/LinuxThen, from the root of the repository:
cd user-guides
uv venv # creates ./.venv, downloading Python if needed
source .venv/bin/activate
uv pip install -r requirements.txtEquivalently, make install-uv runs the uv venv and uv pip install steps for you.
To rebuild the environment from scratch (for example, to drop packages no longer in
requirements.txt), run uv venv --clear and reinstall.
Alternatively, skip the virtual environment entirely and prefix each command with
uv run, which resolves the dependencies on the fly:
uv run --with-requirements requirements.txt make serveThese temporary environments live in uv's cache, not the repo; uv cache prune removes unused ones.
Check that Python 3.10+ is installed:
python --versione.g. Python 3.13.5. Then create a new virtual env to isolate the mkdocs installation, and
install the dependencies into it:
cd user-guides
python -m venv env
source env/bin/activate
make install-devRun mkdocs serve or make serve to auto-build and serve the docs for preview in your web browser:
make serveGitHub Actions are used to automatically validate all changes in pull requests before they are merged, by executing mkdocs build --strict. The --strict flag will print out warnings and return a nonzero code if any of a number of checks fail (e.g. broken relative links, orphaned Markdown pages that are missing from the navigation sidebar, etc.). To see if your changes will pass these tests, run the following command locally:
make build-docs
The optimize plugin (image compression) and social plugin (link-preview cards in site/assets/images/social/) run only in CI. To build with them locally, install pngquant and Cairo (brew install pngquant cairo on macOS, apt install pngquant libcairo2 on Ubuntu) and run CI=true mkdocs build. On Apple Silicon, also set DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib so CairoSVG can find Cairo, and call mkdocs directly: macOS strips DYLD_* variables when running make.
To test search changes, run node scripts/search_test.js "query" against a running mkdocs serve.
LaTeX math renders via MathJax: inline $...$ or \(...\), blocks $$...$$ or \[...\].
Keep shell commands i
85BB
n backticks or code fences. A prose line with two bare $ (e.g. $MODEL_DIR ... /home/$(whoami)) can be misparsed as math; escape with \$ if needed.
A page can start with a YAML front-matter block:
---
description: "Run LLM inference with vLLM on Aurora: provided installation, memory sizing, and serving from one tile to many nodes."
tags:
- LLMs
keywords:
- huggingface
---description:one sentence, 120 characters max. Shown in link previews and search results.make check-descriptionslists pages without one.tags:only topics the page is about. Must be listed intags_allowedinmkdocs.yml. Search weights tags heavily, so don't over-tag.keywords:search terms the page doesn't use itself (e.g.MFA,vscode). Not shown on the page.search:withboost: 2to rank a page higher, orexclude: trueto hide it from search.- Tags for a whole folder go in its
.meta.yml(e.g.docs/aurora/.meta.ymladdsAurora). authors:the people who wrote the page (a list of names); everyone else who changed it is listed from git as "Edited by".last_verified:the date (YYYY-MM-DD) you last checked the whole page against the system. It's shown as stale after a year, or once the page changes;make check-verified(after a build) lists pages with a stale date or none.exclude_contributors:names to leave out of the page's contributors, e.g. someone credited only for mergingmaininto a PR branch.- Changes to only front matter, trailing spaces, or blank lines don't change a page's "Last Updated" date. Put other mechanical changes across many pages, such as re-wrapping, in their own commits, and list them in
.git-blame-ignore-revs(#1139).
- All commits must have a commit message
- Create your own branch from the
mainbranch. Here, we are usingYOURBRANCHas an example:
cd user-guides
git fetch --all
git checkout main
git pull origin main
git checkout -b YOURBRANCH
git push -u origin YOURBRANCH- Commit your changes to the remote repo:
cd user-guides
git status # check the status of the files you have edited
git commit -a -m "Updated docs" # preferably one issue per commit
git status # should say working tree clean
git push origin YOURBRANCH # push YOURBRANCH to origin
git checkout main # move to the local main
git pull origin main # pull the remote main to your local machine
git checkout YOURBRANCH # move back to your local branch
git merge main # merge the local develop into **YOURBRANCH** and
# make sure NO merge conflicts exist
git push origin YOURBRANCH # push the changes from local branch up to your remote branch- Create merge request from https://github.com/argonne-lcf/user-guides from
YOURBRANCHtomainbranch.
AGENTS.md gives AI coding agents the project context they would otherwise have to rediscover: what content edits may touch, the site's writing and formatting conventions, Markdown pitfalls, how to add or move pages, page front matter, and contributing rules. Build and theme details are in a separate section at the end. Codex, the Copilot coding agent, Cursor, and others read it automatically, and CLAUDE.md imports it for Claude Code. REVIEW.md is the short list of rules that Copilot code review applies to pull requests.
If you use an AI tool to edit these docs:
- Review the full diff yourself before committing; you're responsible for every change.
- Check facts about ALCF systems (queue limits, hostnames, module names, paths, versions) against the live system or the staff who own it, not the tool's output or another system's page. Say in the PR how you checked them.
- Keep each PR to one topic. Don't run sweeping "consistency" or typo passes across many pages.
- Keep commit messages and PR descriptions concise, and edit any generated text before submitting.
- Run
make build-docsbefore opening a PR. - Check the "AI tools were used" box in the pull request template, and name the tools in the description.
When a convention changes, update AGENTS.md in the same PR, and REVIEW.md too if reviewers should flag it.
External URLs pointing to our docs are tracked in includes/validate-inbound-URLs.txt and validated during build to prevent broken links from the main ALCF site, etc. Add URLs to that file to ensure that the matching .md in this repository is never moved, renamed, or deleted.
There are two Python scripts/ that perform this function:
- (works with
mkdocs buildandserve): Translate URLs to relative path links to their matching source.mdfiles; write these links todocs/inbound-links.md. Use MkDocs' built-in validation (adding--strictflag when runningmkdocs build, in order to return an error code if they are invalid). - (works with
mkdocs build, only): Use a lightweight post-build validation on generatedsite/directory HTML contents.