dinject 1.3.0

Executes and injects code in Markdown documents

🥪 Dinject

Dinject is a Python package and CLI tool for executing code blocks in Markdown documents then injecting the results.

• Example
• Installation
• Injection attributes
• Command line usage
• Python usage
  • Injection
  • Custom parsers
• Languages
  • Bash
  • Python
  • Text
• Project
  • Contributing
  • Licence
  • Author
  • Acknowledgements

Example

This example creates a Markdown document with a code block and an injection site, then performs the injection:

from dinject import inject
from io import StringIO

markdown = """This is a demonstration of Dinject.

```bash
python --version
```

<!--dinject-->
"""

writer = StringIO()

inject(markdown, writer)

print(writer.getvalue())

In the output, the injection site has been replaced by the execution result:

This is a demonstration of Dinject.

```bash
python --version
```

<!--dinject as=markdown fence=backticks host=shell range=start-->

```text
Python 3.10.0
```

<!--dinject range=end-->

Fun fact! The documentation you're reading right now was generated by Edition which uses Dinject under the hood. The example output above was generated and injected by Dinject executing the code block preceding it.

Installation

Dinject requires Python 3.8 or later.

Install Dinject via pip:

pip install dinject

Injection attributes

The most basic injection site is simply:

<!--dinject-->

To fence the injection with tildes instead of backticks (for example, if you're embedding Markdown within Markdown) then set the fence attribute:

<!--dinject fence=tildes-->

To inject the result as HTML instead of Markdown (for example, to render the colours and other styles in the command's output) then set the as attribute:

<!--dinject as=html-->

To have the code executed in a pseudo terminal rather than a sub shell (for example, if the command emits formatted output only in non-interactive shells) then set the host attribute:

<!--dinject host=terminal-->

Command line usage

Run dinject and pass paths to Markdown documents to update:

dinject README.md docs/example.md

Python usage

Injection

The inject() function takes:

• A reader, which can be a text stream or a string.
• A text stream writer.
• An optional parser.

Custom parsers

A customised Parser can be passed into inject() to tweak some runtime configuration.

The keyword describes the injection site keyword. This is "dinject" by default. If you wanted to injection sites to be marked up by, say, <!--foo--> then set the keyword to "foo".

Languages

Bash

Dinject executes Bash code blocks via /usr/bin/env bash -c CODE.

This will require a Linux-like operating system or operating system layer.

Python

Dinject executes Bash code blocks via python -c CODE.

The first Python interpreter available in your path will be used; this includes your virtual environment if you're in one. Dinject will rely on that interpreter/virtual environment to perform the imports.

Text

Text blocks will be passed-through unchanged.

Project

Contributing

To contribute a bug report, enhancement or feature request, please raise an issue at github.com/cariad/dinject/issues.

If you want to contribute a code change, please raise an issue first so we can chat about the direction you want to take.

Licence

Dinject is released at github.com/cariad/dinject under the MIT Licence.

See LICENSE for more information.

Author

Hello! 👋 I'm Cariad Eccleston and I'm a freelance DevOps and backend engineer. My contact details are available on my personal wiki at cariad.earth.

Please consider supporting my open source projects by sponsoring me on GitHub.

Acknowledgements

• Epic ❤️ to John Gruber for developing the original Markdown specification.
• Markdown parsing by Comprehemd.
• Pseudo terminal support by NaughTTY.
• HTML conversion of command output by thtml.
• This documentation was pressed by Edition.