Elm Markup

is a markup language that integrates closely with Elm. github package

You describe your document and get a Parser that can parse that document or hand you nice error messages.

VSCode support for the Elm Markup package. page github package

This talk is called markup for the statically typed and I'm Matthew Griffith and kind of exciting I actually just moved from Cornell Tech and now I'm writing Elm code 100% of the time at blissfully which is super awesome go check us out if you want to check it out it does kind of sass management for like onboarding people and managing their services they need

but this is really about Elm Markup and what I'm going to be talking about is I'm going to be talking about version 3 which is not out yet so if you like look through this stuff and go to the package and then try to do the thing and you're like where is the feature it's like it's it's coming it's coming but hopefully you'll see that it's it's it'll be worth it so in building an elm mark-up library I would frequently get kind of this interaction where I'm like I'm writing like a new markup language and in Elm and they were like yeah I saw you were doing that but you know like why like and so I kind of want to go into my journey

What was my journey? Actually to sort of get where I got and it kind of came down to three practical problems I had I really wanted to write some documentation for L me why that was interactive there was only so much I could do on the actual documentation website and I wanted to make these kind of interactive widgets that you could actually mess around with and maybe you would like manipulate some code and also show you kind of the results and I'm like okay well you know I could write some markdown but I want like a view function in the middle and okay well that's weird and then you know life kind of went on I'm like oh I really do want to write some articles too and I want to you know put some again some inner of content sort of in the middle and like okay well I'm running did this problem again and then there this other thing came up my plan for this year is to actually do some video game development and I'm really excited about kind of like writing the narrative for video games and I was like oh well again markdown would be great but if you're writing narrative for a video game it is classically you need to intermingle data with your prose and so you have a lot of these solutions that are out there that are more graphical they're like whole system's there are some languages that have very specific semantics around this I was like okay this all feels kind of weird

(2:56) and so the Challenges I was running into in each of these is again I want to insert a view function in the middle of my document an arbitrary view function not just a static view function but something I could actually like it could like look at my model and it could like do a little thing and and it's like that would be great why is this kind of so difficult and I was already using Elm UI because if I wasn't that would be kind of absurd and so I didn't want to write CSS I was like I just don't feel good if I have to like okay I built this whole thing where I never have to use CSS again except when I have to write my markdown I need to write I mean it's just a little bit of CSS but you know well but you know I didn't want to kind of go there and again with the narrative video game I want to embed arbitrary data it wasn't about HTML in a lot of these cases it may eventually become HTML but could be a lot of different things and the last one is really important because it should be convenient for my girlfriend to write in the narrative game my plan is that her and I would actually write these stories together so she's not a programmer she's a writer so um great like or any of the solutions I had before like do they meet that criteria and that actually became kind of a guiding light for a lot of this stuff

(4:14) so I had a lot of almost solutions a lot of things where it's actually talking with different people people have kind of like the solution they figured out to kind of any number of things that we mentioned up like okay I have the thing like you know it just like you know grabs the markdown it like does some substitution like some pre-processing and then like I make it I'm a I make it work and I wasn't really satisfied with almost solutions I really I really want something that was just like it felt nice and would be a tool that I could really build on and so I went on this journey

(5:00) and this journey sort of started with well What Is Markup? and I ran into this kind of initial problem where I'm like what's the difference between markup and just data serialization and I didn't really have I'm like okay well I don't I don't think there's a difference I think we we have two terms right interesting and well interestingly enough YAML seems to have like an issue with this or the same like confusion because it's like yet another markup language was the original like-like-like acronym that's what that meant and then they actually changed it to ya mole ain't a markup language so I'm like okay well I think we're on the same page that we just don't know what's going on so that's great

