Using Marks to quickly render documents

Background

I've been a long-time Markdown fan when it comes to quickly formatting documentation.

But soon enough, I ran into a recurring problem. How to stylize certain blocks. Not finding a simple solution, I had to systematically mix HTML and Markdown.

When github added some blocks like Tasks, tables and syntax colored blocks of code, it made it possible to have even more possibilities in the documents.

But you know how it is... the more you have, the more you want. Quickly I needed to style the tables, or to tell myself that even if they are convenient, most of my data comes from csv files, and it becomes hard to do the conversion.

I was thinking that, eventually, I could opt to modify a Markdown parser, and adapt it to my needs. After several evenings of trying this, I came to the conclusion that it would finally be easier to start from scratch and write a custom Markdown rendering engine, so that I could style as I wanted.

Thinking about the technical approach needed to write this component, I realized that the blocks that extend the syntax are relatively complex to parse. And I absolutely wanted to have a simple way to extend existing blocks while keeping the parsing simplicity.

That's when the idea of Marks was born. Keep what makes the use of Markdown simple, and expose a way to declare custom blocks.

Marks

I will try to provide a simple overview of what can be done with Marks. Using emphasis is as simple as in markdown, there is no need to change. If you write :

You will have the following output :

Marks keeps almost the same syntax as in Markdown whenever it's possible. The following blocks are provided out of the box.

• Emphsasis
• Links
• Images
• Tables
• Tasks
• Heading
• Blockquote
• Rules

Marks blocks

Marks provides a simple way to declare a custom block.

[NAME OPTIONS] {{
  BODY
}}

For example, the table block allows you to define a table with the Markdown format, or a csv one. Marks block can have options to specify more way to render the content.

And a csv option can be set too.

Both statements will make the same point

Another example with the Mermaid Marks Block

Using Styles

With Marks, you can use predefined styles or css classes on each block. With a Marks block, you simply specify the style options after the block name.

Predefined style options are defined by the theme and variant, but classes can be used to access css classes directly.

And for classic block such as paragraph, you can set options after the following sequence "::-"

Nesting

Nesting is a way to embed elements, for example a table inside a table, or a block inside another block. Just put a reference on the first one, and a placehoder in the second one.

Actions

Actions are simple commands that help configure the rendering. Data context can be passed to the rendering instance so that it can be used with the actions.

• mk-show command will define if a block is visible or not
• mk-repeat command will repeat a block

That's all for the scope of this overview, thank you very much for reading it. You will find more information and documentation on the website.