Enveloppe: A GitHub Vault Publisher

I have updated Obsidian Mkdocs Publisher to make it more universal. In fact, today I’m introducing Obsidian GitHub Publisher.

This plugin is used to upload files to a configured GitHub repo. Unlike Obsidian Git, the plugin allows sharing only files marked by a pre-configured meta-data key, similar to publish: true in Obsidian Publish.

The configuration of the plugin makes it possible to share files in any repo you own.

The final idea is to provide a plugin/workflow for the majority of alternatives to Obsidian Publish.

Thus, the plugin allows configuring different workflows:

  • It is possible to push in a GitHub repo by setting a receiving folder ;
  • But also to push in a folder respecting a hierarchy, either from Obsidian (relative path) or from a key configured in the frontmatter.

The idea is to be able to push in a specific place of your repository, to respect the constraints of mkdocs or Jekyll.

Moreover, you can choose to transfer (or not) the images, with the choice of a specific reception folder for it.

Finally, it is possible to configure the autodeletion of files that have been deleted or that you have stopped sharing.

Be careful though, the autodeletion is only possible if you have configured the reception folder (as well as the “Root” folder if you use the YAML frontmatter). Also, you can loose data!


To use the plugin, you need to fill the correct information to allow the workflow.

1. GitHub

  • Repo name: The repository where the information will be sent.
  • GitHub username: Your username.
  • GitHub Token: Get your GitHub Token here. The correct settings should already be applied. If you want to avoid generating this every few months, select the “No expiration” option. Click the “Generate token” button, and copy the token you are presented with on the next page.

2. Download configuration.

Folder reception settings.

You have two options :

  • Use a “fixed” folder : Every file will be sent in this folder.
  • Use a folder created based on a category key.
  • Use the relative path from obsidian. You can prepend a folder using the default folder.

You need, in all case, to configure the default folder : The file will be sent here.

If you use the option for frontmatter, this folder will be the default folder : the file will be sent here if the key doesn’t exist.

Metadata frontmatter

Using the second option will activate two more options :

  • Front matter key: The key you want to use in your file.
  • Root folder : To prepend a path before the category key found (if any key are found!)

:thinking: Example

  • You use category in a file with category: Roleplay/Characters/DND
  • You set a root folder with _docs/pages
  • And you set a default folder on _docs/draft

The final path (in GitHub!) will be : _docs/pages/Roleplay/Characters/DND

But, if you don’t set category, the path will be _docs/draft

Fixed folder

Every file will be sent in the default folder. If you leave the default folder blank, it will be sent in the root of the repository.

:thinking: Example

  • If you set source for the default folder, any file will be sent in your_repo/source, whatever is their frontmatter key or their relative path.
  • If you leave it blank, it will be sent in your_repo directly.

Obsidian Path

It uses the relative path in your Obsidian vault. The default folder will be prepended before the relative obsidian path. You can leave it blank to use the root repository.

:thinking: Example
For a file in 20. Compendium/DND/Monster

  • If you set source : the final path will be source/20. Compendium/DND/Monster
  • If you leave the default folder blank, the final path will be 20. Compendium/DND/Monster


If your workflow needs to activate a GitHub actions, set the name here.

Leave it blank to disable the GitHub actions activation.

You can also set up an “auto-delete” when you use the commands to delete files:

  • Deleted from your vault
  • Which you have stopped sharing

This option will also add a new command to delete file (without sharing new file).

:warning::zap: Warning
You can’t use the delete command if you don’t have set a default folder (and a root folder if you use the YAML configuration)
Also, you can lost some files using this commands, so be careful! Don’t forget that you can revert commit in case the plugin delete a file you don’t want to delete.

Embedded file

Occasionally, you want to avoid sending the image linked (why? Don’t know. It’s your GitHub repo, after all!). You can remove the transfer of these files.

If you choose to send image, you can set a default folder for image.

3. Plugin settings

You can configure :

  • The share key used by the plugin. By default, it is share
  • Folder excluded. The share key can’t work here. Useful if you forget to remove the share (or turn it to false) and move a file in your archive…
  • Add the command to share the file on the file menu (right-click on a file in the explorer or using the three dot) and editor menu (right-click on an opened edited note)

In the Readme, you can see some workflow example.


I updated the plugin :slight_smile:

In 3.3.0 : Use a better way to push change : now, the plugin will create a new branch (named as your_vault_name-day-month-year). It will pull request it and merge.

This update is for two things:

  • First, it will be more secure, as the workflow will fail if there are some merge conflict. You must resolve it first.
  • Second, if you found any error, or want to revert things, you just need to revert the PR, not file by file.
  • It allows more GitHub actions based on PR, merge and push.

In 3.4.0, I added a setting where you can put folder path to exclude them from being deleted by the auto-clean. Each path must be separated by a comma. Files including these path won’t be deleted.

:thought_balloon: Example
If you set assets/image
A filepath with docs/assets/image/logo won’t be deleted.

It will be more secure for mkdocs constrains.

