https://github.com/entangled/mkdocs-plugin
An MkDocs plugin that lets you do Literate Programming through Entangled.
https://github.com/entangled/mkdocs-plugin
literate-programming markdown mkdocs-plugin
Last synced: 4 months ago
JSON representation
An MkDocs plugin that lets you do Literate Programming through Entangled.
- Host: GitHub
- URL: https://github.com/entangled/mkdocs-plugin
- Owner: entangled
- License: apache-2.0
- Created: 2023-04-11T13:06:53.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2023-10-14T12:19:27.000Z (over 2 years ago)
- Last Synced: 2025-05-13T17:22:48.178Z (9 months ago)
- Topics: literate-programming, markdown, mkdocs-plugin
- Language: Python
- Homepage: https://entangled.github.io/mkdocs-plugin/
- Size: 144 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Welcome to MkDocs Entangled Plugin
Using this plugin, you can make your Entangled documents look better.
## Examples
Detailed examples are found in the [entangled/mkdocs-examples repository](https://entangled.github.io/mkdocs-examples).
## Install
Install this with `pip install mkdocs-entangled-plugin`. To use the entangled plugin, add the following lines to your `mkdocs.yml`:
```yaml
plugins:
- entangled
markdown_extensions:
- pymdownx.superfences
- pymdownx.tabbed:
alternate_style: true
```
For more information, see [the documentation](https://entangled.github.io/mkdocs-plugin).
## Components
This plugin bundles functionality for literate programming with Entangled.
- Annotate code blocks with titles.
- Build artifacts using Make.
### Annotate code blocks
The default markdown syntax that Entangled supports has fenced code blocks as follows
~~~markdown
``` {.python file=examples/hello_world.py}
if __name__ == "__main__":
<>
```
~~~
Which renders like this:
``` {.python file=examples/hello_world.py}
if __name__ == "__main__":
<>
```
Or named code blocks
~~~markdown
``` {.python #hello-world}
print("Hello, World!")
```
~~~
that render like this:
``` {.python #hello-world}
print("Hello, Universe!")
```
### Build Artifacts
Build artifacts by specifying a Makefile.
~~~markdown
=== "Figure 1"
=== "Source"
``` {.gnuplot file=examples/plot.gp}
# enter your plotting commands here
```
``` {.make .build-artifact}
.RECIPEPREFIX = >
docs/fig/plot.svg: examples/plot.gp
> mkdir -p $(@D)
> gnuplot $^ > $@
```
~~~
=== "Figure 1"
=== "Source"
``` {.gnuplot file=examples/plot.gp}
set term svg background rgb 'white' size 700, 500
sinc(r) = sin(pi*r) / (pi*r)
set isosamples 50, 50
set hidden3d
set xrange [-4:4]
set yrange [-4:4]
set xyplane 0
set title "Sinc function"
splot sinc(sqrt(x**2 + y**2)) t'' lc rgb '#5533cc'
```
``` {.make .build-artifact}
.RECIPEPREFIX = >
docs/fig/plot.svg: examples/plot.gp
> mkdir -p $(@D)
> gnuplot $^ > $@
```
## License
Licensed under the Apache-2 license agreement: see LICENSE