Supporting “commands” in addition to “classes” in attributes?

rauschma commented 3 months ago

(As an aside: I’m working on a Markdown parser and just discovered djot yesterday – after having been a fan of Pandoc for years. It fixes virtually every complaint I have about Markdown/CommonMark. Thanks for creating this project!)

For my Markdown dialect, I have introduced “commands” – which are syntactically very similar to classes but live in a separate namespace – which, for HTML output, has the benefit of them not having to play double duty of CSS class (which should appear in output) vs. command (which should not appear in output).

Let me know what you think!

Syntax of commands

Inside attributes, !cmd works syntactically like .cmd.
Outside attributes (code blocks, div blocks), !cmd works like cmd.

For single-line commands, I have found it useful to support attributes for thematic breaks like this:

--- !cmd

--- !cmd {key="value"}

--- {!cmd key="value"}

Following djot rules, this could be changed to:

--- !cmd

{key="value"}  
--- !cmd

{!cmd key="value"}
---

More examples:

``` !cmd
Code block with command

::: !cmd Div block with command :::


## Use cases for commands

My tool supports all of the following constructs for HTML and LaTeX. It uses commands as extension points for Pandoc-style filters to implement (most of) them.

### Table of contents

``````md
--- !global-toc

--- !local-toc

Floats (figures, tables, etc.)

[](#fig:diagram){!float} visualizes how everything is connected.

::: !float {for="Figure" #fig:diagram}
![](img/venn-diagram.svg){width="277.164" height="176.5"}
--- !caption
Visual explanation.
:::

[](#tbl:summary){!float} contains a summary.

::: !float {for="Table" #tbl:summary}
| Output | Vector | Bitmap |
|--------|--------|--------|
| HTML   | `.svg` | `.jpg` |
| LaTeX  | `.pdf` | `.jpg` |
--- !caption
Brief summary.
:::

If !float links contain text, my tool only adds the number of the float (each kind of float has its own per-chapter counter). That helps with languages that have declension (cases):

[Figure](#fig:diagram){!float}
[Table](#tbl:summary){!float}

Content indices

Displaying the index:

--- !printindex

Specifying entries for the index:

Basic index entry:

[mammals]{!index}
[]{!index key="mammals"}

Formatted text with a different sort key:

[`async`]{!index key="async"}
[]{!index md="`async`" key="async"}

Multiple levels of keys (the span content between square brackets is ignored):

[]{!index key1="Array" key2="Array index"}
[]{!index key1="Array" key2="Array hole"}

Book structure

	Chapter numbering	Page numbering
`--- !frontmatter`	Off	Roman numerals
`--- !mainmatter`	Normal	Normal
`--- !appendix`	Letters	Normal
`--- !backmatter`	Off	Normal

Boxouts

Boxes with notes and (optionally) icons:

::: !boxout {icon="icon/tip.svg"}
**This is a special tip**
---
This text describes the tip.
:::

Users can specify default images sizes elsewhere.

Vertical spaces

--- !vspace {height="0.5em"}

matklad commented 3 months ago

It fixes virtually every complaint I have about Markdown/CommonMark

Yup yup yup, have a similar story here, where I blogged a list of my markdown/adoc complaints and got pointed towards the djot afterwards, which turned out to be exactly the thing I wanted!

Could you tell more about the intended semantics of !cmd syntax? I understand that your custom tool could treat it specially, but what's the default behavior? If you paste


::: !cmd
Div block with command
:::

into the djot's playgroud, what is the expected output?

See also https://github.com/jgm/djot/issues/240 which also suggests to carve out syntactic space for something which isn't necessary a css class semantically.

rauschma commented 3 months ago

Could you tell more about the intended semantics of !cmd syntax?

By default, parsers would simply ignore commands. They are mainly intended as extension points for Pandoc-style filters.
But they could also trigger some built-in functionality – e.g.: --- !appendix

jgm / djot