Collective PDF rendering environment (work-in-progress)
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
decentral1se faa4c25ccc
fix: use PAD_URL in template files
5 days ago
snapshots oops double 8 months ago
static chore: strip/clean with auto-formatter 6 days ago
templates fix: use PAD_URL in template files 5 days ago
Makefile fix: don't error out if .venv exists when setting up 6 days ago refactor: override config from env 6 days ago fix: use PAD_URL in template files 5 days ago
requirements.txt chore: sort requirements 6 days ago



Octomode is a collective editing space for PDF making, using Etherpad, Paged.js and Flask.

How to use Octomode?

If you want to work collectively on making a PDF, you can use octomode. There is an instance installed here: You can write any name of in the input field, this will create a new octomode environment.

Working in octomode includes:

  • pad: all materials for the PDF are collected here. (written in Markdown)
  • stylesheet: all CSS rules for the PDF are collected here (written in CSS)
  • html: render the lay out as a HTML (rendered with PyPandoc)
  • pdf: render the lay out as a PDF (rendered with Paged.js)

When creating a new environment, a few things happen:

  • a pad is created for collecting the materials of your PDF. The name of the octomode environment will become the name of this pad. For example:
  • another pad is created for writing the stylesheet of your PDF. The name of the octomode environment will become the name of this pad, followed by .css. For example:
  • If both pads were not created yet, a template is added to the pad. The main pad will get a Markdown template and the stylesheet pad a CSS template.

In case a pad was already made, you can copy the templates below and paste them at the top of your pads.

The PDFs are rendered using Paged.js, a free and open source JavaScript library "that paginates content in the browser to create PDF output from any HTML content. This means you can design works for print (eg. books) using HTML and CSS!" The project is maintained by the Coko Foundation. Paged.js adds features to the CSS3 standards, expanding the possibilities to make lay outs for specific sections, place content in the margins of pages, and render indexes (amonst other things). The documentation is very ufesul and can be found here:

Octomode Markdown template

title: tentacular thinking
language: en

# tentacular thinking

Octomode CSS template

@charset "utf-8";

    size: A5;

    background-color: pink;

    color: green;

    page-break-after: always;


When working with multiple people on one PDF it is recommended to use the same browser. CSS rules are rendered slightly differently on different browsers.


Octomode resonates other software practices based on pad-to-PDF workflows or collective infrastructure, including:

Use octomode locally

You can clone this repository to run octomode on your own computer or server.

git clone

cd octomode

make setup (sets up a virtual environment and install the requirements, you only need to do this once)

Then you can configure your environment:

  • OCTOMODE_PORTNUMBER: optional, default: 5001
  • OCTOMODE_PAD_URL: optional, default:
  • OCTOMODE_PAD_API_URL: optional, default:
  • OCTOMODE_PAD_API_KEY: required, no default

You must provide a value for OCTOMODE_PAD_API_KEY.

You can do this by passing the values on the command-line before running octomode:


make run (runs the Flask application)

Open the application at http://localhost:5001.


python dependencies are listed in requirements.txt

To install them, you can run:

make setup


It's recommended to use Firefox when working with octomode locally. Chrome or Chromium do not load external etherpads in iframes.

Use octomode on a server

  • Configure the webserver to listen to the port of the flask application, for example with a subdomain
  • Expand the current https certificate for a subdomain
  • Restart nginx (sudo service reload nginx)
  • To keep the flask application running in the background: add a new config to supervisor (cp /etc/supervisor/conf.d/previousexample.conf new.conf)
  • Restart supervisor (sudo service reload supervisor)