Obsidian Export is a CLI program and a Rust library to export an [Obsidian] vault to regular Markdown.
[[note]]-style references as well as ![[note]] file includes..export-ignore).Please note obsidian-export is not officially endorsed by the Obsidian team. It supports most but not all of Obsidian's Markdown flavor.
Binary releases for x86-64 processors are provided for Windows, Linux and Mac operating systems on a best-effort basis.
They are built with GitHub runners as part of the release workflow defined in .github/workflows/release.yml.
The resulting binaries can be downloaded from https://github.com/zoni/obsidian-export/releases
When binary releases are unavailable for your platform, or you do not trust the pre-built binaries, then obsidian-export can be compiled from source with relatively little effort. This is done through [Cargo], the official package manager for Rust, with the following steps:
Run: cargo install obsidian-export
It is expected that you successfully configured the PATH variable correctly while installing the Rust toolchain, as described under "Configuring the PATH environment variable" on https://www.rust-lang.org/tools/install.
If you downloaded a pre-built binary, upgrade by downloading the latest version to replace the old one.
If you built from source, upgrade by running cargo install obsidian-export again.
The main interface of obsidian-export is the obsidian-export CLI command.
As a text interface, this must be run from a terminal or Windows PowerShell.
It is assumed that you have basic familiarity with command-line interfaces and that you set up your PATH correctly if you installed with cargo.
Running obsidian-export --version should print a version number rather than giving some kind of error.
If you downloaded a pre-built binary and didn't put it a location referenced by
PATH(for example, you put it inDownloads), you will need to provide the full path to the binary instead.For example
~/Downloads/obsidian-export --versionon Mac/Linux or~\Downloads\obsidian-export --versionon Windows (PowerShell).
In it's most basic form, obsidian-export takes just two mandatory arguments, a source and a destination:
sh
obsidian-export /path/to/my-obsidian-vault /path/to/exported-notes/
This will export all of the files from my-obsidian-vault to exported-notes, except for those listed in .export-ignore or .gitignore.
Note that the destination directory must exist, so you may need to create a new, empty directory first.
If you give it an existing directory, files under that directory may get overwritten.
It is also possible to export individual files:
````sh
obsidian-export my-obsidian-vault/some-note.md /tmp/export/
obsidian-export my-obsidian-vault/some-note.md /tmp/exported-note.md ````
Note that in this mode, obsidian-export sees some-note.md as being the only file that exists in your vault so references to other notes won't be resolved.
This is by design.
If you'd like to export a single note while resolving links or embeds to other areas in your vault then you should instead specify the root of your vault as the source, passing the file you'd like to export with --start-at, as described in the next section.
Using the --start-at argument, you can export just a subset of your vault.
Given the following vault structure:
my-obsidian-vault
├── Notes/
├── Books/
└── People/
This will export only the notes in the Books directory to exported-notes:
sh
obsidian-export my-obsidian-vault --start-at my-obsidian-vault/Books exported-notes
In this mode, all notes under the source (the first argument) are considered part of the vault so any references to these files will remain intact, even if they're not part of the exported notes.
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.
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.
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.
The syntax for .export-ignore files is identical to that of [gitignore] files.
Here's an example:
````
/private
testtest
!special.pdf ````
For more comprehensive documentation and examples, see the [gitignore] manpage.
It's possible to end up with "recursive embeds" when two notes embed each other.
This happens for example when a Note A.md contains ![[Note B]] but Note B.md also contains ![[Note A]].
By default, this will trigger an error and display the chain of notes which caused the recursion.
This behavior may be changed by specifying --no-recursive-embeds.
Using this mode, if a note is encountered for a second time while processing the original note, instead of embedding it again a link to the note is inserted instead to break the cycle.
The [Hugo] static site generator does not support relative links to files.
Instead, it expects you to link to other pages using the [ref and relref shortcodes].
As a result of this, notes that have been exported from Obsidian using obsidian-export do not work out of the box because Hugo doesn't resolve these links correctly.
[Markdown Render Hooks] (only supported using the default goldmark renderer) allow you to work around this issue however, making exported notes work with Hugo after a bit of one-time setup work.
Create the file layouts/_default/_markup/render-link.html with the following contents:
```` {{- $url := urls.Parse .Destination -}} {{- $scheme := $url.Scheme -}}
{{- /* whitespace stripped here to avoid trailing newline in rendered result caused by file EOL */ -}} ````
And layouts/_default/_markup/render-image.html for images:
```` {{- $url := urls.Parse .Destination -}} {{- $scheme := $url.Scheme -}}
{{- /* whitespace stripped here to avoid trailing newline in rendered result caused by file EOL */ -}} ````
With these hooks in place, links to both notes as well as file attachments should now work correctly.
Note: If you're using a theme which comes with it's own render hooks, you might need to do a little extra work, or customize the snippets above, to avoid conflicts with the hooks from your theme.
All of the functionality exposed by the obsidian-export CLI command is also accessible as a Rust library, exposed through the obsidian_export crate.
To get started, visit the library documentation on obsidianexport and obsidianexport::Exporter.
Obsidian-export is dual-licensed under the [Apache 2.0] and the [MIT] licenses.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
Happy new year! On this second day of 2022 comes a fresh release with one notable new feature.
Support Obsidian's "Strict line breaks" setting. [Nick Groenen]
This change introduces a new --hard-linebreaks CLI argument. When
used, this converts soft line breaks to hard line breaks, mimicking
Obsidian's "Strict line breaks" setting.
Implementation detail: I considered naming this flag
--strict-line-breaksto be consistent with Obsidian itself, however I feel the name is somewhat misleading and ill-chosen.
Give release binaries file extensions. [Nick Groenen]
This may make it more clear to users that these are precompiled, binary
files. This is especially relevant on Windows, where the convention is
that executable files have a .exe extension, as seen in #49.
Upgrade dependencies. [Nick Groenen]
This commit upgrades all dependencies to their current latest versions. Most notably, this includes upgrades to the following most critical libraries:
pulldown-cmark v0.8.0 -> v0.9.0
pulldown-cmark-to-cmark v7.1.1 -> v9.0.0
In total, these dependencies were upgraded:
bstr v0.2.16 -> v0.2.17
ignore v0.4.17 -> v0.4.18
libc v0.2.101 -> v0.2.112
memoffset v0.6.4 -> v0.6.5
num_cpus v1.13.0 -> v1.13.1
once_cell v1.8.0 -> v1.9.0
ppv-lite86 v0.2.10 -> v0.2.16
proc-macro2 v1.0.29 -> v1.0.36
pulldown-cmark v0.8.0 -> v0.9.0
pulldown-cmark-to-cmark v7.1.1 -> v9.0.0
quote v1.0.9 -> v1.0.14
rayon v1.5.0 -> v1.5.1
regex v1.5.3 -> v1.5.4
serde v1.0.130 -> v1.0.132
syn v1.0.75 -> v1.0.84
unicode-width v0.1.8 -> v0.1.9
version_check v0.9.3 -> v0.9.4
Bump serde_yaml from 0.8.21 to 0.8.23 (#52) [dependabot[bot]]
Bumps serde_yaml from 0.8.21 to 0.8.23.
updated-dependencies:
dependency-name: serde_yaml dependency-type: direct:production update-type: version-update:semver-patch ...
Bumps pulldown-cmark-to-cmark from 7.1.0 to 7.1.1.
Bumps pulldown-cmark-to-cmark from 7.0.0 to 7.1.0.
Bumps pulldown-cmark-to-cmark from 6.0.4 to 7.0.0.
Bumps pathdiff from 0.2.0 to 0.2.1.
Bumps pulldown-cmark-to-cmark from 6.0.3 to 6.0.4.
Bumps pretty_assertions from 0.7.2 to 1.0.0.
Bumps serde_yaml from 0.8.20 to 0.8.21.
This was caught by a recently introduced clippy rule
Bumps serde_yaml from 0.8.17 to 0.8.19.
Bumps regex from 1.4.6 to 1.5.3.
Bumps pretty_assertions from 0.7.1 to 0.7.2.
Bumps regex from 1.4.5 to 1.4.6.
Postprocessing support. [Nick Groenen]
Add support for postprocessing of Markdown prior to writing converted notes to disk.
Postprocessors may be used when making use of Obsidian export as a Rust library to do the following:
Context, for example to change the destination
filename or update its Frontmatter.MarkdownEvents.For example, a future release might include functionality to make notes more suitable for the Hugo static site generator. This functionality would be implemented as a postprocessor that could be enabled through command-line flags.
Also percent-encode ? in filenames. [Nick Groenen]
A recent Obsidian update expanded the list of allowed characters in
filenames, which now includes ? as well. This needs to be
percent-encoded for proper links in static site generators like Hugo.
Bump pretty_assertions from 0.6.1 to 0.7.1. [dependabot[bot]]
Bumps pretty_assertions from 0.6.1 to 0.7.1.
Bump walkdir from 2.3.1 to 2.3.2. [dependabot[bot]]
Bumps walkdir from 2.3.1 to 2.3.2.
Bump regex from 1.4.3 to 1.4.5. [dependabot[bot]]
Bumps regex from 1.4.3 to 1.4.5.
--version flag. [Nick Groenen]Don't Box FilterFn in WalkOptions. [Nick Groenen]
Previously, filter_fn on the WalkOptions struct looked like:
pub filter_fn: Option<Box<&'static FilterFn>>,
This boxing was unneccesary and has been changed to:
pub filter_fn: Option<&'static FilterFn>,
This will only affect people who use obsidian-export as a library in other Rust programs, not users of the CLI.
For those library users, they no longer need to supply FilterFn
wrapped in a Box.
Recognize notes beginning with underscores. [Nick Groenen]
Notes with an underscore would fail to be recognized within Obsidian
[[_WikiLinks]] due to the assumption that the underlying Markdown
parser (pulldown_cmark) would emit the text between [[ and ]] as
a single event.
The note parser has now been rewritten to use a more reliable state machine which correctly recognizes this corner-case (and likely some others).
Support self-references. [Joshua Coles]
This ensures links to headings within the same note ([[#Heading]])
resolve correctly.
Avoid redundant "Release" in GitHub release titles. [Nick Groenen]
Add failing testcase for files with underscores. [Nick Groenen]
Add unit tests for display of ObsidianNoteReference. [Nick Groenen]
Add some unit tests for ObsidianNoteReference::from_str. [Nick Groenen]
Also run tests on pull requests. [Nick Groenen]
Apply clippy suggestions following rust 1.50.0. [Nick Groenen]
Fix infinite recursion bug with references to current file. [Joshua Coles]
Add tests for self-references. [Joshua Coles]
Note as there is no support for block references at the moment, the generated link goes nowhere, however it is to a reasonable ID
Bump tempfile from 3.1.0 to 3.2.0. [dependabot[bot]]
Bumps tempfile from 3.1.0 to 3.2.0.
Bump eyre from 0.6.3 to 0.6.5. [dependabot[bot]]
Bumps eyre from 0.6.3 to 0.6.5.
Bump regex from 1.4.2 to 1.4.3. [dependabot[bot]]
Bumps regex from 1.4.2 to 1.4.3.
Find uppercased notes when referenced with lowercase. [Nick Groenen]
This commit fixes a bug where, if a note contained uppercase characters
(for example Note.md) but was referred to using lowercase
([[note]]), that note would not be found.
Add --no-recursive-embeds to break infinite recursion cycles. [Nick Groenen]
It's possible to end up with "recursive embeds" when two notes embed
each other. This happens for example when a Note A.md contains
![[Note B]] but Note B.md also contains ![[Note A]].
By default, this will trigger an error and display the chain of notes which caused the recursion.
Using the new --no-recursive-embeds, if a note is encountered for a
second time while processing the original note, rather than embedding it
again a link to the note is inserted instead to break the cycle.
See also: https://github.com/zoni/obsidian-export/issues/1
Make walk options configurable on CLI. [Nick Groenen]
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.
Support links referencing headings. [Nick Groenen]
Previously, links referencing a heading ([[note#heading]]) would just
link to the file name without including an anchor in the link target.
Now, such references will include an appropriate #anchor attribute.
Note that neither the original Markdown specification, nor the more recent CommonMark standard, specify how anchors should be constructed for a given heading.
There are also some differences between the various Markdown rendering implementations.
Obsidian-export uses the [slug] crate to generate anchors which should be compatible with most implementations, however your mileage may vary.
(For example, GitHub may leave a trailing - on anchors when headings
end with a smiley. The slug library, and thus obsidian-export, will
avoid such dangling dashes).
Support embeds referencing headings. [Nick Groenen]
Previously, partial embeds (![[note#heading]]) would always include
the entire file into the source note. Now, such embeds will only include
the contents of the referenced heading (and any subheadings).
Links and embeds of [arbitrary blocks] remains unsupported at this time.
Print warnings to stderr rather than stdout. [Nick Groenen]
Warning messages emitted when encountering broken links/references will now be printed to stderr as opposed to stdout.
Correct relative links within embedded notes. [Nick Groenen]
Links within an embedded note would point to other local resources relative to the filesystem location of the note being embedded.
When a note inside a different directory would embed such a note, these links would point to invalid locations.
Now these links are calculated relative to the top note, which ensures these links will point to the right path.
Report file tree when RecursionLimitExceeded is hit. [Nick Groenen]
This refactors the Context to maintain a list of all the files which have been processed so far in a chain of embeds. This information is then used to print a more helpful error message to users of the CLI when RecursionLimitExceeded is returned.
Add extra whitespace around multi-line warnings. [Nick Groenen]
This makes errors a bit easier to distinguish after a number of warnings has been printed.
Setup gitchangelog. [Nick Groenen]
This adds a changelog (CHANGES.md) which is automatically generated with [gitchangelog].
Allow custom filter function to be passed with WalkOptions. [Nick Groenen]
Re-export vault_contents and WalkOptions as pub from crate root. [Nick Groenen]
Run mdbook hook against README.md too. [Nick Groenen]
Update installation instructions. [Nick Groenen]
Installation no longer requires a git repository URL now that a crate is published.
Add MdBook generation script and precommit hook. [Nick Groenen]
Add more reliable non-ASCII tetscase. [Nick Groenen]
Create FUNDING.yml. [Nick Groenen]