enveloppe / mkdocs-embed_file-plugin Goto Github PK

A way to embed a file present in your docs

License: GNU Affero General Public License v3.0

Python 100.00%

attributes custom custom-attributes markdown mkdocs plugin python

mkdocs-embed_file-plugin's Introduction

order
1

✉️ Enveloppe : An Obsidian GitHub Vault Publisher

Publish your notes in your own GitHub repository for free and do whatever you want with them. ✨

This allows you to set up any template: Jekyll, Mkdocs, Hugo, or custom-made ones!

📑 Documentation

Here, you will only get a quick setup!

🪄 Features

Converting [[wikilinks]] to markdown links
Linking to other notes and updating the links according to your settings
Cleaning the repo by removing depublished and deleted files
Folder notes (renaming them to a specific name, like index.md)
All dataview queries are supported (including dataviewjs, inline DQL and inline dataviewJS.)
Supporting any markdown syntax supported by your template, as well as other formats like Mermaid or Latex
And many more ✨

Warning

Do not use this plugin to sync or save your Obsidian Vault! Avoid opening the converted files from your repository in Obsidian!

🖥️ Initial setup

There are plenty of options available, some of which are pre-configured and others are optional.

Before you begin, you will need to configure your GitHub repository.

Fill in your username, repository name, and branch.
Generate a GitHub token from the settings link and paste it here.
Click the button to check if everything is working as intended.
Now, let's try publishing your first note! To achieve this, you need to set the key share: true in the frontmatter of a file, like this:
```
---
share: true
---
```
Now, run the command to publish: Upload single current active note
If everything is good, a PR will be created on your repository and will be automatically merged (this can be disabled if desired!).

That's it! However, there are many options that a simple README cannot cover, so please refer to the documentation for more information. 💕.

⚙️ Usage

The plugin adds 8 commands in the palette, one of which is also available in the right-click menu.

Upload single current active note (available in the right-click menu)
Upload all notes
Upload unpublished notes
Refresh published and upload new notes
Refresh all published notes
Purge depublished and deleted files
Test the connection to the configured repository
Check the rate limit of the GitHub API

Each of the commands are explained here.

🤖 How it works

The plugin will create a branch named after your vault, where spaces are replaced by a -.
The plugin will perform all conversion (based on your settings) and push the note(s) into the branch.
By default, the branch will be merged once all the notes (and their embedded files) have been processed.

Warning

Sometimes, the branch may not be merged due to merge conflicts. This can occur if you push too frequently.

🪛 Developing

You can :

🪧 Looking for something?

→ Settings explanation ← Commands references → GitHub Discussion

If you find this plugin and workflow useful, you can give me some coffee money!

mkdocs-embed_file-plugin's People

Contributors

Stargazers

Watchers

Forkers

enatecnologia flashshare

mkdocs-embed_file-plugin's Issues

[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] 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

Get a template from https://github.com/ObsidianPublisher/obsidian-mkdocs-publisher-template
Commit a file to the template.
Check mkdocs action on Github.
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

[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] 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

Desktop :

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

[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] ImportError: cannot import name 'etree' from 'markdown.util'

Crossreferencing this issue : neurobin/mdx_wikilink_plus#10 , because it concerns this plugin as well.