If you want to backup your Roam graph to Markdown instead of EDN files, this guide is what you're looking for. Markdown files are plain text files that can read by most note-taking apps and text editors.
This walkthrough has been developed from the process described by Quinten Lockefeer in a Medium article. The process uses Mathtieu Bizien’s roam-to-git code, enabling you to create backups at any interval that you want.
Process summary
- The backup process will be using Matthieu Bizien’s roam-to-git code, which is hosted on GitHub.
- Your backups will be saved in a Github repository.
- You need to configure this repository to allow it to log in to your Roam database and take backups.
- You then set up a workflow that will take regular backups of your Roam database.
- You can then access these backups to look at or download.
Action steps
- Set up a GitHub account or login to your existing one.
- Create a new repository.
- Add in the details of your Roam database and your login information.
- Create a GitHub Action with the roam-to-git code to run the backup process.
- Check that the process is working.
Step 1: Creating a new account/logging in
If you don’t have a GitHub account, create one at GitHub.com.
On the next screen, you’ll be asked to fill in details about yourself: your type of work, your programming experience and your use for GitHub. Then, click on Complete set up. You will then receive a verification email. When you click the link in it, you return to GitHub. On the initial screen, click on Create a repository button:
If you already have a GitHub account, log in. To create a new repository, click on the green New button in the Repositories areas:
Step 2: Setting up a new repository
Whether you have just set up a GitHub account or you have logged into an existing account, you will then arrive at the Create a new repository page.
- a) Add in the name for your repository — ‘notes’ would be fine or ‘backups’.
- b) Click on Private. It is critical you do this, otherwise your backups become public.
- c) Click on Create repository to set it up. You should leave the Initialize this repository with a README checkbox empty.
Step 3: Adding in your Roam login information
If you’ve logged out and are coming back to this process, log back in and click on the relevant repository.
Then click on Settings. If you’re carrying on from Step 2, also click on Settings.
Click on Secrets in the left menu.
You now need to add in your Roam account email, your Roam account password and your Roam database name by creating three New Secrets. So, before you continue, please ensure you have all these details to hand. You can find the names of all your Roam databases (or graphs) in the top corner of the left-hand sidebar of your Roam database.
If the left-hand sidebar is not showing, click on the three lines icon to expand it.
Click on New Secret.
Then the following window will open:
- In Name, enter ROAMRESEARCH_DATABASE
- In Value, fill in your database’s name
- Click on Add secret.
Click on New Secret again (see above).
- In Name, enter ROAMRESEARCH_USER
- In Value, enter your Roam account email address
- Click on Add secret.
Click on New Secret again (see above).
- In Name, enter ROAMRESEARCH_PASSWORD
- In Value, fill in your Roam account password
- Click on Add secret.
When you’ve finished this is what your Secrets page should look like this:
Step 4: Creating a GitHub Action to run the backup process
Now you need to set up an Action so that the backup process runs. In the top navigation bar of your repository, click on Actions:
b) in the window that opens, click on the set up a workflow yourself link:
You will then see code for main.yml. Select all the existing code and delete it:
In a new browser tab or window, go to this page and copy the code:
Go back to your GitHub repository and paste the code in the main.yml window:
Click on Start commit and then Commit new file:
Your screen should now look like this:
Your Roam database backup should now run hourly. You can change the time periods by altering the following code cron: "0 * * * *". Please do a search for information about the cron function if you would like to do this.
Step 5: Verification of process
If you go back to the Actions tab a few hours after you have set the workflow up, you will see that the Roam Research backup process has been actioned:
Occasionally, you may get emails from GitHub saying that a backup run has failed. There is nothing to worry about unless you are getting these continually. In that case, you should investigate further.
Step 6: Accessing your backups
Viewing your backups on GitHub
If you go to the code tab, you will see three backup directories:
- formatted
- json
- markdown
The formatted directory includes markdown files of individual Roam pages with clickable links to other pages:
However, there seems to be a limit of 1,000 pages for viewing. So, if you have more than 1,000 pages, you will need to download the backup to view them:
Downloading your current backup
To download your current backup, click on the green Code button in the Code tab and then click on Download ZIP in the dropdown. You can then save the file to your hard drive.
Downloading previous backups
To download a previous backup, click on the commits link in the Code tab. It is not obvious it is a link until you hover your mouse over it. (Obviously the number of commits recorded here will depend on how long you have been doing the backups.)
Find the particular backup you want to download and click on angle brackets:
Click on the green Code button and then click on Download ZIP in the dropdown:
Join the conversation.