Missing breadcrumb name in maven site module

[abelsromero]

Thank you for taking your time to talk with us!

What is this issue about?

• [x] Bug report
• [ ] Feature request
• [ ] Question

Description

When enabling breadcumbs in a maven site, the name for the current page is not present.

The expected behauviour should be similar to:

Environment information

• asciidoctor-maven-plugin version: 2.2.5
• asciidoctorj version: 2.5.11
• Maven, Java and OS version: all

[abelsromero]

Some reverse engineering from the maven-site-plugin documentation shows, that information must come from the metadata encoded in the same document. For the site plugin the APT module uses the document title which is the document header https://github.com/apache/maven-site-plugin/blob/d78b8da70fd186738707f14166812d721064b766/src/site/apt/examples/adding-deploy-protocol.apt.vm#L2.

Note that the breadcrumb configuration is inherited from https://github.com/apache/maven-parent/blob/e1bc57ba6a9b1ac220d810af9d7301b8a95f0806/src/site/site.xml#L65-L68. To test in isolation those elements and fluido config need to be added to a local project.

We can take the opportunity to also add the other metadata https://github.com/apache/maven-doxia/blob/4eda5adb3c9010131ac1f9118d8ed6c262883762/doxia-sink-api/src/main/java/org/apache/maven/doxia/sink/Sink.java#L162-L176.

[abelsromero]

For a possible approach for the asciidoctor plugin we can use asciidoctor.load() to obtain the source metadata and pass it to the sink, the issue is that we'll be effectively parsing the documents twice with a significant performance cost.

sink.head();
sink.title();
sink.text("Example Manual");
sink.title_();
sink.head_();

[mojavelinux]

Fortunately, there is a trick to avoid this overhead. First, you can set the :parse_header_only option to restrict the parsing to the document header. (See https://docs.asciidoctor.org/asciidoctor/latest/api/options/). Another trick you can use is to try to detect the end of the header and split the source so the parser only has to read the lines from the header. We use this trick in Antora. See https://gitlab.com/antora/antora/-/blob/main/packages/asciidoc-loader/lib/load-asciidoc.js?ref_type=heads#L72-77 However, that trick does impose some restrictions on how the document is formatted and may not be appropriate. You'll need to decide whether it is worth it.

[abelsromero]

You'll need to decide whether it is worth it.

I like the idea of splitting the header. The issue is the parse receives an InputStreamReader so we'd need to see how to extract the data without impacting the conversion or duplicating buffers.

Also, note to future self, we'd need to pass options and attributes to load in case the user is composing that data into other attributes like title.

[abelsromero]

PR is ready https://github.com/asciidoctor/asciidoctor-maven-plugin/pull/769. Still on plan to release tomorrow.

[abelsromero]

@kriegaex v2.2.6 is out, thanks for the report and the research.

[kriegaex]

I upgraded, and it works. Thank you so much.

[abelsromero]

Moving this to 3.0.0. The fix for 2.2.6 was already done in a way that can be easily ported.