Obsidian-export - A rust library and CLI to export an Obsidian vault to regular Markdown

Over the past few weeks I’ve been working on an exporter for Obsidian’s custom Markdown dialect in my spare time.

While I really love Obsidian and plan on using it for many years to come, I want to ensure that I can really get my data out again with all of my links and references intact, which obsidian-export now allows me to do (mostly - a few pieces of Obsidian syntax aren’t supported).

In addition, I also wanted to be able to build a Git (+GitHub Actions) publishing pipeline for MkDocs to publish select notes in a way that gives me more flexibility and control than what Obsidian Publish offers right now (at the obvious cost of having to wire everything up yourself, and losing a couple of other features in the process - so don’t see this as a Publish replacement, but rather a DIY alternative).

While there’s still a lot of rough edges I want to address, I’m releasing it to the public now rather than trying to get everything perfect from day one.

It’s only been tested on Linux, but automated tests seem to show it even runs on Windows. :grinning:

If you’re interested, you can find code and installation instructions on GitHub: https://github.com/zoni/obsidian-export. And if you end up running this on your own vault, I’d love to hear your experiences!

9 Likes

Thanks for the exporter Zoni!

It feels amazing to have our data totally free :slight_smile:

1 Like

I’ve just released v0.5.0 of obsidian-exporter, the biggest update since open sourcing this project about a month and a half ago.

From the changelog:

v0.5.0 (2021-01-05)

New

  • 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.

Changes

  • 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.

Other

  • Include filter_fn field in WalkOptions debug display. [Nick Groenen]
4 Likes

I am very happy with obsidian-export. I use it mostly for my created “meta notes” in which a multitude of notes are included with ![[xxx]]. Obsidian-export includes those notes in the “freshly created vault”. pandoc is then used to convert one of the meta notes into a word document (necessary for others). Feed back on the word document is used to enhance the original notes and the process is iterated until the word document stands on its own. The final document is pandoced to latex and finally into a pretty PDF.

This is an awesome workflow to create reports, papers, …, and avoid using word too much and still work with others that do use word and at the end of the day get a good result!

And it is lightning fast too! Well done @zoni!

1 Like

It’s really great to hear how others use this, helps keep me motivated to work on it. Thanks for taking the time to write up your experiences!

1 Like

@zoni thank you kindly for this tremendous work! I am doing technical documentation.

Using mac on M1 processor, installed through

brew install rust

and

cargo install obsidian-export

and it worked like magic! Kudos to the streamlined process.

Still looking for similar solution as @jonastidstrom for workflow in a small team.

  1. edit in obsidian 2. export with obsidian-export 3. open “marked 2” to export individual pages to printable PDF with page numbers, headers and footers or, ideally to some collaborative word processing like goodle docs or similar

The only two features in Obsidian, which are missing are:

  • ![[included_file]] include file with custom format, ideally a single word or paragraph inclusion. Sadly, this is not standard Markdown.
  • page numbers in PDF export / customized headers / footers

Once again, thank you for your effort.

1 Like