diff --git a/site/docs/guides/documentation/guide.md b/site/docs/guides/documentation/guide.md index c02f091e76..4f95160f25 100644 --- a/site/docs/guides/documentation/guide.md +++ b/site/docs/guides/documentation/guide.md @@ -31,6 +31,13 @@ When contributing to the documentation, you can easily use this to test document !!! tip "Look for warnings" As part of running its generator, MkDocs will automatically warn you if it finds any broken links within your documentation. Pay close attention to these, as the PR merge mechanism for documentation will strictly enforce that no broken links are found in order to merge any changes into the main documentation. +!!! tip "Incremental viewing" + If you have the mkdocs server running as you edit page source, it will detect changed files and rebuild automatically. However this can take a minute or two. + To speed this up to a second or two, use the `--dirtyreload` flag to `mkdocs serve`. + + Note that any deleted pages will not be removed, and some links may break as a result that would otherwise work with a full reload (i.e. navigation structure changes). + See [Release notes](https://www.mkdocs.org/about/release-notes/#support-for-dirty-builds-990) for further information. + !!! warning "Special handling of index.md" Be aware that the specific theme we use will treat every `index.md` as an index page for a section: these behave in special ways depending on the level of the navigation in which they appear. Unless you mean to create an overview of some section of the navigation, do **not** name your Markdown file `index.md`.