Documentation markdown language

Author(s): The Ciao Development Team.

This section describes the markdown-flavor lightweight syntax for writing documentation. LPdoc supports combining both markup and markdown syntax in the same document. Internally, all markdown syntax is translated to the equivalent markup before processing.

Syntax

Sections

Sections are marked with one or more # symbols at the beginning of a line:

# Sections and subsections

Text for the section.

## Subsection

Text for the subsection.

### Subsubsection

Text for the subsubsection.

Styling text

Text surrounded by _ (or *), __ (or **) produces emphasized or bold text:

Text can be _emphasized_ (*emphasized*) or __bold__ (**bold**).

produces the following results:

Text can be emphasized (emphasized) or bold (bold).

Paragraphs

Paragraphs are break by blank lines, as follows:

Begin of
a paragraph.
This paragraph ends here.

Begin of a new paragraph.
This paragraph ends here.

The last new paragraph. This paragraph ends here.

which produce the following results:

Begin of a paragraph. This paragraph ends here.

Begin of a new paragraph. This paragraph ends here.

The last new paragraph. This paragraph ends here.

Lists

Lists are composed of lines beginning with - items, which can be nested:

- item 1
  - subitem 1-1
  - subitem 1-2
    - subitem 1-2-1
  - subitem 1-3
- item 2
  - subitem 2-1
- item 3

produces the following result:

item 1
- subitem 1-1
- subitem 1-2
  - subitem 1-2-1
- subitem 1-3
item 2
- subitem 2-1
item 3

Additionally you can write enumerated lists:

Enumerated list with automatic numbering:
  -# First
  -# Second
  -# Third

Enumerated list with explicit numbering:
  1. First
  2. Second
  3. Third

Enumerated list with non-consecutive explicit numbering:
  2. First
  4. Second
  6. Third

Enumerated list mixing all above:

 2. First
 4. Second
 -# Third
 -# Fourth
 10. Fifth
 -# Sixth

producing:

Enumerated list with automatic numbering:

First
Second
Third

Enumerated list with explicit numbering:

First
Second
Third

Enumerated list with non-consecutive explicit numbering:

First
Second
Third

Enumerated list mixing all above:

First
Second
Third
Fourth
Fifth
Sixth

Description lists are used to describe some denoted elements:

- opt :: First
- foo :: Second
- bar :: Third

which produces:

opt: First
foo: Second
bar: Third

Description lists may contain richer elements as items:

- `atom` :: an atom.
- `append/3` :: a predicate or functor name.
- `f(X0,...,Xn)` :: some term with variables `X0`, ..., `Xn`.
- `X` :: a variable.
- $x^2$ :: some math.
- $igwedge_j f_j(x_0, ldots, x_n)$ :: some complex math.

which produces:

atom: an atom.
append/3: a predicate or functor name.
f(X0,...,Xn): some term with variables X0, ..., Xn.
X: a variable.
$x^2$: some math.
$igwedge_j f_j(x_0, ldots, x_n)$: some complex math.

Links (markdown style)

You can write links in markdown style:

A link to \href{https://ciao-lang.org} showing its URL.

A link to [Ciao](https://ciao-lang.org) hiding its URL.

A link to [The **Ciao** System](https://ciao-lang.org) hiding its URL
with a complex string.

which produces:

A link to https://ciao-lang.org showing its URL.

A link to Ciao hiding its URL.

A link to The Ciao System hiding its URL with a complex string.

Org-mode style links are also suppored:

A link to [[https://ciao-lang.org]] showing its URL.

A link to [[https://ciao-lang.org][Ciao]] hiding its URL.

A link to [[https://ciao-lang.org][The **Ciao** System]] hiding its URL
with a complex string.

A link to https://ciao-lang.org showing its URL.

A link to Ciao hiding its URL.

A link to The Ciao System hiding its URL with a complex string.

Code spans and code blocks

In addition to the @tt{} markup environments, we support code spans with a single backtick, as follows:

This is a predicate name `append/3`, a variable name `X`, an
atom name `foo`, a quoted atom name `'foo'`.

producing:

This is a predicate name append/3, a variable name X, an atom name foo, a quoted atom name 'foo'.

Blocks of code are marked with triple backticks (you may use ~~~ to escape ```, if your code contains that sequence of backtick characters):

Text that is 4-char indented is recognized as code:

    list([]).
    list([X|Xs]) :- list(Xs)

which produces:

Text that is 4-char indented is recognized as code:

list([]).
list([X|Xs]) :- list(Xs)

Code blocks also support (optional) language specifier to enable syntax coloring and other special features (like runnable code blocks):

```ciao
list([]).
list([X|Xs]) :- list(Xs)
```

which produces:

list([]).
list([X|Xs]) :- list(Xs)