THE GITHTML FIELD GUIDE
Build MkDocs HTML locally before sharing it
Run MkDocs locally in an already configured project to generate its HTML site, then inspect the output before distribution. The build creates a collection of files; it does not automatically publish them or make them a standalone reading document. Keep the source directory and generated output separate, and review any plugins before running an unfamiliar project.
Inspect the existing project
Find the MkDocs configuration and the documentation source directory. Read the project’s setup instructions and identify its installed version, theme, and plugins. Do not add arbitrary packages or execute unknown build extensions simply because the repository contains a familiar configuration filename.
Confirm where generated output belongs. Use a dedicated disposable build directory, never a directory containing source files or unrelated work. Generators can replace existing output, so the destination choice deserves attention before the command runs.
Generate a local review artifact
With the project’s documented environment prepared, run the example build command from the configuration directory. The explicit site directory makes the output location clear. Choose a new dedicated path if that example location already contains something you need.
Read the build messages and investigate warnings that affect navigation or content. A generated index file is not proof that every source page was included correctly or that links and images will work in the intended environment.
mkdocs build --site-dir build/reading-siteInspect the site as a collection
Open the site through the project’s supported local preview workflow and walk a representative task. Review the homepage, one deep guide, one code-heavy page, and a page containing images. Confirm that the navigation matches the reader’s needs.
Keep the output directory together when evaluating the complete site. Its HTML files can depend on shared assets and theme behavior. Copying only the first index.html may produce a misleading or incomplete reading experience.
Choose a distribution mode
For a hosted documentation site, publication is a separate authorized step involving a hosting environment. For repository-based reading, decide which generated .html files should be retained and what their dependencies require. gitHtml does not build the MkDocs sources or promise to mirror the site’s entire asset tree.
If the task is a small offline packet, consider a focused standalone export instead of distributing the full theme. Record the source revision and build settings, then test the actual artifact with the intended connectivity and script settings.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.