[MSKINS-226] Add custom option to explicitly enable AnchorJS along with options

[michael-o]

This closes #51

[hboutemy]

having an option to disable, why not, but please enable by default: what is the issue with these (visual) anchors added in https://issues.apache.org/jira/browse/MSKINS-167?

[michael-o]

having an option to disable, why not, but please enable by default: what is the issue with these (visual) anchors added in https://issues.apache.org/jira/browse/MSKINS-167?

Why I didn't enable it by default: consistency with the rest. That is:

• Other extras aren't enable by default
• None of the others have an explicit enable/disable flag, this would require one
• Not everyone wants to have it

[michael-o]

having an option to disable, why not, but please enable by default: what is the issue with these (visual) anchors added in https://issues.apache.org/jira/browse/MSKINS-167?

Why I didn't enable it by default: consistency with the rest. That is:

* Other extras aren't enable by default

* None of the others have an explicit enable/disable flag, this would require one

* Not everyone wants to have it

@hboutemy @slawekjaranowski Please let me know what you think regarding this.

[slawekjaranowski]

Will be better disable it ... generated anchors ids are not the same as doxia generate

[slachiewicz]

If we have working Doxia, why we need also js generated?

[michael-o]

If we have working Doxia, why we need also js generated?

Doxia does not generate any IDs by default, you have to request it in the markup. If Doxia would generate them by default, it might lead to duplicate IDs. See here for details.

[michael-o]

@hboutemy I will first apply the AnchorJS upgrade separately. As said, there is no way to explicitly disable this just like with other options and the inconsistency between AnchorJS IDs and Doxia IDs remains. I will leave this open for now. I still think that this is the right way since any other feature has to be enabled explicitly. This shouldn't be any different.

[hboutemy]

I don't understand the whole discussion about generated ids: do we care about it?

the objective is the deep anchors = the "Basic Link" in https://www.bryanbraun.com/anchorjs/
which makes sharing pointers to precise points in documentation easier

this PR makes whole things more complex: do you have any concrete issue with the current links we have in many Doxia generated sites since a few years that you want to disable it by default?

one solution to enable by default but be able to disable could be:

  <custom>
    <fluidoSkin>
      <anchorJs>
        <disable>true</disable>
      </anchorJs>
    </fluidoSkin>
  </custom>

[michael-o]

Yes, problem is TOC macro for example. People assume that the refs in the TOC use the same id as generated by anchorjs which is not true. In fact, this skins knows nothing about Doxia. They are completely disjoint. I will need to add a note that these IDs do not correspond with Doxia IDs. Adding <disabled> is possible, but would make it inconsistent with other options.

Ref:

• https://issues.apache.org/jira/browse/DOXIA-696

[michael-o]

Added note about incompat.

[michael-o]

Branch rebased and I still consider this reasonable to include in the next major for consistency reasons with the other custom options.

[michael-o]

@hboutemy We have auto TOC now by @kwin done with Doxia.