Add information on migrating Zettlr notes to a new computer or OS-install.

[zettlr]

Add information on migrating Zettlr notes to a new computer or OS-install.

[nathanlesage]

Please feel free to amend the documentation accordingly, basically you don't have to do anything to preserve your information. There are a few files you'd maybe want to backup, described here in the documentation: https://docs.zettlr.com/en/troubleshooting/#3-try-resetting-the-app

[wideaperture]

Hi @nathanlesage! Thanks so much for this. I've taken a crack at putting together a documentation section on migrating to a new machine — see below. I did have a question about a couple of the .json files that the doc you linked to discusses. I'm not certain whether these two should be backed up when moving Zettlr. To wit:

• stats.json — Wouldn't the information in this file be repopulated once the user adds their old workspaces and notes to the new install? If so, does it need to be moved? And if not, is there data in the file that would create conflicts or confusion with the data produced when the user adds those workspaces and notes?_

• config.json — Since the workspaces and files the user is adding from their old computer may well live in different locations on the new machine, is it better not to import this file? Is there data that's lost if they don't? Or would any missing data simply be repopulated when the user adds their old workspaces and files to the new install?

If copying those files over to a new machine isn't advisable, they can just be removed from the doc below. Feel free to edit, amend, discard, or perform any quality control you wish on what follows.

---

Migrating Your Zettlr Workspaces to a New Computer

If you're taking full advantage of Zettlr's functionality, you'll eventually create an extensive library of workspaces and interconnected notes. And, when the time comes to replace your computer, or perhaps migrate to a new operating system, you'll obviously want to take this data with you.

You'll be pleased to know that this is a straightforward process, which typically involves three steps:

1. Copying your application settings to the new machine.
2. Copying the workspaces containing your notes to the new machine.
3. Reconnecting your reference manager.

Copying Your Application Settings to the New Machine

If you've customized Zettlr at all and/or you want to retain the various stats about your notes, there are a few configuration files that you may want to back up and copy over to your new machine. This data is located in the application data path whose location depends on your Operating System:

• Windows: C:\Users\<your username>\AppData\Roaming\Zettlr (note that AppData is a hidden folder, so you might want to change the Explorer settings so it shows up)
• macOS: /Users/<your username>/Library/Application Support/Zettlr (open a Finder window, hold down "Alt" while opening the "Go"-menu, and click on the appearing "Library" entry)
• Linux: /home/<your username>/.config/Zettlr (note that .config is a hidden folder, so you might want to use a command line to open it)

Once you've located this folder, save a copy of the following files within it to move to your new machine:

• stats.json (your writing statistics)
• config.json (the app settings — including the location of your workspaces and open files)
• custom.css (your custom CSS, if any)
• tags.json (your colour-coded tags)
• targets.json (your writing targets)
• user.dic (your own custom dictionary)

Once you've installed Zettlr on your new computer and launched it for the first time, the software will create a new application path folder (see above). At this point, close the application and copy the backup files above into the newly created folder. If you're prompted as to whether it's okay to replace existing files, you can say "okay." You've now copied over the application settings from your old computer.

Copying the Workspaces Containing Your Notes to the New Machine

Because Zettlr workspaces are simply folders on your computer and your notes are simply text files, moving this data to a new computer is as simple as copying these folders from one computer to the next. All of the metadata about your notes and the connections between them — note IDs, tags, etc. — is saved to the individual note files themselves, meaning this information travels right along with the files.

Once you've copied the workspace folders containing your notes from your old computer and placed them on the new machine, you can add each workspace and its files to your new Zettlr install simply by going to the File > Open Workspace … menu option and selecting the that workspace folder. Note that this is the same process you would use you if were adding any other folder to Zettlr. The workspace folder, the notes it contains will immediately be populated into your new Zettlr install. The connections between notes will also be retained, though if you have links to notes that live in different workspaces, you'll have to make sure you've likewise opened those workspace folders and their contents within your new Zettler install.

Reconnecting Your Reference Manager

Finally, if you're using Zettlr with a reference manager like Zotero, you'll need to go through that software's migration process. Once your reference manager is up and running again on the new machine, you can reconnect it to Zettlr by once again following the steps in the "Enabling Citations in Zettlr" portion of this documentation.

[wideaperture]

Proofread the doc and amended it based on the info provided on Discord. I've now added it to Github and proposed it as a new file, since I didn't see a straightforward place to add it to an existing doc.

[nathanlesage]

I think that looks perfect and should work like this. Any invalid path will be purged from the config so that the remaining config will be retained. I would say we can add this to the docs!

[wideaperture]

Thanks much! The aforementioned PR should now be in the system. I'd forgotten to hit "confirm" previously and realized I hadn't committed it.