```
    |||||      _    _ _                       _
  =  Z .  =   | |_ | | |_ __  _ _    _ _  ___| |_
  =    ,  =   | ' \| | | '  \| ' \ _| ' \/ -_)  _|
  = o  `  =   |_||_|_|_|_|_|_|_||_(_)_||_\___|\__|
    |||||
```

# Markup Syntax

All content on this site is written in the light markup language
[djot](https://djot.net). The syntax used is the one described in the [Djot
syntax reference][djot-ref] with some additional extensions that are described
below.

[djot-ref]: https://htmlpreview.github.io/?https://github.com/jgm/djot/blob/master/doc/syntax.html

Table of contents

- 1 [Page parameters][]
- 2 [Markup preprocessing][]

    - 2.1 [Generated elements][]
    - 2.2 [Include files for code blocks and raw blocks][]

- 3 [Plain text postprocessing][]

    - 3.1 [Image replacement][]

- 4 [HTML generation][]

    - 4.1 [Rendered equations][]
    - 4.2 [Syntax highlighting][]

## Page parameters

A parameter of a page can be specified by using a [reference link definition][]
with a label that starts with `:` followed by the parameter name. The link
destination is used for the parameter value. All parameters must be specified
in the beginning of the file. For example, to set the parameter `title` to the
value "Markup Syntax", one can write:

```djot
[:title]: Markup Syntax
```

The current available parameters are:

- `title`: set page title, used in e.g. the HTML `<title>` tag,
- `logo`: set URI to favicon and banner logo,
- `static`: copy static files to the output directory, filename relative to the
  markup file,
- `usage`: force usage of element types,
- `fullscreen`: use full screen width.

[reference link definition]: https://htmlpreview.github.io/?
    https://github.com/jgm/djot/blob/master/doc/syntax.html#reference-link-definition

## Markup preprocessing

All markup files are preprocessed at first. The processed output will be Djot
and will be used for generating both the final plain text page and the HTML.
The sections below describe directives that will be executed during the
preprocessing stage.

### Generated elements

Elements that must be generated can be embedded into a page by adding a
generate specifier. An example of a generated element is a list of blog posts.
The specifier is an [link][] with any label, the destination as the identifying
name of the element and eventual arguments as the title. For example, one can
embed the generated element `blog_list` with the argument "3" like

```djot
[][:blog_list 3]
```

in order to get a list with the latest 3 blog posts:

- *2024-04-24* - [The Web Without JavaScript](/blog/2024-04-24_nojs)
- *2023-09-18* - [Exploring The Halo 1 System Link Protocol](/blog/2023-09-18_h1x-net)
- *2023-04-20* - [Revisiting The Fast Inverse Square Root - Is It Still Useful?](/blog/2023-04-20_rsqrt)

All currently available generated elements are listed in the table below.

|Identifier|Description|Arguments|
|-|-|-|
|`blog_list`|list of all blog posts, each with date and title, newest first|number of posts to list|
|`man_list`|list of all man pages, grouped by section||
|`include`|include the contents of a file directly|filename relative to current file|
|`src`|url to the source code of the current page||
|`srcdir`|url to the directory that contains the source code of the current page||
|`toc`|table of contents for the current page||

[link]: https://htmlpreview.github.io/?https://github.com/jgm/djot/blob/master/doc/syntax.html#link

### Include files for code blocks and raw blocks

Source code for a [code block][] can be retrieved from a separate file by
adding an `@` followed by a file path after the filetype specifier. The path is
relative to the directory that the source file resides in. For example, next to
the `about` directory is a directory `blog` that contains a file `index.dj`.
So, the code block

~~~djot
```djot@../blog/index.dj
```
~~~

will turn into

```djot
[:title]: Blog

## Blog posts ([rss](/blog/index.xml))

[][:blog_list]
```

which happens to be the contents of `blog/index.dj`.

## Plain text postprocessing

There is also a postprocessing step to the markup files, the postprocessed
output will become the published plain text page. It will not affect the HTML
output in any way.

### Image replacement

All included [images][] will be replaced by plain text from a separate file
inside a [code block][]. For each image, there must be a file with the same
name in the same directory, but with the extension changed to `ascii`. So for
example,

```djot
![](/ic_16.svg)
```

will create an `<img>` tag to `ic_16.svg` in HTML but will be replaced by the
contents of `ic_16.ascii` in the plain text output:

```
  |||||
=  Z .  =
=    ,  =
= o  `  =
  |||||
```

[images]: https://spec.commonmark.org/0.30/#images

## HTML generation

The preprocessed markup page will be used to generate HTML. The sections below
describe extensions to the CommonMark specification that affect the HTML
output.

### Rendered equations

Inline or display math elements may contain equations written in LaTeX that
will be converted to [MathML][]. E.g. ``$`y = 2x` `` will be rendered as
$`y=2x` and

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

will be rendered as

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

{% plain text output is unaffected %}

[MathML]: https://www.w3.org/TR/MathML/

### Syntax highlighting

Source code within a [code block][] will be syntax highlighted. All code blocks
must have a filetype specifier. To highlight a shell script, one can for
example use:

~~~djot
```sh
if [ -e "file" ]; then echo "file exists"; fi
```
~~~

which turns into

```sh
if [ -e "file" ]; then echo "file exists"; fi
```

{% plain text output is unaffected %}

The highlighting is performed by vim so the specified filetype has to match a
syntax file that is either part of the [vim distribution][vim-syntax] or
available in [this website's repo][hllmn-syntax].

[code block]: https://htmlpreview.github.io/?
    https://github.com/jgm/djot/blob/master/doc/syntax.html#code-block
[vim-syntax]: https://github.com/vim/vim/tree/master/runtime/syntax
[hllmn-syntax]: https://git.sr.ht/~nhellman/hllmn/tree/master/item/gen/syntax