Creating a New WriteFreely Editor

August 31, 2020

WriteFreely allows instance admins to choose the writing experience their users enjoy. This guide will walk you through building and integrating a new editor.

Overview

Building a new editor involves a few steps:

Create a new editor template file in the templates/ directory
Implement the editor
Set editor = TEMPLATE_NAME in your configuration file
Start WriteFreely

Background

In the vast majority of cases, creating a new editor will only involve client-side work. You do not need to build WriteFreely; you can simply download the latest version, create a new template file, and configure your instance to use the new editor.

WriteFreely uses Go's text/template and html/template libraries for templating. You can find more information about syntax on those help pages.

Prior Art

Today, WriteFreely has two editors to choose from:

pad (default)
bare

We recommend looking at these files for help in implementing your own editor.

Getting Started

To start, we'll copy the pad.tmpl template and then modify it to meet your needs. For illustrative purposes, we'll call this new file fancy.tmpl throughout this tutorial.

Writing UX

At minimum, you'll want to allow the user to submit a new post, containing a title and a body. The user should be able to load an existing post into the editor, modify it, and publish any updates. Lastly, the editor should automatically save via localStorage (details below).

A very basic editor looks like the one you'll find in pad.tmpl (source):

<textarea id="writer" placeholder="Write..." class="{{.Post.Font}}" autofocus>{{if .Post.Title}}# {{.Post.Title}}

{{end}}{{.Post.Content}}</textarea>

This single template is used for both new and existing posts. When a user is editing a post, the {{.Post}} struct will be populated (containing these fields). Otherwise it and all of its fields will be empty / evaluate to false, as dictated by the text/template library.

In the case of our bare minimum editor, when editing a post:

The textarea uses the post's chosen font as its CSS class, ensuring that text renders in the correct font (relevant CSS here).
If the post has a title ({{if .Post.Title}}), it inserts a Markdown H1 header (# {{.Post.Title}}) and two line breaks.
Finally, it fills in the rest of the textarea with the raw contents of the post ({{.Post.Content}})

Combine these basic elements to populate the editor when editing a post.

Auto-save

In pad.tmpl, drafts are automatically saved while a user types (relevant lines).

TODO: details

Publishing

TODO

Testing

Assuming a template file named fancy.tmpl, you'll now set editor = fancy in your configuration file. Finally, run WriteFreely and log in to see the new editor in action.

#WriteFreely

Get future updates via RSS and ActivityPub: @devlog@matt.writefreely.dev.