It would be nice to have code blocks; this doesn’t exist.

I hoped em dashes would only be inserted as double-hyphens — are they? (no, they’re still magic hyphens)

Finally, we’ll publish with Ctrl+Enter.

#WriteFreely

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

Bold some text. New line and funky spacing ksjfdwkl

#WriteFreely #test

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

Bold some text.\ New line\ and funky spacing ksjdf

#WriteFreely #test

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

Hashtagged posts will show up in searches from the fediverse (when someone on your instance follows your blog), and you can @-mention someone to send them a notification and continue the conversation.

Comments? Let me know @matt@writing.exchange.

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

I’m now writing with that editor. (You can view the raw output here.)

It’s built on ProseMirror, and gives you a more classic writing experience while converting everything to Markdown (as WriteFreely understands) behind the scenes.

It also auto-saves, just like any other standard editor that comes with WF. I’ve refreshed the page a few times (saving everything to the clipboard first) and it’s always sucessfully loaded. This is the most basic requirement for our editors, so that’s great!

Some issues

It does seem to insert magic quotes in the editor (“ instead of “), which is not what we want — that happens automatically on the rendering side, which is good (it seems to do it for em-dashes too).

I’m not sure if our shortcodes will work, like <!—more—> — especially with the auto-em-dash stuff.

Also, the scroll bar is right next to the text instead of outside the text area padding, which is un-ideal, but fine.

Poetry\ probably\ b r e a k s\ (It doesn’t completely! But the spaces before “breaks” gets removed when going back into the editor to update the post.)

Ctrl+K should add a link to the selected text. Also “Target” in that modal is confusing even to me. Hopefully we can fix that.

The editor doesn’t render HTML.

The editor inserts a backslash on the following before the first # symbol, preventing the hashtag from activating.

#WriteFreely #wfdev

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

Overview

Building a new editor involves a few steps:

1. Create a new editor template file in the templates/ directory
2. Implement the editor
3. Set editor = TEMPLATE_NAME in your configuration file
4. 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.

[
  {
    "title": "Optional Post Title",
    "slug": "optional-post-title",
    "body": "Entire post content, in Markdown or HTML, including any images and #hashtags.\n\nNote: newlines should be preserved in this field, even when using HTML.",
    "font": "serif",
    "lang": "en",
    "rtl": false,
    "created": "2006-01-02T15:04:05Z"
  }
]

These field names map directly to the API — you can read details in the API documentation. Otherwise, a few notes:

• The slug should contain only alphanumerics and hypens. Any invalid characters will be automatically converted.

• The body property should include all original markup (HTML) and Markdown, with newlines (WriteFreely respects and requires newline literals). Note: Getting as close to Markdown / plain text as possible here is ideal, as it provides the best editing and data export experience. But WF will render HTML.

• Include any categories or tags as #hashtags, inline in the body. To make it look nice, you might append any to the end of the post, separated from the post body by \n\n.

• Supply a created time, in the RFC3339 format (shown above) and converted to the UTC timezone, to preserve original publish date and time.

In this format, we can trivially loop through the array of objects and POST each one directly to the WriteFreely API — creating either drafts or blog posts.

#WriteFreely #import #dataMigration

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

First, personally, I took a step back from almost everything in June — I needed to spend more time around other people, friends and family, and less time thinking about code. But when I was in front of a computer, I had my focus on the new “collaborative blogs” feature we recently launched on Write.as. This was a crucial step for us as we work toward sustainability as a project.

Now I'll be addressing bug reports and pull requests over the next several days / week. Keep an eye on the GitHub repo and @writeas_dev@abunchtell.com for updates!

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

We'll support three different OAuth providers in v0.12, thanks to Nick Gerakines who laid all the OAuth groundwork and support for Write.as & Slack, and Kyle Robbertze who added GitLab support.

This development was initially driven by our Write.as for Teams service. Since Teams customers need a Write.as account for spinning up an instance and managing billing, the extra step of creating another account in WriteFreely caused plenty of confusion. Our Write.as OAuth integration helped alleviate that — and paired with Slack sign-in, now entire teams can easily join a WF instance.

Aside: It's entirely possible that our locked-down “Write.as” provider will change into a generic “WriteFreely” provider in the future, if it makes sense for WF to become an OAuth provider. Especially with more federation capabilities on the reading side, multiple WF instances and identities hosted in WF could make more sense.

Thoughts or ideas? Let me know @matt@writing.exchange.

Next, with the start of the Debian Social team, Kyle approached us about utilizing their GitLab instance for user authentication. The timing couldn't have been better, and we were able to collaborate and merge his work on #277 in time for this next release!

Adding a new provider

Now that the basics are there, we'd love to support new OAuth providers that will make it easier for WF communities to grow. While not completely seamless today, fortunately the work is pretty straightforward, whether you know Go or not.

I wrote a step-by-step guide on how to modify WriteFreely for this over on the forum. Even if you haven't worked with Go before, as long as you can set up your development environment and copy some existing code, you can add a new provider.

As mentioned in that forum topic, we're more than happy to accept new providers that'll help you and benefit many other people. So don't be afraid to reach out to us about your use case, and contribute new code for this.

#wfdev

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

• Dates on blog posts. It's been missing for years. They'd show on the blog home page, but not blog posts. Well, this is no longer the case. Soon, posts on blogs that use the Blog display format will consistently show dates both on their home page and individual posts. Other display formats will continue not showing dates, because that's exactly what they're there for: not showing dates.
  • Also, dates are now correct, relative to your device's timezone!
• <table> style. These elements were previously unstyled. Now they'll have some improved, basic styling that you can easily override with custom CSS. See #194.
• Consistent user page headers. User pages (Blogs, Drafts, Account Settings, etc.) were all over the map with their headers. I'd start using a new style on new pages and not update the old ones. Well, now that's fixed in #262. Write.as users will notice this change is already live.
• Slightly more line height. We've added 10% more space between lines of text. It's perhaps too small to really notice, but large enough to make a nice improvement. Changes in #263.

On the admin side, we're redesigning the dashboard to make it much more user friendly, and optionally less technical, in cases where an instance is in a hosted environment and the admin doesn't care about getting into the weeds. See #264. We need this change in Write.as for Teams, but it should also prove helpful for other WriteFreely hosts.

Particularly since these are visible changes that affect users, we want your feedback! Please jump into those pull requests on GitHub, try things out, and let us know what you think. We want to be sure people are happy with these upcoming changes before they get released to everyone.

#wfdev #design #WriteFreely

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