Do not override heading ids

[aurelien-baudet]

Current behavior

Context

I use Asciidoctor to generate documentation. Asciidoctor generates anchors and a toc using headings:

• Either by generating an id based on heading text
• Or by using an explicit id that is set in document source (using [[custom-id]])

Ids generated by Asciidoctor are also important because we can make links between different documents (using <<other-document.adoc#custom-id, text>>).

Conflict

Reflow Maven Skin also generates ids for headings based on heading text. However, Reflow Maven Skin always overrides the ids present on the headings.

Therefore, links between documents and anchors generated by Asciidoctor don't work.

Expected behavior

If a heading already has an id, let the id as-is and use it directly.

I think skipping existing ids should be the default behavior. There could have configuration paramters to indicate that all ids are overriden.

The other possibility is to keep id overriding by default but provide configuration parameters to control that. For example, HtmlTool line 1074 could use a configuration parameter to exclude particular pages.

Deal with symbols

As stated in HtmlTool lin 1090, existing id may be malformed. As it is explicitly created by the developer (or a tool used by the developer), there could only have a warning in logs.

Another possibility is to add a configuration parameter to:

• either map an id to another
• or just indicate to override this id with an auto-generated one
• or simply rewrites the id by removing unexpected symbols

Additional information

asciidoctorj version: 1.5.6 asciidoctor-maven-plugin: 1.5.6 reflow-maven-skin: 2.2.0 maven-site-plugin: 3.7

[devacfr]

@aurelien-baudet hello, Thank you for your feedback. I'm following the your work on project ogham. And for this reason, i'll prepare a new version (2.3.0) to (try) simplify your expectation concerning the visual. Normally in your project, your user manual documentation page (i suppose) shouldn't call this method (do not contains TOC).

Now, you can integrate a free content directly (without modification) in body page (https://github.com/devacfr/reflow-maven-skin/issues/61).

< reflowSkin>
  <pages>
    <index type="body" />
  </pages>
</reflowSkin>

A snapshot version 2.3.0-SNAPSHOT is available on maven central. Be careful, This version includes also a big change on header (https://github.com/devacfr/reflow-maven-skin/issues/58) (also for you) allowing to custom the header component.

I'm waiting your feedback. Best Regards. available online on Gitter

[devacfr]

@aurelien-baudet, could you say me on which pages of your project you are this problem? For me, the problem is the execution of method htmlTool.ensureHeadingIds is executed even there is no toc <toc>false</toc>. And also set <html5Anchor>false</html5Anchor> globally or on specific page. see HTML5-style anchors

[devacfr]

@aurelien-baudet A new snapshot version 2.3.0-SNAPSHOT is available on maven central with the fix 098068c. If you want a hot fix on previous version 2.2.0. Let me know.

[aurelien-baudet]

Great !

I will try the snapshot version as soon as possible to give you a feedback.

[aurelien-baudet]

Mgration to 2.30 done with no issue !

[devacfr]

@aurelien-baudet. I recommend use maven-site-plugin 3.9.1, fix problem on <pre> element rendering.

[aurelien-baudet]

Did you mean 3.9.0 ? Because 3.9.1 doesn't seem to exist.

[devacfr]

@aurelien-baudet sorry, I confused with the version of Doxia-tools. Yes, the version of maven-site-plugin is 3.9.0.