logo: an integrated circuit

Markup Syntax

All content on this site is written in the light markup language djot. The syntax used is the one described in the Djot syntax reference with some additional extensions that are described below.

Table of contents

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:

[: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.

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

[][:blog_list 3]

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

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

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@../blog/index.dj
```

will turn into

[: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,

![](/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:

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 $y=2x$ and

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

will be rendered as

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

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:

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

which turns into

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

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