so what I really thought about is like okay well markup is about writing data cool well how would we write some data and I kind of like started to like think like okay well if I'm writing data if I'm in the headspace of data I would like some types I would like to actually know the Shape of the data but I would also like I want to write prose I'm not sure if everybody can see this it says easy to write prose down here or another way to say it is like easy to write a novel would you want to write a novel in it so you probably wouldn't want to write a novel and protobuf you know no not json yamo you might maybe you want to write it like more in the animal than json and elm i felt like it was kind of like okay well i've definitely written content in elm for blog posts and everything where's just like String Literals or whatever so I'm like okay that seems like obviously more types but like similar baby into like writing YAML and then it's like okay you know markdown and asciidoc and there's there's like so many of these things it's absurd and like well isn't there something there like what about over there and it's kind of like this question of like what would an elm like markup look like well the first requirement is it's got to have like a light weight same syntax we can't like I want to be able to write a novel on this I don't want to be in here in like just really trying to figure out okay what's the nesting what's whatever and it would have types and specifically like with types

(7:25) Why do we want Types because we have to work a little bit to get them and they allow human-computer collaboration that's they have we have a similar language we can both talk and we can actually like figure out what we're gonna do about creating this content we want to create together

and we know this like in Elm we have this lovely like collaboration with a compiler you know you're like I want to do this compiler is like that does make any sense thing like oh yeah you're right it's great and it would be specifically about writing data could we do that well where are your writing data so what is the where did I actually land if that was kind of like my guiding light what does the language actually look like

so this is the language this contains nearly every constructor in the language every special like case you know we got an image down here we got a header you may think like well I it's not just all about headers and images which we'll get to that you know we got some bold text Oslo elm day and cat is italicized I really like the idea of like representing like what it looks like physically you know so it's like italicized and I wanted like unambiguous syntax and this is because me I've shipped multiple versions of my documentation for Elm UI with markdown that was rendering not how I wanted it and it was because I was kind of too lazy to sort of check the visual it's like oh I was indented too far so that for therefore I'm like I'm not a list I'm a code block great but I'm already published so I'm am I gonna publish a patch version to actually fix that well no I'm just gonna feel bad about it

so everything is unambiguous you have a human name at the top of this stuff no block is also hard-coded will see header there's no special thing about header it's actually a block that's named header and we'll see how to name those later

(09:32) Limited Special Characters. Some of these markup languages when they extend their there are some really interesting ones like there's one called Inc which is specifically for narrative like creating a narrative structure in your game right so it's got all these like crazy like characters that mean stuff and these people are it like they've done the narrative game design stuff so they know kind of the concerns but you come into it you just like oh my god like what's happening there's so many characters on here and there's gonna be a lot of learning to actually figure out what's going on so these are the special characters and for arbitrary in line stuff we have essentially like an inline ability to attach certain attributes and again these are all arbitrary data attached to you know a range of text

(10:25) so the definition if we want types we need to inform the compiler which is basically what I ended up writing what it should be expecting so how would we do this well this is like an example of the language and this is slightly simplified we'll get into that in a moment but you know we have a document and that document should be rendered as an HTML article that would be great and the document is composed of many of text and images and we say well text is just some text but here is an image it's a record of two things and these are the things great and it's very obvious to see that this is just a mapping from one to the other and also that we don't just have to have HTML we could it could be any data anything you absolutely wanted

(11:13) and we can also do things like we can add additional constraints to our documents so we can say this thing is an integer between whatever and whatever that's cool and we can also say oh you know this document or this thing starts with a record and then I want a bunch of like paragraphs so this is a classic example for you know I want to create this blog and I want my frontmatter at the front and it's required it has to be there but if we have types we have error messages

now I actually have kind of wondered if like this fact is why as far as I know there is not a like lightweight markup language with types on the level of elm and it's because it's like oh well if we have types that it'll break my flow you know I'll be writing I'll run into a type error and then everything is broken and then you know so what would these actually these error messages look like well fortunately have some pretty good guidance on that and this is actually an error message from the Elm markup compiler formatted to look familiar and it'll actually like figure out exactly what's going on there are a lot of different error messages that can give and they're all hopefully pretty intuitive but that's actually not enough if we just got these errors you can imagine if you have an error we really want to again we're writing data you writing is in like you are sitting down to write your novel and but your novel is in data

