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.