Package: mkdocs-embed-external-markdown
MkDocs Embed External Markdown PluginAboutMkDocs Embed External Markdown plugin that allows to injectsectionorfull markdowncontent from a given url.
The goal is to embed different markdown from different sources inside your MkDocs project.InstallationInstall the package with pip:pipinstallmkdocs-embed-external-markdownInstallation for developmentTo run the tests, first install the package and its test dependencies with pip:pipinstall.[test]You can now run the tests intests/withpytest:python-mpytesttests/ConfigurationEnable the plugin in yourmkdocs.ymlfile:plugins:-external-markdownCompatibility with Github private reposIf 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 fetchedUsageSection defined by"##/###/####..."header (h2/h3/h4...)"#"header (h1) will beremovedfrom source content so you can use use your own header"##/###/####..."header (h2/h3/h4...) will beremovedfrom sourcesectioncontent so you can use use your own headerSupports multiplesectionsfrom any sourceexternal_markdownrequires 2 parameters:urlandsection name.{{ external_markdown('url', '## section name') }}Full Markdown ContentEmbed full markdown content from a given url, you can use the following example:{{ external_markdown('https://raw.githubusercontent.com/fire1ce/DDNS-Cloudflare-Bash/main/README.md', '') }}Specific SectionEmbed markdown section from a given url, you can use the following example:{{ external_markdown('https://raw.githubusercontent.com/fire1ce/DDNS-Cloudflare-Bash/main/README.md', '## Installation') }}MkDocs ExampleThe following example shows how to use the plugin in mkdocs project:# Example PageThis 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 OfJinja-likeStatementsThe most frequent issue when adding theMkDocs Embed External Markdown Pluginto 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 theMkDocs Embed External Markdown Pluginmeets 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)DescriptionCodeDocumented Jinja2 statements (or similar syntax), LaTeXMathsLaTeX statementsElsewhereSome pre-existing templating or macro language, typically with some constructs starting with{#or{{.Code Blocks Containing Similar LanguagesWith MkDocs, this situation typically occurs when the website
is documenting an application that relies on adjangolike/jinjalike languagelike:Django Template LanguageJinja2 (Python)Nunjucks (Javascript)Twig (PHP)...This may also happen for pages that documentsAnsibledirectives, which often containvariables expressed in a Jinja2 syntax.Solutions - Explicitly Marking The Snippets asraw{% raw %}```bashdockerinspect-f'{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}'container_name_or_id```{% endraw %}Known Issues[ ]ChangelogVersion 3.xxVersion 3.0.1 (2023-06-21)Fixed:Crash caused by conflict with Jinja2 render engine expectsconfigparameter from other 3rd party plugins.Version 3.0.0 (2023-06-20)AddedModularized the code into separate methods for improved readability and maintainability.Added type hints for better code understanding and possible performance improvements.Included regex pre-compilation for performance enhancement.Enhanced URL validation to check for the structure of a URL rather than just the presence of .md.Improved error logging through the use of logger.warning instead of print statements, which integrates with MkDocs' logging system.Added handling for relative links in the markdown, making them absolute based on the base URL.Introduced better error handling for Connection Errors and Status Codes through optional return types.Removed:Removed the use of sys.exit(1) on error, allowing the MkDocs build process to continue even if the plugin encounters an issue.Removed the strict requirement for a section level at the beginning of a section name.ChangedSwitched from using re.compile for one-time regex patterns to using re.match or re.search.Extracted the GitHub token once at the beginning of the request method instead of multiple times.Replaced the check for .md at the end of the URL with a more comprehensive regular expression to validate the URL's structure.Fixed: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 ArchiveBraking change: Section name must include Markdown Section header like:## Section nameChangelog:Add ability to import content from private github repositories. Thanks to @sd0408Added support for multi level sections such as### Section nameand#### Section nameBetter Handling of parsing makrdowns wich contains#in the contentFailing Mkdocs Build when Markdown content cannot be fetchedLicenseThis project is licensed under the terms of theMIT License.