A lightweight markup language to format documents using plain text
The syntax of Arcadam is heavily inspired by AsciiDoc and by Markdown.
= Document Title
---
# Level 1 Section Title
## Level 2 Section Title
### Level 3 Section Title...
Use "#" in front of the heading, repeated as needed to increase the level.
The document title may be followed immediately by an optional document header which contains metadata related to the document, such as the authors or a marker for the generator to insert a table of contents.
Example:
= Document title
:key:authors Author Name <[email protected]>
:key:revision v2.0, 2019-03-22
:key:toc
---A sequence of non-empty lines form a paragraph.
To force a line break in the middle of a paragraph, end the line with "+".
Example:
This is part of a single
paragraph spread over
multiple lines of text. +
Because of the line break, this goes on a separate line.
Paragraphs may be grouped in a free block by enclosing them with "--".
Example:
--
This is the first paragraph.
Another paragraph is added
to the block.
--
A paragraph should be followed by an empty line. If the paragraph is at the end of a block, then the empty or indented line can come after the end block marker. In practice, that means it is better to separate paragraphs with empty lines and always leave an empty line after a block.
This is *bold*
This is _italic_
This is `monospaced`
This is ^superscript^
This is ~subscript~
This is #highlighted#
This is +_normal text_ (no style)+Styles can be combined. Any style can be used in the middle of a word by doubling the format markers (loose formatting), except for superscript and subscript which don't require doubling. Single format markers are applied first then loose format markers, from left to right. Format markers cannot cross a boundary.
Example:
*_Combine bold and italic_*
the "it" is __it__alic
superscri^pt^ for "pt"To enter text which contains format markers, enclose the text with "`" (monospaced text) or with "+" (regular text) to prevent the generator from interpreting the text.
When applying multiple styles in combination they must be in the following order:
| Format marker | Style |
|---|---|
# |
highlighted |
~ ^ |
subscript, superscript |
* |
bold |
_ |
italic |
` + |
monospaced, no style |
Subscript cannot be combined with superscript and monospaced cannot be combined with unstyled.
Horizontal line:
---
Page break (not visible in the browser if the output is a HTML document):
<<<
Arcadam tries to break the text at a natural place between pages, like the end of a paragraph. Add ">>>" at the end of the line to prevent this behaviour in a specific place. That may force a page break in the middle of a paragraph.
Boxed break:
+++
That type of break makes the text jump to the next position which is not constrained in width. It is useful to get past a floating image, for example.
The backslash "\" is used to prevent the generator from interpreting the following character specially.
Example:
\* not a bullet list!
See also Text Formatting to prevent format markers from being interpreted over a span of text using "+" or "`".
1. Number one
. Number two
. Number three
* First bullet
* Second bullet
* Third bullet
+ Item 1: First description
+ Item 2: Second description
+ Item 3: Third descriptionNumber 1 for the first item is optional and no other number is permitted. A list that immediately follows an item from another list is automatically nested. The ">" indent sign can be used to mark the nesting level, and it can be replaced with spaces after the first line. The count of spaces has no importance.
The list markers can be repeated to indicate the level, just like headings.
Example:
1. This is item number one
> * It has two bullet points
> * That is the second bullet
. This is item number two
> 1. This is a sublist
. Repeating ">" is optional
.. Other list nested inside
. Third element of item
number two sublist
> 1. Nested sublist with
multiline content
. This is item number three
[list]
1. The list attribute forces a
> new list to start up
Indented paragraphs that follow an indented list item are automatically attached to it. The list ends when a non-indented paragraph starts.
Additional lines of a non-indented list item can optionally be indented using an indent sign at the beginning of each, which can be replaced with spaces after the first line. The indent sign is required when adding a paragraph if there are no indented lines before, to signify its nesting.
Alternatively a sequence of nesting dots at the start of an empty line sets the nesting level for the next indented block or paragraph. Repeated indent signs can optionally be separated by spaces.
Choose a size:
- short
- regular
- large
The dash "-" at the start of a line is reserved for an enumeration or a quotation. An enumeration item does not behave like a list item. In particular it does not allow nesting.
An empty line should separate an enumeration from the text that follows.
[Go to Products page on this site](/Products.html)
[Go to Offers page in current path](Offers.html)
[Go to an arbitrary webpage](https://www.github.com)
Part 1: {#anchor} This text is selected by the anchor.
[Go to Part 1](#anchor)The text inside square brackets becomes a hyperlink which loads the content specified in the round brackets. If the square brackets are only [?] then the address is shown as link. If the round brackets are empty and the text matches a section title then the link goes to that section.
When the output format allows it, footnotes {^} and bibliographic references
{>} are also hyperlinks.
Example:
There are contractual implications to this statement.{^terms}
[^terms]:
> Please refer to our Terms and Conditions {>T&C} for more information.Note
The initial ">" on the lines that follows a marker is optional.
= sample image
[!image Arcadam logo](Arcadam-logo.png)
The Github mascot: [?image Github](octocat.jpg)Use the "image" custom control to insert an image or the "video" custom control to insert a video. The content type should have "!" in front to put the content in a new block or it should have "?" in front for content floating in line with the text.
The remainder of the text in square brackets is used as the "alt" label in HTML.
Content captions are set using a block title.
= Fruit basket
,===
apples,oranges,pears
,===
= A mountain sunset on [Flickr](https://www.flickr.com/photos/javh/5448336655)
[width=200,height=100]
[!image Sunset](sunset.jpg)A block title starts with "=" and a space. It comes before the attributes. A block title can continue on more than one line; then any additional line must begin with a ">".
If a document starts with a block title applied to a horizontal line, it is used as the document title.
If a block title is added to a block image, it is used as caption. If the image caption contains a link then clicking on the image loads the (first) link.
:key:key-name value to be insertedIf the value continues on more than one line then the additional lines must be introduced with ">" at the start. Arcadam blocks and commands cannot be used. Once defined, replacement values can be added anywhere using the key name.
Example:
Using the {key-name}
[{key-name}](/index.html)The key name is replaced with the value to be inserted.
Code blocks (monospaced):
Indented text is added to
a code block unless the
previous line starts with
"." or ">"
```
Another way to create a code
block is to use the ``` block
delimiter
```
A paragraph of indented text which is not attached becomes a code block. Indented text attaches to the previous paragraph if it is an indented paragraph, including indented with ">", or it contains only nesting signs ".".
For simplicity the processor only looks at the first character of the line: ">", "." and whitespace prevent the next paragraph from becoming a code block.
Other blocks:
___
Quote text using
three underscores
___
====
Example block used to
enclose an example
====
****
Sidebar block used to
expand on a topic or
highlight an idea
****
~~~~
Content block for text
content understood by a
plug-in or external app
~~~~
|===
| Header 1
| Header 2
| Header 3
|:
| Row 1 Column 1 | Row 1 Column 2
| Row 1 Column 3
| Row 2 Column 1
2+| Row 2 Merged columns 2, 3
|===A line starting with "|:" separates the header row from the following rows. If that line is missing the table has no headers by default. The only additional content allowed on the headers separation line is a sequence of characters containing only "|", ":" and "-".
Each new row should start on a new line. If a row is split in multiple lines there should be an empty line before the next row.
Arcadam markup can be used inside a table cell. When the contents of a cell are written on multiple lines they can optionally be indented with a ">" indent sign at the beginning of each. The start of next cell must be in a normal paragraph or on a new line.
Other table styles:
[table]
|Row 1 Column 1 |Row 1 Column 2 |Row 1 Column 3
|Row 2 Column 1 |Row 2 Column 2 |Row 2 Column 3
,===
Header 1,Header 2,Header 3
|-
Row 1 Column 1,Row 1 Column 2,Row 1 Column 3
Row 2 Column 1,Row 2 Column 2,Row 2 Column 3
,===
:===
Header 1:Header 2:Header 3
|-
Row 1 Column 1:Row 1 Column 2:Row 1 Column 3
Row 2 Column 1:Row 2 Column 2:Row 2 Column 3
:===
[form]
====
= Field label
[!input input-id= Default value]
[checkbox]
|+| Checkbox description | value
| | Unchecked checkbox description
[options,value="choice 2"]
* choice 1
* choice 2
* choice 3
= Picker label
[picker]
Any valid Arcadam content
[?submit Send](target)
[?cancel](home)
[?clear]()
====
A form layout has two columns, one for labels and one for form elements. An input field label or a picker label appears in the first column while a checkbox description or text for an option appears in the second column.
All form elements can have a value. If an element also has an id then the value becomes a replacement value using the id of the element as key.
In case of a checkbox, the replacement value is only defined when the checkbox is checked. The default value is "on".
In case of options, if the list is a description list then the item is used as value and the description as text. If the list is a numbered list then the item number is used as value. If the list is a bullet list then the text is used both as value and as text.
Buttons have an action and are displayed when the output format allows user interaction. The "submit" action sends the replacement values set in the form to the target. The "cancel" action abandons the form and loads the target. The "clear" action clears all the selections.
The cancel and clear buttons show a dialog asking for confirmation if the user made any changes.
A button can be activated by clicking a picture used as button label. The "call" custom control sends information about the button to a predefined function with the name and the parameter value that follow.
Example:
:key:submit-button [?image](submit-button.png)
:key:submit-action [?call my-function](param)
[?submit {submit-button}]({submit-action})
[tabset]
--
[tablist,id=maintab,value=Products]
* Products
* Portfolio
* Contact
[tab="maintab:Products"]
****
This is the products tab
****
[tab="maintab:Portfolio"]
****
This is the portfolio tab
****
[tab="maintab:Contact"]
****
This is the contact tab
****
--
If a block title is defined for a tab then that replaces the item in the tablist as the tab title.
When the output format allows user interaction then the chosen tab is displayed and other tabs display only their titles. Tabset content that is not a tab is not displayed.
In other cases, the generator outputs all the tabs in the tab list as well as tabset content. That is useful to insert page breaks between tabs. The tablist is always hidden.
To enable user interaction a tablist must be defined and the corresponding tablist entry must be specified for each tab. A numbered list can be used instead of a bullet list to select the tab by a number, or a description list to select it by an item. The tablist "value" attribute defines the initial tab selection.
= Proof for [this triangle](http://www.cut-the-knot.org/pythagoras/proof31.gif)
> where {`a}, {`b} and {`c} are the side lengths.
~~~~
// Comments, replacement values and callouts are allowed
mtable(
msup(\( a + b \) : 2) ` = ` msup(c 2) + 4 &sdot \( mfrac(1 : 2) * a * b \)
: msup(a 2) + 2 * a * b + msup(b 2) ` = ` msup(c 2) + 2 * a * b
: msup(a 2) + msup(b 2) ` = ` msup(c 2)
)
~~~~
~~~~
msub("C" x) msub("H" (2 y))
mover(&rightarrow : \( "burned in O~2~" \))
x _ "CO~2~" + y _ "H~2~O"
~~~~
Using half angle formula:
{`tan #(mfrac(π 12)) = mfrac(1 - cos #(mfrac(π 6)) : sin #(mfrac(π 6))) = 2 - msqrt(3)}
By default a content block contains Arcadam mathematical notation.
The mathematical notation uses a human-readable form of MathML. MathML entities written with a "&" are supported as well as equivalent Unicode characters to write complex formulas. Spaces are required.
Attributes can be applied by appending a tilde "~" and a replacement key name to any object. The replacement value contains the attributes. Formulas can be aligned in a table-like matrix using "mtable" with the backtick "`" as cell separator and the colon ":" as row separator.
Symbols with a special meaning are:
; invisible comma
* invisible times
_ horizontal space
# apply function
#( ) apply function with brackets
: group or row separator
` cell separator
" " regular text
( ) align contents in a row
{ } replacement key name
[ ] reserved
// comment
[content=text/html]
~~~~
<strong>"Hello!"</strong>
~~~~
[!type Standalone control](additional info)
Inline control: [?type Optional details](brackets required here)
{@ custom element}
[@custom marker]:
Arcadam offers custom content blocks, custom controls, custom elements and custom markers.
When the content block type contains "/" it is considered a MIME type.
A standalone custom control must be on its own line and the end brackets are optional. On the other hand, the end brackets are required even if they are empty for an inline custom control.
A custom element can be used anywhere. It always starts with a special character. A custom marker applies to the following paragraph or block. It must be on its own line. A custom marker always starts with a special character. The optional ">" indent sign at the beginning of the lines that follow is removed in the output.
A custom marker can be followed by a single character on the same line to change the paragraph or block visibility.
The options are:
| character | display option |
|---|---|
+ |
visible |
- |
hidden |
> |
expanded |
^ |
collapsed |
The default option is set by the custom marker. If the output format is interactive, the viewer can switch between collapsed or expanded. By default the block title is used as the toggle.
An attribute is written inside square brackets and applies to the immediate following paragraph or block.
Additional attributes can be applied using commas to separate them.
Example:
[code=xml,.partial]
<root>
<element>
This is XML text which
can be colourised
</element>
[NOTE]
====
This is important.
====Some attributes can take a value. If the value contains any special characters it should be enclosed in double quotes.
Example:
[rows=">h,^,^"]
If the attribute name starts with a dot "." and a stylesheet is defined then the specified style class is applied.
Style class attribute can be used in the middle of text by highlighting the part of the text they apply to.
Example:
This paragraph contains #underlined text#{.underline}.
[!include region-tag](Shared-file.arcd)Use the "include" custom control to insert the contents of an Arcadam file found at the specified location.
A tag name may be provided in the square brackets so only the designated region of the Arcadam file is inserted instead of the whole contents.
Note that for security reasons, including a file from an arbitrary location is disabled by default.
The begin and end tags define a named region for include:
{:begin region}
This text can be included
on its own
{:end region}
```
Inside a code block, a named region
// {:begin coderegion}```
is defined using begin and end tags
before a code block marker that ends
// {:end coderegion}```
the line.
``````
require 'sinatra'
# {1}```
get '/hi' do
# {2}```
"Hello World!"
# {3}```
end
# {:in ruby}```
```
> + [?info Import](1): Library import
+ [?info Mapping](2): URL mapping
+ [?info Response](3): HTTP response bodyFor automatic callout numbering use {#} and (#) instead of numbers.
Allowed numbers go from 0 to 9 and can be replaced in the output to keep them in sequence.
The same number can be used multiple times to indicate that the information relates to more than one line.
When it encounters callouts in a code block, the generator inserts the callout symbols in the line above and the entire line which contains callouts is deleted.
If the deleted line starts with a known block comment marker, the
generator looks for a matched closing comment marker at the
beginning of next line and deletes that too, for example /* and
the closing comment marker */ in C.
// Line comment
////
Comment
block
////
Comments are for information only.
Arcadam documents can be localised for an international audience.
Define the "translations" replacement value to enable it:
:key:translations cn en es fr jp kr ru
This tells the generator to look for translations in the listed directories.
Localisation files contain the text to translate with
synchronisation marks @ which serve as placeholders for
untranslatable text. These marks always appear at the start of
a line.
The following are included in the translation:
- formatting
- hyperlinks and custom controls (images and buttons)
- markers and custom elements (bibliography, footnotes and anchors)
- callouts
- user-defined replacement values
- comments
By default, code and content blocks are excluded. To include a code block use the "localize" attribute:
[localize=Y]
```
This will be translated.
```
```
Use a localize tag inside a code
// {:localize Y +1}```
block to translate the line above.
You can also extend the selection
by adding a number of lines below
the tag that should be translated.
```Conversely, the attribute can be used to prevent the translation of text:
[localize=N]
This must not be translated.
If applied to an include, it prevents the generator from looking for a matching localisation file. Instead, the include link is added to the translation so that it can be customised for each locale.
The generator applies the following steps in order to transform the contents of the document:
apply - apply markers and attributes
localize - localise the text using translations (if enabled)
convert - replace special characters with their corresponding entities (
<,>and&for HTML). This step also converts custom content (for example math to MathML) and enables syntax highlighting in code blockscustomize - process callouts, includes, custom elements and custom controls
format - apply inline text formatting
replace - put replacement values in place of key names
symbols - replace sequences of characters with symbols, for example replace
->with →layout - process pages breaks, enumerations and the line break character
+
The current style class controls which transformation steps are applied. For example, code blocks use the ".verbatim" style class which only does the customize and convert transformations.
To choose which steps are applied for a particular style class, define a special replacement value called "steps" followed by the style class.
Example:
:key:steps.formatted replace, format, symbols