(12:59) so we need additional ways to actually handle errors so here's kind of an expanded version of what we just saw before Marc record actually doesn't take just the view function or really this is it turns it into it doesn't just turn into HTML but it also has the idea of converting if there is an error in this block do this content so you still at the high level have the ability to you know know oh this is a successful totally valid document but this allows you to actually make things sort of dynamic which again we're getting back into this collaboration idea with the computer

(13:42) so with Elm markup there's kind of one final piece and started out as a parser where it would just like parse some stuff and then you have the thing and great it's done and then I said like I gotta go nuts and instead I was like well we have to have this intermediate step so that we can do all these other cool things so we have a string great we can parse it then we get an ast it's called mark description and once we have this ast which we can store in our model we can then convert it to our results it's just a generalized data structure the mark dot description we can convert to our result at any time and our results can actually emit error edit messages to edit the ast and the ast intern can actually to string itself back into the code you may notice this looks like a conversation that's convenient

so demo time man okay how do I get this thing out there perfect oh man is flux on where is that just we're good so this is an editor this is basically just an elm program the cool thing about it is that the model is just that mark description we also capture the source text the string of our document which is on the left and we also like track I think one boolean and one other thing but it's mostly just the document so what do we get from having this document well you can see the documents rendered under here like it's partially rendered we know this is an image there's something wrong with it so it's just like hey if this is this is broken at the moment but we can kind of see everything else in case we need that we had these two error messages so if we go over here and we correct that it's like okay well that's good and then we want to align this F image not aligned Lert but aligned left that would be fantastic okay and we need to be oh we have an int out of range between 30 and 80 800 and we have a width of 20 so it's like okay well great so we had that it's like okay well we now have a valid document these are my two cats they're awesome that's Bardot that's Phoebe it's like okay well we actually have this this issue here this is like welcome to L marker it's like well could we just do that and you can see actually it connects over here in fact we can say like we're actually pretty excited about this but can we can we go can we go even farther so what I did here you might have seen in the corner now says editable that's the boolean that we're storing all it's doing here is that because we're also storing the cursor position on the actual text so when we highlight different things you can see it knows where it is and we actually have some controls so that feels pretty good but how much farther could we take it so this is just this is like my cheating right like I'm able to add some stuff so we have a new component called draw it's like okay well we have this record of you know three fields we have a width and a height and we have we want some circles now I could have made like a very like elaborate like actually drawing mechanic all this does is draw circles but but it does draw circles and we can change this to our way to go you know everything's modifiable so that's great

(18:06) where my slides again so that's kind of where we landed or I landed the results everything's fully typed we have this ability to be fully types but not just like throw everything out the water or out the window when like there's something wrong we can actually increment incrementally fixed stuff it's easy to make fragment errors so or editors so a fragment editor is basically like oh I know I have an image here and in order to like modify this field of this image I can send a mark dot update float with a special opaque ID that represents that float and whatever I want it to be and then the actual ast will figure out what needs to change this is actually very convenient for my girlfriend to write like it's able to actually set something up where she can modify the text or even build a tool that she could use to actually have this lovely like collaboration experience

(19:11) and there's potential for the future there's you know we can have automatic semantic versioning kind of the entire realm that we're familiar with an elm all of a sudden becomes just available it's just like sort of free it's sort of just like oh it's there great just in markup for writing your content we have an L markup format this is literally like one function we already have this description of what we should be it's a very simple syntax there aren't many edge cases hardly at all so writing that I just haven't gotten around to it yet making a code editor integration is actually pretty easy like we just like hawk that data outside of Elm through a port and then do whatever kind of transformation we want to do and then having CLI like support is kind of naturally that's what you'd want with that and that's it thanks thanks for all the organizers and yeah I'm Matt Griffith [Music] [Applause]

⇒ Elmstatic: Type-safe markup for your static site with Elmstatic and elm-markup post and An introduction to elm-markup by way of Elmstatic post