THE GITHTML FIELD GUIDE
Configure MkDocs links for file-oriented reading
For a MkDocs edition intended to be opened directly from files, review the use_directory_urls setting. Setting it to false generates direct HTML-file links instead of directory-style destinations. This addresses one navigation assumption; it does not embed assets, replace script-dependent features, or guarantee compatibility with every document-reading application.
Identify the failing navigation assumption
A hosted site may resolve a directory URL to an index.html file. A local file viewer may not perform that same resolution. If the homepage opens but chapter links fail, inspect whether those links point to directories rather than explicit files.
Compare the generated path with the link destination before changing configuration. Missing assets, incorrect relative paths, and absent pages can produce similar symptoms. A targeted diagnosis avoids treating every broken link as a directory-URL problem.
Create a file-oriented build configuration
MkDocs documents use_directory_urls: false for cases such as opening pages directly from the filesystem. Add the setting through the project’s approved configuration workflow, preferably in a clearly identified export configuration when the hosted site needs different behavior.
Build into a new dedicated output directory and inspect the resulting paths. Keep the hosted edition’s requirements separate. A setting that improves file-oriented reading may change public URL conventions if accidentally applied to the production site.
use_directory_urls: falseReview the remaining dependencies
Check theme stylesheets, images, fonts, and any search or navigation scripts. Direct links to HTML files solve only the destination shape. They do not make referenced assets available or turn a full generated site into a single portable document.
Test deep pages opened directly, not only pages reached from the homepage. Readers may select an individual HTML file in an app, and that entry point can expose assumptions hidden by the normal website route.
Decide whether the result fits the reader
Walk the intended task with the actual destination app and connectivity settings. For gitHtml, verify the selected .html files and their visible content; do not infer complete site support from the presence of indexed filenames.
If file-oriented output remains too dependent on theme behavior, produce a simpler companion handbook for the offline use case. Keep an explicit note explaining which edition is hosted and which is a reading export, along with the source revision and known feature differences.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.