# MkDocs Embed Markdown Plugin
[![MIT license][license-image]][license-url]
[license-image]: https://img.shields.io/badge/License-MIT-blue.svg
[license-url]: https://mit-license.org/
## About
Fork from [MkDocs Embed External Markdown Plugin](https://github.com/fire1ce/mkdocs-embed-external-markdown) 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:
```shell
pip install mkdocs-embed-markdown
```
## Configuration
Enable the plugin in your `mkdocs.yml` file:
```yaml
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**.
```makrdown
@include('url', '## section name')
```
### Full Markdown Content
Embed full markdown content from a given url, you can use the following example:
```markdown
@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:
```markdown
@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:
````markdown
# 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](https://github.com/fire1ce/mkdocs-embed-external-markdown#changelog)
## License
This project is licensed under the terms of the [MIT License](LICENSE.md).
Raw data
{
"_id": null,
"home_page": "",
"name": "mkdocs-embed-markdown",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "mkdocs,plugin,markdown,external-markdown,embed,external,markdown-section",
"author": "",
"author_email": "yanedie <zinyi073@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/39/6f/dc399e5dab9a3ca174a5cf713fd316ba3d607939ffdd8f2f4fa81a6a6d80/mkdocs-embed-markdown-3.0.2.tar.gz",
"platform": null,
"description": "# MkDocs Embed Markdown Plugin\r\n\r\n[![MIT license][license-image]][license-url]\r\n\r\n[license-image]: https://img.shields.io/badge/License-MIT-blue.svg\r\n[license-url]: https://mit-license.org/\r\n\r\n## About\r\n\r\nFork from [MkDocs Embed External Markdown Plugin](https://github.com/fire1ce/mkdocs-embed-external-markdown) 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.\r\n\r\n## Installation\r\n\r\nInstall the package with pip:\r\n\r\n```shell\r\npip install mkdocs-embed-markdown\r\n```\r\n\r\n## Configuration\r\n\r\nEnable the plugin in your `mkdocs.yml` file:\r\n\r\n```yaml\r\nplugins:\r\n - external-markdown\r\n```\r\n\r\n## Compatibility with Github/Gitea Private Repository\r\n\r\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.\r\n\r\nFor 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.\r\n\r\n## Usage\r\n\r\n- Section defined by **\"##/###/####...\"** header (h2/h3/h4...)\r\n- **\"#\"** header (h1) will be **removed** from source content so you can use use your own header\r\n- **\"##/###/####...\"** header (h2/h3/h4...) will be **removed** from source **section** content so you can use use your own header\r\n- Supports multiple **sections** from any source\r\n\r\n`@include` requires 2 parameters: **url** and **section name**.\r\n\r\n```makrdown\r\n@include('url', '## section name')\r\n```\r\n\r\n### Full Markdown Content\r\n\r\nEmbed full markdown content from a given url, you can use the following example:\r\n\r\n```markdown\r\n@include('https://raw.githubusercontent.com/fire1ce/DDNS-Cloudflare-Bash/main/README.md', '')\r\n```\r\n\r\n### Specific Section\r\n\r\nEmbed markdown section from a given url, you can use the following example:\r\n\r\n```markdown\r\n@include('https://raw.githubusercontent.com/fire1ce/DDNS-Cloudflare-Bash/main/README.md', '## Installation')\r\n```\r\n\r\n## MkDocs Example\r\n\r\nThe following example shows how to use the plugin in mkdocs project:\r\n\r\n````markdown\r\n# Example Page\r\n\r\nThis is an example page.\r\n\r\n## Embedding Multiple Markdown Sections From Different URLs\r\n\r\n### First Embedded Section\r\n\r\n```markdown\r\n@include('https://raw.githubusercontent.com/mkdocs/mkdocs/master/README.md', '## Features')\r\n```\r\n\r\n### Second Embedded Section\r\n\r\n```markdown\r\n@include('https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/README.md', '## Quick start')\r\n```\r\n````\r\n\r\nWill produce the following page:\r\n\r\n\r\n\r\n## Known Issues\r\n\r\n- [ ]\r\n\r\n## Changelog\r\n\r\nSee [https://github.com/fire1ce/mkdocs-embed-external-markdown#changelog](https://github.com/fire1ce/mkdocs-embed-external-markdown#changelog)\r\n\r\n## License\r\n\r\nThis project is licensed under the terms of the [MIT License](LICENSE.md).\r\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/yanedie/mkdocs-embed-external-markdown"
},
"split_keywords": [
"mkdocs",
"plugin",
"markdown",
"external-markdown",
"embed",
"external",
"markdown-section"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a37f26017ce5e4841215aa126fc83fe879e8925babdd4ae06316e6d0f0ccf0a2",
"md5": "e9126342c31298091098fe7823291766",
"sha256": "827b52edf8c832e5cd6a5ea3995fbf6269dd9d29bad950eb0e2c5b0e0608504a"
},
"downloads": -1,
"filename": "mkdocs_embed_markdown-3.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e9126342c31298091098fe7823291766",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 6136,
"upload_time": "2023-09-06T09:15:41",
"upload_time_iso_8601": "2023-09-06T09:15:41.725694Z",
"url": "https://files.pythonhosted.org/packages/a3/7f/26017ce5e4841215aa126fc83fe879e8925babdd4ae06316e6d0f0ccf0a2/mkdocs_embed_markdown-3.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "396fdc399e5dab9a3ca174a5cf713fd316ba3d607939ffdd8f2f4fa81a6a6d80",
"md5": "ad282684081b457d75d80a1d809e4513",
"sha256": "9ca37fb78f15c9c3ad3a592586da3fed3f06b9d3f69045d863adc3c8e3c1385d"
},
"downloads": -1,
"filename": "mkdocs-embed-markdown-3.0.2.tar.gz",
"has_sig": false,
"md5_digest": "ad282684081b457d75d80a1d809e4513",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 5525,
"upload_time": "2023-09-06T09:15:43",
"upload_time_iso_8601": "2023-09-06T09:15:43.533683Z",
"url": "https://files.pythonhosted.org/packages/39/6f/dc399e5dab9a3ca174a5cf713fd316ba3d607939ffdd8f2f4fa81a6a6d80/mkdocs-embed-markdown-3.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-06 09:15:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yanedie",
"github_project": "mkdocs-embed-external-markdown",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "mkdocs-embed-markdown"
}
JSON
