[DOXIA-771] Markdown: Generated anchors of headings are incompatible with "regular" inpage-links

[jira-importer]

Matthias Bünger opened DOXIA-771 and commented

(Disclaimer: I'm not sure if the issue is right here of must be placed in Doxiasitetools, please move it, if wrong).

---

I updated a page of the Maven-Site (so I think affected version is latest 2.0.0-M12) and wanted to create links to section headings on the same page. The "regular" way according to Google is that anchors are generated with all lowercase, minus between words and removed special chars. So you can create a link like this

      1. How do I skip unit tests when building a project?


Create a [link to that](how-do-i-skip-unit-tests-when-building-a-project)

The IDE (IntelliJ) is happy with that (meaning shows no warning, that the anchor may not exist), but the link does not work, because DOXIA generates another anchor

<a id="How_do_I_skip_unit_tests_when_building_a_project.3F"></a>

Which results, that you (I did not find another way) you have to create the link using exactly this generated anchor

      1. How do I skip unit tests when building a project?

Create a [link to that](#How_do_I_skip_unit_tests_when_building_a_project.3F)

Which is not very intuitiv to write.

Note: I also tried to manually create and use an anchor, e.g.

<a id="HowDoISkipUnitTests"></a>
      1. How do I skip unit tests when building a project?

Create a [link to that](#HowDoISkipUnitTests)

But this manual defined anchor got totally ignored and not generated in the resulting HTML.

---

Affects: 2.0.0-M12

[jira-importer]

Konrad Windszus commented

For Maven Sites each heading automatically gets an anchor. There is no standard way to create an anchor ID from an arbitrary heading text. The logic in https://github.com/apache/maven-doxia/blob/a6158e2f29d8d2f12b606a5c18a147842f0ee78e/doxia-core/src/main/java/org/apache/maven/doxia/util/DoxiaUtils.java#L159 is applied, but this is an implementation detail, i.e. you should not reference that manually (it is only supposed to be used with the TOC macro).

For the 2nd issue please provide a failing testcase in https://github.com/apache/maven-doxia/blob/master/doxia-modules/doxia-module-markdown/src/test/java/org/apache/maven/doxia/module/markdown/MarkdownParserTest.java.

[jira-importer]

Matthias Bünger commented

Hi Konrad Windszus, thanks for your response.

There is no standard way to create an anchor ID from an arbitrary heading text. The logic in https://github.com/apache/maven-doxia/blob/a6158e2f29d8d2f12b606a5c18a147842f0ee78e/doxia-core/src/main/java/org/apache/maven/doxia/util/DoxiaUtils.java#L159 is applied, but this is an implementation detail, i.e. you should not reference that manually (it is only supposed to be used with the TOC macro).

To be honest I was surprised by this and read up some more. Some markdown guides highlight that (e.g. this for Jekyll), most do not. So yes I assumed that the following code is standard markdown, because I didn't find any guide that says something different

      1. How do I skip unit tests when building a project?


Create a [link to that](how-do-i-skip-unit-tests-when-building-a-project)

So yes I can agree on the fact, that automatically generated id s for headings are part of the implementation, which bother's me why the Doxia one behave different from most others, but well.

I then looked up if I find a standard way to create custom ids for headings. I assume that this also does not exists in the original markdown, so maybe this tool agnostic Markdown guide might be "wrong" too. It says that the following code should create an anchor for the heading the id id custom-id

      1. How do I skip unit tests when building a project? {#custom-id}

Also refer to [How do I skip unit tests when building a project? Custom](#custom-id)

But also here the Doxia one does not behaves different and ignores the custom id

<a id="How_do_I_skip_unit_tests_when_building_a_project.3F_.7B.23custom-id.7D"></a>
<h3>How do I skip unit tests when building a project? {#custom-id}</h3>

P.S. Don't have time trying to create MarkdownParserTest based test for both, will try the next days (new job positions starts kicking in with new year)

edit: After forking and importing the doxia project into my IDE, I thought I could create a fix test, but all test fails due com.google.inject.CreationException. Will read docs, what I have to do to make the Doxia tests run...

[jira-importer]

Matthias Bünger commented

Ok wrote two tests

1. The custom-html anchor now worked - don't know why it did not on the day when I created the issue. Tested it back then and today with a markdown file in site
2. the custom anchor in heading is not supported as it seems, see this test

https://github.com/Bukama/maven-doxia/blob/9becd7f4b2dda571c9f98ade7b61fa905a17c947/doxia-modules/doxia-module-markdown/src/test/java/org/apache/maven/doxia/module/markdown/MarkdownParserTest.java#L906

I'm okay to closing this issue as the custom html anchor seems to be working. I'm also fine when the issuse is used to fix/introduce support for custom anchors in headings. You decide Konrad Windszus