Obsidian Github 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.

1 Like

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