Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [asciidoc-wg] AsciiDoc support of custom highlighting

Hi Alexander

yes, please add me to interested party ( and Inria )

About the code block highlighting I think this is not just an implementation issue but this should come to the specification too.

AFAIK, the current situation is: asciidoc only specify the name of the language for the code block, then the implementation has to find a highlighter to deal with it. Then implementations such as asciidoctor relies on external highlighters each of them supporting only a finite set of languages. - This is fine is you deal only with mainstream languages, but there is usually no support for custom languages (or recent ones) If we stick to Eclipse world there plenty of languages that would appreciate to have such support (Xtext, xtend), not speaking about all the DSL (Domain Specific Language) that are quite easy to build today or the DSLs of many communities. - This doesn't scale well when you need several backends (both pdf and html for ex) leading to inconsistent presentation outputs for these blocks.

The situation back with docbook was slightly better, it allows to specify custom language in a SyntaxHighlighters specification (cf. ) which is used in a pre-processing phase before doing the final backend rendering (html/pdf/word/epub)

I think asciidoc should also have in its specification a part equivalent to the syntax highlighter regardless of the implementation backends.

Didier Vojtisek

On 11/06/2020 21:29, Alexander Schwartz wrote:
Hallo Didier,

breaking down the implementation to different modules sounds like a best
practive: this would keep the parsing of AsciiDoc and creating an AST
separate from creating an output format.

The Asciidoctor implementation already pluggable output formats (called
backends), and this proved very valuable in different scenarios. I think
it is a best practice this implementation should adopt. It also creates
a block-level AST that can be inspected at run-time.

If you are using Asciidoctor today and given some Ruby knowledge, you
could try your luck with either a tree processor (the Asciidoctor
extensions lab contains varios tree processors already) or a backend
(you might want to strip down the html5 backend, see the source of

If you have problems with Asciidoctor souce highlighting, maby as this
question with an example in the Asciidoctor forum.

Regarding the project proposal: If you want to add yourself as an
interested party to try out early releases, or if you want to suggest
requirements for the scope, please let me know.


On 11.06.2020 14:48, Didier Vojtisek wrote:

(not sure this is the best thread)
what are the plan about implementation extensions in order to support
various output variants or complement?

for example, one of my daily usecase is to generate both the html and
the toc.xml files in order to include the generated html file in the
Eclipse help system.

As far as I known this toc.xml generation doesn't exist in
asciidoctor, so our current tool chain is more complex: first generate
the docbook from the asciidoc then use the docbook toolchain to
generate the complementary toc files.

similarly, there is also the point about supporting custom variants
for html such as webhelp (again a quite old output from docbook
toolchain but that has the good benefit to have a scalable outline/toc)

Best regard
Didier Vojtisek

ps: short introduction about myself:
I started using docbook since ~2005 to write the documentation of our
research tools, I moved to asciidoc as input language but regularly
still need to fallback to docbook toolchain due to lacks in asciidoc
toolchain such as the one above or the poor support of highlighting
for custom languages in the [source] code block

Alexander Schwartz (alexander.schwartz@xxxxxxx)

asciidoc-wg mailing list
To unsubscribe from this list, visit

Didier Vojtisek
SED Rennes - DiverSE Team - LogicA Team
Inria, Univ Rennes, CNRS, IRISA
Campus de beaulieu
35042 Rennes
02 99 84 75 07

Back to the top