Migrating from zkn3 to obsidian without losing your tags and internal links: documentation

Edit: I have finally developed a detailed workaround for the problems described in this post which was originally formulated as a question. See my post below

As mentioned earlier, I have been working for years with Daniel Lüdecke’s wonderful zkn3-Zettelkasten. Although from its very philosophy I still think it is - to date - maybe the best digital implementation of a Luhmann-like workflow, I finally decided to give it up for several reasons (among others, stagnating development, lack of interoperability, lack of a lively community) and move all of my zettels to my obsidian vault.

Although zkn3 meanwhile uses markdown syntax as default for writing notes, the notes are not stored in separate text files but in a single archive (consisting of several xml files) where each zettel has its unique ID. The xml file is structured in a way similar to a bib file: the information about a specific note starts with the zettel UID, followed by several categories that hold the relevant information (including links to other notes, keywords, the actual text of your zettel etc.).

Thus, when you link from one zettel to another note, the link in the editor view looks like this:

So each internal link is started by something like [z 225] - where the number points to the unique zettel id. The word “control” in the above example is not necessarily the title of the note but can be chosen individually (comparable to what follows the |sign in a typical wikilink).

You can export your complete zkn3 to single markdown files - yet, these internal links won’t be transformed to markdown or wiki links. This basically means that when I migrate my zettelkasten to obsidian, all the internal links I have established over years to connect my notes completely disappear. Of course they are not lost - when opening the note, I still see the zettel number my former link was pointing to. As the markdown export stores your notes as files named "zettel number - note title" I can do an easy search for the file with the respective number in its title and then replace the old link. Yet, with a zkn3 database that consists of several thousand notes this actually requires way too much work - although my information doesn’t get lost, I have to edit all of them step by step in order to be able again to use them as a real knowledge base.

This problem is reinforced by the fact that even my tags (and actually tagging in zkn3 is the core of linking) cannot be exported in a way that they are recognized as tags by obsidian. Means, they are not exported as #tag but as a simple list following a h2-heading named “null”:


So my final question is:

Has anyone already migrated from zkn3 to obsidian (or any other markdown editor)?

  • What was your migration workflow?
  • Have you found any workarounds making migration easier?
  • Any ideas if there could be a working automation of replacing zkn3 links with wiki or markdown links? (Kind of grep-regex combination, for example)?
1 Like

After spending a couple of hours on this topic again, I found at least an easy solution to the first problem (transforming zkn3-links into wiki-links - doesn’t probably work on Windows though…).

If anybody has the same problem and is interested in the solution, just tell my and I can describe it in detail!

Update: Found a (actually quite obvious…) solution to the tagging question as well! :slightly_smiling_face:

Great topic, always good to add to the migration knowledge base. I’m going to move this to #knowledge-management.

Thank you @sam.baron - as I think sooner or later anyone might be interested in the process I developed today, I will describe it here in detail:

Be aware that this, as mentioned above, is a solution for Linux OS and might possibly work on MAC as well!

If you want to migrate from zkn3-zettelkasten without losing your internal links and your tags, use the following documentation. The sequence of the single steps is important - otherwise your migration experience might end up in a mess…

  1. First we have to prepare the zkn3 keywords for export:

    • If you have used some keywords that consist of several words (like for example “migration from zkn3”), replace the spaces with hyphens. Do a “Search and replace” (ctrl + r), be sure to have activated the “regular expression” field, choose only “keywords” and replace \s with -.
    • Then convert all your zettelkasten keywords in a format that obsidian can recognize as a tag. Use “Search and replace” again, be sure again to have activated the “regular expression” field and again choose only “keywords”. Then replace ^(which is the regular expression for the beginning of the line) with #.
    • Having both done, your former tag “migration from zkn3” should now look like “#migration-from-zkn3”.
  2. Now export your complete zettelkasten to markdown. Be sure to have activated both “export as single files” and “put zettel number before zettel heading”. Your single zettels will now be exported to markdown files named with the pattern “Number Title”, for example: “1 Title_of_my_note.md”.

  3. In order to be able to convert internal zettelkasten links to wikilinks, we first have to rename all our files such that the name only consists of the zettel number - for example “1.md”. In the terminal, we cd to the directory where we exported our files to and use the “rename” command: rename 's/\s\S+/.md/' *.md

  4. For finally converting the links in the single files, we now use “sed” in the terminal. Execute the following commands in exactly the following sequence:

  • sed -i 's/\[z\s/\[\[/g' *.md

    • this command searches in all *.md files in the current folder and replaces [z with [[
  • sed -i 's/\]/\]\]/g' *.md

    • this command replaces all ] with ]]

Now, we finished the insertion of the respective wikilinks. Whereas before the link looked like [z 1]Link to another note[\z], we now have: [[1]]Link to another note[\z]]. The first part of this is a working wikilink which takes us to the file “1.md”. Yet, as you see, we have to do some cleanup (and notice that by executing the last command the closing part of the former zkn3 link [\z]has also been replaced by [\z]]!).

Let us now remove this complete string from all our text files:

  • sed -i 's/\[\/z\]\]//g' *.md

