Include a file with anchor in mkdocs
This is a pluglet which defines a macro to include file contents using jinja2 template in mkdocs
In order for this to work, mkdocs macros plugin must be installed and defined.
I saw a really useful feature in mdbook
here
which essentially let you include a portion of the file into your web page.
A similar functionality is provided by this plugin. But it didn't seem to remove anchors tags when there are multiple of them defined in a file.
This pluglet bridges that gap.
This pluglet requires python 3.10. Support for other versions may be added.
pip install mkdocs-macros-plugin
pip install mkdocs-pluglet-file-include
update your mkdocs.yaml
file with
plugins:
- search
- macros:
modules:
- mkdocs_pluglet_file_include
To include a portion of a file use
{{include_with_anchor('<file-name>', '<anchor name>')}}
File with sections defined (use the ANCHOR and ANCHOR_END keyword)
$ cat inc.txt
ANCHOR: begin
1. Item 1
2. Item 2
# ANCHOR: a
3. Item 3
4. Item 4
# ANCHOR_END: a
# ANCHOR_END: begin
File that includes contenets between anchors.
cat included.txt
Example: Include selected lines.
{{include_with_anchor('inc.txt', 'a')}}
Example: Include all lines.
{{include_with_anchor('inc.txt', 'begin')}}
After running mkdocs build, the resulting page would look like
Example: Include selected lines.
3. Item 3
4. Item 4
Example: Include all lines.
1. Item 1
2. Item 2
3. Item 3
4. Item 4