Pagedown: Deactivate anchor sections for pagedown

[cderv]

@yihui the activation of anchor_sections by default and the quick release after that was a bit too much because all the format were not checked in time.

I believe like for xaringan, this feature should be deactivated by default for pagedown. Or at least adapted because it does not render well currently.

See: https://pagedown.rbind.io/#pagedjs

[yihui]

Yes, I actually had this concern in mind and am open to deactivating it by default in the next release. I'm not too concerned by the packages in our own hands, since we could quickly make changes accordingly. I was mainly concerned by packages maintained by other authors.

[cderv]

It is nice to have it by default because a lot of standard content will gain this feature and it is nice for better linking in docs, but as we don't communicate yet this type of change, and we do without a period of feedback before release, and because a lot of people have extended format using html_document(), any default change will have impact we don't measure correctly yet.
(For now, we know of xaringan, learnr, pagedown)

We could inform all developers extending rmarkdown of this type of change in advance, or we could not change the default at all. Former case would mean to have a place / way to communicate easily to developers. Later case would mean to communicate about the change so that people know they can activate it if they want.

If we add none default features without communication, I doubt that a lot of person will read the help page, or the NEWS file and use it.

Anyhow, in all the case, we may take some more time to tests and communicate before release. What could be a nice feature for some, could also be a breaking change for others, and we need to make both type of user happy ! And here I guess @RLesur was not happy to see his pagedown document weirdly impacted without notice 😄

[yihui]

I intentionally held the PR from being merged into rmarkdown v2.4 exactly for the reason you mentioned: to give users more time for testing. After v2.4 was released, I merged the PR almost immediately, hoping to give it more time for the v2.5 release. Unfortunately the Pandoc 2.11 disruption made the release of v2.5 much sooner than I planned. Regarding announcement, I feel you can play the role of "press spokesman" than me. Sometimes I feel I'm getting too much attention for little things (on the other hand, I'm a little worried about "training" users not to read release notes any more but tweets or blog posts instead). This year the only two things that I feel I need to announce are the cookbook and the blogdown releases :)

As I said, if you feel there is too much disruption, I'll be totally happy to disable this feature by default.

And my apologies to @RLesur!

[RLesur]

No worries @yihui !

IMO, adding HTML dependencies (JS/CSS) in rmarkdown::html_document() is a risky choice. They can easily mess up downstream output formats extending rmarkdown::html_document().
I understand the motivations but I wonder whether this is a good choice.
If rmarkdown::html_document() is intended to be less stable, one should explain to downstream maintainers that they should extend rmarkdown::html_document_base() rather than rmarkdown::html_document().

[yihui]

No, html_document() is definitely not intended to be less stable. I was aware of the risk but still underestimated the impact of this feature, i.e., how could an extra anchor link break your document? I guess pagedown is the worst case scenario (which could have been discovered if I had more time). For xaringan, the anchors do not break the output; they are simply useless or annoying or confusing.

Given the above feedback, @cderv what do you think of deactivating this feature by default? If you think it's a good idea, please feel free to do it in the master branch (with a news item). No need to send a PR. Thanks!

[cderv]

I think we have dealt with the feedback we had:

• learnr has deactivated it
• pagedown also
• xaringan
• distill did not have an issue because we already deal with format that have already anchors
• bookdown is working

We did not had any feedback on GH regarding some breakage in other place.

I think we could keep it now it is done - but we will be carefully add other feature. I don't like having all new features turned off by default only to prevent some breakage somewhere. We may need to provide new formats with a set of feature active more often - to differentiate from standard html_document.
But also I think we could better prepare the change to get some feedbacks before release. Pandoc 2.11 support indeed forced us to release earlier has we dont have a git workflow supported patch release at the same time as next new feature release. (We could have played a bit with git to manage that though - just the time to do the release with Pandoc support only 😄 )

I understand the motivations but I wonder whether this is a good choice.
@RLesur, what do you think ? Has it broken some of your internal format built on rmarkdown ?

[RLesur]

@RLesur, what do you think ? Has it broken some of your internal format built on rmarkdown ?

My concern is quite technical:

• the execution of JS scripts is sensitive to the order of execution. IMO, the maintainer of an R Markdown output formats wants to keep control of all the JS scripts
• same thing for Cascading Style Sheets

This is related to a problem that we have with HTML dependencies: it is very hard (and almost impossible in many circumstances) to control the order of the HTML dependencies.

I wonder whether new CSS/JS features could be:

• activated for one of the rmarkdown::html_document() builtin theme default values
• deactivated by default when theme is NULL providing a parameter to include them

[cderv]

I wonder whether new CSS/JS features could be:

activated for one of the rmarkdown::html_document() builtin theme default values
deactivated by default when theme is NULL providing a parameter to include them

I like those ideas !

[atusy]

I love the idea, too.
I tried to use Honoka (https://github.com/windyakin/Honoka) which is a Bootstrap theme for Japanese language.
However, if I set theme = NULL and and include Honoka as an HTML dependency, I lost some features such as floating ToC and code folding.
If I can provide a parameter to include some features manually, I can re-try Honoka.
(Sorry, I guess this is slightly an off topic)