Mkdocs

Class MkdocsTemplate

class MkdocsTemplate(Template)

[view_source]

A template to bootstrap an MkDocs build using Novella. It will set up actions to copy files from the content_directory and the mkdocs.yml config relative to the Novella configuration file (if the configuration file exists).

This template registers the following options:

--serve Use mkdocs serve --port The port to serve under (defaults to 8000). --site-dir Build directory for MkDocs (defaults to "_site") --base-url The base URL to prefix to autogenerated link inside the documentation.

This template produces the following actions:

1. copy-files – A CopyFilesAction that copies the content_directory and the mkdocs.yml (if it exists) to the build directory.
2. mkdocs-update-config – A MkdocsApplyDefaultAction to create or update the MkDocs configuraton file.
3. preprocess-markdown – An instance of the MarkdownPreprocessorAction. i. {@link pydoc:novella.markdown.tags.anchor.AnchorTagProcessor.flavor} is set to an {@link pydoc:novella.markdown.flavor.MkDocsFlavor} instance, and the prefix is set to base_url.
4. mkdocs-run – A RunAction that invokes MkDocs.

If the --serve option is provided, the template enables file watching for everything copied by the copy-files action and marks the mkdocs-run as reload-capable, allowing for a seemless live editing experience while using Novella as a preprocessor.

Example:

template "mkdocs"

action "mkdocs-update-config" {
  site_name = "My documentation"
}

action "preprocess-markdown" {
  use "pydoc"
}

content_directory

The directory that contains the MkDocs context. Defaults to content/.

base_url

The base URL at which the documentation will be hosted.

---

Class MkdocsUpdateConfigAction

class MkdocsUpdateConfigAction(Action)

[view_source]

An action to update the MkDocs configuration file, or create one if the user did not provide it.

The following configuration serves as the default configuration if the user did not provide an MkDocs configuration of their own. If a configuration file is already present, it will be updated such that top-level keys that don't exist in the provided configuration are set to the one present in the default below.

To disable this behaviour, set apply_defaults to False.

Available default profiles:

MaterialReadthedocs

docs_dir: content
site_name: My documentation
theme:
  name: material
  features:
  - navigation.indexes
  - navigation.instant
  - navigation.sections
  - navigation.tracking
  - navigation.top
  - toc.follow
markdown_extensions:
- admonition
- markdown.extensions.extra
- meta
- pymdownx.betterem
- pymdownx.caret
- pymdownx.details
- pymdownx.highlight
- pymdownx.inlinehilite
- pymdownx.keys
- pymdownx.mark
- pymdownx.smartsymbols
- pymdownx.superfences
- pymdownx.tabbed: { alternate_style: true }
- pymdownx.tasklist: { custom_checkbox: true }
- pymdownx.tilde

docs_dir: content
site_name: My documentation
theme:
  name: readthedocs
  highlightjs: true
  hljs_languages:
    - python
    - toml
    - yaml
  include_homepage_in_sidebar: true
  sticky_navigation: true
markdown_extensions:
- admonition
- markdown.extensions.extra
- meta

Check out the the Material for MkDocs // Setup documentation for more information. Other common theme features to enable are toc.integrate and navigation.tabs.

apply_defaults

Whether to apply the template to the MkDocs configuration (shown above).

Deprecated; use profile instead.

profile

The configuration profile to apply. Set to None to not update the MkDocs config.

site_name

The MkDocs site_name to inject. Will override an existing site name if not present in the MkDocs configuration.

autodetect_repo_url

Whether to autodetect the Git repository URL and inject it into the MkDocs configuration. Enabled by default. If the repository URL is already configured, it will do nothing.

content_directory

The content directory that contains the MkDocs source files. This is used only to construct the edit URI if autodetect_repo_url is enabled. This passed through by the MkdocsTemplate automatically.

update

def update(json_path: str,
           *,
           add: t.Any = NotSet.Value,
           set: t.Any = NotSet.Value,
           do: t.Callable[[t.Any], t.Any] | None = None) -> None

[view_source]

A helper function to update a value in the MkDocs configuration by either setting it to the value specified to the set argument or by adding to it (e.g. updating it if it is a dictionary or summing them in case of other values like strings or lists) the value of add. The do operation can also be used to perform an action on the existing value at json_path, but the value must be directly mutated and already exist in the configuration.

Note that the json_path argument is treated very simplisticly and does not support wildcards or indexing. The string must begin with $. Quotes in keys are not supported either.

Example

template "mkdocs"

action "mkdocs-update-config" {
  site_name = "My documentation"
  update '$.theme.features' add: ['toc.integrate', 'navigation.tabs']
  update '$.theme.palette' set: {'primary': 'black', 'accent': 'amber'}
}

update_with

def update_with(func: t.Callable[[dict[str, t.Any]], t.Any]) -> None

[view_source]

Adds a callback that can modify the MkDocs config before it is updated.