Elm Markup Parser

This is a parser for a markup language allows you to write content and render Elm view functions from within the markup.

This is a solution to an intersection between two problems I've had when considering existing markup languages like Markdown or Asciidoc.

1. I want to render Elm views in my markup and maintain the opportunity to make them interactive. So, that means not just static HTML.
2. All of my projects use Elm UI for handling layout and styling. I really didn't want to start duplicating style information in CSS just to style some HTML generated by Markdown or Asciidoc.

In that way, this isn't really a replacement for Markdown or Asciidoc.

Here's a taste:

| title
    My fancy cat blog article


Welcome!  Have you hear about /cats/?  They're great.

| image "http://placekitten/200/500"
    "Here's a great picture of my cat, pookie."

How much do I like cats?  A bunch.


| mycatwidget

mycatwidget is a custom block that can be defined in the config. You can choose what it actually means.

Note Why aren't title and header given special syntax? They're just like any other block! I imagine some syntax highlighting will help with the aesthetic differences compared to markdown though.

Principles

Here are the ideas I used to put this library together:

• There is one unambiguous way to construct a given element.

• This library inherits Elm's wariness of infix or symbol based operators. Instead of having a bunch of symbols and custom syntax rules to denote concepts, we can usually just use real words.

• The following should always be easy:

  • Writing markup
  • Reading markup
  • Modifying markup

• In order to do this, the parser needs to be strict about form. This means that invalid markup will make the parser fail with a nice error message instead of rendering half correct and half wonky. Think of this as "No runtime errors" but for elm-markup and layout.

• You can add custom blocks and custom inline elements, which means embedding whatever elm view you'd like. This library is about letting you be expressive in creating content, just with some ground rules about the form it will take.

• On the flip side, we avoid directly embedding any other langauges like HTML. My current feeling is that a document like this benefits hugely from being high level and embedding code can get really messy with weird details. Fortunately custom blocks are pretty convenient.

  • Unless you're putting it in the document as a code example!

Basic Text Markup

There are only a very limited set of characters for formatting text.

• /italic/ italic
• *bold* bold
• ~strike~ strike
• `code` code
• [link text](http://fruits.com) to create a link.

You can also define custom inline elements using:

• {mycustominline| some text I can style as I please }

Blocks

Everything else is marked using blocks, which begin with | and the name of the block.

Here's the beginning of a blog post with a title block, which will render as an h1, some text, and then an image, some text and a list.

| title
    My fancy blog article

Welcome.  Have you heard about /cats/?  They're great.

| image "http://placekitten/200/500"
    "Here's a great picture of my cat, pookie."

How much do I like cats?  Let's make a list.

| list
    - They're great.
    - Seriously, so great.
        - But, lists are pretty good too.

Blocks that come with the library are:

• title - The title of your document. This is equivalent to an h1. You should only have one of them.

• header - A header in your document, which is equivalent to h2.

• list - A nested list with an expected indentation of 4 spaces per level. As far as icons:

  • - indicates a bullet
  • -> indicates an arrow
  • 1. indicates it should be numbered. Any number can work.

• image - Expects two strings, first the src, and then a description of the image.

• monospace - Basically a code block without syntax highlighting.

But one of the great powers of this library is in writing custom blocks that suite your specific domain or style needs.

You can also restyle any aspect of existing or new blocks using Mark.parseWith.

Reclaiming Typography

We can also reclaim some useful typography that is a bit awkward to handle otherwise. Normal text will have the following transformations applied.

• ... is converted to the ellipses unicode character.
• " Straight double quotes are replaced with curly quotes
• ' Single Quotes are replaced with apostrophes. In the future we might differentiate between curly single quotes and apostrophes.
• -- is replaced with an en dash –
• --- is replaced with an em dash —
• <> - will create a non-breaking space ( ). This is not for manually increasing space (sequential <> tokens will only render as one  ), but to signify that the space between two words shouldn't break when wrapping. Think of this like glueing two words together.

Note Escaping the start of any of these characters will cause the transformation to be skipped in that instance.

These transformations also don't apply inside inline `code` or inside the monospace block.

Note If you're not familiar with en-dash or em-dash, I definitely recommend reading a small bit about it—they're incredibly useful.