Skip to content

It is possible to construct a basic documentation websites for without much effort. We will construct a small website for MkDocs.

The following config...

INHERIT: mkdocs_shared.yml

site_name: MkDocs
site_description: A MkDocs page created by MkNodes
repo_url: "https://github.com/mkdocs/mkdocs/"
site_url: https://phil65.github.io/mknodes/mkdocs/
repo_path: https://github.com/mkdocs/mkdocs.git
clone_depth: 100
build_fn: mkdocs_mknodes:parse
docs_dir: ../docs
build_kwargs:
    pages:
        - title: Home
          type: MkText
          text: "``` py title='__main__.create_github_index_md' linenums="86" hl_lines="3"
def create_github_index_md() -> mk.MkPage:
    page = mk.MkPage("Github index")
    page += mk.MkCode.for_object(create_github_index_md)
    page += mk.MkHeader("MkNodes", level=1)
    page += mk.MkHeader("Don't write docs. Code them.", level=4)
    page += mk.MkShields()
    page += mk.MkLink(DOC_URL, "Read the completely coded documentation!")
    page += mk.MkInstallGuide(header="How to install")
    page += mk.MkHeader("All the nodes!")
    page += mk.MkClassDiagram(mk.MkNode, mode="subclasses", direction="LR")
    return page

MkNodes (Mkdocs Plugin)

Don't write docs. Code them.

PyPI License Package status Daily downloads Weekly downloads Monthly downloads Distribution format Wheel availability Python version Implementation Releases Github Contributors Github Discussions Github Forks Github Issues Github Issues Github Watchers Github Stars Github Repository size Github last commit Github release date Github language count Github commits this week Github commits this month Github commits this year Package status Code style: black PyUp

Read the completely coded documentation!

How to install

pip

The latest released version is available at the Python package index.

pip install mkdocs-mknodes
" is_index: true - Usage: - type: MkTemplate title: Getting started template: https://raw.githubusercontent.com/mkdocs/mkdocs/master/docs/getting-started.md - type: MkTemplate title: Configuration template: https://raw.githubusercontent.com/mkdocs/mkdocs/master/docs/user-guide/configuration.md - type: MkTemplate title: Deploying your docs template: https://raw.githubusercontent.com/mkdocs/mkdocs/master/docs/user-guide/deploying-your-docs.md - type: MkTemplate title: Installation template: https://raw.githubusercontent.com/mkdocs/mkdocs/master/docs/user-guide/installation.md - title: API type: MkDoc section_name: "API" recursive: true - title: CLI type: MkCliDoc show_subcommands: true condition: "typer" - Development: - title: Changelog type: MkChangelog - title: Code of Conduct type: MkCodeOfConduct - title: Contributing type: MkCommitConventions - title: Pull requests type: MkPullRequestGuidelines - title: Dependencies type: MkPage items: - title: Dependency table type: MkDependencyTable - title: Dependency tree type: MkPipDepTree direction: LR - title: Dependencies type: MkDependencyTable - title: MkDocs Plugins condition: 'True' type: MkPluginFlow - title: License type: MkLicense

plugins: - mknodes

Combined with this CLI call...

``` {.terminal }
mknodes build

Will create this website:

https://phil65.github.io/mkdocs-mknodes/mkdocs

Page info
Code for this page
mkdocs_mknodes.manual.use_cases_section._
14
15
16
17
18
19
@nav.route.page("Creating a website via config", hide="toc")
def _(page: mk.MkPage):
    """Create the "Creating a sample website" MkPage."""
    config = pathlib.Path("configs/mkdocs_mkdocs.yml").read_text()
    variables = dict(config=config)
    page += mk.MkTemplate("use_case_default_website.jinja", variables=variables)
Resources 
Resources(css=[],
          markdown_extensions={'attr_list': {},
                               'md_in_html': {},
                               'pymdownx.emoji': {'emoji_generator': <function to_svg at 0x7f6e52627c40>,
                                                  'emoji_index': <function twemoji at 0x7f6e52627b00>},
                               'pymdownx.highlight': {'anchor_linenums': True,
                                                      'line_spans': '__span',
                                                      'pygments_lang_class': True},
                               'pymdownx.magiclink': {'repo': 'mkdocs_mknodes',
                                                      'repo_url_shorthand': True,
                                                      'user': 'phil65'},
                               'pymdownx.superfences': {}},
          plugins=[],
          js=[],
          assets=[],
          packages=[])
Metadata 
created:
  source_filename: /home/runner/work/mkdocs-mknodes/mkdocs-mknodes/mkdocs_mknodes/manual/use_cases_section.py
  source_function: null
  source_line_no: 14
hide:
- toc
template: SUMMARY.html
title: Creating a website via config