# MkDocs Embed External Markdown Plugin
[![PyPI - Downloads][pypi-image]][pypi-url]
[![contributions welcome][contributions-image]][contributions-url]
[![MIT license][license-image]][license-url]
[pypi-image]: https://img.shields.io/pypi/dm/mkdocs-embed-external-markdown
[pypi-url]: https://pypi.org/project/mkdocs-embed-external-markdown/
[contributions-image]: https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat
[contributions-url]: https://github.com/fire1ce/mkdocs-embed-external-markdown
[license-image]: https://img.shields.io/badge/License-MIT-blue.svg
[license-url]: https://mit-license.org/
## About
MkDocs Embed External Markdown plugin that allows to inject **section** or **full markdown** content from a given url.
The goal is to embed different markdown from different sources inside your MkDocs project.
## Installation
Install the package with pip:
```shell
pip install mkdocs-embed-external-markdown
```
### Installation for development
To run the tests, first install the package and its test dependencies with pip:
```shell
pip install .[test]
```
You can now run the tests in `tests/` with `pytest`:
```shell
python -m pytest tests/
```
## Configuration
Enable the plugin in your `mkdocs.yml` file:
```yaml
plugins:
- external-markdown
```
## Compatibility with Github private repos
If the GH_TOKEN environment variable is set with an authorized personal access token then the authorization header will be added to the request and content from private repositories can be fetched
## Usage
- Section defined by **"##/###/####..."** header (h2/h3/h4...)
- **"#"** header (h1) will be **removed** from source content so you can use use your own header
- **"##/###/####..."** header (h2/h3/h4...) will be **removed** from source **section** content so you can use use your own header
- Supports multiple **sections** from any source
`external_markdown` requires 2 parameters: **url** and **section name**.
```makrdown
{{ external_markdown('url', '## section name') }}
```
### Full Markdown Content
Embed full markdown content from a given url, you can use the following example:
```markdown
{{ external_markdown('https://raw.githubusercontent.com/fire1ce/DDNS-Cloudflare-Bash/main/README.md', '') }}
```
### Specific Section
Embed markdown section from a given url, you can use the following example:
```markdown
{{ external_markdown('https://raw.githubusercontent.com/fire1ce/DDNS-Cloudflare-Bash/main/README.md', '## Installation') }}
```
## MkDocs Example
The following example shows how to use the plugin in mkdocs project:
````markdown
# Example Page
This is an example page.
## Embedding Multiple Markdown Sections From Different URLs
### First Embedded Section
```markdown
{{ external_markdown('https://raw.githubusercontent.com/mkdocs/mkdocs/master/README.md', '## Features') }}
```
### Second Embedded Section
```markdown
{{ external_markdown('https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/README.md', '## Quick start') }}
```
````
Will produce the following page:
## How To Prevent Accidental Interpretation Of `Jinja-like` Statements
The most frequent issue when adding the `MkDocs Embed External Markdown Plugin` to an existing mkdocs project, is that some markdown pages may not be rendered correctly, or cause a syntax error, or some other error.
The reason is that if Jinja2 template engine in the **MkDocs Embed External Markdown Plugin** meets any text that has the standard markers (typically starting with `{%`} or `{{`) this will cause a conflict: it will try to interpret that text as a macro and fail to behave properly.
The most likely places where this can occur are the following:
| Location in Markdown file (Block or Inline) | Description |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| **Code** | Documented Jinja2 statements (or similar syntax), LaTeX |
| **Maths** | LaTeX statements |
| _*Elsewhere*_ | Some pre-existing templating or macro language, typically with some constructs starting with `{#` or `{{`. |
### Code Blocks Containing Similar Languages
With MkDocs, this situation typically occurs when the website
is documenting an application that relies on a
[djangolike/jinjalike language](https://medium.com/@i5ar/template-languages-a7b362971cbc) like:
- Django Template Language
- Jinja2 (Python)
- Nunjucks (Javascript)
- Twig (PHP)
- ...
This may also happen for pages that documents
[Ansible](https://ansible-docs.readthedocs.io/zh/stable-2.0/rst/intro.html) directives, which often contain
[variables expressed in a Jinja2 syntax](https://ansible-docs.readthedocs.io/zh/stable-2.0/rst/playbooks_variables.html#using-variables-about-jinja2).
### Solutions - Explicitly Marking The Snippets as `raw`
````markdown
{% raw %}
```bash
docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' container_name_or_id
```
{% endraw %}
````
## Known Issues
- [ ]
## Changelog
### Version 3.xx
Version 3.0.1 (2023-06-21)
Fixed:
- [x] Crash caused by conflict with Jinja2 render engine expects `config` parameter from other 3rd party plugins.
Version 3.0.0 (2023-06-20)
Added
- [x] Modularized the code into separate methods for improved readability and maintainability.
- [x] Added type hints for better code understanding and possible performance improvements.
- [x] Included regex pre-compilation for performance enhancement.
- [x] Enhanced URL validation to check for the structure of a URL rather than just the presence of .md.
- [x] Improved error logging through the use of logger.warning instead of print statements, which integrates with MkDocs' logging system.
- [x] Added handling for relative links in the markdown, making them absolute based on the base URL.
- [x] Introduced better error handling for Connection Errors and Status Codes through optional return types.
Removed:
- [x] Removed the use of sys.exit(1) on error, allowing the MkDocs build process to continue even if the plugin encounters an issue.
- [x] Removed the strict requirement for a section level at the beginning of a section name.
Changed
- [x] Switched from using re.compile for one-time regex patterns to using re.match or re.search.
- [x] Extracted the GitHub token once at the beginning of the request method instead of multiple times.
- [x] Replaced the check for .md at the end of the URL with a more comprehensive regular expression to validate the URL's structure.
Fixed:
- [x] Handling of section extraction is now more robust and less prone to errors.
Please note that this is a major version update and may contain breaking changes. Carefully read the updated documentation and test the plugin thoroughly before upgrading in a production environment.
### Version 2.xx Changelog Archive
**Braking change: Section name must include Markdown Section header like: `## Section name`**
Changelog:
- [x] Add ability to import content from private github repositories. Thanks to @sd0408
- [x] Added support for multi level sections such as `### Section name` and `#### Section name`
- [x] Better Handling of parsing makrdowns wich contains `#` in the content
- [x] Failing Mkdocs Build when Markdown content cannot be fetched
## License
This project is licensed under the terms of the [MIT License](LICENSE.md).
Raw data
{
"_id": null,
"home_page": "",
"name": "mkdocs-embed-external-markdown",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "mkdocs,plugin,markdown,external-markdown,embed,external,markdown-section",
"author": "",
"author_email": "Stas Yakobov <dev@3os.org>",
"download_url": "https://files.pythonhosted.org/packages/41/0d/99c54195df8a06c751bbbaaf743be771aa538eee28f39f33fe397ceb602c/mkdocs-embed-external-markdown-3.0.2.tar.gz",
"platform": null,
"description": "# MkDocs Embed External Markdown Plugin\n\n[![PyPI - Downloads][pypi-image]][pypi-url]\n[![contributions welcome][contributions-image]][contributions-url]\n[![MIT license][license-image]][license-url]\n\n[pypi-image]: https://img.shields.io/pypi/dm/mkdocs-embed-external-markdown\n[pypi-url]: https://pypi.org/project/mkdocs-embed-external-markdown/\n[contributions-image]: https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat\n[contributions-url]: https://github.com/fire1ce/mkdocs-embed-external-markdown\n[license-image]: https://img.shields.io/badge/License-MIT-blue.svg\n[license-url]: https://mit-license.org/\n\n## About\n\nMkDocs Embed External Markdown plugin that allows to inject **section** or **full markdown** content from a given url.\nThe goal is to embed different markdown from different sources inside your MkDocs project.\n\n## Installation\n\nInstall the package with pip:\n\n```shell\npip install mkdocs-embed-external-markdown\n```\n\n### Installation for development\n\nTo run the tests, first install the package and its test dependencies with pip:\n\n```shell\npip install .[test]\n```\n\nYou can now run the tests in `tests/` with `pytest`:\n\n```shell\npython -m pytest tests/\n```\n\n## Configuration\n\nEnable the plugin in your `mkdocs.yml` file:\n\n```yaml\nplugins:\n - external-markdown\n```\n\n## Compatibility with Github private repos\n\nIf the GH_TOKEN environment variable is set with an authorized personal access token then the authorization header will be added to the request and content from private repositories can be fetched\n\n## Usage\n\n- Section defined by **\"##/###/####...\"** header (h2/h3/h4...)\n- **\"#\"** header (h1) will be **removed** from source content so you can use use your own header\n- **\"##/###/####...\"** header (h2/h3/h4...) will be **removed** from source **section** content so you can use use your own header\n- Supports multiple **sections** from any source\n\n`external_markdown` requires 2 parameters: **url** and **section name**.\n\n```makrdown\n{{ external_markdown('url', '## section name') }}\n```\n\n### Full Markdown Content\n\nEmbed full markdown content from a given url, you can use the following example:\n\n```markdown\n{{ external_markdown('https://raw.githubusercontent.com/fire1ce/DDNS-Cloudflare-Bash/main/README.md', '') }}\n```\n\n### Specific Section\n\nEmbed markdown section from a given url, you can use the following example:\n\n```markdown\n{{ external_markdown('https://raw.githubusercontent.com/fire1ce/DDNS-Cloudflare-Bash/main/README.md', '## Installation') }}\n```\n\n## MkDocs Example\n\nThe following example shows how to use the plugin in mkdocs project:\n\n````markdown\n# Example Page\n\nThis is an example page.\n\n## Embedding Multiple Markdown Sections From Different URLs\n\n### First Embedded Section\n\n```markdown\n{{ external_markdown('https://raw.githubusercontent.com/mkdocs/mkdocs/master/README.md', '## Features') }}\n```\n\n### Second Embedded Section\n\n```markdown\n{{ external_markdown('https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/README.md', '## Quick start') }}\n```\n````\n\nWill produce the following page:\n\n\n\n## How To Prevent Accidental Interpretation Of `Jinja-like` Statements\n\nThe most frequent issue when adding the `MkDocs Embed External Markdown Plugin` to an existing mkdocs project, is that some markdown pages may not be rendered correctly, or cause a syntax error, or some other error.\n\nThe reason is that if Jinja2 template engine in the **MkDocs Embed External Markdown Plugin** meets any text that has the standard markers (typically starting with `{%`} or `{{`) this will cause a conflict: it will try to interpret that text as a macro and fail to behave properly.\n\nThe most likely places where this can occur are the following:\n\n| Location in Markdown file (Block or Inline) | Description |\n| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |\n| **Code** | Documented Jinja2 statements (or similar syntax), LaTeX |\n| **Maths** | LaTeX statements |\n| _*Elsewhere*_ | Some pre-existing templating or macro language, typically with some constructs starting with `{#` or `{{`. |\n\n### Code Blocks Containing Similar Languages\n\nWith MkDocs, this situation typically occurs when the website\nis documenting an application that relies on a\n[djangolike/jinjalike language](https://medium.com/@i5ar/template-languages-a7b362971cbc) like:\n\n- Django Template Language\n- Jinja2 (Python)\n- Nunjucks (Javascript)\n- Twig (PHP)\n- ...\n\nThis may also happen for pages that documents\n[Ansible](https://ansible-docs.readthedocs.io/zh/stable-2.0/rst/intro.html) directives, which often contain\n[variables expressed in a Jinja2 syntax](https://ansible-docs.readthedocs.io/zh/stable-2.0/rst/playbooks_variables.html#using-variables-about-jinja2).\n\n### Solutions - Explicitly Marking The Snippets as `raw`\n\n````markdown\n{% raw %}\n\n```bash\ndocker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' container_name_or_id\n```\n\n{% endraw %}\n````\n\n## Known Issues\n\n- [ ]\n\n## Changelog\n\n### Version 3.xx\n\nVersion 3.0.1 (2023-06-21)\n\nFixed:\n\n- [x] Crash caused by conflict with Jinja2 render engine expects `config` parameter from other 3rd party plugins.\n\nVersion 3.0.0 (2023-06-20)\n\nAdded\n\n- [x] Modularized the code into separate methods for improved readability and maintainability.\n- [x] Added type hints for better code understanding and possible performance improvements.\n- [x] Included regex pre-compilation for performance enhancement.\n- [x] Enhanced URL validation to check for the structure of a URL rather than just the presence of .md.\n- [x] Improved error logging through the use of logger.warning instead of print statements, which integrates with MkDocs' logging system.\n- [x] Added handling for relative links in the markdown, making them absolute based on the base URL.\n- [x] Introduced better error handling for Connection Errors and Status Codes through optional return types.\n\nRemoved:\n\n- [x] Removed the use of sys.exit(1) on error, allowing the MkDocs build process to continue even if the plugin encounters an issue.\n- [x] Removed the strict requirement for a section level at the beginning of a section name.\n\nChanged\n\n- [x] Switched from using re.compile for one-time regex patterns to using re.match or re.search.\n- [x] Extracted the GitHub token once at the beginning of the request method instead of multiple times.\n- [x] Replaced the check for .md at the end of the URL with a more comprehensive regular expression to validate the URL's structure.\n\nFixed:\n\n- [x] Handling of section extraction is now more robust and less prone to errors.\n\nPlease note that this is a major version update and may contain breaking changes. Carefully read the updated documentation and test the plugin thoroughly before upgrading in a production environment.\n\n### Version 2.xx Changelog Archive\n\n**Braking change: Section name must include Markdown Section header like: `## Section name`**\n\nChangelog:\n\n- [x] Add ability to import content from private github repositories. Thanks to @sd0408\n- [x] Added support for multi level sections such as `### Section name` and `#### Section name`\n- [x] Better Handling of parsing makrdowns wich contains `#` in the content\n- [x] Failing Mkdocs Build when Markdown content cannot be fetched\n\n## License\n\nThis project is licensed under the terms of the [MIT License](LICENSE.md).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Mkdocs plugin that allow to inject external markdown or markdown section from given url",
"version": "3.0.2",
"project_urls": {
"Source": "https://github.com/fire1ce/pypi-test"
},
"split_keywords": [
"mkdocs",
"plugin",
"markdown",
"external-markdown",
"embed",
"external",
"markdown-section"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a219c8e5b85ff0bc58862b32667a2a274afdf54610febbf93a7b91f070525275",
"md5": "135b3af79dc9af1d0f8cb329816cbc86",
"sha256": "82088296cfd117b36ef45b58b4342005727a1f891f0c429c21756215e89099d2"
},
"downloads": -1,
"filename": "mkdocs_embed_external_markdown-3.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "135b3af79dc9af1d0f8cb329816cbc86",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 7787,
"upload_time": "2024-02-26T12:18:14",
"upload_time_iso_8601": "2024-02-26T12:18:14.088321Z",
"url": "https://files.pythonhosted.org/packages/a2/19/c8e5b85ff0bc58862b32667a2a274afdf54610febbf93a7b91f070525275/mkdocs_embed_external_markdown-3.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "410d99c54195df8a06c751bbbaaf743be771aa538eee28f39f33fe397ceb602c",
"md5": "0ce79d575f8475eb6985634e159751c0",
"sha256": "9a3d14a9cc6efb4201175530f277e84da472a576772db264a3b19570cf266317"
},
"downloads": -1,
"filename": "mkdocs-embed-external-markdown-3.0.2.tar.gz",
"has_sig": false,
"md5_digest": "0ce79d575f8475eb6985634e159751c0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 7123,
"upload_time": "2024-02-26T12:18:15",
"upload_time_iso_8601": "2024-02-26T12:18:15.705063Z",
"url": "https://files.pythonhosted.org/packages/41/0d/99c54195df8a06c751bbbaaf743be771aa538eee28f39f33fe397ceb602c/mkdocs-embed-external-markdown-3.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-26 12:18:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fire1ce",
"github_project": "pypi-test",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "mkdocs-embed-external-markdown"
}
JSON
