[
https://issues.apache.org/jira/browse/DOXIA-771?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17910776#comment-17910776
]
Matthias Bünger edited comment on DOXIA-771 at 1/7/25 7:39 PM:
---------------------------------------------------------------
Hi [~kwin],
thanks for your response.
{quote}
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).
{quote}
To be honest I was surprised by this and read up some more. Some markdown
guides highlight that (e.g. [this for
Jekyll|https://simonewebdesign.it/anchor-link-heading-markdown/]), 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
{code}
### 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)
{code}
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|https://www.markdownguide.org/extended-syntax/#heading-ids] might be
"wrong" too. It says that the following code should create an anchor for the
heading the id id {{custom-id}}
{code}
### 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)
{code}
But also here the Doxia one does not behaves different and ignores the custom id
{code:xml}
<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>
{code}
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...
was (Author: JIRAUSER302100):
Hi [~kwin],
thanks for your response.
{quote}
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).
{quote}
To be honest I was surprised by this and read up some more. Some markdown
guides highlight that (e.g. [this for
Jekyll|https://simonewebdesign.it/anchor-link-heading-markdown/]), 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
{code}
### 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)
{code}
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|https://www.markdownguide.org/extended-syntax/#heading-ids] might be
"wrong" too. It says that the following code should create an anchor for the
heading the id id {{custom-id}}
{code}
### 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)
{code}
But also here the Doxia one does not behaves different and ignores the custom id
{code:xml}
<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>
{code}
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)
> Markdown: Generated anchors of headings are incompatible with "regular"
> inpage-links
> ------------------------------------------------------------------------------------
>
> Key: DOXIA-771
> URL: https://issues.apache.org/jira/browse/DOXIA-771
> Project: Maven Doxia
> Issue Type: Bug
> Affects Versions: 2.0.0-M12
> Reporter: Matthias Bünger
> Priority: Major
>
> (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
> {code}
> ### 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)
> {code}
> 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
> {code}
> <a id="How_do_I_skip_unit_tests_when_building_a_project.3F"></a>
> {code}
> Which results, that you (I did not find another way) you have to create the
> link using exactly this generated anchor
> {code}
> ### 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)
> {code}
> Which is not very intuitiv to write.
> Note:
> I also tried to manually create and use an anchor, e.g.
> {code}
> <a id="HowDoISkipUnitTests"></a>
> ### How do I skip unit tests when building a project?
> Create a [link to that](#HowDoISkipUnitTests)
> {code}
> But this manual defined anchor got totally ignored and not generated in the
> resulting HTML.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
