plugin ¤

MkDocs plugin that generates a Markdown file at the end of the build.

Classes:

MkdocsLLMsTxtPlugin –

The MkDocs plugin to generate an llms.txt file.

MkdocsLLMsTxtPlugin ¤

MkdocsLLMsTxtPlugin()

Bases: BasePlugin[PluginConfig]

The MkDocs plugin to generate an llms.txt file.

This plugin defines the following event hooks:

on_page_content
on_post_build

Check the Developing Plugins page of mkdocs for more information about its plugin system.

Methods:

on_config –

Save the global MkDocs configuration.
on_files –

Expand inputs for generated files.
on_page_content –

Record pages contents.
on_post_build –

Combine all recorded pages contents and convert it to a Markdown file with BeautifulSoup and Markdownify.

Source code in src/mkdocs_llmstxt/plugin.py

def __init__(self) -> None:  # noqa: D107
    self.html_pages: dict[str, dict[str, str]] = defaultdict(dict)

on_config ¤

on_config(config: MkDocsConfig) -> MkDocsConfig | None

Save the global MkDocs configuration.

Hook for the on_config event. In this hook, we save the global MkDocs configuration into an instance variable, to re-use it later.

Parameters:

config (MkDocsConfig) –

The MkDocs config object.

Returns:

MkDocsConfig | None –

The same, untouched config.

Source code in src/mkdocs_llmstxt/plugin.py

def on_config(self, config: MkDocsConfig) -> MkDocsConfig | None:
    """Save the global MkDocs configuration.

    Hook for the [`on_config` event](https://www.mkdocs.org/user-guide/plugins/#on_config).
    In this hook, we save the global MkDocs configuration into an instance variable,
    to re-use it later.

    Arguments:
        config: The MkDocs config object.

    Returns:
        The same, untouched config.
    """
    self.mkdocs_config = config
    return config

on_files ¤

on_files(
    files: Files, *, config: MkDocsConfig
) -> Files | None

Expand inputs for generated files.

Hook for the on_files event. In this hook we expand inputs for generated file (glob patterns using *).

Parameters:

files (Files) –

The collection of MkDocs files.
config (MkDocsConfig) –

The MkDocs configuration.

Returns:

Files | None –

Modified collection or none.

Source code in src/mkdocs_llmstxt/plugin.py

def on_files(self, files: Files, *, config: MkDocsConfig) -> Files | None:  # noqa: ARG002
    """Expand inputs for generated files.

    Hook for the [`on_files` event](https://www.mkdocs.org/user-guide/plugins/#on_files).
    In this hook we expand inputs for generated file (glob patterns using `*`).

    Parameters:
        files: The collection of MkDocs files.
        config: The MkDocs configuration.

    Returns:
        Modified collection or none.
    """
    for file in self.config.files:
        file["inputs"] = self._expand_inputs(file["inputs"], page_uris=list(files.src_uris.keys()))
    return files

on_page_content ¤

on_page_content(
    html: str, *, page: Page, **kwargs: Any
) -> str | None

Record pages contents.

Hook for the on_page_content event. In this hook we simply record the HTML of the pages into a dictionary whose keys are the pages' URIs.

Parameters:

html (str) –

The rendered HTML.
page (Page) –

The page object.

Source code in src/mkdocs_llmstxt/plugin.py

def on_page_content(self, html: str, *, page: Page, **kwargs: Any) -> str | None:  # noqa: ARG002
    """Record pages contents.

    Hook for the [`on_page_content` event](https://www.mkdocs.org/user-guide/plugins/#on_page_content).
    In this hook we simply record the HTML of the pages into a dictionary whose keys are the pages' URIs.

    Parameters:
        html: The rendered HTML.
        page: The page object.
    """
    for file in self.config.files:
        if page.file.src_uri in file["inputs"]:
            logger.debug(f"Adding page {page.file.src_uri} to page {file['output']}")
            self.html_pages[file["output"]][page.file.src_uri] = html
    return html

on_post_build ¤

on_post_build(config: MkDocsConfig, **kwargs: Any) -> None

Combine all recorded pages contents and convert it to a Markdown file with BeautifulSoup and Markdownify.

Hook for the on_post_build event. In this hook we concatenate all previously recorded HTML, and convert it to Markdown using Markdownify.

Parameters:

config (MkDocsConfig) –

MkDocs configuration.

Source code in src/mkdocs_llmstxt/plugin.py

def on_post_build(self, config: MkDocsConfig, **kwargs: Any) -> None:  # noqa: ARG002
    """Combine all recorded pages contents and convert it to a Markdown file with BeautifulSoup and Markdownify.

    Hook for the [`on_post_build` event](https://www.mkdocs.org/user-guide/plugins/#on_post_build).
    In this hook we concatenate all previously recorded HTML, and convert it to Markdown using Markdownify.

    Parameters:
        config: MkDocs configuration.
    """

    def language_callback(tag: Tag) -> str:
        for css_class in chain(tag.get("class", ()), tag.parent.get("class", ())):
            if css_class.startswith("language-"):
                return css_class[9:]
        return ""

    converter = MarkdownConverter(
        bullets="-",
        code_language_callback=language_callback,
        escape_underscores=False,
        heading_style=ATX,
    )

    for file in self.config.files:
        try:
            html = "\n\n".join(self.html_pages[file["output"]][input_page] for input_page in file["inputs"])
        except KeyError as error:
            raise PluginError(str(error)) from error

        soup = Soup(html, "html.parser")
        if self.config.autoclean:
            autoclean(soup)
        if self.config.preprocess:
            preprocess(soup, self.config.preprocess, file["output"])

        output_file = Path(config.site_dir).joinpath(file["output"])
        output_file.parent.mkdir(parents=True, exist_ok=True)
        markdown = mdformat.text(converter.convert_soup(soup), options={"wrap": "no"})
        output_file.write_text(markdown, encoding="utf8")

        logger.info(f"Generated file /{file['output']}")

plugin ¤

MkdocsLLMsTxtPlugin ¤

on_config ¤

on_files ¤

on_page_content ¤

on_post_build ¤

Feedback