Markdown Include: A Plugin for Pelican
======================================
[](https://github.com/pelican-plugins/markdown-include/actions)
[](https://pypi.org/project/pelican-markdown-include/)
This plugin allows the use of the [Markdown-Include extension][] in Pelican articles.
[Markdown-Include extension]: https://github.com/cmacmackin/markdown-include
Installation
------------
This plugin can be installed via:
python -m pip install pelican-markdown-include
As long as you have not explicitly added a `PLUGINS` setting to your Pelican settings file, then the newly-installed plugin should be automatically detected and enabled. Otherwise, you must add `md_include` to your existing `PLUGINS` list. For more information, please see the [How to Use Plugins](https://docs.getpelican.com/en/latest/plugins.html#how-to-use-plugins) documentation.
Usage
-----
The syntax for use within Pelican articles is `{!filename!}`. According to the documentation of the [Markdown-Include extension][], this statement will be replaced by the contents of `filename` and will work recursively. The replacement is done prior to any other Markdown processing, so any Markdown syntax that is wanted can be used within the included files. For more details, see the [Markdown-Include extension documentation][].
[Markdown-Include extension documentation]: https://github.com/cmacmackin/markdown-include/#readme
Configuration
-------------
The following variables control the behavior of the plugin and can be set in the Pelican settings file:
- `MD_INCLUDE_BASE_PATH`: By default, the file name is given relative to the directory from where Pelican is run. This can be changed via this variable.
- `MD_INCLUDE_ENCODING`: The encoding of the included files. Default: `"utf-8"`
- `MD_INCLUDE_INHERIT_HEADING_DEPTH`: If `True`, increases headings on included file by amount of previous heading. Combines with `MD_HEADING_OFFSET` option below. Default: `False`
- `MD_HEADING_OFFSET`: Increases heading depth by a specific amount, in addition to the `MD_INCLUDE_INHERIT_HEADING_DEPTH` option. Default: `0`
Alternatives to this Plugin
---------------------------
Pelican allows the use of extra Markdown extensions by declaring them in the `MARKDOWN` configuration variable. However, as [explained][] in the Pelican documentation, adding new extensions via the `MARKDOWN` setting is awkward, because all the extensions loaded by default must also be explicitly listed. In addition to avoiding this problem, this plugin provides a “Pelican-ish” way of setting the configuration values of the Markdown-Include extension (`base_path`, `encoding`, `inherit_heading_depth`, and `heading_offset`). Furthermore, the [Markdown-Include extension][] must be installed in a place where Pelican can find it, which may be tricky.
[explained]: https://docs.getpelican.com/en/latest/settings.html
Contributing
------------
Contributions are welcome and much appreciated. Every little bit helps. You can contribute by improving the documentation, adding missing features, and fixing bugs. You can also help out by reviewing and commenting on [existing issues][].
To start contributing to this plugin, review the [Contributing to Pelican][] documentation, beginning with the **Contributing Code** section.
[existing issues]: https://github.com/pelican-plugins/markdown-include/issues
[Contributing to Pelican]: https://docs.getpelican.com/en/latest/contribute.html
Acknowledgments
---------------
Thanks to [Justin Mayer][] for helping with migration of this plugin under the Pelican Plugins organization.
[Justin Mayer]: https://justinmayer.com
Author
------
Copyright © 2015, 2021-2024 Rafael Laboissière (<rafael@laboissiere.net>)
License
-------
This project is licensed under the terms of the the AGPL-3.0 license.
Raw data
{
"_id": null,
"home_page": null,
"name": "pelican-markdown-include",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8.1",
"maintainer_email": null,
"keywords": "pelican, plugin, markdown include",
"author": null,
"author_email": "=?utf-8?q?Rafael_Laboissi=C3=A8re?= <rafael@laboissiere.net>",
"download_url": "https://files.pythonhosted.org/packages/43/f1/ae1387a7089654ca0a2843c00e486aeadd1b3cc3e3e60f6c9530daf5548b/pelican_markdown_include-1.0.4.tar.gz",
"platform": null,
"description": "Markdown Include: A Plugin for Pelican\n======================================\n\n[](https://github.com/pelican-plugins/markdown-include/actions)\n[](https://pypi.org/project/pelican-markdown-include/)\n\n\nThis plugin allows the use of the [Markdown-Include extension][] in Pelican articles.\n\n[Markdown-Include extension]: https://github.com/cmacmackin/markdown-include\n\nInstallation\n------------\n\nThis plugin can be installed via:\n\n python -m pip install pelican-markdown-include\n\nAs long as you have not explicitly added a `PLUGINS` setting to your Pelican settings file, then the newly-installed plugin should be automatically detected and enabled. Otherwise, you must add `md_include` to your existing `PLUGINS` list. For more information, please see the [How to Use Plugins](https://docs.getpelican.com/en/latest/plugins.html#how-to-use-plugins) documentation.\n\nUsage\n-----\n\nThe syntax for use within Pelican articles is `{!filename!}`. According to the documentation of the [Markdown-Include extension][], this statement will be replaced by the contents of `filename` and will work recursively. The replacement is done prior to any other Markdown processing, so any Markdown syntax that is wanted can be used within the included files. For more details, see the [Markdown-Include extension documentation][].\n\n[Markdown-Include extension documentation]: https://github.com/cmacmackin/markdown-include/#readme\n\n\nConfiguration\n-------------\n\nThe following variables control the behavior of the plugin and can be set in the Pelican settings file:\n\n- `MD_INCLUDE_BASE_PATH`: By default, the file name is given relative to the directory from where Pelican is run. This can be changed via this variable.\n\n- `MD_INCLUDE_ENCODING`: The encoding of the included files. Default: `\"utf-8\"`\n\n- `MD_INCLUDE_INHERIT_HEADING_DEPTH`: If `True`, increases headings on included file by amount of previous heading. Combines with `MD_HEADING_OFFSET` option below. Default: `False`\n\n- `MD_HEADING_OFFSET`: Increases heading depth by a specific amount, in addition to the `MD_INCLUDE_INHERIT_HEADING_DEPTH` option. Default: `0`\n\n\nAlternatives to this Plugin\n---------------------------\n\nPelican allows the use of extra Markdown extensions by declaring them in the `MARKDOWN` configuration variable. However, as [explained][] in the Pelican documentation, adding new extensions via the `MARKDOWN` setting is awkward, because all the extensions loaded by default must also be explicitly listed. In addition to avoiding this problem, this plugin provides a \u201cPelican-ish\u201d way of setting the configuration values of the Markdown-Include extension (`base_path`, `encoding`, `inherit_heading_depth`, and `heading_offset`). Furthermore, the [Markdown-Include extension][] must be installed in a place where Pelican can find it, which may be tricky.\n\n[explained]: https://docs.getpelican.com/en/latest/settings.html\n\nContributing\n------------\n\nContributions are welcome and much appreciated. Every little bit helps. You can contribute by improving the documentation, adding missing features, and fixing bugs. You can also help out by reviewing and commenting on [existing issues][].\n\nTo start contributing to this plugin, review the [Contributing to Pelican][] documentation, beginning with the **Contributing Code** section.\n\n[existing issues]: https://github.com/pelican-plugins/markdown-include/issues\n[Contributing to Pelican]: https://docs.getpelican.com/en/latest/contribute.html\n\nAcknowledgments\n---------------\n\nThanks to [Justin Mayer][] for helping with migration of this plugin under the Pelican Plugins organization.\n\n[Justin Mayer]: https://justinmayer.com\n\nAuthor\n------\n\nCopyright \u00a9 2015, 2021-2024 Rafael Laboissi\u00e8re (<rafael@laboissiere.net>)\n\nLicense\n-------\n\nThis project is licensed under the terms of the the AGPL-3.0 license.\n",
"bugtrack_url": null,
"license": "AGPL-3.0",
"summary": "Pelican plugin for using the Markdown-Include extension",
"version": "1.0.4",
"project_urls": {
"Funding": "https://donate.getpelican.com/",
"Homepage": "https://github.com/pelican-plugins/markdown-include",
"Issue tracker": "https://github.com/pelican-plugins/markdown-include/issues"
},
"split_keywords": [
"pelican",
" plugin",
" markdown include"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "de68863b59cb30bfd10203186946f50b142cf0d492adc60fef295f61980bd490",
"md5": "78ae8238a6af30f3989c48d1ee8121fb",
"sha256": "16489d6bb7f53618125d531fd53f516a45c7d0c9a68551d583378ebe4e6e915e"
},
"downloads": -1,
"filename": "pelican_markdown_include-1.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "78ae8238a6af30f3989c48d1ee8121fb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8.1",
"size": 6263,
"upload_time": "2024-04-14T11:31:58",
"upload_time_iso_8601": "2024-04-14T11:31:58.697211Z",
"url": "https://files.pythonhosted.org/packages/de/68/863b59cb30bfd10203186946f50b142cf0d492adc60fef295f61980bd490/pelican_markdown_include-1.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "43f1ae1387a7089654ca0a2843c00e486aeadd1b3cc3e3e60f6c9530daf5548b",
"md5": "0ecc1848e0b5826ba852d958da2590f6",
"sha256": "3c6febd2a9f4fd1d0d98bb8b519defc4541a1cfb73d2eab16e9a36051f1ce363"
},
"downloads": -1,
"filename": "pelican_markdown_include-1.0.4.tar.gz",
"has_sig": false,
"md5_digest": "0ecc1848e0b5826ba852d958da2590f6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8.1",
"size": 5401,
"upload_time": "2024-04-14T11:32:00",
"upload_time_iso_8601": "2024-04-14T11:32:00.130520Z",
"url": "https://files.pythonhosted.org/packages/43/f1/ae1387a7089654ca0a2843c00e486aeadd1b3cc3e3e60f6c9530daf5548b/pelican_markdown_include-1.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-14 11:32:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pelican-plugins",
"github_project": "markdown-include",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pelican-markdown-include"
}
JSON
