Skip to content

Pad migration guide from etherpad-lite

The goal of this migration is to do a "dumb" import from all the pads in Etherpad, to notes in HedgeDoc. In particular, the url locations of the pads in Etherpad will be lost. Furthermore, any metadata in Etherpad, such as revisions, author data and also formatted text will not be migrated to HedgeDoc (only the plain text contents).

Note that this guide is not really meant as a support guide. I migrated my own Etherpad to HedgeDoc, and it turned out to be quite easy in my opinion. In this guide I share my experience. Stuff may require some creativity to work properly in your case. When I wrote this guide, I was using etherpad 1.7.0 and codimd 1.2.1. Good luck!

0. Requirements

  • curl
  • running Etherpad server
  • running HedgeDoc server
  • hedgedoc-cli

1. Retrieve the list of pads

First, compose a list of all the pads that you want to have migrated from your Etherpad. Other than the admin interface, Etherpad does not have a dedicated function to dump a list of all the pads. However, the Etherpad wiki explains how to list all the pads by talking directly to the database.

You will end up with a file containing a pad name on each line:


2. Run the migration

Download hedgedoc-cli and put the script in the same directory as the file containing the pad names. Add to this directory the file listed below, I called it Modify at least the configuration settings ETHERPAD_SERVER and HEDGEDOC_SERVER.


# Description: Migrate pads from etherpad to HedgeDoc
# Author: Daan Sprenkels <>

# This script uses the HedgeDoc command line script[1] to import a list of pads from
# [1]:

# The base url to where etherpad is hosted

# The base url where HedgeDoc is hosted

# Write a list of pads and the urls which they were migrated to

# Fail if not called correctly
if (( $# != 1 )); then
    echo "Usage: $0 PAD_NAMES_FILE"
    exit 2

# Do the migration
for PAD_NAME in $1; do
    # Download the pad
    curl "$ETHERPAD_SERVER/p/$PAD_NAME/export/txt" >"$PAD_FILE"

    # Import the pad into HedgeDoc
    OUTPUT="$(./hedgedoc import "$PAD_FILE")"

Call this file like this:

./ pad_names.txt

This will download all the pads in pad_names.txt and put them on HedgeDoc. They will get assigned random ids, so you won't be able to find them. The script will save the mappings to a file though (in my case redirects.txt). You can use this file to redirect your users when they visit your etherpad using a 301 Permanent Redirect status code (see the next section).

3. Setup redirects (optional)

I got a redirects.txt file that looked a bit like this:

date-ideas -> Found. Redirecting to
groceries -> Found. Redirecting to
london -> Found. Redirecting to
weddingchecklist -> Found. Redirecting to

Using some sed magic, I changed it to an nginx config snippet:

location = /p/date-ideas {
    return 301;
location = /p/groceries {
    return 301;
location = /p/london {
    return 301;
location = /p/weddingchecklist {
    return 301;

I put this file into my nginx config, such that all the users would be redirected accordingly.