Enveloppe publishes Obsidian notes through GitHub pull requests

Enveloppe moves notes out of the vault through GitHub itself

Enveloppe is an Obsidian plugin whose stated purpose is to publish notes from an Obsidian Vault onto a GitHub repository. The project description says plainly that this happens for free, and the setup notes add that once notes sit in your own repository you can do whatever you want with them, including wiring up Jekyll, Mkdocs, Hugo or a template of your own making. The audience is therefore people with a large private vault who want a second, public-facing copy shaped for a static site generator rather than for Obsidian. The mechanism is worth stating plainly because it shapes everything else. The plugin does not maintain a separate publishing database. It creates a branch, converts notes according to your settings, pushes the result, and lets GitHub's pull request machinery carry the change. Since a repository, a branch and a token are the moving parts, a failed merge is a GitHub conflict rather than a plugin bug, and the plugin's own command list includes a connection test and a rate limit check to make that boundary visible.

The share key in frontmatter is the only publish trigger

Enveloppe does not decide what to publish from folder names, tags or a whitelist in settings. A note becomes public because its own frontmatter carries a key. The README's setup sequence tells you to set share: true in the frontmatter of a file:

---
share: true
---

That single decision lives in the note, which is a good fit for a vault that mixes confidential and publishable notes side by side. The command palette reinforces the model with separate verbs for different jobs. Upload single current active note is the quick path, and it is the one command also exposed in the right-click menu. Upload unpublished notes sweeps up everything carrying the key that has not been sent yet. Refresh published and upload new notes re-sends what is already out there and adds what is new, while Refresh all published notes rewrites the whole published set. If your template rewrites or strips frontmatter during publication, that is the first thing to check, because a missing key means the note simply never leaves the vault.

Wikilinks, folder notes and dataview queries are the real work

The interesting part of Enveloppe is not the upload, it is the reshaping that happens on the way out. The feature list promises conversion of wikilinks into markdown links, and it says links to other notes are updated according to your settings, so the published copy points at real URLs rather than at Obsidian syntax that a static site cannot resolve. Folder notes are supported by renaming them to a specific name such as index.md, which is the move most Jekyll and Hugo layouts expect. Dataview support is broader than the plugin name suggests: the README says all dataview queries are supported, including dataviewjs, inline DQL and inline dataviewJS, and the repository's package.json pins a dedicated dataview package as a development dependency. On top of that, any markdown syntax your template supports is preserved, and formats such as Mermaid or LaTeX are handled too. The practical consequence is that a vault written with heavy internal linking can become a linked public site without a second hand editing pass.

A vault named branch is where merge conflicts come from

The publishing flow is described in three steps. First, the plugin creates a branch named after your vault, with spaces replaced by a hyphen, so a vault called My Notes produces a branch called My-Notes. Second, it performs all conversion based on your settings and pushes the notes into that branch. Third, by default the branch is merged once all notes and their embedded files have been processed. That default is convenient and also the source of the failure mode the README warns about: sometimes the branch is not merged because of merge conflicts, and this can occur if you push too frequently. A shared branch that another push has already moved is exactly the situation where a conflict appears. The command list shows how the plugin reacts to the repository drifting from the vault. Purge depublished and deleted files cleans up files you removed or unpublished locally, and the feature list describes this as cleaning the repo by removing depublished and deleted files. Automatic merging can be disabled if you would rather review every change.

Enveloppe is not a sync engine and the README admits it

There is a warning block in the project documentation that any evaluator should read before installing: do not use this plugin to sync or save your Obsidian Vault, and avoid opening the converted files from your repository in Obsidian. That is an unusual admission, and it defines the tool's real boundary. Enveloppe produces a transformed copy for publication, and the transformation is lossy in ways that matter. Folder notes are renamed, wikilinks are rewritten, and template output may differ from the source note, so a clone of the repository is not a usable copy of the vault. If your requirement is a second copy that stays byte identical, or a way to work from your phone and a desktop against one set of files, this is the wrong tool and the failure shows up as lost structure rather than a merge conflict. It is also the wrong tool when the destination is a service that needs server side rendering, since the output is a file tree of static pages.

Building the plugin from source uses the bundled Dockerfile

The quick setup section covers people who install the released plugin and points to the documentation site for anything beyond that, saying that many options cannot be covered in a short setup guide. For people working on the plugin itself, the repository carries a Dockerfile whose own comment describes it as building and exporting plugin artifacts, and the Dockerfile documents the build command as docker build --output ./dist . at the repository root:

docker build --output ./dist .

The image is based on node:20-slim, installs pnpm globally and then installs the project dependencies, and runs the production build before copying the dist directory out:

pnpm install
pnpm run build

The package.json scripts line up with that flow. The build script runs esbuild in production mode, the dev script runs the same config without the production flag, and the export script adds the vault flag used for release artifacts. The test script runs vitest, and the end to end suite runs through wdio with a dedicated configuration file. A plugin contributor therefore needs Node and pnpm, or the container image, and nothing else from the toolchain is required to produce a build.

Two licence statements, one release train, and a dated last push

Licence information needs care here because the project is not consistent about it. The licence field on the repository says Apache-2.0, while the package.json in the repository declares the package licence as AGPL-3.0 and marks the package as private. We are not giving legal advice, but the practical point is that you should not assume which one governs the code you copy, and the safest route is to ask the maintainers through the GitHub Discussion linked from the project documentation. On maintenance, the repository is not archived, and the last push was on 2026-10-21. The release history shows version 8.0.0-1 published on 2026-07-29, preceded by the 8.0.0-0 release on 2026-07-10 and by 7.8.2 on 2026-04-07, and the version field in package.json matches 8.0.0-1. The top level of the repository also holds a manifest-beta.json beside manifest.json and a CHANGELOG-beta.md beside CHANGELOG.md, which points to a beta line running alongside the stable one.

Editorial conclusion

Enveloppe fits writers who keep a personal Obsidian vault and want a clean, templated public copy in GitHub, and it fits teams who want publishing to go through review. It does not fit anyone looking for two-way sync, a backup of the vault, or a repository that mirrors the vault layout, because folder notes are renamed and the README warns against opening the converted files in Obsidian. Before adopting it, check the token scope you are willing to grant, confirm the merge behaviour and the branch name you want, and read the plugin settings reference at enveloppe.ovh, since the README states that many options cannot be covered in a short setup guide.

Frequently asked questions

Official sources

1. Enveloppe/obsidian-enveloppe on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases