Mkdocs plugin that allow to inject external markdown or markdown section from given url
Project description
MkDocs Embed Markdown Plugin
About
Fork from MkDocs Embed External Markdown Plugin and fix the conflict with mkdocs-macros plugin and support access of Gitea private repo by token. The basic functionality is the same as the original plugin. But when rendering markdown, it search the opening tag (@include) in the whole text and replace it with the content of the included file.
Installation
Install the package with pip:
pip install mkdocs-embed-markdown
Configuration
Enable the plugin in your mkdocs.yml
file:
plugins:
- external-markdown
Compatibility with Github/Gitea Private Repository
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.
For Gitea users, the GT_TOKEN environment variable can be used instead. You may need to go to profile > settings > applications > Manage Access Tokens, and add your token to the environment variable. The key is GT_TOKEN, and the value is your token.
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
@include
requires 2 parameters: url and section name.
@include('url', '## section name')
Full Markdown Content
Embed full markdown content from a given url, you can use the following example:
@include('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:
@include('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:
# Example Page
This is an example page.
## Embedding Multiple Markdown Sections From Different URLs
### First Embedded Section
```markdown
@include('https://raw.githubusercontent.com/mkdocs/mkdocs/master/README.md', '## Features')
```
### Second Embedded Section
```markdown
@include('https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/README.md', '## Quick start')
```
Will produce the following page:
Known Issues
- [ ]
Changelog
See https://github.com/fire1ce/mkdocs-embed-external-markdown#changelog
License
This project is licensed under the terms of the MIT License.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for mkdocs-embed-markdown-3.0.2.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9ca37fb78f15c9c3ad3a592586da3fed3f06b9d3f69045d863adc3c8e3c1385d |
|
MD5 | ad282684081b457d75d80a1d809e4513 |
|
BLAKE2b-256 | 396fdc399e5dab9a3ca174a5cf713fd316ba3d607939ffdd8f2f4fa81a6a6d80 |
Hashes for mkdocs_embed_markdown-3.0.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 827b52edf8c832e5cd6a5ea3995fbf6269dd9d29bad950eb0e2c5b0e0608504a |
|
MD5 | e9126342c31298091098fe7823291766 |
|
BLAKE2b-256 | a37f26017ce5e4841215aa126fc83fe879e8925babdd4ae06316e6d0f0ccf0a2 |