markdoll spec

this content of this page is an automatic transclusion from the specification on codeberg

this rest of this page is rendered using this site's custom variants of tags click here to see what this page looks like with markdoll's original standard library

the site's CSS applies always, so this will look different than a plain html render

this is markdoll

markdoll is an extensible markup language written in rust, made: by dolls, for dolls

how is it different from other markup languages?

like HTML, markdoll is a tree shaped system. for example, headers always precede sections, which have a defined ending point, an explicit hierarchy, rather than an implicit one

specification

whitespace

in markdoll, tab characters are significant, they help define sections and lists, and provide a boundary for block-content tags

markdoll specifically does not assign importance to spaces, but does prohibit them in certain cases

newlines are also very signficant:

unless the last character of the line is a backslash (\), splitting text by a newline instead inserts a space
separating text/tags by an empty line splits it into two paragraphs
separating list elements by an empty line splits it into two lists

do note that all .doll files must be LF, CR characters will cause a fatal parsing error

kind	syntax	result
no-arg & no-content	#txt · 1 lines `[sometag]`	invokes `sometag`, does not provide an argument or any content
arg & no-content	#txt · 1 lines `[sometag(argument that can have any non-parenthesis tokens in it)]`	invokes `sometag`, providing the argument text, but no content
no-arg & content	#txt · 4 lines `[sometag:content]` `[sometag::` `block content` `]`	invokes `sometag`, does not provide an argument, but provides content*
arg & content	#txt · 4 lines `[sometag(argument that can have any non-parenthesis tokens in it):content]` `[sometag(argument that can have any non-parenthesis tokens in it)::` `block content` `]`	invokes `sometag`, providing an argument and content*

escape sequences

most parts of markdoll support escape sequences with the backslash character (\)

for example:

[em:\]] results in: ]
[em:\\] results in: \

inline tags do not need to escape balanced square brackets, however

[em:]] is unbalanced and will end early
[em:[]] is balanced and will not end early

block tags completely ignore escaping/balancing, their content is fed as-is into the tag, after the indentation of the tag + 1 has been stripped. they dont have to care about escaping/balancing because the only way to terminate them is to lower the indentation again, which isnt something that could be escaped

lists

unordered and ordered lists are also easy:

kind	syntax	result
unordered	#txt · 5 lines `- single line` `- [em:can also include formatting]` `- lists can also` `span multiple lines` `if the same indent is kept`	single line can also include formatting lists can also span multiple lines if the same indent is kept
ordered	#txt · 5 lines `= single line` `= [em:can also include formatting]` `= lists can also` `span multiple lines` `if the same indent is kept`	single line can also include formatting lists can also span multiple lines if the same indent is kept

sections

a section is preceded by a heading, and its content is indented 1 level higher

syntax	result
#txt · 5 lines `&hello` `&world` `content` `goes` `here`	hello world content goes here

when emitting to HTML, it is not recommended to have more than one top-level section, as multiple h1 elements causes accessibility issues

frontmatter

markdoll differentiates between parsing as a document and everything else:

each tag parses its content as embedded markdoll source via parse_embedded, so frontmatter would not be parsed in these situations
but when parsing a main document via parse_document, frontmatter is permitted.

frontmatter works almost identically to the way it does in many other markup languages, with an optional section at the very beginning of a file that is fenced with ---:

#txt · 5 lines
---
whatever
---

normal content goes here

while some languages choose to parse frontmatter as YAML or TOML, markdoll does not wish to take part in the war between the two, and just returns it as a string

extensibility

markdoll and its standard library emits HTML by default, but it doesn't have to!

markdoll does not load any tags automatically, all of them must be manually inserted. the standard library all supports HTML by default, and can be extended with other targets

standard extensions

the standard library is in the markdoll::ext module

common

in module markdoll::ext::common

tag	description	syntax	result
`//`	the comment tag is very simple, its content is not parsed and is excluded from the output	#txt · 1 lines `[//:this will not be included in the output]`

formatting

in module markdoll::ext::formatting

tag	description	syntax	result
`em`	apply one or more forms of emphasis to the content flags: i italics default if no flags are specified b bold u underline s strikethrough h highlight q quote	#txt · 1 lines `[em:italics]`	italics
		#txt · 1 lines `[em(i):italics (explicit)]`	italics (explicit)
		#txt · 1 lines `[em(b):bold]`	bold
		#txt · 1 lines `[em(u):underline]`	underline
		#txt · 1 lines `[em(s):strikethrough]`	~~strikethrough~~
		#txt · 1 lines `[em(h):highlight]`	highlight
		#txt · 1 lines `[em(q):quote]`	quote
		#txt · 1 lines `[em(i)(b)(u)(s)(h)(q):everything]`	~~everything~~
