Use cases

There are a lot of different ways MkNodes can be used to generate websites. This section will highlight some of them.

MkNodes can be used in many different ways

  • Create complete websites

    • MkNodes can be used to create a whole website (like it is done with this page) The most useful setup probably would be to put the whole navigation into code, create MkCodes via code when the complexity favours that, and otherwise just use MkPage.from_file or MkTemplate to embed static pages. That way you can get the best of both worlds, the simplicity from writing markdown files combined with the possibilities of using python for repititive work or more complex / dynamic tasks.

  • Load existing markdown content and extend it.

    • By using [MkNav.parse.folder][mknodes.navs.navparser.NavParser.folder] / [MkNav.parse.file][mknodes.navs.navparser.NavParser.file] as well as MkPage.from_file, the existing Markdown pages can become part of our tree (which we can then extend programatically). You dont need to start from ground up if you have an existing documentation.

  • Create a subsection with MkNodes and reference it from your "static" page.

    • You can also create an MkNodes tree and reference that tree from your nav: section in mkdocs.yml.

  • Create single static pages / blocks for your page You can also just use MkNodes to create some Nodes, stringify them and include the markdown in your static pages. It can also be used to create your GitHub / PyPi overview page.

  • Using Markdown-Exec or similar inline execution plugins You can also embed MkNodes code directly by using various plug-ins (personal recommendation: Markdown-Exec) For most cases the built-in jinja2 environment should include enough to display complex Markdown in an easy way.

  • Create "multi-pages" MkNodes can even "merge" multiple websites into one. In its core, MkNodes is nothing more than one large tree ranging from the start page down to individual markdown elements. It is very easy to make a complete website tree the subtree of another Parent-tree.

  • Create a "structure template" for multiple sites MkNodes separates content and appearance for writing documentation. Website templates can be written in a way that they work for multiple websites without any manual adaption.

Page info
Code for this section
mkdocs_mknodes.manual.use_cases_section._
 9
10
11
@nav.route.page(is_index=True, hide="toc")
def _(page: mk.MkPage):
    page += mk.MkTemplate("use_cases_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/use_cases_section.py
  source_function: null
  source_line_no: 9
hide:
- toc
template: SUMMARY.html
title: Use cases