Skip to content

Show source on GitHub

Node to include the text of other Markdown files / MkNodes.

Description

This node only keeps a reference to given target and resolves it when needed. Target can either be an URL or any other fsspec protocol path to a markdown file, a file system path to a markdown file, or another MkNode.

Example: Include from URL

Jinja

{{ "https://raw.githubusercontent.com/phil65/mknodes/main/README.md" | MkInclude }}

Python

MkInclude('https://raw.githubusercontent.com/phil65/mknodes/main/README.md')

MkNodes

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 PyUp

Read the completely coded documentation!

Programatically create web pages

__main__.create_github_index_md
86
87
88
89
90
91
92
93
94
95
96
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

Create a website tree

@nav.route.page("Changelog", icon="format-list-group")
def _(page: mk.MkPage):
    page += mk.MkChangelog()

Powerful templating

{{ "Inlined text" | MkAdmonition(inline="left") }}

How to install

pip

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

pip install mknodes

# MkNodes

#### Don't write docs. Code them.

[![PyPI License](https://img.shields.io/pypi/l/mknodes.svg)](https://pypi.org/project/mknodes/)
[![Package status](https://img.shields.io/pypi/status/mknodes.svg)](https://pypi.org/project/mknodes/)
[![Daily downloads](https://img.shields.io/pypi/dd/mknodes.svg)](https://pypi.org/project/mknodes/)
[![Weekly downloads](https://img.shields.io/pypi/dw/mknodes.svg)](https://pypi.org/project/mknodes/)
[![Monthly downloads](https://img.shields.io/pypi/dm/mknodes.svg)](https://pypi.org/project/mknodes/)
[![Distribution format](https://img.shields.io/pypi/format/mknodes.svg)](https://pypi.org/project/mknodes/)
[![Wheel availability](https://img.shields.io/pypi/wheel/mknodes.svg)](https://pypi.org/project/mknodes/)
[![Python version](https://img.shields.io/pypi/pyversions/mknodes.svg)](https://pypi.org/project/mknodes/)
[![Implementation](https://img.shields.io/pypi/implementation/mknodes.svg)](https://pypi.org/project/mknodes/)
[![Releases](https://img.shields.io/github/downloads/phil65/mknodes/total.svg)](https://github.com/phil65/mknodes/releases)
[![Github Contributors](https://img.shields.io/github/contributors/phil65/mknodes)](https://github.com/phil65/mknodes/graphs/contributors)
[![Github Discussions](https://img.shields.io/github/discussions/phil65/mknodes)](https://github.com/phil65/mknodes/discussions)
[![Github Forks](https://img.shields.io/github/forks/phil65/mknodes)](https://github.com/phil65/mknodes/forks)
[![Github Issues](https://img.shields.io/github/issues/phil65/mknodes)](https://github.com/phil65/mknodes/issues)
[![Github Issues](https://img.shields.io/github/issues-pr/phil65/mknodes)](https://github.com/phil65/mknodes/pulls)
[![Github Watchers](https://img.shields.io/github/watchers/phil65/mknodes)](https://github.com/phil65/mknodes/watchers)
[![Github Stars](https://img.shields.io/github/stars/phil65/mknodes)](https://github.com/phil65/mknodes/stars)
[![Github Repository size](https://img.shields.io/github/repo-size/phil65/mknodes)](https://github.com/phil65/mknodes)
[![Github last commit](https://img.shields.io/github/last-commit/phil65/mknodes)](https://github.com/phil65/mknodes/commits)
[![Github release date](https://img.shields.io/github/release-date/phil65/mknodes)](https://github.com/phil65/mknodes/releases)
[![Github language count](https://img.shields.io/github/languages/count/phil65/mknodes)](https://github.com/phil65/mknodes)
[![Github commits this week](https://img.shields.io/github/commit-activity/w/phil65/mknodes)](https://github.com/phil65/mknodes)
[![Github commits this month](https://img.shields.io/github/commit-activity/m/phil65/mknodes)](https://github.com/phil65/mknodes)
[![Github commits this year](https://img.shields.io/github/commit-activity/y/phil65/mknodes)](https://github.com/phil65/mknodes)
[![Package status](https://codecov.io/gh/phil65/mknodes/branch/main/graph/badge.svg)](https://codecov.io/gh/phil65/mknodes/)
[![PyUp](https://pyup.io/repos/github/phil65/mknodes/shield.svg)](https://pyup.io/repos/github/phil65/mknodes/)

[Read the completely coded documentation!](https://phil65.github.io/mknodes/)



## Programatically create web pages

``` 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

Create a website tree

@nav.route.page("Changelog", icon="format-list-group")
def _(page: mk.MkPage):
    page += mk.MkChangelog()

Powerful templating

{{ "Inlined text" | MkAdmonition(inline="left") }}

How to install

pip

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

pip install mknodes

```

<h1 id="mknodes">MkNodes</h1>
<h4 id="dont-write-docs-code-them">Don't write docs. Code them.</h4>
<p><a href="https://pypi.org/project/mknodes/"><img alt="PyPI License" src="https://img.shields.io/pypi/l/mknodes.svg"></a>
<a href="https://pypi.org/project/mknodes/"><img alt="Package status" src="https://img.shields.io/pypi/status/mknodes.svg"></a>
<a href="https://pypi.org/project/mknodes/"><img alt="Daily downloads" src="https://img.shields.io/pypi/dd/mknodes.svg"></a>
<a href="https://pypi.org/project/mknodes/"><img alt="Weekly downloads" src="https://img.shields.io/pypi/dw/mknodes.svg"></a>
<a href="https://pypi.org/project/mknodes/"><img alt="Monthly downloads" src="https://img.shields.io/pypi/dm/mknodes.svg"></a>
<a href="https://pypi.org/project/mknodes/"><img alt="Distribution format" src="https://img.shields.io/pypi/format/mknodes.svg"></a>
<a href="https://pypi.org/project/mknodes/"><img alt="Wheel availability" src="https://img.shields.io/pypi/wheel/mknodes.svg"></a>
<a href="https://pypi.org/project/mknodes/"><img alt="Python version" src="https://img.shields.io/pypi/pyversions/mknodes.svg"></a>
<a href="https://pypi.org/project/mknodes/"><img alt="Implementation" src="https://img.shields.io/pypi/implementation/mknodes.svg"></a>
<a href="https://github.com/phil65/mknodes/releases"><img alt="Releases" src="https://img.shields.io/github/downloads/phil65/mknodes/total.svg"></a>
<a href="https://github.com/phil65/mknodes/graphs/contributors"><img alt="Github Contributors" src="https://img.shields.io/github/contributors/phil65/mknodes"></a>
<a href="https://github.com/phil65/mknodes/discussions"><img alt="Github Discussions" src="https://img.shields.io/github/discussions/phil65/mknodes"></a>
<a href="https://github.com/phil65/mknodes/forks"><img alt="Github Forks" src="https://img.shields.io/github/forks/phil65/mknodes"></a>
<a href="https://github.com/phil65/mknodes/issues"><img alt="Github Issues" src="https://img.shields.io/github/issues/phil65/mknodes"></a>
<a href="https://github.com/phil65/mknodes/pulls"><img alt="Github Issues" src="https://img.shields.io/github/issues-pr/phil65/mknodes"></a>
<a href="https://github.com/phil65/mknodes/watchers"><img alt="Github Watchers" src="https://img.shields.io/github/watchers/phil65/mknodes"></a>
<a href="https://github.com/phil65/mknodes/stars"><img alt="Github Stars" src="https://img.shields.io/github/stars/phil65/mknodes"></a>
<a href="https://github.com/phil65/mknodes"><img alt="Github Repository size" src="https://img.shields.io/github/repo-size/phil65/mknodes"></a>
<a href="https://github.com/phil65/mknodes/commits"><img alt="Github last commit" src="https://img.shields.io/github/last-commit/phil65/mknodes"></a>
<a href="https://github.com/phil65/mknodes/releases"><img alt="Github release date" src="https://img.shields.io/github/release-date/phil65/mknodes"></a>
<a href="https://github.com/phil65/mknodes"><img alt="Github language count" src="https://img.shields.io/github/languages/count/phil65/mknodes"></a>
<a href="https://github.com/phil65/mknodes"><img alt="Github commits this week" src="https://img.shields.io/github/commit-activity/w/phil65/mknodes"></a>
<a href="https://github.com/phil65/mknodes"><img alt="Github commits this month" src="https://img.shields.io/github/commit-activity/m/phil65/mknodes"></a>
<a href="https://github.com/phil65/mknodes"><img alt="Github commits this year" src="https://img.shields.io/github/commit-activity/y/phil65/mknodes"></a>
<a href="https://codecov.io/gh/phil65/mknodes/"><img alt="Package status" src="https://codecov.io/gh/phil65/mknodes/branch/main/graph/badge.svg"></a>
<a href="https://pyup.io/repos/github/phil65/mknodes/"><img alt="PyUp" src="https://pyup.io/repos/github/phil65/mknodes/shield.svg"></a></p>
<p><a href="https://phil65.github.io/mknodes/">Read the completely coded documentation!</a></p>
<h2 id="programatically-create-web-pages">Programatically create web pages</h2>
<div class="highlight"><table class="highlighttable"><tr><th colspan="2" class="filename"><span class="filename">__main__.create_github_index_md</span></th></tr><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">86</span>
<span class="normal">87</span>
<span class="normal">88</span>
<span class="normal">89</span>
<span class="normal">90</span>
<span class="normal">91</span>
<span class="normal">92</span>
<span class="normal">93</span>
<span class="normal">94</span>
<span class="normal">95</span>
<span class="normal">96</span></pre></div></td><td class="code"><div><pre><span></span><code><span class="k">def</span><span class="w"> </span><span class="nf">create_github_index_md</span><span class="p">()</span> <span class="o">-&gt;</span> <span class="n">mk</span><span class="o">.</span><span class="n">MkPage</span><span class="p">:</span>
    <span class="n">page</span> <span class="o">=</span> <span class="n">mk</span><span class="o">.</span><span class="n">MkPage</span><span class="p">(</span><span class="s2">&quot;Github index&quot;</span><span class="p">)</span>
<span class="hll">    <span class="n">page</span> <span class="o">+=</span> <span class="n">mk</span><span class="o">.</span><span class="n">MkCode</span><span class="o">.</span><span class="n">for_object</span><span class="p">(</span><span class="n">create_github_index_md</span><span class="p">)</span>
</span>    <span class="n">page</span> <span class="o">+=</span> <span class="n">mk</span><span class="o">.</span><span class="n">MkHeader</span><span class="p">(</span><span class="s2">&quot;MkNodes&quot;</span><span class="p">,</span> <span class="n">level</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>
    <span class="n">page</span> <span class="o">+=</span> <span class="n">mk</span><span class="o">.</span><span class="n">MkHeader</span><span class="p">(</span><span class="s2">&quot;Don&#39;t write docs. Code them.&quot;</span><span class="p">,</span> <span class="n">level</span><span class="o">=</span><span class="mi">4</span><span class="p">)</span>
    <span class="n">page</span> <span class="o">+=</span> <span class="n">mk</span><span class="o">.</span><span class="n">MkShields</span><span class="p">()</span>
    <span class="n">page</span> <span class="o">+=</span> <span class="n">mk</span><span class="o">.</span><span class="n">MkLink</span><span class="p">(</span><span class="n">DOC_URL</span><span class="p">,</span> <span class="s2">&quot;Read the completely coded documentation!&quot;</span><span class="p">)</span>
    <span class="n">page</span> <span class="o">+=</span> <span class="n">mk</span><span class="o">.</span><span class="n">MkInstallGuide</span><span class="p">(</span><span class="n">header</span><span class="o">=</span><span class="s2">&quot;How to install&quot;</span><span class="p">)</span>
    <span class="n">page</span> <span class="o">+=</span> <span class="n">mk</span><span class="o">.</span><span class="n">MkHeader</span><span class="p">(</span><span class="s2">&quot;All the nodes!&quot;</span><span class="p">)</span>
    <span class="n">page</span> <span class="o">+=</span> <span class="n">mk</span><span class="o">.</span><span class="n">MkClassDiagram</span><span class="p">(</span><span class="n">mk</span><span class="o">.</span><span class="n">MkNode</span><span class="p">,</span> <span class="n">mode</span><span class="o">=</span><span class="s2">&quot;subclasses&quot;</span><span class="p">,</span> <span class="n">direction</span><span class="o">=</span><span class="s2">&quot;LR&quot;</span><span class="p">)</span>
    <span class="k">return</span> <span class="n">page</span>
</code></pre></div></td></tr></table></div>
<h2 id="create-a-website-tree">Create a website tree</h2>
<div class="highlight"><pre><span></span><code><span class="nd">@nav</span><span class="o">.</span><span class="n">route</span><span class="o">.</span><span class="n">page</span><span class="p">(</span><span class="s2">&quot;Changelog&quot;</span><span class="p">,</span> <span class="n">icon</span><span class="o">=</span><span class="s2">&quot;format-list-group&quot;</span><span class="p">)</span>
<span class="k">def</span><span class="w"> </span><span class="nf">_</span><span class="p">(</span><span class="n">page</span><span class="p">:</span> <span class="n">mk</span><span class="o">.</span><span class="n">MkPage</span><span class="p">):</span>
    <span class="n">page</span> <span class="o">+=</span> <span class="n">mk</span><span class="o">.</span><span class="n">MkChangelog</span><span class="p">()</span>
</code></pre></div>
<h2 id="powerful-templating">Powerful templating</h2>
<div class="highlight"><pre><span></span><code><span class="cp">{{</span> <span class="s2">&quot;Inlined text&quot;</span> <span class="o">|</span> <span class="nf">MkAdmonition</span><span class="o">(</span><span class="nv">inline</span><span class="o">=</span><span class="s2">&quot;left&quot;</span><span class="o">)</span> <span class="cp">}}</span>
</code></pre></div>
<h2 id="how-to-install">How to install</h2>
<h3 id="pip">pip</h3>
<p>The latest released version is available at the <a href="https://pypi.org/project/mknodes">Python package index</a>.</p>
<div class="highlight"><pre><span></span><code><span class="n">pip</span> <span class="n">install</span> <span class="n">mknodes</span>
</code></pre></div>

Bases: MkText

__init__ 

__init__(target: str | PathLike[str] | MkText, **kwargs: Any)

Parameters:

Name Type Description Default
target str | PathLike[str] | MkText

target to include

 required
kwargs Any

Keyword arguments passed to parent

 {}
Name Children Inherits
MkText
mknodes.basenodes.mktext
Class for any Markup text.		 
graph TD
  94875592692784["mkinclude.MkInclude"]
  94875593471104["mktext.MkText"]
  94875594508576["mknode.MkNode"]
  94875592833088["node.Node"]
  140216716431552["builtins.object"]
  94875593471104 --> 94875592692784
  94875594508576 --> 94875593471104
  94875592833088 --> 94875594508576
  140216716431552 --> 94875592833088
/home/runner/work/mknodes/mknodes/mknodes/templatenodes/mkinclude/metadata.toml
[metadata]
name = "MkInclude"
icon = "octicon:file-symlink-file-24"

[examples.url]
title = "Include from URL"
jinja = """
{{ "https://raw.githubusercontent.com/phil65/mknodes/main/README.md" | MkInclude }}
"""

[output.markdown]
template = """
{{ node.text }}
"""
mknodes.templatenodes.mkinclude.MkInclude
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
class MkInclude(mktext.MkText):
    """Node to include the text of other Markdown files / MkNodes.

    This node only keeps a reference to given target and resolves it when needed.
    Target can either be an URL or any other fsspec protocol path to a markdown file,
    a file system path to a markdown file, or another MkNode.
    """

    ICON = "octicons/file-symlink-file-24"

    def __init__(self, target: str | os.PathLike[str] | mktext.MkText, **kwargs: Any):
        """Constructor.

        Args:
            target: target to include
            kwargs: Keyword arguments passed to parent
        """
        super().__init__(**kwargs)
        self.target = target

    @property
    def text(self) -> str:
        match self.target:
            case os.PathLike() | str():
                return pathhelpers.load_file_cached(os.fspath(self.target))
            case mktext.MkText():
                return str(self.target)
            case _:
                raise TypeError(self.target)