From 4e7566214811001f1a75341a3e957d1a7cfb8e60 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Fri, 9 Oct 2026 13:18:14 +0200 Subject: [PATCH] docs: document `exclude_docs`, `draft_docs` and `not_in_nav` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Timothée Mazzucotelli --- docs/compatibility/mkdocs/migration.md | 8 +- docs/compatibility/mkdocs/plugins.md | 6 +- docs/setup/basics.md | 110 +++++++++++++++++++++++++ docs/setup/navigation.md | 4 + docs/usage/build.md | 5 ++ docs/usage/preview.md | 4 + 6 files changed, 130 insertions(+), 7 deletions(-) diff --git a/docs/compatibility/mkdocs/migration.md b/docs/compatibility/mkdocs/migration.md index 42fe899..711500a 100644 --- a/docs/compatibility/mkdocs/migration.md +++ b/docs/compatibility/mkdocs/migration.md @@ -64,9 +64,6 @@ The following `mkdocs.yml` settings are not yet supported in Zensical: - `remote_branch` - `remote_name` -- [`exclude_docs`][draft_exclude_docs] -- [`draft_docs`][draft_exclude_docs] -- [`not_in_nav`][not_in_nav] - `hooks` ## Build and preview @@ -137,15 +134,16 @@ When moving older or extensively customized overrides: [command-line reference]: ../../usage/cli.md [configuration reference]: ../../setup/basics.md [docs_dir]: ../../setup/basics.md#docs_dir -[draft_exclude_docs]: https://github.com/zensical/backlog/issues/65 +[draft_docs]: ../../setup/basics.md#draft_docs [Editor]: ../../assets/screenshots/editor.png#gh-light-mode-only [Editor dark]: ../../assets/screenshots/editor-dark.png#gh-dark-mode-only +[exclude_docs]: ../../setup/basics.md#exclude_docs [filters]: https://docs.rs/minijinja/latest/minijinja/filters/index.html#functions [MiniJinja]: https://docs.rs/minijinja/latest/minijinja/ [MkDocs plugins]: plugins.md [Modern theme]: ../../assets/screenshots/theme-modern.png#gh-light-mode-only [Modern theme dark]: ../../assets/screenshots/theme-modern-dark.png#gh-dark-mode-only -[not_in_nav]: https://github.com/zensical/backlog/issues/63 +[not_in_nav]: ../../setup/basics.md#not_in_nav [publishing method]: ../../publish-your-site.md [site_dir]: ../../setup/basics.md#site_dir [tests]: https://docs.rs/minijinja/latest/minijinja/tests/index.html#functions diff --git a/docs/compatibility/mkdocs/plugins.md b/docs/compatibility/mkdocs/plugins.md index 95298e4..fcd231b 100644 --- a/docs/compatibility/mkdocs/plugins.md +++ b/docs/compatibility/mkdocs/plugins.md @@ -224,7 +224,7 @@ Customize navigation with a `.nav.yml` file in each documentation directory. **Differences**: - Extglob expressions are not supported; regular [glob patterns] are supported. -- MkDocs' [`not_in_nav`][not_in_nav] setting is not supported. +- The [`not_in_nav`][not_in_nav] setting is not applied to navigation generated by `awesome-nav`. Page visibility must be configured in `.nav.yml`. For more information, see the [plugin documentation][awesome-nav]. @@ -430,6 +430,7 @@ Jinja variables, filters, and Python macros are supported in Markdown. | `include_yaml` | `[]` | YAML files providing variables. | | `include_dir` | `""` | Directory for Jinja includes and imports, relative to the project root. If empty, `docs_dir` is used. | | `render_by_default` | `true` | Render Jinja on all pages unless their metadata overrides it. | +| `force_render_paths` | `""` | Additional pages selected for Jinja rendering with multiline [file patterns], relative to `docs_dir`. Page metadata takes precedence. | | `on_error_fail` | `false` | With `true`, the build is stopped on rendering errors. With `false`, error diagnostics are inserted into the page. | | `on_undefined` | `keep` | With `keep`, simple undefined expressions are preserved. With `silent`, undefined values are rendered as empty strings. With `strict`, errors are raised. With `lax`, missing attributes are also rendered as empty strings. | @@ -991,6 +992,7 @@ without using their original codebases. [compatibility roadmap]: #compatibility-roadmap [create a change request]: https://github.com/zensical/zensical/issues/new/choose [exclude]: https://github.com/apenwarr/mkdocs-exclude +[file patterns]: ../../setup/basics.md#file-patterns [gen-files]: https://oprypin.github.io/mkdocs-gen-files/ [gh-admonitions]: https://pypi.org/project/mkdocs-github-admonitions-plugin/ [git-authors]: https://timvink.github.io/mkdocs-git-authors-plugin/ @@ -1008,7 +1010,7 @@ without using their original codebases. [minify]: https://github.com/byrnereese/mkdocs-minify-plugin [mkdocs-nav-weight]: https://github.com/shu307/mkdocs-nav-weight [mkdocstrings]: https://mkdocstrings.github.io/ -[not_in_nav]: https://github.com/zensical/backlog/issues/63 +[not_in_nav]: ../../setup/basics.md#not_in_nav [offline]: https://squidfunk.github.io/mkdocs-material/plugins/offline/ [open-in-new-tab]: https://pypi.org/project/mkdocs-open-in-new-tab/ [open-in-new-tab JavaScript]: https://github.com/JakubAndrysek/mkdocs-open-in-new-tab/blob/main/open_in_new_tab/js/open_in_new_tab.js diff --git a/docs/setup/basics.md b/docs/setup/basics.md index 18aa85b..2753c12 100644 --- a/docs/setup/basics.md +++ b/docs/setup/basics.md @@ -219,6 +219,100 @@ server. The default value is `true`. | usage.md | usage.html | /usage.html | | about/license.md | about/license.html | /about/license.html | +### `exclude_docs` + +Files matched by `exclude_docs` are excluded from both [`zensical build`][build] and [`zensical serve`][preview]. [File pattern syntax](#file-patterns) is supported. The patterns are applied to Markdown pages and other files within [`docs_dir`](#docs_dir), including images and other assets. + +=== "`zensical.toml`" + + ``` toml + [project] + exclude_docs = """ + /private/ + *.tmp + """ + ``` + +=== "`mkdocs.yml`" + + ``` yaml + exclude_docs: | + /private/ + *.tmp + ``` + +Dotfiles, files inside dot directories, and the top-level `templates/` directory are excluded by default. These default patterns are applied before the configured patterns. Default exclusions can be reversed with `!`: + +=== "`zensical.toml`" + + ``` toml + [project] + exclude_docs = """ + !.* + !/templates/ + """ + ``` + +=== "`mkdocs.yml`" + + ``` yaml + exclude_docs: | + !.* + !/templates/ + ``` + +Files matched by `exclude_docs` are excluded even when matched by [`draft_docs`](#draft_docs) or [`not_in_nav`](#not_in_nav). + +### `draft_docs` + +Files matched by `draft_docs` are excluded from [`zensical build`][build] but included during [`zensical serve`][preview]. [File pattern syntax](#file-patterns) is supported. No files are marked as drafts by default. + +=== "`zensical.toml`" + + ``` toml + [project] + draft_docs = """ + /drafts/ + *.draft.md + """ + ``` + +=== "`mkdocs.yml`" + + ``` yaml + draft_docs: | + /drafts/ + *.draft.md + ``` + +During preview, a draft notice is added to draft pages. Draft pages are omitted from the default, automatically generated navigation, even during preview. They can be opened by URL or added to an explicit [`nav`][explicit navigation] for preview. + +Patterns are also applied to assets within `docs_dir`. Assets required only by draft pages can be matched by `draft_docs` to exclude them from builds. + +### `not_in_nav` + +Pages matched by `not_in_nav` are omitted from the default, automatically generated navigation. These pages are still built and included in search and the sitemap. [File pattern syntax](#file-patterns) is supported. No pages are omitted by this setting by default. + +=== "`zensical.toml`" + + ``` toml + [project] + not_in_nav = """ + /internal/ + changelog.md + """ + ``` + +=== "`mkdocs.yml`" + + ``` yaml + not_in_nav: | + /internal/ + changelog.md + ``` + +Matched pages can still be included in an explicit [`nav`][explicit navigation]. The setting is not applied to navigation generated by [`awesome-nav`][awesome-nav]. + ### `dev_addr` When running `zensical serve`, the built-in web server binds to this address @@ -284,8 +378,24 @@ configuration: - fragments ``` +## File patterns + +The [`exclude_docs`](#exclude_docs), [`draft_docs`](#draft_docs), and [`not_in_nav`](#not_in_nav) settings must be configured as strings, with one pattern per line. `.gitignore` syntax is supported, and paths are resolved relative to [`docs_dir`](#docs_dir): + +- A leading `/` is used to anchor a pattern to `docs_dir`: only `/private.md` at the root is matched. +- A name without `/` is matched at any depth: `guides/private.md` is also matched by `private.md`. +- A trailing `/` is used to match a directory and its contents: draft directories at any depth are matched by `drafts/`. +- Wildcards are supported: Markdown files are matched by `*.md`, and Markdown files throughout `guides/` are matched by `guides/**/*.md`. +- A leading `!` is used to reverse a previous match: `drafts/keep.md` is restored by `!drafts/keep.md` after `drafts/`. +- Blank lines and lines beginning with `#` are ignored. A literal leading `#` or `!` must be escaped with `\`. + +Patterns are evaluated in order, and the last matching pattern is used. Negation is applied only within the same setting. For example, an `exclude_docs` match cannot be reversed by a negated `not_in_nav` pattern. + +[awesome-nav]: ../compatibility/mkdocs/plugins.md#awesome-nav [backlog item]: https://github.com/zensical/backlog/issues/101 +[build]: ../usage/build.md [description in the page metadata]: ../authoring/frontmatter.md +[explicit navigation]: navigation.md#explicit-navigation [Macros]: ../compatibility/mkdocs/plugins.md#macros [macros-include_dir]: ../compatibility/mkdocs/plugins.md#macros [macros-include_yaml]: ../compatibility/mkdocs/plugins.md#macros diff --git a/docs/setup/navigation.md b/docs/setup/navigation.md index 2fa81ab..51c63f4 100644 --- a/docs/setup/navigation.md +++ b/docs/setup/navigation.md @@ -21,6 +21,8 @@ By default, Zensical creates the navigation sidebar on the basis of the folder structure and content of the Markdown pages. Likewise, it uses a default layout that can be overridden using various feature flags described on this page. +Pages can be omitted from the default navigation with [`not_in_nav`][not_in_nav]. They are still built and included in search and the sitemap. Pages matched by [`draft_docs`][draft_docs] are also omitted from the default navigation, including during preview. + ### Explicit navigation If you want to exercise more control over the structure of your navigation, you @@ -775,9 +777,11 @@ of CSS: [additional style sheet]: ../customization.md#additional-css [docs_dir]: basics.md#docs_dir +[draft_docs]: basics.md#draft_docs [in the footer]: footer.md#navigation [instant navigation]: #instant-navigation [instant previews]: #instant-previews +[not_in_nav]: basics.md#not_in_nav [Navigation expansion disabled]: ../assets/screenshots/navigation.png#gh-light-mode-only [Navigation expansion disabled dark]: ../assets/screenshots/navigation-dark.png#gh-dark-mode-only [Navigation expansion enabled]: ../assets/screenshots/navigation-expand.png#gh-light-mode-only diff --git a/docs/usage/build.md b/docs/usage/build.md index fdbf830..a3e9f86 100644 --- a/docs/usage/build.md +++ b/docs/usage/build.md @@ -17,6 +17,8 @@ zensical build [OPTIONS] This will generate the static site in the configured [`site_dir`][site_dir], with the default being `site`. +Files matched by [`exclude_docs`][exclude_docs] or [`draft_docs`][draft_docs] are excluded from the generated site. Draft files can be included during [preview]. + ## Options You can run `zensical build --help` to get command-line help for the `build` @@ -46,5 +48,8 @@ the near term. If the problem recurs after a clean build, please [create an issue]. [create an issue]: https://zensical.org/contributing/bug-reports/ +[draft_docs]: ../setup/basics.md#draft_docs +[exclude_docs]: ../setup/basics.md#exclude_docs +[preview]: preview.md [site_dir]: ../setup/basics.md#site_dir [strict mode]: ../setup/validation.md#strict-mode diff --git a/docs/usage/preview.md b/docs/usage/preview.md index 0bdda33..f863681 100644 --- a/docs/usage/preview.md +++ b/docs/usage/preview.md @@ -27,6 +27,8 @@ This starts a local web server that serves your documentation site on [localhost:8000][live preview]. As you make changes to source files, the browser will automatically reload the page you're on. +Files matched by [`draft_docs`][draft_docs] are included during preview, and a draft notice is added to draft pages. Draft pages are omitted from the default navigation and can be opened by URL. Files matched by [`exclude_docs`][exclude_docs] are excluded from preview. + ## Options The `serve` command accepts the following options: @@ -38,4 +40,6 @@ The `serve` command accepts the following options: | `--dev-addr ` | `-a` | IP address and port (default: localhost:8000) | | `--help` | | Show a help message and exit. | +[draft_docs]: ../setup/basics.md#draft_docs +[exclude_docs]: ../setup/basics.md#exclude_docs [live preview]: http://localhost:8000