Code Monkey home page Code Monkey logo

mkdocs-embed_file-plugin's Introduction

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 : 
    plugins:
  - search
  - embed_file
  3. Override your main.html with : 
    {% extends "base.html" %}
{% block extrahead %}

    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@fortawesome/[email protected]/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 : 
    <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 :

extra_css:
    - assets/css/embed_link.css

You can find an example of custom css in docs

Configuration

If you want, you can add compatibility with :

To do that, adjust your mkdocs.yml

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 for the tooltip plugin.

mkdocs-embed_file-plugin's People

Contributors

actions-user avatar mara-li avatar

Stargazers

avatar avatar avatar avatar avatar avatar

Watchers

avatar

Forkers

enatecnologia flashshare

mkdocs-embed_file-plugin's Issues

[BUG] IndexError: list index out of range

Say my mkdocs.yaml is:

site_name: test
site_url: https://example.com
plugins:
  - embed_file:
      callouts: true

and in the docs folder I have 2 files: a.md and b.md. The content of a.md is:

![z](b)

And the content of b.md is:

[](index)

Running mkdocs build returns this error:

INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: D:\QC
           supplements\Code\Websites\CW-obsidian-quan-ly-du-an-va-cong-cu-nghi\site
WARNING -  Doc file 'b.md' contains a relative link
           'index.md', but the target is not found     
           among documentation files.
ERROR   -  Error building page 'a.md': list index out
           of range
