Allow headingpermlink attaching to the heading

[MrSpoocy]

Additionally:

• Always add tests and ensure they pass.
• Avoid breaking backward compatibility
• New features and deprecations must be submitted against the "main" branch
• Absolutely nothing changes in the default configuration.

https://commonmark.thephpleague.com/2.3/extensions/heading-permalinks/
This extension makes all of your heading elements (<h1>, <h2>, etc) linkable so that users can quickly grab a link to that specific part of the document - almost like the headings in this documentation!

Yup and this update, allows setting the anchor directly on the headline. Just like you have in your documentation xD

I also think that maybe there should be the possibility to disable the tag completely but then have the anchor in the headline.

I put a lot of effort to consider everything, UnitTest, documentation updated and no breaking changes. I hope that the pull request gets your approval.

[MrSpoocy]

And now I had to realize that I had created the branch from 2.3 instead of the main :(

[MrSpoocy]

[BC] CHANGED: The number of required arguments for League\CommonMark\Extension\HeadingPermalink\HeadingPermalink#__construct() increased from 1 to 3

Is it a breaking change if the class was final (can not extend) and the first parameter is the same? Yes, can be, i have to give the other two param a default value.

[colinodell]

Yup and this update, allows setting the anchor directly on the headline.

Could you explain the value here? Like, I fully understand what this feature allows, but I'm having trouble understanding why this would be important to allow. What's the use case here? Knowing that will help me to give this a proper review :)

Is it a breaking change if the class was final (can not extend) and the first parameter is the same?

Yes, because any external code that used to instantiate a new HeadingPermalink() with one parameter will no longer work.

[MrSpoocy]

It first ensures the separation of the anchor and the link to it. Currently, for example, the icon for an anchor is set by configuration and also decided where it is set. But this decision should be made by the desginer e.g. via CSS.

Further I would like to add the possibility that the <a> tag is not generated, that allows users to link within the own document to the headline (exactly that is my goal without writing extra a new extension).

It sounds more plausible to me to use the already existing extension for Headline instead of parsing the document again and adding more HTML.

EDIT: It also makes more sense to me that the id belongs around <h>, if for example on mobile the headline is wrapped due to the display and the icon is at the end of the headline, the browser would jump too far when calling it.

[colinodell]

Got it, thank you for those extra details! I agree, I think changes like this could be useful :)

Would you mind making a few changes to the proposed implementation?

[MrSpoocy]

If I'm already working on it, should I include the ability to disable the <a> tag already? So that the user can always decide for himself where in the document there is a link on the anchor everywhere.

If so, extend the insert option with a constant HeadingPermalinkProcessor::INSERT_NONE?

[colinodell]

If so, extend the insert option with a constant HeadingPermalinkProcessor::INSERT_NONE?

Yeah, that makes sense to me! Let's do it :)

[colinodell]

Thanks for the contribution! This will be released in 2.4.0.