Furthermore, only file supported by obsidian will be deleted, aka:

  • Markdown md file
  • Image files : png, jpg, jpeg, gif, bmp, svg
  • Audio file : mp3, webm, wav, m4a, ogg, 3gp, flac
  • Video files : mp4, webm, ogv
  • PDF files : pdf
1 Like

Hello !
Little changelog for 3.6.1 version :

  • Adding internal links converter and wikilinks to mdlinks
  • Adding more support for Folder Note : now, the internal links will match the folder settings, so you don’t lose the citation during exporting.

More information here : GitHub - Mara-Li/obsidian-github-publisher: A plugin to easily publish note to github

Hello everyone ! It’s been a while since I made a update report here :slight_smile:
I created some QoL function and made some hotfix.

Here is the list :

  • Update for the 0.15.3 Obsidian API version, with using the new placement for context menu. Well better! You will see (or already see)
  • A big hotfix for the auto-clean function, that will loved to delete file with YAML list in the frontmatter. Now fixed. You can safely use the auto-clean function.
  • The path of unshared linked file won’t be converted anymore. Pretty convenient if you use shortlinks and won’t to alias it.
  • Embed files will be converted if there are shared.
  • You can select a subfolder when using the Obsidian Path settings. This path will be “removed” from file during conversion. For example, if you set vault/blog, the file vault/blog/epidemiology/odd ratio.md will just become epidemiology/odd ratio.md.
  • I added new shiny and cool commands to share only edited files (since the last repo update) and new files.
  • A bunch of bugfixe, like relative links creator, crash on empty default path…

You can get the complete changelog at obsidian-github-publisher/CHANGELOG.md at master · obsidianMkdocs/obsidian-github-publisher · GitHub

1 Like

Interesting. Will give this a shot soon.

New update :slight_smile:

  • Deepscanning when sharing one notes : Now, embed notes can be included! Only work if the embedded notes is also shared.
  • Added a status bar to indicate the real number send if multiple embed are found (only for one note). I looking for a way to add a visual indication in the same way for mobile (as status bar doesn’t exists for mobile). Please reply if you have an idea! I want to avoid multiple notice.

You can use BRAT to update your version!

Hello! What’s up in this little summer ? I hope you drink well!

This week, a bunch of Hotfix, but also:

  1. The plugin is now translated in french (including the documentation!) and chinese (only for the plugin). Here is a little tutorial to add a new language for the plugin (detected by your obsidian configuration).

    1. First, get your obsidian “language id”. I use templater for that, with that : <% tp.obsidian.moment.locale() %>
    2. Clone the file i18n/locales/en-us.ts and rename it with your language.
    3. Translate the differents variables in the new created file.
    4. In i18n/index.ts import the new file with `import from “.locales/”
    5. In the localeMap, add in a new line : <obsidian language found>:<filename>.
    6. Additionnality, try your new translation.
    7. Generate a pull request to add your translation.
  2. With the last Dataview update, it is now possible to transform dataview (not javascript one) query in markdown, so the plugin support it naturally. Thanks to @oleeskild in obsidian-digital-garden, where i take the code !

Hello ! I just release the 3.14 version of the plugins.
This release includes :

  • The support of Dataview “simple” query. The plugin will convert simple dataview query in markdown. For the moment, dataviewjs isn’t supported. Also, the dataview link created will follow your settings. This settings can be disabled.
  • You can add hard break (two space before each new line)
  • Support for folder note with outside folder strategies.
  • Send a link to the clipboard when sharing one note. You can configure to remove some part of the link, as the .md or removing folder.

Hello everyone !
I just published the v.4.3.0 version, that includes:

  1. :sparkles: Features:
    • Removing embed mentionning using the removeEmbed frontmatter key
    • Allow to share a file if they are externally modified (using metadata menu or metaedit for example)
  2. :ambulance: Bug fixes
    • Better handling error during merge
    • A perf optimization of frontmatter options for conversion
    • Fix relative path for same folder
    • A double fileHistory prevented pushing embeds
    • title was not found when renaming files
    • Links creation when a file was non-existant (or option set to false)
    • Adding hardbreak per-file option.

I also created a discord guild for the plugin, to get in touch with user and get more quickly help!

1 Like

Hi there, I love the plugin, it is not known enough. It solves the entire issue with sharing obsidian notes on our own website (Jekyll, Hugo, mkdocs). I’ll write a guide when I end fine tuning it, but it deserves more recognition.


A guide would be very helpful! Let us know if / when you are able to create one.

Thank you!

It now works properly. I have a one click upload to my website using Obsidian Github Publisher and some handy regex. I’ll take time in the following days to write something and publish a guide here and on my newly created website. Keeping you tuned !


Thank you for your time and effort! Greatly appreciated!

1 Like

There you go :


THANK YOU!!! Very much appreciate this!

Sorry, I didn’t post here too much.

I updated and changed the name of the plugin to be Enveloppe.

Here the new links:

The mkdocs template is deprecated (too much to do to support Obsidian, python is too much low…) and now I use Quartz.

1 Like