Include file between line numbers

[motowilliams]

This https://mkdocs-macros-plugin.readthedocs.io/en/latest/tips.html#i-would-like-to-include-a-text-file-from-line-a-to-line-b is awesome, but it requires a main.py file next to the users mkdocs.yml file. Any chance of just building in this sample into the project also so that we can easily include files throughout the repo and not just the docs_directly. Think of source code file references here. I did try fiddling with the various extra config, macros includes but just couldn't find the right incantation to make it work, where as that sample worked in seconds.

My use case is that I'm building automation to install documentation into a repo's source tree at the root (to avoid unnecessary nesting and to keep the docs as close to the top as possible). The approach is to generate the minimum stubbed out directories and config files to get developers started down the happy path of have a docs folder in their project. A new or existing repo is cloned, they run the automation the source tree items, a place holder markdown file, a mkdocs.yml, and depending on the CI tool a stub of yaml for their pipeline.

[github-actions[bot]]

Welcome to this project and thank you!' first issue

[fralau]

If I understand well, you wish to create a "happy" environment were your documentation writers would not have to worry about the boilerplate of creating a mkdocs project, with nice extras?

Yep... Such a thing could exist: pluglets. As the documentation says:

A pluglet is a preinstalled module for mkdocs-macros, which is installed thanks to Python's standard packaging process.

https://mkdocs-macros-plugin.readthedocs.io/en/latest/pluglets.html

Then you would only have to ask the use to install the pluglet (e.g. mkdocs_macros_test, which actually exists on github in pypi) and invoke it, with the following incantation:

plugins:
  ...
  - macros:
      modules: [mkdocs_macros_test]

To install: pip install mkdocs-macros-test

(I apologize for the hyphen/underscore ambiguity, but that's more or less dictated by the linguistic differences between shell and Python)

Would that fit your use case?

[motowilliams]

I debated using my use-case because I feared it would distract and it did. I have the automation mostly covered by another means.

What I'm actually asking about here is if it would possible to get that include-file functionality built-in to the plugin. That's a great feature that allows you do include files from all over the repo and the line blocking is also very useful.

[fralau]

I see...

Actually, you do have include-file functionality built-in: it is the standard include directive (of Jinja2):

{% include 'html/content1.html' %}

Would that not be sufficient, usually?

[motowilliams]

Yes, I suppose but what I'm finding at least for technical docs is that referencing source code, config files, Dockerfiles in the documentation is very useful. The jinja include by default can't include content from outside the docs_dir and I wasn't able to find a configuration combination to be able to 'see' include files from anywhere in the repo.

[fralau]

That's true... that would be an argument for this function.

I wouldn't want to include this function into the standard package because this function might be objectionable to others, for the same reason it would be desirable to you (i.e. "jailbreaking" from the repo).

A pluglet wouldn't be a bad idea though 🤔, especially since it would be quickly written, exactly to your specifications, and you could publish it on github?

[fralau]

I see your position as perfectly legitimate.

It is only that some other users of this library who could have have a different context, where security is important.

What would be your objection against implementing this function as a pluglet?

[motowilliams]

I ended up going that route. I'll circle back to this once I get that sorted ... properly. Thanks for the direction on this!

[fralau]

@motowilliams You're welcome 👍: let me know how it worked.

Do not hesitate to reach out, if you meet a difficulty.

[fralau]

@motowilliams Added an auto-install feature for pluglets (ef86efd8) in version 0.6.1. This should facilitate the management of plugets for your use case (if you need specific functions designed specifically for your environment).

Essentially, this will attempt to pip install the missing pluglets.

New type of declaration:

plugins:
  ...
  - macros:
      modules: [mkdocs-macros-test:mkdocs_macros_test]

If the name of the source package is the same as the import name, there is no need to specify it (nothing is changed compared to today's syntax).

See documentation.