`quote`	block quotes an optional cite argument may be provided	#txt · 3 lines `[quote::` `block quotes can contain [em:markdoll]` `]`	block quotes can contain markdoll
`quote`	block quotes an optional cite argument may be provided	#txt · 3 lines `[quote(citation goes here)::` `block quotes can contain [em:markdoll]` `]`	citation goes here block quotes can contain markdoll

code

in module markdoll::ext::code

tag	description	syntax	result
`code`	inline code blocks	#txt · 1 lines `[code:whatever code goes here, it is not [parsed]]`	`whatever code goes here, it is not [parsed]`
`codeblock`	multi-line code blocks	#txt · 3 lines `[codeblock::` `anything can go here :3` `]`	#txt · 1 lines `anything can go here :3`

links

in module markdoll::ext::links

tag	description	syntax	result
`link`	link to content	#txt · 1 lines `[link(https://codeberg.org/0x57e11a/markdoll):markdoll]`	markdoll
`img`	insert images	#txt · 3 lines `[img(https://codeberg.org/0x57e11a/markdoll/raw/branch/main/button.png)::` `alt text goes here (88x31 button that says MADE WITH MARKDOLL)` `]`
`anchor`	invisible anchors to be used with the `ref` tag (ideal for section heads)	#txt · 1 lines `[anchor(anchor-tag)]`
`def`	in-page anchors to be used with the `ref` tag	#txt · 1 lines `[def(def-tag):some definition]`	[def-tag]: some definition
`ref`	link to an anchor defined by the `def` tag	#txt · 1 lines `this is a reference[ref(def-tag)][ref(anchor-tag)]`	this is a reference**

table

in module markdoll::ext::table

tag description syntax result

table

tables

tables have two syntaxes (that can be mix-matched, even within eachother):

list syntax
unordered list elements define normal rows/cells, ordered lists define head rows/cells
cannot create cells that span multiple rows/columns, use tags for that
tag syntax
using tr/tc tags and their arguments/flags

#txt · 13 lines
[table::
	=	=	r1c1
		=	r1c2
		=	r1c3

	-	=	r2c1
		-	r2c2
		-	r2c3

	-	=	r3c1
		-	r3c2
		-	r3c3
]

r1c1	r1c2	r1c3
r2c1	r2c2	r2c3
r3c1	r3c2	r3c3

#txt · 19 lines
[table::
	[tr(head)::
		[tc(head):r1c1]
		[tc(head):r1c2]
		[tc(head):r1c3]
	]

	[tr::
		[tc(head):r2c1]
		[tc:r2c2]
		[tc:r2c3]
	]

	[tr::
		[tc(head):r3c1]
		[tc:r3c2]
		[tc:r3c3]
	]
]

r1c1	r1c2	r1c3
r2c1	r2c2	r2c3
r3c1	r3c2	r3c3

tr

create table rows inside tables

pass the head flag to insert it into the head section

#txt · 5 lines
[table::
	[tr::
		[tc:cells go here, whether by list or tag syntax]
	]
]

cells go here, whether by list or tag syntax

#txt · 8 lines
[table::
	[tr(head)::
		[tc(head)::
			cells go here, they should be [code:head] cells,
			whether by list or tag syntax
		]
	]
]

cells go here, they should be `head` cells, whether by list or tag syntax

tc

create table cells inside table rows

pass the head flag to make it a head cell

set the rows/cols props to make cells that span multiple rows/columns

#txt · 5 lines
[table::
	[tr::
		[tc:content]
	]
]

content

#txt · 5 lines
[table::
	[tr::
		[tc(head):content]
	]
]

content

#txt · 9 lines
[table::
	[tr::
		[tc(rows=2):two rows]
		[tc:upper]
	]
	[tr::
		[tc:lower]
	]
]

two rows	upper
	lower

#txt · 9 lines
[table::
	[tr::
		[tc(cols=2):two cols]
	]
	[tr::
		[tc:left]
		[tc:right]
	]
]

two cols
left	right

danger zone

by enabling the crate feature danger, the ext::danger module becomes available for use, and is automatically loaded into the default binary

this contains potentially dangerous tags, proceed with caution

tag	description	syntax
`invoke`	invoke an external command, passing arguments as cli args, content as stdin, dumping stdout into the output stream	#txt · 1 lines `[invoke(./test.sh)(flip):hello world]` imagine `test.sh` sees the `flip` argument and returns a version of stdin with all the letters flipped around

created:	fri apr 11 2025 03:36 utc
updated:	sat apr 12 2025 03:37 utc
built:	mon jan 26 2026 04:38 utc