By default hidden files, patterns listed in `.export-ignore` as well as any files ignored by git are excluded from exports. This behavior has been made configurable on the CLI using the new flags `--hidden`, `--ignore-file` and `--no-git`.
4.4 KiB
Obsidian Export
Rust library and associated CLI program to export an Obsidian vault to regular Markdown (specifically: CommonMark)
- Recursively export Obsidian Markdown files to CommonMark.
- Supports
[[note]]
-style references as well as![[note]]
file includes.[[note#heading]]
linking/embedding not yet supported, but planned.
- Support for gitignore-style exclude patterns (default:
.export-ignore
). - Automatically excludes files that are ignored by Git when the vault is located in a Git repository.
Please note obsidian-export is not officially endorsed by the Obsidian team. It supports most but not all of Obsidian's Markdown flavor.
Installation
Note
: Obsidian-export has been developed on Linux. Windows and Mac OS are covered as part of the continuous integration tests run on GitHub, but these have not been tested by the author. Experience reports from users on these operating systems would be welcomed.
Binary releases for x86-64 processors are provided for Windows, Linux and Mac operating systems on a best-effort basis. These may be downloaded from: https://github.com/zoni/obsidian-export/releases
Alternatively, obsidian-export may be compiled from source using Cargo, the official package manager for Rust, by using the following steps:
- Install the Rust toolchain: https://www.rust-lang.org/tools/install
- Run:
cargo install obsidian-export
The same cargo install
command can later be used to upgrade to a newer release as well.
Usage
The main interface of obsidian-export is the obsidian-export
CLI command.
In it's most basic form, obsidian-export
takes just two mandatory arguments, a source and a destination:
obsidian-export my-obsidian-vault /tmp/export
This will export all of the files from my-obsidian-vault
to /tmp/export
, except for those listed in .export-ignore
or .gitignore
.
It is also possible to export individual files:
# Export as some-note.md to /tmp/export/
obsidian-export my-obsidian-vault/some-note.md /tmp/export/
# Export as exported-note.md in /tmp/
obsidian-export my-obsidian-vault/some-note.md /tmp/exported-note.md
Character encodings
At present, UTF-8 character encoding is assumed for all note text as well as filenames. All text and file handling performs lossy conversion to Unicode strings.
Use of non-UTF8 encodings may lead to issues like incorrect text replacement and failure to find linked notes. While this may change in the future, there are no plans to change this behavior in the short term.
Frontmatter
By default, frontmatter is copied over "as-is".
Some static site generators are picky about frontmatter and require it to be present.
Some get tripped up when Markdown files don't have frontmatter but start with a list item or horizontal rule.
In these cases, --frontmatter=always
can be used to insert an empty frontmatter entry.
To completely remove any frontmatter from exported notes, use --frontmatter=never
.
Ignoring files
By default, hidden files, patterns listed in .export-ignore
as well as any files ignored by git (if your vault is part of a git repository) will be excluded from exports.
These options may be adjusted with --hidden
, --ignore-file
and --no-git
if desired.
(See --help
for more information).
Notes linking to ignored notes will be unlinked (they'll only include the link text). Embeds of ignored notes will be skipped entirely.
Ignorefile syntax
The syntax for .export-ignore
files is identical to that of gitignore files.
Here's an example:
# Ignore the directory private that is located at the top of the export tree
/private
# Ignore any file or directory called `test`
test
# Ignore any PDF file
*.pdf
# ..but include special.pdf
!special.pdf
For more comprehensive documentation and examples, see the gitignore manpage.
License
Obsidian-export is dual-licensed under the Apache 2.0 and the MIT licenses.