dllup markup language

2015-03-12

1 Introduction

dllup is a lightweight markup language designed for creating simple websites. It is now mostly Markdown, with a few site-specific conventions that the dllup renderer turns into static HTML pages. This document covers the Markdown-facing syntax used to produce HTML webpages.

The name “dllup” is a portmanteau of my username and “markup”. It was inspired by jemdoc and Markdown. It supports LaTeX equations, tables, figure captioning, syntax highlighting of source code, and automatic section numbering with table of contents. However, it lacks many other features as it is deliberately simple.

1.1 Philosophy

1.2 Comparison to other languages

Why make yet another markup language when there are already so many available? The answer is:

  1. Just for fun.
  2. I want several features not available in current markup languages, and I don’t need several features which are available in current markup languages.

Thus, this project is for my own personal use. That notwithstanding, here are comparisons to jemdoc and Markdown.

1.2.1 Comparison to Markdown

There are several small differences:

The syntax for headers, links, lists, numbered lists, emphasis, strong text, code fences, tables, and images is valid Markdown.

1.2.2 Comparison to Jemdoc

There are several differences:

There is a key similarity: the goal of maintaining personal webpages, especially in an academic setting, is identical.

2 Syntax

2.1 Article header

Use YAML frontmatter for the page title and optional date.

---
title: "dllup markup language"
date: "2015-03-12"
---

# Introduction
 
**dllup** is a lightweight markup language...

2.2 Code

2.2.1 Raw HTML

Raw HTML can be written directly as Markdown raw HTML.

Blah blah.

<script>
window.alert('hi');
</script>

Blah blah blah.

2.2.2 Code blocks

A code block uses a Markdown code fence. Put the language in the fence info string when syntax highlighting should be applied.

Blah blah.

```c++
#include <iostream>
int main() {
    std::cout << "Hello world!" << endl;
}
```

Blah blah blah.

For example,

#include <iostream>
int main() {
    std::cout << "Hello world!" << endl;
}

2.3 Block elements

All block elements are separated by at least one empty line. For example there must be an empty line between a header and the paragraph that follows it. This behaviour is similar to LaTeX and allows you to use hard wraps (i.e. line breaks) to enforce a maximum line length.

2.3.1 Section headers

Headers are specified by preceding octothorpes, up to six. These will show up in the Table of Contents, which appears in the article header. Using more than three levels of section headers is not recommended.

# This is a first level header

## This is a second level header

### This is a third level header
that is very, very long

###### This is a sixth level header

2.3.2 Blockquotes

Blockquotes are preceded by a greater than symbol.

> The quick brown fox jumps over the lazy dog and
also jumps over the lazy cat.

This gets rendered as:

The quick brown fox jumps over the lazy dog and also jumps over the lazy cat.

2.3.3 Images

Image-only paragraphs are captioned figures by default. Use standard Markdown image syntax. The image label becomes both the alt text and the figure caption.

![_Ghost_ is a novelty chess set I designed which looks cool but is totally impractical for playing. The pieces are very flat and can be stacked together for compact storage.](http://i.imgur.com/WpEUM8S.jpg)

This gets rendered as:

Ghost is a novelty chess set I designed which looks cool but is totally impractical for playing. The pieces are very flat and can be stacked together for compact storage.

FIGURE 1 Ghost is a novelty chess set I designed which looks cool but is totally impractical for playing. The pieces are very flat and can be stacked together for compact storage.

Download

2.3.4 Display math equations

Display math equations use double dollar fences.

$$
x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$

This gets rendered as:

1 x=−b±b2−4ac2a\begin{aligned}x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}\end{aligned}

2.3.5 Lists

Lists use standard Markdown bullets, indentation, and ordered list markers.

- Item one.
- Item two.
  Multi-line list item.
  - Nested.
    - More nested.
  - Nested.
- Item 3.

1. Item one
99. Item ninety-nine? Nah it's actually item two.

This gets rendered as:

  1. Item one
  2. Item ninety-nine? Nah it’s actually item two.

The first number of a numbered list should be 1, although for the remaining list items any number works.

2.3.6 Tables

Tables use GitHub-flavored Markdown table syntax. A following paragraph beginning with Table: becomes the caption.

