Ivan's wiki

Site Tools

syntax

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
syntax [May 14, 2026 at 13:31] – yanevskivsyntax [August 22, 2026 at 15:22] (current) – created - external edit 127.0.0.1
Line 1: Line 1:
 +# Wiki syntax
  
-------+This wiki runs **DokuWiki** with the [[list-of-syntaxes|markdowku]] plugin on top, so **both DokuWiki markup and Markdown work in the same page**, often interchangeably. Math is handled by **KaTeX** and LaTeX figures by **texrender**. 
 + 
 +Where the two markups overlap, this page shows both and says which one to prefer. Everything below was checked against this installation. The differences from stock DokuWiki are real, not theoretical. 
 + 
 +Pages are stored as `.md` files under `data/pages/`. The first heading of a page becomes its title everywhere it is linked. 
 + 
 +## Headings 
 + 
 +Both heading styles work and mix freely. Markdown `#` counts levels downward, DokuWiki `=` counts them upward. 
 + 
 +<code> 
 +# Level 1        ====== Level 1 ====== 
 +## Level 2       ===== Level 2 ===== 
 +### Level 3      ==== Level 3 ==== 
 +#### Level 4     === Level 4 === 
 +##### Level 5    == Level 5 == 
 +</code> 
 + 
 +Setext headings work too: 
 + 
 +<code> 
 +Level 1 
 +======= 
 + 
 +Level 2 
 +------- 
 +</code> 
 + 
 +House style is `#` for the page title and `##`/`###` for sections. 
 + 
 +The table of contents appears as soon as there is one heading, and lists levels 1 and 2 only. A page whose title starts with `(WIP)` is treated as work in progress: it is listed separately on the [[:sitemap|sitemap]] and every link to it is coloured gold. 
 + 
 +## Text formatting 
 + 
 +<code> 
 +**bold** and //italic// and *italic* and _italic_ 
 +__underline__ and ''monospace'' and `monospace` 
 +**//combined//** works too 
 +<del>deleted</del>, <sub>subscript</sub>, <sup>superscript</sup> 
 +</code> 
 + 
 +**bold** and //italic// and *italic* and _italic_ 
 +__underline__ and ''monospace'' and `monospace` 
 +**//combined//** works too 
 +<del>deleted</del>, <sub>subscript</sub>, <sup>superscript</sup> 
 + 
 +Note that `''...''` is DokuWiki markup and still parses what is inside it, while backticks are Markdown and take their content literally. Markdown's `~~strikethrough~~` is **not** supported. Use `<del>` instead. 
 + 
 +## Paragraphs and line breaks 
 + 
 +A blank line starts a new paragraph. Single newlines inside a paragraph are ignored. 
 + 
 +Forced line breaks come in two forms, both of which need the trailing whitespace: 
 + 
 +<code> 
 +DokuWiki style\\ next line 
 +Markdown style, two trailing spaces   
 +next line 
 +</code> 
 + 
 +`\\` immediately followed by a letter does nothing. It needs a space or an end of line after it. 
 + 
 +## Links 
 + 
 +### Internal 
 + 
 +<code> 
 +[[qubit]]                     same namespace, title taken from the page 
 +[[qubit|a qubit]]             explicit link text 
 +[[qubit]]                fully qualified 
 +[[qubit#basis-states]]        jump to a section 
 +[[#headings]]                 section of the current page 
 +</code> 
 + 
 +[[qubit]], [[qubit|a qubit]], [[qubit#basis-states|a section]]. 
 + 
 +Almost every article lives in the `wiki:` namespace, so the short form is what you want. Links to pages that do not exist yet are red, links to `(WIP)` pages are gold. 
 + 
 +Section anchors are the heading text, lowercased, with spaces turned into dashes. 
 + 
 +### External 
 + 
 +<code> 
 +https://example.com                    bare URL, linked automatically 
 +[[https://example.com|Example]]        DokuWiki style 
 +[Example](https://example.com)         Markdown style 
 +<https://example.com>                  angle-bracket autolink 
 +<[email protected]>                     e-mail, obfuscated in the output 
 +[[wp>Quantum_computing]]               interwiki: Wikipedia 
 +[[doku>syntax]]                        interwiki: DokuWiki manual 
 +</code> 
 + 
 +A **bare e-mail address is not linked**. It needs the angle brackets. The available interwiki shortcuts are listed in `conf/interwiki.conf`. 
 + 
 +Link text is plain text: `**bold**` inside a link title is printed literally, not rendered. Math and images are the exceptions: `[[ket-0|$\lvert 0\rangle$]]` and `[[qubit|{{img.png}}]]` both work. 
 + 
 +## Footnotes and references 
 + 
 +<code> 
 +A claim((and the reason it is only a claim)). 
 +</code> 
 + 
 +A claim((and the reason it is only a claim)). Footnotes collect at the bottom of the page and are the **only** citation mechanism here. There is no `<ref>`. That is MediaWiki syntax, provided in DokuWiki by the `refnotes` plugin, which is not installed. Written out, `<ref>` prints literally. 
 + 
 +Links, images and math all work inside a footnote: 
 + 
 +<code> 
 +Shor's algorithm((Shor 1994, see [[shor]] and https://arxiv.org/abs/quant-ph/9508027)). 
 +</code> 
 + 
 +Shor's algorithm((Shor 1994, see [[shor]] and https://arxiv.org/abs/quant-ph/9508027)). 
 + 
 +### Citing the same source twice 
 + 
 +Repeating a footnote **with byte-identical text** collapses it into a single entry at the bottom, with one backlink per marker. That is the closest thing available to MediaWiki's named references, and it needs no name: 
 + 
 +<code> 
 +Sorting((Knuth 1998)) and searching((Knuth 1998)) and concurrency((Dijkstra 1968)). 
 +</code> 
 + 
 +Sorting((Knuth 1998)) and searching((Knuth 1998)) and concurrency((Dijkstra 1968)). 
 + 
 +The markers still count up, but the two Knuth markers point at one shared entry. Change a single character and the entry splits in two, so copy and paste the citation rather than retyping it. 
 + 
 +For pointing at other articles, the house convention is a plain `[[link]]` in the prose and a **See also** section at the end, as at the bottom of this page. Footnotes are for sources and asides, not for navigation. 
 + 
 +## Lists 
 + 
 +Bullet lists work in both markups. The DokuWiki form needs **two leading spaces**, the Markdown form needs a **blank line before it**. Indent by two more spaces to nest. 
 + 
 +<code> 
 +  * DokuWiki bullet 
 +    * nested 
 + 
 +* Markdown bullet 
 +  * nested 
 +</code> 
 + 
 +Numbered lists are **Markdown only**: 
 + 
 +<code> 
 +1. first 
 +2. second 
 +</code> 
 + 
 +DokuWiki's `  - item` produces a *bullet*, not a number, because the Markdown plugin claims `-` first. This is the one place where the two markups genuinely collide, so always number with `1.`. 
 + 
 +## Tables 
 + 
 +Tables are DokuWiki syntax. Markdown pipe tables are **not** supported. The `|---|---|` separator row shows up as a literal row of dashes. 
 + 
 +`^` marks a header cell, `|` a normal one: 
 + 
 +<code> 
 +^ Fruit ^ Colour ^ Count ^ 
 +| apple | red | 12 | 
 +| lemon | yellow | 3 | 
 +</code> 
 + 
 +^ Fruit ^ Colour ^ Count ^ 
 +| apple | red | 12 | 
 +| lemon | yellow | 3 | 
 + 
 +**Exactly one space each side is the neutral padding.** Two or more spaces are not whitespace, they are the alignment marker: extra space on the left aligns right, on the right aligns left, on both sides centres. This is why table source on this wiki looks cramped and cannot be padded into neat columns. Widening a cell to line the pipes up would silently re-align it. 
 + 
 +<code> 
 +^ Left ^ Centre ^ Right ^ 
 +| a  |  b  |  c | 
 +</code> 
 + 
 +^ Left ^ Centre ^ Right ^ 
 +| a  |  b  |  c | 
 + 
 +An empty cell (`||`) merges with the one to its left; `:::` merges with the one above: 
 + 
 +<code> 
 +^ A ^ B ^ C ^ 
 +| spans two columns || third | 
 +| tall | x | y | 
 +| ::: | z | w | 
 +</code> 
 + 
 +^ A ^ B ^ C ^ 
 +| spans two columns || third | 
 +| tall | x | y | 
 +| ::: | z | w | 
 + 
 +Links and math work inside cells, which is how most tables on this wiki are built: 
 + 
 +<code> 
 +^ State ^ Vector ^ 
 +| [[ket-0|$\lvert 0\rangle$]] | $\begin{pmatrix}1\\0\end{pmatrix}$ | 
 +</code> 
 + 
 +^ State ^ Vector ^ 
 +| [[ket-0|$\lvert 0\rangle$]] | $\begin{pmatrix}1\\0\end{pmatrix}$ | 
 +| [[ket-1|$\lvert 1\rangle$]] | $\begin{pmatrix}0\\1\end{pmatrix}$ | 
 + 
 +A bare `^` or `|` inside a cell splits it. Wrap it as `''%%^%%''` to print one. 
 + 
 +## Code 
 + 
 +Fenced blocks are syntax highlighted by language: 
 + 
 +<file> 
 +```python 
 +def f(x): 
 +    return x ** 2 
 +``` 
 +</file> 
 + 
 +```python 
 +def f(x): 
 +    return x ** 2 
 +``` 
 + 
 +The DokuWiki form takes an optional language and an optional filename; with a filename the block gets a download link: 
 + 
 +<file> 
 +<code python demo.py> 
 +print("hello") 
 +</code> 
 +</file> 
 + 
 +<code python demo.py> 
 +print("hello") 
 +</code> 
 + 
 +`<file>` is the same thing without highlighting, for output, config files and plain text. Use `<file - name.txt>` to give a filename but no language. 
 + 
 +Indenting a line by **two or more spaces** also makes a code block. That is DokuWiki's own preformatted syntax, not Markdown's four-space rule, and it fires on any stray indentation that is not a list item. Inline code is `` `backticks` `` or `''two apostrophes''`. 
 + 
 +Nothing inside a code block is parsed, so it is the safest way to show wiki markup, math or TikZ literally. 
 + 
 +## Math 
 + 
 +KaTeX renders math in the browser. Inline math uses single dollars, display math double: 
 + 
 +<code> 
 +The identity $e^{i\pi} + 1 = 0$ is inline. 
 + 
 +$$\int_0^1 x^2\,dx = \frac{1}{3}$$ 
 +</code> 
 + 
 +The identity $e^{i\pi} + 1 = 0$ is inline. 
 + 
 +$$\int_0^1 x^2\,dx = \frac{1}{3}$$ 
 + 
 +Math works inside table cells, headings and link titles. 
 + 
 +Five shorthand macros are defined for the number sets: 
 + 
 +^ Macro ^ Renders ^ 
 +| ''%%\NN%%'' | $\NN$ | 
 +| ''%%\ZZ%%'' | $\ZZ$ | 
 +| ''%%\QQ%%'' | $\QQ$ | 
 +| ''%%\RR%%'' | $\RR$ | 
 +| ''%%\CC%%'' | $\CC$ | 
 + 
 +Two limitations worth knowing: 
 + 
 + - `\(...\)` and `\[...\]` **do not work**, even though KaTeX is configured for them. The Markdown escape handling eats the backslash before KaTeX ever sees it. Use `$` and `$$`. 
 + - Math inside code blocks and inline code stays literal, which is exactly what you want when writing *about* math syntax. 
 + 
 +## LaTeX figures 
 + 
 +The texrender plugin runs LaTeX on the server and embeds the result as inline SVG. Two forms are recognised. 
 + 
 +A small picture in the middle of a sentence, using TikZ's own `\tikz` shorthand. It ends at the first semicolon outside braces, or at the closing brace of `\tikz{...}`: 
 + 
 +<code> 
 +An arrow \tikz \draw[->] (0,0) -- (0.6,0); in a sentence. 
 +</code> 
 + 
 +An arrow \tikz \draw[->] (0,0) -- (0.6,0); in a sentence. It sits on the text baseline and takes the surrounding text colour. 
 + 
 +A standalone document gets a block of its own: 
 + 
 +<file> 
 +\documentclass[border=2pt]{standalone} 
 +\usepackage{tikz} 
 +\begin{document} 
 +\begin{tikzpicture} 
 +  \draw[thick] (0,0) circle (0.6); 
 +  \draw[->] (-1.2,0) -- (1.2,0) node[right] {$x$}; 
 +  \draw[->] (0,-1.2) -- (0,1.2) node[above] {$y$}; 
 +  \fill (0.42,0.42) circle (0.05) node[above right] {$\psi$}; 
 +\end{tikzpicture} 
 +\end{document} 
 +</file> 
 + 
 +\documentclass[border=2pt]{standalone} 
 +\usepackage{tikz} 
 +\begin{document} 
 +\begin{tikzpicture} 
 +  \draw[thick] (0,0) circle (0.6); 
 +  \draw[->] (-1.2,0) -- (1.2,0) node[right] {$x$}; 
 +  \draw[->] (0,-1.2) -- (0,1.2) node[above] {$y$}; 
 +  \fill (0.42,0.42) circle (0.05) node[above right] {$\psi$}; 
 +\end{tikzpicture} 
 +\end{document} 
 + 
 +Anything found in the wild that is already a standalone document can be pasted in unchanged. No preamble is added and nothing is wrapped around it. Figures are cached, follow the surrounding text colour, and are capped in size and render time; a figure that fails to compile shows the LaTeX error instead of silently disappearing. 
 + 
 +## Images and media 
 + 
 +Images live in the media manager and are referenced by ID, exactly like pages. The one below is `wiki:syntax:image.png`, stored in a namespace named after the page that uses it, which keeps per-page images together instead of piling them into one folder. 
 + 
 +<code> 
 +{{wiki:syntax:image.png}} 
 +</code> 
 + 
 +{{wiki:syntax:image.png}} 
 + 
 +Options go after a `?`, a caption after a `|`. The live examples on this page are all left at full size to keep the markup readable, but any of these can be used, and combined: 
 + 
 +^ Written ^ Does ^ 
 +| ''%%{{wiki:syntax:image.png}}%%'' | full size | 
 +| ''%%{{wiki:syntax:image.png?200}}%%'' | 200 pixels wide | 
 +| ''%%{{wiki:syntax:image.png?200x120}}%%'' | 200 wide, 120 tall | 
 +| ''%%{{wiki:syntax:image.png|Additive RGB mixing}}%%'' | caption, also the alt text | 
 +| ''%%{{wiki:syntax:image.png?nolink}}%%'' | no link to the detail page | 
 +| ''%%{{wiki:syntax:image.png?linkonly|Download}}%%'' | link only, no image | 
 +| ''%%{{https://example.com/x.png}}%%'' | external image | 
 +| ''%%![alt](https://example.com/x.png)%%'' | Markdown form | 
 + 
 +### Alignment 
 + 
 +Alignment is a space **inside** the braces, and it is easy to miss when reading source. Think of the space as padding that shoves the image away from that side: a space on the left pushes the image right. 
 + 
 +^ Written ^ Space on ^ Image goes ^ 
 +| ''%%{{wiki:syntax:image.png}}%%'' | neither side | inline, no alignment | 
 +| ''%%{{ wiki:syntax:image.png}}%%'' | left | right | 
 +| ''%%{{wiki:syntax:image.png }}%%'' | right | left | 
 +| ''%%{{ wiki:syntax:image.png }}%%'' | both sides | centred | 
 + 
 +The three aligned forms, in order: 
 + 
 +{{ wiki:syntax:image.png}} 
 + 
 +{{wiki:syntax:image.png }} 
 + 
 +{{ wiki:syntax:image.png }} 
 + 
 +## Quotes 
 + 
 +<code> 
 +> a quoted line  
 +> a second one 
 +</code> 
 + 
 +> a quoted line  
 +> a second one 
 + 
 +Quotes have two quirks here. Consecutive lines are joined **without a space**, so end each line with a trailing space as above. Nesting with `>>` does not produce a nested quote; separate paragraphs with a bare `>` line instead. 
 + 
 +## Horizontal rules 
 + 
 +A line of four or more dashes on its own gives a rule, as do the Markdown forms `***` and `___`: 
 + 
 +---- 
 + 
 +Keep a **blank line above it**. A row of dashes directly underneath a line of text is a Setext heading, not a rule. That is true even inside a code block, which is why the example above is a live rule rather than a listing. 
 + 
 +## Smileys and typography 
 + 
 +Text smileys are replaced by icons: 
 + 
 +^ Type ^ Get ^ Type ^ Get ^ 
 +| ''%%:-)%%'' | :-) | ''%%8-)%%'' | 8-) | 
 +| ''%%:-(%%'' | :-( | ''%%;-)%%'' | ;-) | 
 +| ''%%:-D%%'' | :-D | ''%%:-P%%'' | :-P | 
 +| ''%%m(%%'' | m( | ''%%LOL%%'' | LOL | 
 +| ''%%FIXME%%'' | FIXME | ''%%DELETEME%%'' | DELETEME | 
 + 
 +`FIXME` and `DELETEME` are the useful ones. They mark a page for later without any extra markup. 
 + 
 +Some character sequences are replaced as you would expect in print: 
 + 
 +^ Type ^ Get ^ Type ^ Get ^ 
 +| ''%%->%%'' | -> | ''%%(c)%%'' | (c) | 
 +| ''%%<-%%'' | <- | ''%%(tm)%%'' | (tm) | 
 +| ''%%<->%%'' | <-> | ''%%(r)%%'' | (r) | 
 +| ''%%=>%%'' | => | ''%%...%%'' | ... | 
 +| ''%%--%%'' | -- | ''%%---%%'' | --- | 
 +| ''%%640x480%%'' | 640x480 | ''%%"quotes"%%'' | "quotes" | 
 + 
 +The full list lives in `conf/entities.conf` and `conf/smileys.conf`. Straight quotes become curly ones automatically. Acronym expansion is switched off, so `ACL` and `API` are left alone. 
 + 
 +## Escaping 
 + 
 +To show markup rather than have it interpreted: 
 + 
 +<code> 
 +%%no //markup// here%% 
 +<nowiki>no //markup// here either</nowiki> 
 +\*escaped\* \_underscore\_ \`backtick\` 
 +</code> 
 + 
 +%%no //markup// here%%. The `%%...%%` form is the shortest and works inside table cells. 
 + 
 +For inline examples that contain math or wiki markup, combine the two: `''%%$x^2$%%''` renders as ''%%$x^2$%%''. The monospace wrapper keeps KaTeX out and the `%%` keeps the parser out. That idiom is used throughout this page. 
 + 
 +Backslash escapes work for `` ` * _ { } [ ] ( ) > # + - . ! ``. That is also why `\(` and `\[` cannot be used as math delimiters. 
 + 
 +## Control macros 
 + 
 +<code> 
 +~~NOTOC~~     suppress the table of contents on this page 
 +~~NOCACHE~~   re-render the page on every request 
 +</code> 
 + 
 +## Embedding a feed 
 + 
 +<code> 
 +{{rss>https://example.com/feed.xml 5 author date}} 
 +</code> 
 + 
 +The number caps how many items are shown; `author`, `date` and `description` are optional flags. `nosort` keeps the feed's own order, and a bare number like `2h` sets the refresh period. 
 + 
 +## Where each syntax comes from 
 + 
 +Four independent parsers contribute to this page: DokuWiki core, markdowku, katex and texrender. Which one owns a given construct is usually what explains its quirks, and when two claim the same characters the lower `getSort()` wins. 
 + 
 +[[syntax-origin|Syntax origin]] lists every construct above against the component that implements it. 
 + 
 +## Quick reference of the gotchas 
 + 
 +^ Looks like it should work ^ What actually happens ^ Use instead ^ 
 +| ''%%- item%%'' as a numbered list | renders as a bullet | ''%%1. item%%'' | 
 +| ''%%\(x\)%%'', ''%%\[x\]%%'' | backslash is eaten, no math | ''%%$x$%%'', ''%%$$x$$%%'' | 
 +| ''%%~~strike~~%%'' | printed literally | ''%%<del>strike</del>%%'' | 
 +| Markdown pipe tables | separator row shows as dashes | DokuWiki ''%%^%%'' / ''%%|%%'' tables | 
 +| ''%%[text][ref]%%'' reference links | printed literally | inline links | 
 +| ''%%[email protected]%%'' | plain text | ''%%<[email protected]>%%'' | 
 +| ''%%[[page|**bold**]]%%'' | asterisks printed literally | plain text, or math/image | 
 +| ''%%\\%%'' before a letter | printed literally | ''%%\\%%'' plus a space | 
 +| Markdown list right after a paragraph | may swallow what follows | leave a blank line, or use ''%%  *%%'' | 
 +| ''%%----%%'' right under a line of text | that line becomes a heading | leave a blank line above the rule | 
 +| a bare ''%%^%%'' or ''%%|%%'' inside a table cell | splits the cell in two | wrap it in a nowiki, as the left column does | 
 + 
 +## See also 
 + 
 + - [[syntax-origin|Syntax origin]] 
 + - [[list-of-syntaxes|List of syntaxes]] 
 + - [[latex-syntax|LaTeX syntax]] 
 + - [[general-writing-guide|General writing guide]] 
 + - [[doku>syntax|DokuWiki's own syntax page]]
  
-[id]: fdsafdsa 
syntax.1778765493.md.gz · Last modified: by yanevskiv