Traceback (most recent call last):
  File "<frozen runpy>", line 198, in _run_module_as_main
  File "<frozen runpy>", line 88, in _run_code
  File "C:\Users\ganuo\AppData\Local\Programs\Python\Python311\Scripts\mkdocs.exe\__main__.py", line 7, in <module>
  File "C:\Users\ganuo\AppData\Local\Programs\Python\Python311\Lib\site-packages\click\core.py", line 1130, in __call__
    return self.main(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\ganuo\AppData\Local\Programs\Python\Python311\Lib\site-packages\click\core.py", line 1055, in main
    rv = self.invoke(ctx)
         ^^^^^^^^^^^^^^^^
  File "C:\Users\ganuo\AppData\Local\Programs\Python\Python311\Lib\site-packages\click\core.py", line 1657, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\ganuo\AppData\Local\Programs\Python\Python311\Lib\site-packages\click\core.py", line 1404, in invoke
    return ctx.invoke(self.callback, **ctx.params)     
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^     
  File "C:\Users\ganuo\AppData\Local\Programs\Python\Python311\Lib\site-packages\click\core.py", line 760, in invoke
    return __callback(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\ganuo\AppData\Local\Programs\Python\Python311\Lib\site-packages\mkdocs\__main__.py", line 286, in build_command
    build.build(cfg, dirty=not clean)
  File "C:\Users\ganuo\AppData\Local\Programs\Python\Python311\Lib\site-packages\mkdocs\commands\build.py", line 349, in build
    _build_page(
  File "C:\Users\ganuo\AppData\Local\Programs\Python\Python311\Lib\site-packages\mkdocs\commands\build.py", line 235, in _build_page
    output = config.plugins.on_post_page(output, page=page, config=config)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\ganuo\AppData\Local\Programs\Python\Python311\Lib\site-packages\mkdocs\plugins.py", line 586, in on_post_page
    return self.run_event('post_page', output, page=page, config=config)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\ganuo\AppData\Local\Programs\Python\Python311\Lib\site-packages\mkdocs\plugins.py", line 507, in run_event
    result = method(item, **kwargs)
             ^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\ganuo\AppData\Local\Programs\Python\Python311\Lib\site-packages\mkdocs_embed_file_plugins\plugin.py", line 201, in on_post_page
    soup = cite(
           ^^^^^
  File "C:\Users\ganuo\AppData\Local\Programs\Python\Python311\Lib\site-packages\mkdocs_embed_file_plugins\plugin.py", line 77, in cite
    quote = convert_links_if_markdown(quote, (docs, url, md_link_path))
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\ganuo\AppData\Local\Programs\Python\Python311\Lib\site-packages\mkdocs_embed_file_plugins\src\links_correction.py", line 28, in convert_links_if_markdown
    url = create_url(internal_link, link[1], base, url_blog_path, False)
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\ganuo\AppData\Local\Programs\Python\Python311\Lib\site-packages\mkdocs_embed_file_plugins\src\links_correction.py", line 47, in create_url
    search_file_in_documentation(link, md_link_path.parent, base)
  File "C:\Users\ganuo\AppData\Local\Programs\Python\Python311\Lib\site-packages\mkdocs_embed_file_plugins\src\search_quote.py", line 62, in search_file_in_documentation
    linksBaseEquals = [i for i in linksParent if i in baseParent][0]
                      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^
IndexError: list index out of range

The link in a must point to b and be in the embed syntax, and the link in b must contain index in order to get this bug.

[BUG] Embed with link title returns `AttributeError: 'NoneType' object has no attribute 'split'`

Say my mkdocs.yaml is:

site_name: test
plugins:
  - embed_file:
      callouts: true

and in the docs folder I have a file a.md. If its content is:

![](./b.md)

then the build works. However if the content is:

![b](./b.md)

then it returns this error:

INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: D:\QC
           supplements\Code\Websites\CW-obsidian-quan-ly-du-an-va-cong-cu-nghi\site
WARNING -  Doc file 'a.md' contains a relative link
           './b.md', but the target 'b.md' is not found
           among documentation files.
ERROR   -  Error building page 'a.md': 'NoneType'
           object has no attribute 'split'
Traceback (most recent call last):
  File "<frozen runpy>", line 198, in _run_module_as_main
  File "<frozen runpy>", line 88, in _run_code
  File "C:\Users\ganuo\AppData\Local\Programs\Python\Python311\Scripts\mkdocs.exe\__main__.py", line 7, in <module>
  File "C:\Users\ganuo\AppData\Local\Programs\Python\Python311\Lib\site-packages\click\core.py", line 1130, in __call__
    return self.main(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\ganuo\AppData\Local\Programs\Python\Python311\Lib\site-packages\click\core.py", line 1055, in main
    rv = self.invoke(ctx)
         ^^^^^^^^^^^^^^^^
  File "C:\Users\ganuo\AppData\Local\Programs\Python\Python311\Lib\site-packages\click\core.py", line 1657, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\ganuo\AppData\Local\Programs\Python\Python311\Lib\site-packages\click\core.py", line 1404, in invoke
    return ctx.invoke(self.callback, **ctx.params)     
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^     
  File "C:\Users\ganuo\AppData\Local\Programs\Python\Python311\Lib\site-packages\click\core.py", line 760, in invoke
    return __callback(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\ganuo\AppData\Local\Programs\Python\Python311\Lib\site-packages\mkdocs\__main__.py", line 286, in build_command
    build.build(cfg, dirty=not clean)
  File "C:\Users\ganuo\AppData\Local\Programs\Python\Python311\Lib\site-packages\mkdocs\commands\build.py", line 349, in build
    _build_page(
  File "C:\Users\ganuo\AppData\Local\Programs\Python\Python311\Lib\site-packages\mkdocs\commands\build.py", line 235, in _build_page
    output = config.plugins.on_post_page(output, page=page, config=config)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\ganuo\AppData\Local\Programs\Python\Python311\Lib\site-packages\mkdocs\plugins.py", line 586, in on_post_page
    return self.run_event('post_page', output, page=page, config=config)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\ganuo\AppData\Local\Programs\Python\Python311\Lib\site-packages\mkdocs\plugins.py", line 507, in run_event
    result = method(item, **kwargs)
             ^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\ganuo\AppData\Local\Programs\Python\Python311\Lib\site-packages\mkdocs_embed_file_plugins\plugin.py", line 201, in on_post_page
    soup = cite(
           ^^^^^
  File "C:\Users\ganuo\AppData\Local\Programs\Python\Python311\Lib\site-packages\mkdocs_embed_file_plugins\plugin.py", line 77, in cite
    quote = convert_links_if_markdown(quote, (docs, url, md_link_path))
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\ganuo\AppData\Local\Programs\Python\Python311\Lib\site-packages\mkdocs_embed_file_plugins\src\links_correction.py", line 23, in convert_links_if_markdown
    url_blog_path = [x for x in url_blog.split("/") if len(x) > 0]
                                ^^^^^^^^^^^^^^
AttributeError: 'NoneType' object has no attribute 'split'

What does this line do?

[BUG] No module named mkdocs_embed_file_plugins.src

Describe the bug
The 2.0.3 version of mkdocs embed file plugin does not work properly. It cannot find the module. Version 2.0.2 works.

To Reproduce

  1. Get a template from https://github.com/ObsidianPublisher/obsidian-mkdocs-publisher-template
  2. Commit a file to the template.
  3. Check mkdocs action on Github.
  4. Check the log of mkdocs gh-deploy --force --clean command

Log
Run mkdocs gh-deploy --force --clean

Traceback (most recent call last):
  File "/opt/hostedtoolcache/Python/3.10.9/x64/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
  File "/opt/hostedtoolcache/Python/3.10.9/x64/lib/python3.10/site-packages/click/core.py", line 1130, in __call__
    return self.main(*args, **kwargs)
  File "/opt/hostedtoolcache/Python/3.10.9/x64/lib/python3.10/site-packages/click/core.py", line 1055, in main
    rv = self.invoke(ctx)
  File "/opt/hostedtoolcache/Python/3.10.9/x64/lib/python3.10/site-packages/click/core.py", line 1657, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/opt/hostedtoolcache/Python/3.10.9/x64/lib/python3.10/site-packages/click/core.py", line 1404, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/opt/hostedtoolcache/Python/3.10.9/x64/lib/python3.10/site-packages/click/core.py", line 760, in invoke
    return __callback(*args, **kwargs)
  File "/opt/hostedtoolcache/Python/3.10.9/x64/lib/python3.10/site-packages/mkdocs/__main__.py", line 274, in gh_deploy_command
    cfg = config.load_config(remote_branch=remote_branch, remote_name=remote_name, **kwargs)
  File "/opt/hostedtoolcache/Python/3.10.9/x64/lib/python3.10/site-packages/mkdocs/config/base.py", line 363, in load_config
    errors, warnings = cfg.validate()
  File "/opt/hostedtoolcache/Python/3.10.9/x64/lib/python3.10/site-packages/mkdocs/config/base.py", line 228, in validate
    run_failed, run_warnings = self._validate()
  File "/opt/hostedtoolcache/Python/3.10.9/x64/lib/python3.10/site-packages/mkdocs/config/base.py", line 186, in _validate
    self[key] = config_option.validate(value)
  File "/opt/hostedtoolcache/Python/3.10.9/x64/lib/python3.10/site-packages/mkdocs/config/config_options.py", line 147, in validate
    return self.run_validation(value)
  File "/opt/hostedtoolcache/Python/3.10.9/x64/lib/python3.10/site-packages/mkdocs/config/config_options.py", line 939, in run_validation
    self.load_plugin_with_namespace(name, cfg)
  File "/opt/hostedtoolcache/Python/3.10.9/x64/lib/python3.10/site-packages/mkdocs/config/config_options.py", line 975, in load_plugin_with_namespace
    return (name, self.load_plugin(name, config))
  File "/opt/hostedtoolcache/Python/3.10.9/x64/lib/python3.10/site-packages/mkdocs/config/config_options.py", line 993, in load_plugin
    plugin_cls = self.installed_plugins[name].load()
  File "/opt/hostedtoolcache/Python/3.10.9/x64/lib/python3.10/importlib/metadata/__init__.py", line 171, in load
    module = import_module(match.group('module'))
  File "/opt/hostedtoolcache/Python/3.10.9/x64/lib/python3.10/importlib/__init__.py", line 126, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "<frozen importlib._bootstrap>", line 1050, in _gcd_import
  File "<frozen importlib._bootstrap>", line 1027, in _find_and_load
  File "<frozen importlib._bootstrap>", line 1006, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 688, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 883, in exec_module
  File "<frozen importlib._bootstrap>", line 241, in _call_with_frames_removed
  File "/opt/hostedtoolcache/Python/3.10.9/x64/lib/python3.10/site-packages/mkdocs_embed_file_plugins/plugin.py", line 16, in <module>
    from mkdocs_embed_file_plugins.src.links_correction import convert_links_if_markdown, mini_ez_links
ModuleNotFoundError: No module named 'mkdocs_embed_file_plugins.src'
Error: Process completed with exit code 1.

System:

  • Github CI system

[FR] file system link files

When I use Mkdocs-embed-file-plugin with file system (linux) files that are linked throught a linked directory the plugin don't find the file.

Describe the solution you'd like
I would like that the plugin works with linked files in linked directories.

[BUG] Embedding file other than markdown

Describe the bug

Plugin doesn't work

To Reproduce

  • mkdocs.yml
#  Project information
site_name: 'Test'
site_description: 'Test'
site_author: 'Test'

# Plugins
plugins:
  - search
  - embed_file 
  
## Extensions
markdown_extensions:    
  - footnotes
  - pymdownx.highlight:
      linenums: true           
  - pymdownx.inlinehilite  
  - pymdownx.keys
  - pymdownx.snippets  
  - admonition
  - pymdownx.details  
  - attr_list
  - pymdownx.critic
  - pymdownx.caret
  - pymdownx.mark
  - pymdownx.tilde
  - tables
  - toc:
      permalink: true

# ================================================
#         THEME                                                                                       #
# ================================================

theme:
  name: material
  font:
    # text: Sarala
    text: Montserrat
  features:
    - navigation.top
    - search.suggest    
    - search.highlight     
    - search.share        
    - navigation.indexes
    - navigation.instant
    - navigation.tabs
    - header.autohide
    - content.code.annotate
  custom_dir: overrides

  language: 'en'
  # logo: 'images/logo.png'
  # favicon: 'images/logo.png'
  palette:
    - media: "(prefers-color-scheme: light)"
      primary: deep purple
      scheme: default
      toggle:
        icon: material/weather-night
        name: Switch to dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      accent: green
      # primary: deep purple
      toggle:
        icon: material/weather-sunny
        name: Switch to light mode
 
# extra_css:
#   - 'stylesheets/extra.css'  ]
  • *.md in docs/
  • Article.md:
# Introduction

![](CodeExample.java)
![[CodeExample.java]]
  • CodeExample.java:
public class CodeExample {
    public static void main(String[] args) {
        System.out.println("Hello World!");
    }
}

Log

❯ mkdocs serve
INFO     -  Building documentation...
INFO     -  Cleaning site directory
INFO     -  Documentation built in 0.40 seconds
INFO     -  [00:22:14] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO     -  [00:22:14] Serving on http://127.0.0.1:8000/
INFO     -  [00:22:14] Browser connected: http://127.0.0.1:8000/Article/

Screenshots

image

Desktop :

  • OS:
ProductName:	macOS
ProductVersion:	12.6
BuildVersion:	21G115

  • Browser: Safari 16.0, Firefox 105.0.1 (64-bit)

  • pip3 freeze

❯ pip3 freeze
attrs==20.3.0
beautifulsoup4==4.11.1
bleach==5.0.1
CacheControl==0.12.11
cachy==0.3.0
certifi==2022.9.24
cffi==1.15.1
charset-normalizer==2.1.1
cleo==1.0.0a5
click==8.1.3
crashtest==0.3.1
defusedxml==0.7.1
distlib==0.3.6
dulwich==0.20.46
EditorConfig==0.12.3
entrypoints==0.4
fastjsonschema==2.16.2
filelock==3.8.0
ghp-import==2.1.0
html5lib==1.1
idna==3.4
jaraco.classes==3.2.3
Jinja2==3.1.2
jsbeautifier==1.14.6
jsonschema==4.16.0
jupyter-core==4.11.1
jupyter_client==7.3.5
jupyterlab-pygments==0.2.2
jupytext==1.14.1
keyring==23.9.3
lockfile==0.12.2
lxml==4.9.1
Markdown==3.3.7
markdown-it-py==2.1.0
MarkupSafe==2.1.1
mdit-py-plugins==0.3.1
mdurl==0.1.2
mdx-wikilink-plus==1.4.1
mergedeep==1.3.4
mistune==0.8.4
mkdocs==1.4.0
mkdocs-autolinks-plugin==0.6.0
mkdocs-callouts==1.7.0
mkdocs-custom-tags-attributes==0.2.1
mkdocs-embed-file-plugins==2.0.0
mkdocs-jupyter==0.22.0
mkdocs-literate-nav==0.5.0
mkdocs-markmap==2.3.0
mkdocs-material==8.5.3
mkdocs-material-extensions==1.0.3
mkdocs-mermaid2-plugin==0.6.0
mkdocs-roamlinks-plugin==0.2.0
more-itertools==8.14.0
msgpack==1.0.4
nbclient==0.6.8
nbconvert==6.5.4
nbformat==5.6.1
nest-asyncio==1.5.6
packaging==21.3
pandocfilters==1.5.0
pexpect==4.8.0
pkginfo==1.8.3
platformdirs==2.5.2
poetry==1.2.1
poetry-core==1.2.0
poetry-plugin-export==1.0.7
ptyprocess==0.7.0
pycparser==2.21
Pygments==2.13.0
pylev==1.4.0
pymdown-extensions==9.5
pyparsing==3.0.9
pyrsistent==0.18.1
python-dateutil==2.8.2
python-frontmatter==1.0.0
PyYAML==6.0
pyyaml_env_tag==0.1
pyzmq==24.0.1
requests==2.28.1
requests-toolbelt==0.9.1
shellingham==1.5.0
six==1.16.0
soupsieve==2.3.2.post1
tinycss2==1.1.1
toml==0.10.2
tomlkit==0.11.5
tornado==6.2
traitlets==5.4.0
urllib3==1.26.12
virtualenv==20.16.5
watchdog==2.1.9
webencodings==0.5.1
xattr==0.9.9

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.