Konstantin Ryabitsev

WriteFreely recently added support for creating and editing posts via the command-line wf tool and this functionality is available to all users at people.kernel.org.

On the surface, this is easy to use — you just need to write out a markdown-formatted file and then use wf publish myfile.md to push it into your blog (as draft). However, there are some formatting-related caveats to be aware of.

Line-breaks

Firstly, WriteFreely's MD flavour differs from GitHub's in how it treats hard linebreaks: specifically, they will be preserved in the final output. On GitHub, if you write the following markdown:

Hello world! Dis next line. And dis next line.

And dis next para. Pretty neat, huh?

GitHub will collapse single linebreaks and only preserve the double linebreak to separate text into two paragraphs. On the contrary, WriteFreely will preserve all newlines as-is. I was first annoyed by difference from other markdown flavours, but then I realized that this is actually more like how email is rendered, and found zen and peace in this. :)

Therefore, publishing via wf post will apply stylistic markdown formatting and properly linkify all links, but will preserve all newlines as if you were reading an email message on lore.kernel.org.

There's some discussion about making markdown flavouring user-selectable, so if you want to add your voice to the discussion, please do it there.

Making it behave more like GitHub's markdown

If you do want to make it behave more like GitHub's markdown, you need to make sure that:

1. You aren't using hard linebreaks to wrap your long lines
2. You are publishing using --font serif

E.g.:

  $ gedit mypost.md
  $ cat mypost.md | wf post --font serif

This will render things more like how you get them by publishing from the WriteFreely's web interface.

Using “post” and “publish” actually puts things into drafts

I found this slightly confusing, but this is not a bad feature in itself, as it allows previewing your post before putting it out into the world. The way it works is:

  $ vim myfile.md
  $ cat myfile.md | wf post
  https://people.kernel.org/abcrandomstr

You can then access that URL to make sure everything got rendered correctly. If something isn't quite right, you can update it via using its abcrandomstr preview URL:

  $ vim myfile.md
  $ cat myfile.md | wf update abcrandomstr

After you're satisfied, you can publish the post using the “move to Yourblog” link in the Drafts view.

Read the friendly manual

Please read the user guide and the markdown reference to try things out.