https://github.com/Enveloppe/mkdocs-embed_file-plugin

A way to embed a file present in your docs
https://github.com/Enveloppe/mkdocs-embed_file-plugin

attributes custom custom-attributes markdown mkdocs plugin python

Last synced: about 2 months ago
JSON representation

A way to embed a file present in your docs

• Host: GitHub
• URL: https://github.com/Enveloppe/mkdocs-embed_file-plugin
• Owner: Enveloppe
• License: agpl-3.0
• Archived: true
• Created: 2022-01-19T11:03:57.000Z (about 3 years ago)
• Default Branch: main
• Last Pushed: 2023-12-26T11:51:04.000Z (about 1 year ago)
• Last Synced: 2024-11-27T07:03:27.790Z (about 2 months ago)
• Topics: attributes, custom, custom-attributes, markdown, mkdocs, plugin, python
• Language: Python
• Size: 2.62 MB
• Stars: 6
• Watchers: 1
• Forks: 2
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE

Awesome Lists containing this project

• jimsghstars - Enveloppe/mkdocs-embed_file-plugin - A way to embed a file present in your docs (Python)

README

        
# Embed File

A way to embed a file present in your docs.

Support both wikilinks & normal links.

Intended to be used by obsidian user.

![](docs/note3.png)

![](docs/demo.gif)

# Activate the plugin

1. Run `pip install mkdocs-embed-file-plugins`

2. Update your `mkdocs.yml` with :

    ```yaml

    plugins:

      - search

      - embed_file

    ```

3. [Override](https://www.mkdocs.org/user-guide/customizing-your-theme/) your `main.html` with :

    ```html

    {% extends "base.html" %}

    {% block extrahead %}

        

   {% endblock %}

    ```

> [!IMPORTANT]

> You need to set the `site_url` in the `mkdocs.yml` to make the plugin work.

# Usage

| Usage               | wikilinks                | markdown links           |

|---------------------|--------------------------|--------------------------|

| cite a entire file  | `![[filename]] `         | `![](filename) `         |

| Cite a heading part | `![[filename#heading]] ` | `![](filename#heading)`  |

| Cite a block        | `![[filename#^blockid]]` | `![](filename#^blockid)` |

# CSS

The plugin will create :

- A link to the original file, with the form of : ``

- A div with the founded content : `
content founded
`

- In case of the link / contents is not found the following block is created instead :

   ```html

   


 link_alt  {a configured message}



   ```

  The message for the not found file can be customized in `mkdocs.yml`. The default message is `file not exists`.


You can add a css in your `docs/assets/css` (or whatever the path is), and add it to your `mkdocs.yml` :

```yml

extra_css:

    - assets/css/embed_link.css

```

You can find an example of custom css in [docs](docs/embed_link.css)

# Configuration

If you want, you can add compatibility with :

- [mkdocs callouts](https://github.com/sondregronas/mkdocs-callouts)

- [mkdocs custom tags attributes](https://github.com/Mara-Li/mkdocs-custom-tags-attributes)

To do that, adjust your `mkdocs.yml`

```yaml

markdown_extensions:

   - attr_list

   - nl2br

   - admonition

   - pymdownx.details

plugins:

   - search

   - callouts

   - custom-attributes:

        file: 'assets/css/custom_attributes.css'

   - embed_file:

        callouts: true

        custom-attribute: 'assets/css/custom_attributes.css' //need to be the same as in the config!

        language_message: 'file not exists.'

```

Note : Every extension set in `markdown_extensions` will be used for the converting, so you can use any extension you want.

# Limitation

- The embed file don't use plugin you would use.

- Wikilinks ambiguity are not supported : the first file with the name are used.

# Credit

Thanks to [midnightprioriem](https://github.com/midnightprioriem/mkdocs-tooltipster-links-plugin) for the tooltip plugin.