# New supported blocks for odoc

## Decision

Here is the first set of new features we are going to implement (for syntax, see the description below):

- Admonitions: `Note` and `Warning`
- Quotes
- Definition lists (with links)
- Details
- Strikethrough
- Toc (after some more design)
- Productionlists as just a code block with a 'better' highlighter.

## More details

## :bangbang: Admonitions

{<admonition> content}
{{<admonition> title}content}

I've seen the following values for `<admonition>` in the wild:

- `note`
- `tip`
- `hint`
- `caution`
- `attention`
- `warning`
- `danger`
- `info`
- `question`
- `failure`
- `bug`
- `example`
- `success`
- `important`
- `abstract`
- `theorem`

(My personal selection (@panglesd) would be:

- `note`
- `tip`
- `warning`
- `danger`
- `example`
- `bug`
)

Screenshot from github :

Examples:

{note
  It's not always easy for anyone to determine
  in which library a particular module lives,
  which is a problem that current drivers have
  to worry about, and which this document does
  not change.}

{{warning Do not touch!}
  This equipment is sensitive and may malfunction
  if handled improperly. Unless you are excellent
  at "Button Pressing", please refrain from
  touching it. Your cooperation helps keep things
  running smoothly.}

:::info
It's not always easy for anyone to determine in which library a particular module lives, which is a problem that current drivers have to worry about, and which this document does not change.
:::

:::warning
This equipment is sensitive and may malfunction if handled improperly. Unless you are excellent at "Button Pressing", please refrain from touching it. Your cooperation helps keep things running smoothly.
:::

(See for instance https://squidfunk.github.io/mkdocs-material/reference/admonitions/#supported-types for other example of rendering)

## :bangbang: Quote

{quote To be or not to be}
{{quote William Shakespeare}
  To be or not to be}

> To be or not to be

## :bangbang: Definition lists

{deflist
  {{def Carrot}
    Carrots are orange vegetables. They are eaten by rabbits.}
  {{def Pasta}
    Pastas are a yellow type of human food. They are eaten by italians.}
}

<dl>
<dt>Carrots</dt>
<dd>Carrots are orange vegetables. They are eaten by rabbits.</dd>

<dt>Pasta</dt>
<dd>Pastas are a yellow type of human food. They are eaten by italians (among others).</dd>
</dl>

Having definitions list terms referenceable could make it a good fit for a glossary.

## :bangbang: Image, media, figure, ...

Are already featured in the media document.

## :bangbang: Code blocks and spans with odoc content

Odoc can render code spans and code blocks, using the `[code span]` and `{[code block]}` syntax.
The text inside code blocks and code spans is not parsed as odoc content, which would have some usecases: See for instance https://github.com/ocaml/odoc/issues/756

`{c <content>}` could be for code spans, and `{code <content>}` for code blocks. (Unfortunately, code blocks with marked up odoc content cannot be highlighted by highlightjs... using our own highlighter the same way we do for rendering source code could work around that).

Sphinx has it named as "[parsed-litteral](https://docutils.sourceforge.io/docs/ref/rst/directives.html#parsed-literal)".

This is some {c {!f}} code span with a link in it.

{code
  List.map {!f} l
}

Another possibility would be `{code foo}` for code spans, and `{codeblock ...}` for code span.

## :bangbang: Details

{details This is some hidden content}
{{details This is a summary}This is some hidden content}

(sometimes this is also called `spoiler`)

:::spoiler
This is some hidden content
:::

:::spoiler This is a summary
This is some hidden content
:::

# Lesser priority

## :exclamation: Strikethrough

Strikethrough is not very important, but very easy to add.

This is an example of {~ handwritten} typed strikethrough.

This is an example of ~~handwritten~~ typed strikethrough.

## :exclamation: Footnotes

Some content{footnote Is this a good idea?}

Some content[^1]

[^1]: Is this a good idea?

## :exclamation: Table of content

It is also used in dune's doc (through the toctree directive) and felt important by the author.

Renders the table of content at the current location:
{toc}

Renders a table of content below a reference:
{toc page1}
{toc label-a_title}

With a custom depth:
{toc {depth 3} page1}

For instance, HackMD supports autogenerated tables of content, using `[ToC]`:

[ToC]

# Low priority

## :question: Production lists

Dune's doc [uses that](https://dune.readthedocs.io/en/stable/reference/predicate-language.html).

{@productionlist[
   graph      : [ strict ] (`graph` | digraph) [ ID ] '{' `stmt_list` '}'
   stmt_list  : [ `stmt` [ ';' ] `stmt_list` ]
   stmt       : `node_stmt`
              : `edge_stmt`
              : `attr_stmt`
              : ID '=' ID
              : `subgraph`
   attr_stmt  : (`graph` | node | edge) `attr_list`
   attr_list  : '[' [ `a_list` ] ']' [ `attr_list` ]
   a_list     : ID '=' ID [ (';' | ',') ] [ `a_list` ]
   edge_stmt  : (`node_id` | `subgraph`) `edgeRHS` [ `attr_list` ]
   edgeRHS    : edgeop (`node_id` | `subgraph`) [ `edgeRHS` ]
   node_stmt  : `node_id` [ `attr_list` ]
   node_id    : ID [ `port` ]
   port       : ':' ID [ ':' `compass_pt` ]
              : ':' `compass_pt`
   subgraph   : [ `subgraph` [ ID ] ] '{' `stmt_list` '}'
   compass_pt : (n | ne | e | se | s | sw | w | nw | c | _)
]}

This is a reference to the grammar for a {!label-graph}.

See [this](https://jbms.github.io/sphinx-immaterial/additional_samples.html#production-lists) or [dune's doc](https://dune.readthedocs.io/en/stable/reference/predicate-language.html) for examples of rendering.

## :question: Glossary

This is [part of sphinx](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-glossary) and is [used in dune](https://dune.readthedocs.io/en/stable/overview.html#terminology).

It seems similar to a definition list where definitions have labels. I'm not sure we need to introduce a new syntax. However, labels for terms should be accessible "cross pages".

{1 Terminology}

{deflist
  {{def root}
    The top-most directory in a GitHub repo, workspace, and project,
    differentiated by variables such as [workspace_root] and
    [project_root]. Dune builds things from this directory. It knows
    how to build targets that are descendants of the root. Anything
    outside of the tree starting from the root is considered part of
    the installed world. Refer to Finding the Root to learn how the
    workspace root is determined.}
  {{def:w workspace}
    The subtree starting from each root. It can contain any number
    of projects that will be built simultaneously by Dune, and it
    must contain a dune-workspace file.}
}

The {!root} and {!term-w} are two different dune concepts.

# :rocket: The icing on the cake: Blinking

{blink This is the most anticipated odoc feature}

<style>
.blink {
animation: blinker 1.5s steps(1) infinite;
}
@keyframes blinker {
50% { opacity: 0; }
}
</style>

<span class="blink">This is the most anticipated odoc feature</span>