# Embed File
A way to embed a file present in your docs.
Support both wikilinks & normal links.
Intended to be used by obsidian user.
# 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 %}
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@fortawesome/fontawesome-free@5.15.4/css/fontawesome.min.css" integrity="sha384-jLKHWM3JRmfMU0A5x5AkjWkw/EYfGUAGagvnfryNV3F9VqM98XiIH7VBGVoxVSc7" crossorigin="anonymous">
{% 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]] ` | ` ` |
| Cite a heading part | `![[filename#heading]] ` | `` |
| Cite a block | `![[filename#^blockid]]` | `` |
# CSS
The plugin will create :
- A link to the original file, with the form of : `<a href="original link" class="link_citation"><i class='fas fa-link'></i></a>`
- A div with the founded content : `<div class="citation">content founded</div>`
- In case of the link / contents is not found the following block is created instead :
```html
<div class='citation'><a class='link_citation'><i class='fas fa-link'></i></a><p style="text-align: center; display: block"><i class="not_found"> link_alt </i> {a configured message}</p></div>
```
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.
Raw data
{
"_id": null,
"home_page": "https://github.com/Mara-Li/mkdocs_embed_file_plugins",
"name": "mkdocs-embed-file-plugins",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "obsidian,obsidian.md,mkdocs,file,embed,cite,quote",
"author": "Mara-Li",
"author_email": "mara-li@icloud.com",
"download_url": "https://files.pythonhosted.org/packages/5f/f0/1f9d11879a4f73f2a4a24f0a709a00b1c2c1734bdb587c69e2f2d77c9b2d/mkdocs_embed_file_plugins-2.0.9.tar.gz",
"platform": null,
"description": "# Embed File\r\nA way to embed a file present in your docs.\r\nSupport both wikilinks & normal links.\r\nIntended to be used by obsidian user.\r\n\r\n\r\n\r\n\r\n# Activate the plugin\r\n1. Run `pip install mkdocs-embed-file-plugins`\r\n2. Update your `mkdocs.yml` with :\r\n ```yaml\r\n plugins:\r\n - search\r\n - embed_file\r\n ```\r\n3. [Override](https://www.mkdocs.org/user-guide/customizing-your-theme/) your `main.html` with :\r\n ```html\r\n {% extends \"base.html\" %}\r\n {% block extrahead %}\r\n\r\n <link rel=\"stylesheet\" href=\"https://cdn.jsdelivr.net/npm/@fortawesome/fontawesome-free@5.15.4/css/fontawesome.min.css\" integrity=\"sha384-jLKHWM3JRmfMU0A5x5AkjWkw/EYfGUAGagvnfryNV3F9VqM98XiIH7VBGVoxVSc7\" crossorigin=\"anonymous\">\r\n {% endblock %}\r\n ```\r\n\r\n> [!IMPORTANT]\r\n> You need to set the `site_url` in the `mkdocs.yml` to make the plugin work.\r\n\r\n# Usage\r\n\r\n| Usage | wikilinks | markdown links |\r\n|---------------------|--------------------------|--------------------------|\r\n| cite a entire file | `![[filename]] ` | ` ` |\r\n| Cite a heading part | `![[filename#heading]] ` | `` |\r\n| Cite a block | `![[filename#^blockid]]` | `` |\r\n\r\n# CSS\r\n\r\nThe plugin will create :\r\n- A link to the original file, with the form of : `<a href=\"original link\" class=\"link_citation\"><i class='fas fa-link'></i></a>`\r\n- A div with the founded content : `<div class=\"citation\">content founded</div>`\r\n- In case of the link / contents is not found the following block is created instead :\r\n ```html\r\n <div class='citation'><a class='link_citation'><i class='fas fa-link'></i></a><p style=\"text-align: center; display: block\"><i class=\"not_found\"> link_alt </i> {a configured message}</p></div>\r\n ```\r\n The message for the not found file can be customized in `mkdocs.yml`. The default message is `file not exists`.\r\n\r\nYou can add a css in your `docs/assets/css` (or whatever the path is), and add it to your `mkdocs.yml` :\r\n```yml\r\nextra_css:\r\n - assets/css/embed_link.css\r\n```\r\nYou can find an example of custom css in [docs](docs/embed_link.css)\r\n\r\n# Configuration\r\nIf you want, you can add compatibility with :\r\n- [mkdocs callouts](https://github.com/sondregronas/mkdocs-callouts)\r\n- [mkdocs custom tags attributes](https://github.com/Mara-Li/mkdocs-custom-tags-attributes)\r\n\r\nTo do that, adjust your `mkdocs.yml`\r\n```yaml\r\nmarkdown_extensions:\r\n - attr_list\r\n - nl2br\r\n - admonition\r\n - pymdownx.details\r\nplugins:\r\n - search\r\n - callouts\r\n - custom-attributes:\r\n file: 'assets/css/custom_attributes.css'\r\n - embed_file:\r\n callouts: true\r\n custom-attribute: 'assets/css/custom_attributes.css' //need to be the same as in the config!\r\n language_message: 'file not exists.'\r\n```\r\n\r\nNote : Every extension set in `markdown_extensions` will be used for the converting, so you can use any extension you want.\r\n\r\n# Limitation\r\n- The embed file don't use plugin you would use.\r\n- Wikilinks ambiguity are not supported : the first file with the name are used.\r\n\r\n# Credit\r\nThanks to [midnightprioriem](https://github.com/midnightprioriem/mkdocs-tooltipster-links-plugin) for the tooltip plugin.\r\n",
"bugtrack_url": null,
"license": "AGPL",
"summary": "A plugin to quote file from docs",
"version": "2.0.9",
"project_urls": {
"Homepage": "https://github.com/Mara-Li/mkdocs_embed_file_plugins"
},
"split_keywords": [
"obsidian",
"obsidian.md",
"mkdocs",
"file",
"embed",
"cite",
"quote"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "41c6c0bdce4339408ae288e726bf1ce9f26d9c885f9f883056d722e1ca1a909a",
"md5": "74df53eb448d1c7a3758aa8aefaaf3ec",
"sha256": "2a5efd9f60558a65a2a45ff54f810b0a97048d0f232c9c0be41c15f1b6f3c25e"
},
"downloads": -1,
"filename": "mkdocs_embed_file_plugins-2.0.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "74df53eb448d1c7a3758aa8aefaaf3ec",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 20935,
"upload_time": "2023-12-26T11:30:15",
"upload_time_iso_8601": "2023-12-26T11:30:15.522905Z",
"url": "https://files.pythonhosted.org/packages/41/c6/c0bdce4339408ae288e726bf1ce9f26d9c885f9f883056d722e1ca1a909a/mkdocs_embed_file_plugins-2.0.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5ff01f9d11879a4f73f2a4a24f0a709a00b1c2c1734bdb587c69e2f2d77c9b2d",
"md5": "8384267741f45ce2e39d3451741b310d",
"sha256": "c75ec77094c61595b8b8e9dbc801488a8bc16046f8a08f51f27d83bc6540bb7b"
},
"downloads": -1,
"filename": "mkdocs_embed_file_plugins-2.0.9.tar.gz",
"has_sig": false,
"md5_digest": "8384267741f45ce2e39d3451741b310d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 21812,
"upload_time": "2023-12-26T11:30:18",
"upload_time_iso_8601": "2023-12-26T11:30:18.160398Z",
"url": "https://files.pythonhosted.org/packages/5f/f0/1f9d11879a4f73f2a4a24f0a709a00b1c2c1734bdb587c69e2f2d77c9b2d/mkdocs_embed_file_plugins-2.0.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-26 11:30:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Mara-Li",
"github_project": "mkdocs_embed_file_plugins",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "mkdocs-embed-file-plugins"
}
JSON
