MkNodes plugin for MkDocs

Overview

MkDocs-MkNodes integrates the MkNodes toolkit into MkDocs.

MkNodes is a library to create complex documentation websites. It includes a powerful jinja environment to assist in writing Markdown text as well as a a large set of so-called MkNodes, which can be used to create re-usable node trees describing a complete website. That node tree covers the whole site navigation, down to single Markdown elements, allowing the creator anytime to switch between programatically creating documentation and writing Markdown "by hand".

This plugin acts as a bridge: It embeds MkNodes into the MkDocs event hook system and converts the MkNodes tree to a MkDocs-powered website.

Info

Still sounds confusing? The best way to learn how everything works is to start with the MkNodes documentation. This website will focus on the integration with MkDocs.

In addition, all pages on this website include an Admonition box at the bottom, which also includes the code which generated the page. That might be a helpful resource to understand how MkNodes can be used.

Hello, world

A minimum example for a MkNodes website:

def build(project: Project):
    index_page = project.root.get_index_page(hide="toc")
    index += mk.MkAdmonition("Hello world!")

Additional features: - Rewrite MkDocs-Material templates on-the-fly to add additional functionality - An upgraded MkDocs CLI with nicer output and additional functionality

Page info

Code for this page

@router.route_page("MkNodes plugin for MkDocs", hide="toc", is_homepage=True)
def _(page: mk.MkPage):
    page += mk.MkTemplate("index.jinja")

Resources

Resources(css=[],
          markdown_extensions={'attr_list': {},
                               'md_in_html': {},
                               'pymdownx.emoji': {'emoji_generator': <function to_svg at 0x7f170970c540>,
                                                  'emoji_index': <function twemoji at 0x7f170970c400>},
                               'pymdownx.magiclink': {'repo': 'mkdocs_mknodes',
                                                      'repo_url_shorthand': True,
                                                      'user': 'phil65'}},
          plugins=[],
          js=[],
          assets=[],
          packages=[])

Metadata

created:
  source_filename: /home/runner/work/mkdocs-mknodes/mkdocs-mknodes/mkdocs_mknodes/manual/root.py
  source_function: Build.on_root
  source_line_no: 19
hide:
- toc
template: SUMMARY.html
title: MkNodes plugin for MkDocs