Working with documentation files

Why this matters

Documentation in a repository is code-adjacent: reviewed, versioned, built and deployed like the program. That gives you history and review; it also imposes a few conventions, and one real limitation: Git is excellent with text and poor with images. Knowing both keeps your documentation changes small, reviewable and fast to clone.

Where documentation lives

Most projects follow this layout, and the playground does:

If a documentation site is generated (MkDocs, Docusaurus, Sphinx, or GitLab/GitHub Pages), there is also a configuration file at the root (mkdocs.yml, docusaurus.config.js) that lists the pages in navigation order. Adding a page often means adding a line there too; look at how existing pages are registered.

Naming and linking

• File names: lowercase, words separated by hyphens, .md extension: getting-started.md, release-process.md. No spaces (they break links), no capitals (case-sensitive systems treat Faq.md and faq.md as different files).
• Links between pages: relative to the current file: [FAQ](faq.md), [install](../README.md). They work on GitLab, GitHub, in editor previews and on generated sites. Absolute paths or full URLs to the repository break when the project moves.
• Links to headings: [see the rules](contributing.md#branches); the anchor is the heading text lowercased with hyphens.
• One page, one topic, with a single # title at the top.

Images and other binaries

Git stores any file, but it treats text and binaries very differently:

$ git diff --staged --stat

 docs/images/photo.png | Bin 0 -> 9 bytes
 1 file changed, 0 insertions(+), 0 deletions(-)

$ git diff --staged

diff --git a/docs/images/photo.png b/docs/images/photo.png
new file mode 100644
index 0000000..aa860ab
Binary files /dev/null and b/docs/images/photo.png differ

"Binary files differ" is all Git can say: no lines, no review of what changed, and no merging if two people change the same image. Every version of every image stays in history forever, so a 3 MB screenshot replaced ten times costs 30 MB for everyone who clones.

Rules of thumb:

• Prefer SVG for diagrams (it is text: diffable, small, scales). Draw.io and Excalidraw export it.
• Compress screenshots (PNG, under 300 KB; crop to the relevant part). Store them in docs/images/ with descriptive names: merge-request-approve-button.png.
• Never commit videos, large PDFs or datasets to a documentation repository; link to where they live.
• Reference images relatively: ![Approve button](images/merge-request-approve-button.png).

Git LFS

For projects that genuinely need large or frequently changed binaries (design files, datasets, game assets), Git LFS (Large File Storage) stores the file contents outside the repository and keeps only small pointers in Git. GitLab and GitHub both support it. You recognize an LFS project by a .gitattributes file with lines such as *.psd filter=lfs diff=lfs merge=lfs -text, and by needing the git lfs extension installed before cloning. Lesson 13.10 explains what to do when you meet one; a documentation project rarely needs it.

In the platforms

Common mistakes

• Spaces in file names. Getting Started.md needs %20 in links and breaks on some sites. Use hyphens.
• Absolute links. /Users/ana/… or C:\… work for one person only.
• Uncompressed screenshots. Full-screen 4K PNGs are several megabytes each. Crop and compress.
• Editing an image many times in a branch. Each version is stored; squash the branch on merge or replace the image once at the end.
• Committing generated site output (site/, _build/, public/) instead of the source. Ignore it; the pipeline builds it.

# Icons

The trail icon used in the guide.

![Trail icon](images/trail-icon.svg)

See also the [FAQ](faq.md).