The result will now look like [[1]]Link to another note

Yet, there is now also another problem we have to correct. By replacing all ] with ]], standard markdown links in our files have changed from [text](url) to [text]](url). We will finally correct this defective formatting:

  • sed -i 's/\]\](/\](/g' *.md

And that’s it! Finally paste all of your new *.md notes into your vault and you can work with them in obsidian - all of them being tagged and linked correctly! :slightly_smiling_face:


@alltagsverstand: amazing, impressive. I transferred all my ZKN3 notes manually, though not directly to Obsidian but via OneNote, Cherrytree, and other marldown apps before Obs existed.

Your instructions will undoubtedly be helpful to some. As for your initial comment about ZKN3, it may be the best emulation of Luhmann’s workflow, in terms of a digital zettelkasten I don’t find it useful. - my personal view.

Interesting… I think it depends for what purpose you are using it - zkn3 is surely not a note-taking app in the broader sense, it is really “just” a zettelkasten. To be sure, it took some time (I am not talking about weeks, but rather months, maybe even a year) until the zettelkasten unfolded its real power (or “started talking to you”, as Luhmann would have called it…) - but after that point my productivity in writing and thinking kind of exploded! From the view of zettelkasten methodology, I haven’t found any other program so far that includes all of it’s important features. And if zkn3 could deal with single text files, I would still use it in combination with obsidian (which is missing several of these features, though it may further develop some of them and surely brings the flexibility to establish some workarounds…).

What was it that you didn’t find useful?

This is not the platform to discuss the pros and cons of other apps, so I don’t think we should go into too much detail.

It’s been 3-4 years since I stopped using it so cannot remember all the details. What are called “keywords” I did not find intuitive to use, nor the linking. The imposed sequential numbering did seem to add value, and when you delete a note and create a new one you can reuse that deleted number. I did not like the vendor lock-in for file format, as you acknowledged. There was more. I cannot remember the exact length of time I used it, maybe not long enough because I did not experience the explosion in productivity of reading and writing.

So, maybe I am not being fair, but the apps I found the apps I used afterwards to be a lot more intuitive.

I agree - though my interest was less sparked by the fact that someone doesn’t like an app I personally loved but rather by how workflows and related to that the use of different features differ from person to person! :wink: So it can be can be a fruitful discussion within the “knowledge management” category - but there are already other threads for this… :wink:

@alltagsverstand: I agree. My comment was not meant as a criticism of yours. Also, since it is a long time ago that I moved away from ZKN3 I cannot properly remember what I did not like, so anything I say is of less value than what you can say because you are still close to it.

Thank you for your instructions. I tried cd to the directory as advised but got “DNS-Error” trying to rename the .md files. What shall I do? (Was my first time using the terminal ever so I’ve no idea what to do there.)


After trying it again, I get a new error: No more DNS-Error but “Syntax Error”.

Does the terminal give any more information?

Which OS are you using?

Windows 10 (forgot to mention). Ater pondering a while I believe now that the wildcards in Windows 10 are different (or something else is).

Does the terminal give any more information?

Today it doesn’t say more than this.

The above documentation is meant for linux (and probably might work in a similar way on Mac) - “rename” is a pure linux terminal application and not available on Windows…

On Windows, however, the “ren”-command might possibly work - have a look here.

Same problem with the “sed” command, however - you should have a look if this application (or one that does similar things) is available for Windows…

I was afraid it might turn out as something like this. I will check if it’s possible on Windows.

Thanks for your help.

Has anyone by any chance had luck transferring from zkn3 on a mac?

I cannot agree more. However I also are locked in with a few thousand zettels and still counting but on a mac…

@alltagsverstand I know this might be a push too far, but is it possible you to help me convert my zkn3 to markdown with your Linux iOS as I’m very stuck on my mac?

@KPT Have you tried my above instructions? Both “sed” and “rename” are bash commands that should work on MAC OS as far as I know (you might possibly have to install them…). If that does not work, send me a PM.

@alltagsverstand, I’ll try again… Didn’t seem to get it to work the first time around, so I have been experimenting with other solutions…
But if I don’t crack it I’ll PM…

Hi @alltagsverstand, everything worked as prescribed down to the sed part.
You where right rename had to be installed.

However sed does not it for me - it should be installed I tried also ‘sed -n ‘s/[z\s/[[/g’ *.md’ but didn’t work either. I somehow can’t figure out how to PM you, not sure if it’s somehow disabled?

I have another question for you re zkn3 vs obsidian, is the ‘note sequences’ structure kept when transferring with your method?

@KPT no, unfortunately you can’t keep your note sequences - if they are important for you, the only workaround would be to link them directly before export.

As to sed: I have no experience with working on Mac OS - there seem to be some minor differences between the way sed works on different UNIX variants - have a look here or here for example. I haven’t read the discussions so I can’t tell you if it involves a solution to your problem; this is just to demonstrate that you should search the web for the exact sed commands for Mac - maybe you can find something on this page.

If you can’t succeed - yes, I could try to transform your files. You should actually be able to PM me… :thinking: There should be a “Message” button on my profile page…

1 Like