{"id":15017518,"url":"https://github.com/fire1ce/mkdocs-embed-external-markdown","last_synced_at":"2025-07-09T18:34:33.966Z","repository":{"id":43589871,"uuid":"463102282","full_name":"fire1ce/mkdocs-embed-external-markdown","owner":"fire1ce","description":"MkDocs Embed External Markdown plugin that allow to inject section or all full markdown content from a given url. The goal is to show different markdown from different sources inside your MkDocs project.","archived":false,"fork":false,"pushed_at":"2025-02-24T08:33:44.000Z","size":81,"stargazers_count":11,"open_issues_count":1,"forks_count":7,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-12T11:54:41.931Z","etag":null,"topics":["external-markdown","markdown","mkdocs-plugin"],"latest_commit_sha":null,"homepage":"https://3os.org","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fire1ce.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"fire1ce","patreon":"fire1ce","custom":["https://www.buymeacoffee.com/fire1ce"]}},"created_at":"2022-02-24T10:21:12.000Z","updated_at":"2025-03-27T14:08:01.000Z","dependencies_parsed_at":"2024-02-26T13:33:04.693Z","dependency_job_id":"a3a36622-5380-4555-9f82-b7598cbd8eee","html_url":"https://github.com/fire1ce/mkdocs-embed-external-markdown","commit_stats":{"total_commits":75,"total_committers":5,"mean_commits":15.0,"dds":"0.21333333333333337","last_synced_commit":"4c9d82646250812d96857b0e3d0e9b5164eeacda"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/fire1ce/mkdocs-embed-external-markdown","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fire1ce%2Fmkdocs-embed-external-markdown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fire1ce%2Fmkdocs-embed-external-markdown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fire1ce%2Fmkdocs-embed-external-markdown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fire1ce%2Fmkdocs-embed-external-markdown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fire1ce","download_url":"https://codeload.github.com/fire1ce/mkdocs-embed-external-markdown/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fire1ce%2Fmkdocs-embed-external-markdown/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264502387,"owners_count":23618587,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["external-markdown","markdown","mkdocs-plugin"],"created_at":"2024-09-24T19:50:36.045Z","updated_at":"2025-07-09T18:34:33.920Z","avatar_url":"https://github.com/fire1ce.png","language":"Python","funding_links":["https://github.com/sponsors/fire1ce","https://patreon.com/fire1ce","https://www.buymeacoffee.com/fire1ce"],"categories":[],"sub_categories":[],"readme":"# 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![MkDocs Embed External Markdown Plugin](https://user-images.githubusercontent.com/16795594/155761254-17b47e65-d27e-438b-a476-15bd04fdc3ec.jpg)\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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffire1ce%2Fmkdocs-embed-external-markdown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffire1ce%2Fmkdocs-embed-external-markdown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffire1ce%2Fmkdocs-embed-external-markdown/lists"}