The home page opens from an extracted archive, but its Verify link points at a folder instead of an HTML file. Choose MkDocs' URL layout for the actual delivery environment, then inspect the generated links and their target files. A local folder and a web server do not have the same directory-index behavior.
For this fictional exercise, the home page links to a Verify guide. Verify says “Compare the package with its source record.” The desired archive handoff contains an explicit verify.html file that the entry page can reach without relying on a server to turn /verify/ into an index document.
Open the complete example · Download the full HTML source
Set the URL layout in the configuration
The MkDocs configuration reference documents use_directory_urls. With the setting false, a source such as verify.md produces an HTML file rather than an additional directory containing index.html.
site_name: Document handoff
theme:
name: readthedocs
highlightjs: false
use_directory_urls: false
plugins: []
nav:
- Overview: index.md
- Verify: verify.md
The fixture selects the bundled Read the Docs theme and disables remote code highlighting. Keep those theme settings with this local-file reproduction. Disabling plugins here deliberately removes the default search plugin from this tiny navigation reproduction. It is not a general recommendation to remove search from a documentation site. The fixture checks generated page links, not the behavior of a search index opened from a local file.
Write a normal source link in docs/index.md:
[Verify the package](verify.md)
Build the project using the chosen MkDocs release and its configuration:
python -m mkdocs build --strict
The official configuration documentation also explains strict mode and validation levels. A clean command result is useful, but the delivered filenames and link destinations still need inspection.
Match each generated link to a file
For the file-oriented fixture, require site/index.html and site/verify.html. Inspect the home page's actual anchor and confirm that its target is the generated Verify file. Then open the entry page and follow that link in the environment used for delivery.
Do not repair a missing target by leaving an older output file in place. Use separate build destinations when comparing layouts. Otherwise a stale verify.html can make the new configuration appear to work even if it now produces only verify/index.html.
In the directory-oriented comparison, inspect the generated verify/index.html and its corresponding navigation link. That layout can suit a web server configured to serve directory index pages. Describe the selected layout rather than declaring one of the two configurations universally correct.
The existing MkDocs translation-route guide asks whether a localized route uses translated source or fallback content. This task uses one language and addresses generated file paths and navigation. Changing URL layout does not create a translation or establish language coverage.
Keep the generated assets with the entry page
The build contains resources as well as chapter HTML. Preserve the output folder structure when archiving it. A self-contained review excerpt can show the observed filenames and link text, but it should identify itself as a reading copy rather than the complete MkDocs site.
After extraction, follow Verify and confirm the expected source sentence on the destination page. Keep the accepted configuration and Markdown alongside the archive so the next correction can be built again. The useful handoff is the combination of a reproducible source project and links that work in the recipient's actual opening environment.
Download the maintained source and actual output archive. This archive retains the supplied fixture and the original generated files beside the reading copy.