This is a reference of all xidoc commands. A question mark ?
before a parameter means that it's optional. An asterisk *
before a parameter means that it can take any number of values.
These commands can be used anywhere within xidoc, unless overridden by other commands.
[# anything]
Example | Output |
---|---|
| I like xidoc. |
[(]
Example | Output |
---|---|
| I'm a sad robot :[ |
[)]
Example | Output |
---|---|
| I'm a happy robot :] |
[() text]
text
in square brackets.
Example | Output |
---|---|
| [this-is-not-a-command] |
[;]
Example | Output |
---|---|
|
|
[space]
[raw text]
text
without expanding it.
Example | Output |
---|---|
| [I can use [as many brackets [as I want]], but [they] still have to [[be balanced]]]. |
[\ text]
text
, then returns it without expanding. A “smarter” version of [raw]
.
Example | Output |
---|---|
|
|
[pass code]
code
without escaping it. Useful if you want to go outside the capabilities of xidoc. The code
is still expanded so you can parametrize it, see the [pass-raw]
command if you don't want this.
Example | Output |
---|---|
| Haha! I'm in! '; DROP TABLE xidoc; Oh no, this is a static site… |
[pass-raw code]
code
without escaping it. Useful if you want to go outside the capabilities of xidoc. Works as a combination of [pass]
and [raw]
.[hide text]
text
for its side effects, but doesn't return anything.[expand text]
text
, expands it again. Useful for complex command definitions.[render text]
text
, renders it. Useful for complex command definitions.
Example | Output |
---|---|
| This will be italic despite being inside raw . |
[add-to-head directive]
directive
to the head of the document. Returns nothing.[bf text]
text
in bold face.
Example | Output |
---|---|
| xidoc is awesome! |
[code ?language; code]
code
in monospace font. If the language
is specified and the target is HTML, the code is syntax-highlighted during compilation using Prism. See the list of supported languages to know how to specify the language
. xidoc is also supported under the name xidoc
. For generic monospace text, use the [ms]
command.
Example | Output |
---|---|
| print(f"The answer to the universe and stuff is {6 * 7}.") |
[color color text]
text
in the given CSS-style color
.
Example | Output |
---|---|
| You can use names or codes! |
[it text]
text
in italics.
Example | Output |
---|---|
| xidoc is fantastic! |
[lang language; text]
text
with the conventions of the specified language
.
Example | Output |
---|---|
| “Hello!” „Ahoj!“ |
[link ?text; address]
address
with an optional text
visually replacing the address.
Example | Output |
---|---|
|
[ms text]
text
in monospace. If you want to show code, it's recommended to use the [code]
or [code-block]
command instead.
Example | Output |
---|---|
| In HTML, this will produce <code> . In LaTeX, this will produce \texttt . |
[term phrase]
phrase
as a new term. Useful in definitions.
Example | Output |
---|---|
| A group is a monoid where every element has an inverse. |
[unit ?number; unit]
unit
or a quantity expressed with a number
and unit
. Also works inside math commands.
Example | Output |
---|---|
| 6378 km, |
[block-quote text]
Example | Output |
---|---|
| The first rule in the Zen of Nim is: Copying bad design is not good design. |
[checkboxes items]
items
with checkboxes. Use [-]
for an unchecked item, [v]
for a checked item and [x]
for a crossed item.
Example | Output |
---|---|
|
|
[code-block ?language; code]
code
as a block in monospace font. If the language
is specified and the target is HTML, the code is syntax-highlighted during compilation using Prism. See the list of supported languages to know how to specify the language
. xidoc is also supported under the name xidoc
.
Example | Output |
---|---|
|
|
[list *items]
items
.
Example | Output |
---|---|
| Supported targets:
|
[ordered-list *items]
items
.
Example | Output |
---|---|
| TOP 5 LIST OF SMALLEST POSITIVE INTEGERS:
|
[p text]
text
.[section ?title; text]
title
and text
(or without a title if not given). If it's inside another section, it will be a subsection. If it's inside a subsection, it will be a subsubsection. In HTML, this nesting can continue further.
Example | Output |
---|---|
| InceptionAre we going too deep? |
[spoiler visible; secret]
secret
text until the visible
text is clicked. Works only in environments that support interactivity.
Example | Output |
---|---|
| In the series The Simpsons, the surname of the main characters isSimpson |
[table ?spec; content]
content
, which should consist of [row]
commands. The spec
is used to help LaTeX align the table.
Example | Output | ||||||
---|---|---|---|---|---|---|---|
|
|
[row *fields]
[table]
command.[header-row *fields]
[table]
command.[title title; ?author]
title
and sets it as the title of the document. If an author
is specified, their name is mentioned under the title.
[show-title title]
title
without setting it as the title of the document.[" text]
Example | Output |
---|---|
| “Hello!” „Ahoj!“ |
[--]
–
Example | Output |
---|---|
| 80–100% of people don't know the difference between a dash and a hyphen. |
[---]
—
Example | Output |
---|---|
| Em dash — the character many people don't know how to write. |
[...]
…
Example | Output |
---|---|
| You can't just substitute three dots for an ellipsis… |
In HTML, LaTeX math is rendered using KaTeX. This requires a stylesheet and fonts, which are downloaded from the jsDelivr CDN by default. If you'd like to use a different CDN or self-hoost the files, use [set katex-stylesheet-path; path/to/katex.min.css]
to point xidoc to the stylesheet.
[$ latex]
Example | Output |
---|---|
| Einstein's famous equation is |
[$$ latex]
Example | Output |
---|---|
|
[$$& latex]
align
environment).
Example | Output |
---|---|
|
[matext latex]
math
using maTeXt and presents it as preformatted text.
Example | Output |
---|---|
| 𝑛 𝑥⃗ ⋅ 𝑦⃗ = ∑ 𝑥 ⋅ 𝑦 𝑖 = 0 𝑖 𝑖 |
[dfn ?name; text]
name
.
Example | Output |
---|---|
| Definition. An inertial system is a system where the law of inertia holds. |
[theorem ?name; text]
name
.
Example | Output |
---|---|
| Theorem (Pythagorean). In a right triangle with legs |
[proof ?name; text]
name
.
Example | Output |
---|---|
| Proof. Left as an exercise to the reader. |
[example ?name; text]
name
.[exercise ?name; text]
name
.
Example | Output |
---|---|
| Exercise. Determine if the Collatz sequence reaches |
[lemma ?name; text]
name
.[solution ?name; text]
name
.
[spoiler-solution ?name; text]
name
. In environments that support interactivity, the text
is hidden inside a spoiler (see the [spoiler]
command).[props *properties]
properties
. Currently the same as [list]
.
Example | Output |
---|---|
|
[LaTeX]
Example | Output |
---|---|
| LaTeX |
[xidoc]
Example | Output |
---|---|
| ξ |
[inject file]
file
and renders it.[include file; *(name; value)]
file
as a separate document and pastes it. You can give arguments to the subdocument, which can be retrieved with the [template-arg]
command.
[template-arg name]
[include]
, returns the given argument passed to [include]
.[set key; value]
katex-stylesheet-path
, which is explained in the Math section.
[reset key]
[set-doc-lang language]
language
of the document. Returns nothing.[set-syntax-highlighting-theme theme]
theme
for syntax highlighting with the [code]
and [code-block]
commands. The available themes are default
, dark
, funky
, okaidia
, twilight
, coy
, solarized-light
, and tomorrow-night
. You can try out these themes on the Prism website. There is also funky-x
, a modification of funky
with a black background instead of weird stripes.[set-title title]
title
as the title of the document.[def name; ?params; body]
name
that expands to body
. If params
, which should be space-separated words, are given, the command can take arguments, which can be accessed using the [arg]
command and its variants ([arg-expand]
, [arg-raw]
, [arg-raw-escape]
). The command will only be visible in the scope where it was defined; if you want it to be visible everywhere, use [def-global]
.
Example | Output |
---|---|
| Hello, reader! |
[def-global name; ?params; body]
name
that expands to body
. If params
, which should be space-separated words, are given, the command can take arguments, which can be accessed using the [arg]
command and its variants ([arg-expand]
, [arg-raw]
, [arg-raw-escape]
). The command will be visible everywhere; if you want it to be visible only in the scope where it was defined, use [def]
.
Example | Output |
---|---|
| Hello, reader! |
[arg parameter]
[def]
), renders the argument given to the parameter
.
Example | Output |
---|---|
| Hello, reader! |
[arg-expand parameter]
[def]
), expands the argument given to the parameter
, but doesn't render it.[arg-raw parameter]
[def]
), returns the argument given to the parameter
, but doesn't expand it.[arg-raw-escape parameter]
[def]
), returns the argument given to the parameter
, but doesn't expand it; however, the raw string is rendered.[if-html text]
text
only if the target is HTML, otherwise returns nothing.
Example | Output |
---|---|
| You can see this only if you're in HTML! |
[if-latex text]
text
only if the target is LaTeX, otherwise returns nothing.
Example | Output |
---|---|
|
[if-gemtext text]
text
only if the target is Gemtext, otherwise returns nothing.
Example | Output |
---|---|
|
[for-each name; list; template]
template
to each item of the list
, making it available as name
.
Example | Output |
---|---|
| xidoc compiles to HTML. xidoc compiles to LaTeX. xidoc compiles to Gemtext. |
[join separator; list]
list
using the given separator
.
Example | Output |
---|---|
| xidoc compiles to HTML. xidoc compiles to LaTeX. xidoc compiles to Gemtext. |
[get-doc-path-absolute]
[get-doc-path-relative-to-containing name]
name
.
Example | Output |
---|---|
| Within the Git repository of xidoc, the command reference is located at docs/commands.xd . |
[list-dirs pattern]
pattern
, relative to the current file.
Example | Output |
---|---|
| The subdirectories of the src directory of xidoc are: ../src/duktape, ../src/janet, ../src/katex, ../src/pkgs, ../src/prism, ../src/xidocpkg. |
[list-files pattern]
pattern
, relative to the current file.
Example | Output |
---|---|
| The xidoc sources of this documentation are: commands.xd, head.xd, index.xd, manual.xd, playground.xd, todo.xd. |
[janet-call function; *arguments]
function
with the given arguments
as strings and returns the result, which has to be a string. Useful for doing complex logic when xidoc's built-ins don't suffice. Note that all Janet is evaluated in the same context, which you can make use of, but be careful!
Example | Output |
---|---|
| The circumference of a circle with radius 6 is 37.6991. |
[janet-eval code; *(name; value)]
code
. If some pairs of name
and value
are given, the code will have access to global definitions with the given names and values. Useful for doing complex logic when xidoc's built-ins don't suffice. Note that all Janet is evaluated in the same context, which you can make use of, but be careful!
Example | Output |
---|---|
| The greatest common divisor of 128 and 168 is 8. |
[js-call function; *arguments]
function
with the given arguments
as strings and returns the result as a string. Useful for doing complex logic when xidoc's built-ins don't suffice. Note that the JavaScript engine currently used by xidoc is Duktape, which supports only ES5 and certain ES6 features. Notably, it doesn't support arrow functions, so for an anonymous function, you need to use the old (function() { … })
syntax. Also note that all JavaScript is evaluated in the same context, which you can make use of, but be careful!
Example | Output |
---|---|
| The area of a circle with radius 6 is 113.09733552923255. |
[js-eval code; *(name; value)]
code
. If some pairs of name
and value
are given, the code will have access to global variables with the given names and values. Useful for doing complex logic when xidoc's built-ins don't suffice. Note that the JavaScript engine currently used by xidoc is Duktape, which supports only ES5 and certain ES6 features. Notably, it doesn't support arrow functions, so for an anonymous function, you need to use the old (function() { … })
syntax. Also note that all JavaScript is evaluated in the same context, which you can make use of, but be careful!
Example | Output |
---|---|
| The roots of the polynomial |
[html-add-attrs attrs; cmd]
attributes
to the tag produced by cmd
. Supports the .foo
and #foo
syntax for specifying classes and IDs.
Example | Output |
---|---|
| Real men don't fear colors. |
[js-module code]
[js-module-raw]
.
[js-module-raw code]
[js-module]
and [raw]
.
Example | Output |
---|---|
| I will be changed |
[style stylesheet]
Example | Output |
---|---|
| This text is a work of art! |
[draw ?width; ?height; description]
description
. The description
format won't be documented until it's stabilized.
Example | Output |
---|---|
|
[<> a; .click-here; href="https://www.youtube.com/watch?v=dQw4w9WgXcQ"; CLICK HERE]
produces a link with the class click-here
and the text CLICK HERE
. Default tags have a shorthand, so this could also be written as [<a> .click-here; href="https://www.youtube.com/watch?v=dQw4w9WgXcQ"; CLICK HERE]
. However, the latter syntax doesn't work for custom tags.xidoc includes a simple set of commands that can be used to generate CSS without having to embed a completely different syntax in your document. It can be included using the [style]
command. (If you prefer normal CSS, use [add-to-head [<style> …]]
.)
[: property; value]
property: value;
.[:! property; value]
property: value !important;
. Please don't overuse this.[rule selector; declarations]
selector { declarations }
.[var name; ?value]
value
is given, declares a CSS variable: --name: value;
. If used outside a [rule]
, it's assigned to :root
. If used without a value
, it gets the value of the given variable: var(--name)
.These commands are available in LaTeX math. That is, inside the [$]
, [$$]
and [$$&]
commands. They are meant to make certain common combinations of LaTeX commands easier to type.
[_ something]
Example | Output |
---|---|
|
The following commands should be self-explanatory from the examples:
Command | Output |
---|---|
[/ q] | |
[/ p; q] | |
[. \frac{p}{q}] | |
[() \frac{p}{q}] | |
[{} \frac{p}{q}] | |
[<> \frac{p}{q}] | |
[| \frac{p}{q}] | |
[|| \frac{p}{q}] | |
[v. \frac{p}{q}] | |
[floor \frac{p}{q}] | |
[ceil \frac{p}{q}] | |
[dd x] | |
[dv x] | |
[dv f; x] | |
[dv^ 2; x] | |
[dv^ 2; f; x] | |
[pdv x] | |
[pdv f; x] | |
[pdv^ 2; x] | |
[pdv^ 2; f; x] | |
[mat a&b\\c&d] | |
[.mat a&b\\c&d] | |
[(mat) a&b\\c&d] | |
[|mat| a&b\\c&d] | |
[||mat|| a&b\\c&d] | |
[lim] | |
[lim m] | |
[lim x; 0] | |
[liminf] | |
[limsup] | |
[int x; t] | |
[int T; x; t] | |
[int t_1; t_2; x; t] |