build_page

Class info

Classes

Name	Children	Inherits
TemplateContext mkdocs_mknodes.commands.build_page		dict

🛈 DocStrings

The Mkdocs Plugin.

TemplateContext

Bases: TypedDict

Parameters:

Name	Type	Description	Default
nav	ForwardRef('Navigation', module='mkdocs_mknodes.commands.build_page')		required
pages	ForwardRef('Sequence[File]', module='mkdocs_mknodes.commands.build_page')		required
base_url	ForwardRef('str', module='mkdocs_mknodes.commands.build_page')		required
extra_css	ForwardRef('Sequence[str]', module='mkdocs_mknodes.commands.build_page')		required
extra_javascript	ForwardRef('Sequence[str]', module='mkdocs_mknodes.commands.build_page')		required
mkdocs_version	ForwardRef('str', module='mkdocs_mknodes.commands.build_page')		required
mknodes_version	ForwardRef('str', module='mkdocs_mknodes.commands.build_page')		required
build_date_utc	ForwardRef('datetime', module='mkdocs_mknodes.commands.build_page')		required
config	ForwardRef('MkNodesConfig', module='mkdocs_mknodes.commands.build_page')		required
page	ForwardRef('Page | None', module='mkdocs_mknodes.commands.build_page')		required

Source code in mkdocs_mknodes/commands/build_page.py

class TemplateContext(TypedDict):
    nav: Navigation
    pages: Sequence[File]
    base_url: str
    extra_css: Sequence[str]  # Do not use, prefer `config.extra_css`.
    extra_javascript: Sequence[str]  # Do not use, prefer `config.extra_javascript`.
    mkdocs_version: str
    mknodes_version: str
    build_date_utc: datetime
    config: MkNodesConfig
    page: Page | None

build

build(
    config_path: str | PathLike[str],
    repo_path: str,
    build_fn: str | None,
    *,
    site_dir: str | None = None,
    clone_depth: int = 100,
    **kwargs: Any
)

Build a MkNodes-based website.

Parameters:

Name	Type	Description	Default
config_path	str | PathLike[str]	Path to the MkDocs config file	required
repo_path	str	Repository path/URL to build docs for	required
build_fn	str | None	Fully qualified name of build function to use	required
site_dir	str | None	Output directory for built site	None
clone_depth	int	Number of commits to fetch for Git repos	100
kwargs	Any	Additional config overrides passed to MkDocs	{}

Source code in mkdocs_mknodes/commands/build_page.py

def build(
    config_path: str | os.PathLike[str],
    repo_path: str,
    build_fn: str | None,
    *,
    site_dir: str | None = None,
    clone_depth: int = 100,
    **kwargs: Any,
):
    """Build a MkNodes-based website.

    Args:
        config_path: Path to the MkDocs config file
        repo_path: Repository path/URL to build docs for
        build_fn: Fully qualified name of build function to use
        site_dir: Output directory for built site
        clone_depth: Number of commits to fetch for Git repos
        kwargs: Additional config overrides passed to MkDocs
    """
    cfg_builder = configbuilder.ConfigBuilder(
        repo_path=repo_path, build_fn=build_fn, clone_depth=clone_depth
    )
    cfg_builder.add_config_file(config_path)
    config = cfg_builder.build_mkdocs_config(site_dir=site_dir, **kwargs)
    with logfire.span("plugins callback: on_startup", config=config):
        config.plugins.on_startup(command="build", dirty=False)
    _build(config)
    with logfire.span("plugins callback: shutdown", config=config):
        config.plugins.on_shutdown()

get_build_timestamp

get_build_timestamp(*, pages: Collection[Page] | None = None) -> int

Returns the number of seconds since the epoch for the latest updated page.

In reality this is just today's date because that's how pages' update time is populated.

Parameters:

Name	Type	Description	Default
pages	Collection[Page] | None	Optional collection of pages to determine timestamp from	None

Returns:

Type	Description
int	Unix timestamp as integer

Source code in mkdocs_mknodes/commands/build_page.py

def get_build_timestamp(*, pages: Collection[Page] | None = None) -> int:
    """Returns the number of seconds since the epoch for the latest updated page.

    In reality this is just today's date because that's how pages' update time
    is populated.

    Args:
        pages: Optional collection of pages to determine timestamp from

    Returns:
        Unix timestamp as integer
    """
    if pages:
        # Lexicographic comparison is OK for ISO date.
        date_string = max(p.update_date for p in pages)
        dt = datetime.fromisoformat(date_string).replace(tzinfo=UTC)
    else:
        dt = utils.get_build_datetime()
    return int(dt.timestamp())

get_context

get_context(
    nav: Navigation,
    files: Sequence[File] | Files,
    config: MkNodesConfig,
    page: Page | None = None,
    base_url: str = "",
) -> TemplateContext

Return the template context for a given page or template.

Source code in mkdocs_mknodes/commands/build_page.py

def get_context(
    nav: Navigation,
    files: Sequence[File] | Files,
    config: MkNodesConfig,
    page: Page | None = None,
    base_url: str = "",
) -> TemplateContext:
    """Return the template context for a given page or template."""
    if page is not None:
        base_url = mkdocs_utils.get_relative_url(".", page.url)

    extra_javascript = [
        mkdocs_utils.normalize_url(str(script), page, base_url)
        for script in config.extra_javascript
    ]
    extra_css = [mkdocs_utils.normalize_url(path, page, base_url) for path in config.extra_css]

    if isinstance(files, Files):
        files = files.documentation_pages()

    import mkdocs

    import mkdocs_mknodes

    return TemplateContext(
        nav=nav,
        pages=files,
        base_url=base_url,
        extra_css=extra_css,
        extra_javascript=extra_javascript,
        mknodes_version=mkdocs_mknodes.__version__,
        mkdocs_version=mkdocs.__version__,
        build_date_utc=utils.get_build_datetime(),
        config=config,
        page=page,
    )