mkdocs-embed-file-plugins


Namemkdocs-embed-file-plugins JSON
Version 2.0.10 PyPI version JSON
download
home_pagehttps://github.com/ObsidianPublisher/mkdocs-embed_file-plugin
SummaryA plugin to quote file from docs
upload_time2024-12-23 00:42:07
maintainerNone
docs_urlNone
authorMara-Li
requires_python>=3.7
licenseAGPL
keywords obsidian obsidian.md mkdocs file embed cite quote
VCS
bugtrack_url
requirements mkdocs setuptools Markdown beautifulsoup4 python-frontmatter mdx-wikilink-plus mkdocs-callouts mkdocs-custom-tags-attributes pymdown-extensions
Travis-CI No Travis.
coveralls test coverage No coveralls. 
            # 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 %}

        <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]] `         | `![](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 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/ObsidianPublisher/mkdocs-embed_file-plugin",
    "name": "mkdocs-embed-file-plugins",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.7",
    "maintainer_email": null,
    "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/61/53/faaea62f65bb24051328d933a819b497a018dfe73b9a15641f8ebcf1b22e/mkdocs_embed_file_plugins-2.0.10.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![](docs/note3.png)\r\n![](docs/demo.gif)\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]] `         | `![](filename) `         |\r\n| Cite a heading part | `![[filename#heading]] ` | `![](filename#heading)`  |\r\n| Cite a block        | `![[filename#^blockid]]` | `![](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.10",
    "project_urls": {
        "Homepage": "https://github.com/ObsidianPublisher/mkdocs-embed_file-plugin"
    },
    "split_keywords": [
        "obsidian",
        " obsidian.md",
        " mkdocs",
        " file",
        " embed",
        " cite",
        " quote"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "70e29c8984eb3eab675764b0d499a63c05c1c0f66353c0f41e8541f3f13fd451",
                "md5": "dd97be7b04ccb6bb805ee1bca7b903a7",
                "sha256": "299a0f65039057a36458b64b62605a469050a7c4db23423e93fb2590a6810b39"
            },
            "downloads": -1,
            "filename": "mkdocs_embed_file_plugins-2.0.10-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "dd97be7b04ccb6bb805ee1bca7b903a7",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.7",
            "size": 21779,
            "upload_time": "2024-12-23T00:42:05",
            "upload_time_iso_8601": "2024-12-23T00:42:05.765428Z",
            "url": "https://files.pythonhosted.org/packages/70/e2/9c8984eb3eab675764b0d499a63c05c1c0f66353c0f41e8541f3f13fd451/mkdocs_embed_file_plugins-2.0.10-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "6153faaea62f65bb24051328d933a819b497a018dfe73b9a15641f8ebcf1b22e",
                "md5": "c9d5f4870f9e87fa20e2b6549a9a85d4",
                "sha256": "091160455be12d91e2eb2c6174db85997b696128561ff645df7db99fe3bb5e68"
            },
            "downloads": -1,
            "filename": "mkdocs_embed_file_plugins-2.0.10.tar.gz",
            "has_sig": false,
            "md5_digest": "c9d5f4870f9e87fa20e2b6549a9a85d4",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.7",
            "size": 22519,
            "upload_time": "2024-12-23T00:42:07",
            "upload_time_iso_8601": "2024-12-23T00:42:07.917433Z",
            "url": "https://files.pythonhosted.org/packages/61/53/faaea62f65bb24051328d933a819b497a018dfe73b9a15641f8ebcf1b22e/mkdocs_embed_file_plugins-2.0.10.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-12-23 00:42:07",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "ObsidianPublisher",
    "github_project": "mkdocs-embed_file-plugin",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "requirements": [
        {
            "name": "mkdocs",
            "specs": []
        },
        {
            "name": "setuptools",
            "specs": []
        },
        {
            "name": "Markdown",
            "specs": []
        },
        {
            "name": "beautifulsoup4",
            "specs": []
        },
        {
            "name": "python-frontmatter",
            "specs": []
        },
        {
            "name": "mdx-wikilink-plus",
            "specs": []
        },
        {
            "name": "mkdocs-callouts",
            "specs": []
        },
        {
            "name": "mkdocs-custom-tags-attributes",
            "specs": []
        },
        {
            "name": "pymdown-extensions",
            "specs": []
        }
    ],
    "lcname": "mkdocs-embed-file-plugins"
}
Mara-Li
Elapsed time: 0.39451s