| Puppy colour | Awesome? | Purpleness |
| ------------ | -------- | ---------- |
| Red          | $\times$ | 0.1        |
| Orange       | $\times$ | 0          |
| Yellow       | $\times$ | 0          |
| Green        | $\times$ | 0          |
| Blue         | $\times$ | 0.5        |
| Purple       | $\checkmark$ | 1      |

Table: Summary of the awesomeness of puppy colours.

This gets rendered as:

Puppy colourAwesome?Purpleness
Red×\times0.1
Orange×\times0
Yellow×\times0
Green×\times0
Blue×\times0.5
Purple✓\checkmark1
Table 1 Summary of the awesomeness of puppy colours.

The first line is interpreted as a header. The vertical pipes do not need to line up and extra whitespace is discarded.

2.3.7 Big button

A big button is useful in case you want to link to an important page, or a link to download something, or to perform a critical action.

:: big button http://www.dllu.net/

This gets rendered as:

big button

2.3.8 Paragraph

A block with none of the keywords/symbols in front counts as just a paragraph.

2.4 Inline elements

Inline elements, or span elements, apply to any kind of normal text such as paragraph text, header text, caption text, list content, and so on. But they do not apply to math equations or source code. Here are the types of elements processed in order of precedence.

2.4.1 Monospace code snippet

A monospace code snippet comes between backticks.

A `monospace code snippet` comes between backticks.

2.4.2 Inline math

Inline mathematics y=mx+by = mx + b comes between dollar signs.

Inline mathematics $y = mx + b$ comes between dollar signs.

2.4.3 Links

Links follow the Markdown syntax.

Links follow [the Markdown syntax](http://daringfireball.net/projects/markdown/basics).

2.4.4 Emphasis and strong

Text is emphasized or made strong by underscores and double asterisks.

Text is _emphasized_ or made **strong** by underscores and double asterisks.

2.4.5 References

Referring to or citing things can be done with ordinary Markdown links to anchors, such as [Blanco](#blanco). A reference list can be written as a regular unordered list with anchors:

Referring to or citing things can be done with [links](#asdf).

- <span id="asdf"></span> Lu, Daniel. "dllup markup language".

2.5 Typographical character substitutions

dllup makes automatic substitutions:

2.5.1 Special character escaping

You can escape special characters using backslashes.

The dollar sign “$”, backtick “`”, for example, should be escaped as \$ and ``` respectively if you wish to use them in prose.

3 Implementation

dllup is implemented in Rust. The parser uses a Markdown AST and maps it into the existing site renderer.

For rendering math equations, dllup uses KaTeX to create SVG output.

For syntax highlighting, dllup uses inkjet.

The source code of dllup-rs is available on GitHub under the MIT license.

4 Installation

4.1 dllup to HTML

Using dllup is straightforward, but it is not as portable as plain Markdown because the renderer also processes math and images.

4.1.1 Compiling a single file

Run dllup-rs with an input Markdown file and, optionally, a config file.

cargo run -- site/index.md dllup.toml

4.1.2 Compiling a directory

cargo run -- site dllup.toml

Directory builds compile .md files.

4.2 Syntax highlighting

Markdown syntax highlighting works out of the box in most editors.

Syntax highlighting example in vim.

FIGURE 2 Syntax highlighting example in vim.

Download

5 FAQ

Certain features don’t work in my browser.

The output of dllup has been W3C validated and tested in the latest versions of Firefox, Google Chrome, and even Lynx. No attempt shall be made to support other browsers, although you are free to extend dllup as you please.

Why SVG math instead of MathJax or KaTeX?

Client-side MathJax is slow, causes page content to jump around as math is being rendered, and may freeze the browser on old hardware or slow browsers. Saving math equations as SVG files also allows the SVG files to be cached in case a single equation shows up many times. Some users also prefer to disable Javascript for privacy reasons even when they are using a modern browser that supports SVG images.

Where can I find an example of a dllup file?

This documentation itself was written in Markdown-flavoured dllup.

The parser crashed.

This can be due to a syntax error in the input. New content should generally be valid Markdown plus the small dllup conventions described above.