As of February 2024, I played around with Asciidoc, Pelican and Eleventy.
The metadata in my files do not follow the Asciidoc conventions.
They are enclosed in ifeval, so they are only used when the article is
blogged, not when it is included in a bigger book.
Also, there is a blank line between title and metadata.
The Eleventy Asciidoc
plugin
did not pick up the metadata (like author, tags
etc.) from the Asciidoc files.
The Pelican Asciidoc
plugin
does.
And here is why:
It’s quite unspecific.
Which is good, because it allows my slightly non-legal use of Asciidoc
attributes.
All the years I happily blogged in Asciidoc, without ever thinking about the
exact Asciidoc attribute specification.
But when I tried to port my blog to Eleventy it made me wonder why the
Eleventy
Asciidoc plugin did not pick up my Asciidoc attributes.
The Eleventy Asciidoc plugin uses the Asciidoctor.js package,
which seems to stick to the Asciidoc specification and only picks up attributes
that directly follow the documents title and that are not enclosed in an
ifeval block.
The Pelican Asciidoc plugin, on the other hand, picks up every line in the
document that starts with a colon, then has some chars which are followed by a
second colon.
Which is against the convention for Asciidoc attributes that are only allowed
in a block that directly follows the document title.
They call it the document header.
And this picks up every such line, even where it’s not legal for such a line to
appear, for example inside a code block.
You can test that easily:
Take a blog article that has an author in the document attributes, like
:author: Dr. Nikolaus Schüler
Add a code block (enclosed in dots) somewhere down in your Asciidoc file.
Put an author name there, like
:author: Mr. Arthur Miller
When Pelican processes the article, the author name will be, you guessed right:
Mr. Arthur Miller.
Which proves that the Pelican Asciidoctor plugin picked up the second author
attribute.
Case closed.
Indeed, inception strikes again.
I have to set the author a third time so that the correct author is shown in the
blog.
:author: Dr. Nikolaus Schüler
Which nicely demonstrates the point this article tries to make.