The build process

This section provides an overview about the sequence of operations applied by MkNodes when running the full build process.

Step 1

Set up working directory

The target repository gets cloned in case it is a remote one. If no explicit build directory for the later steps is provided by the config, a temporary build folder is created.

Step 2

Create theme

Initialize the theme object based on which theme is chosen in the MkDocs config / CLI."

Step 3

Create project

The theme, the build function, the Git repository (in most cases the current working dir) and a URL linker are consolidated into one project instance.

Step 4

Create context

All available information from following sources are extracted in order to build a context object:

  • metadata.Distribution
  • PyProject File
  • MkDocs Config file
  • Other config files in the cwd
  • Git repository info
  • Information from GitHub

Step 5

Create environment

Create the jinja2 environment and populate it with all the data provided by the context object.

Step 6

Build MkNodes tree

Now, since all needed information is available, the user-coded build function is executed and the node tree is generated (alternatively, a website template like MkDefaultWebSite can be used)

Step 7

Initialize backends

The build backends are initialized. Right now there is one simple Markdown backend and one MkDocs build backend.

Step 8

Collect build artifacts

The BuildCollector aggregates and preprocesses all the data from the node tree (navigation hierarchy, Markdown output, required resources, templates, ...) and passes the prepared data to the build backends.

Step 9

Convert templates

If required, convert the template pages which were populated with Markdown by the user to HTML using the Python-Markdown parser.

Step 10

Write to disk using backends

  • The Markdown backend creates plain Markdown pages and index files on disk. SUMMARY.md files are generated to describe the hierarchy.
  • The MkDocs backend updates the Mkdocs configuration with information from the node tree and adds the required CSS / JS / etc. resources as well as the required Markdown extensions. All Markdown files and templates are written to the location where MkDocs expects them to be and a suiting nav section is written to config.

Step 11

Set edit URIs

Set the page edit URIs to the recorded caller location (gathered from FrameInfo objects).

Step 12

Render jinja2 templates

The pages get rendered by jinja2 and a custom LinkReplacer is doing a bit of work.

Step 13

Finished!

After letting MkDocs do its work, the website is ready.

Step 14

Clean up

Remove possible temporarily created HTML templates from disk.

Page info
Code for this page
mkdocs_mknodes.manual.get_started_section._
41
42
43
44
@router.route_page("The build process", hide="toc")
def _(page: mk.MkPage):
    page += INTRO
    page += mk.MkTimeline(paths.RESOURCES / "timeline_data.toml")
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=[Asset('scrollreveal_cab73ad.js'),
                  Asset('timeline_577131c.js'),
                  Asset('timeline_63b66a4.css')],
          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: Get started/the_build_process.html
title: The build process