Elm Markup v3 - A compiler for a markup language

[mdgriffith]

Hello!

It’s finally come time to release v3.0 of elm-markup! I’m very excited, this has been quite the endeavor.

I got really interested in creating a markup language for two reasons.

1. Markdown doesn’t play nicely with elm-ui or interactive views written in Elm.
2. I wanted to write interactive fiction for a video game I’m designing, which means intermingling styled text and structured data. …or just realizing everything should be structured/known data, but also lightweight and easy to write.

So, what is Elm Markup?

Well, I gave a talk at Oslo Elm Day which might be a good place to start (Side note, Olso Elm Day is a fantastic conference.)

But to give a brief summary:

1. Elm Markup is a lightweight markup langauge where the structure is defined beforehand.
2. You define your document in Elm in a similar way you’d define a JSON decoder.
3. Once defined, you can parse the markup and get a rendered result, which could be html, elm-ui Elements, or even just a list of records. Since you define what you’re decoding to, it can be anything.

That’s the basic functionality for a markup language, but you can go further.

Because once we know the structure that the document should be, we can have nice Elm-esque errors:

Beyond this, I wanted some other capabilities I didn’t usually associate with a markup language:

• To parse your markup into an intermediate data structure called a Mark.Parsed (basically an AST)
• Make edits to Parsed through Mark.Edit.update. (They will be checked to ensure they are valid edits)
• Render that Parsed into your result.
• Convert Parsed back into an elm-markup source.

This is cool because it means elm-markup can be the “brain” of a rich text editor. Or really any sort of editor you’d like to make. Graph-based note taker? Definitely. Embed an interactive drawing program in your blogpost? Why not?

This goes back to reason 2. that I was making this, which is that many game engines benefit from having bespoke, embedded editors in the game.

And because apparently I go nuts when I do a project, I also created

• An Elm Markup CLI which will check your markup source files (*.emu) for errors using any exposing Mark.Documents in your elm project.
• A VS Code Extension with syntax highlighting and error reporting based on the output of the CLI.

So, if your interested in getting started, checkout the examples

I’m particularly excited about the editor example, which is the beginning of a rich text editor in Elm!

Though a caveat, it needs a number of improvements which I’ve listed in the Readme. My hope is that the example shows that some of the really difficult parts about creating an editor are taken care of.

And my other hope is that all of this sparks your creativity.

Whew, this project has quite a lot of surface area, so let me know in the issues if I missed something.

Also, small apologies for the long post :). I didn’t even get into the other cool things that came along with this project like building a tolerant parser that can continue after a parsing error…maybe I should write that up too.

[akoppela]

Fantastic work @mdgriffith

[alexkorban]

Really impressive work, @mdgriffith.

By the way, it’s possible to use elm-markup to generate static web sites with Elmstatic. I wrote about it recently. (It’s based on elm-markup 2.0 but aside from new syntax, it should work exactly the same.)

[giulioungaretti]

Omg omg ! This looks amaze! And if you do feel like it I would love to read about the tolerant parser!

[Blaise]

Wow! would it be possible to make it compatible with python docutils? Then it would open up Elm to the mind-blowing wealth of doc tools in the Sphinx libraries!

[Libbum]

Concerning the rich text editor: the caveats you list there, are they suggested exercises for the reader? Or were these things you just haven’t had the time for yet? If it’s the latter, I guess you’d be happy for some pull requests to get that fleshed out a bit more?

[mdgriffith]

Good question! PRs to improve the rich text editor example are welcome

I mostly ran out of time to get it really polished. If you want to take a stab at any of the improvements mentioned, go for it. I recommend improving it bit-by-bit as opposed to huge PRs.

If you have ideas beyond what’s listed there, feel free to reach out to me on slack about what you’re interested in.

Basically, I’d love for that example to be a slick text editor that’s as concise/readable as possible, while also being performant. It would be very cool if people could use it as a starter-kit to build their own, customized rich text editor.