Quick arguments to suppress or rename homepage sidebar sections

[aaronrudkin]

The default pkgdown behaviour -- to generate home page sidebar groups for Links, License, Developers, and "Dev status" -- is probably a good default, but not an exhaustive one. Users might reasonably want to suppress or rename some of these sections. Renaming has two major use cases: organizational (someone might want "Steering Committee" or some other header for Developers); and internationalization (individuals might reasonably want to translate their documentation websites). Finally, we can't change the order of these sections.

Currently it is possible to work around including dev status by having a separate README.Rmd for Github including badges and an index.Rmd for the pkgdown website excluding badges. But it is impossible to suppress the inclusion of the Links, License, or Developers sections, and impossible to rename any of them, and also a sub-optimal solution because it requires manually synchronizing content text between the two if they are otherwise identical.

In addition, because these sections contain no styling information, it is impossible to suppress sections with custom CSS. This means that anyone who wants to override these must do so by making custom templates (which pkgdown discourages and notes are poorly documented) or to manually edit the generated HTML.

At the risk of proliferating superfluous arguments, would you be open to a patch at some point that adds arguments to build_site and build_home, which would then pass-through to tweak_homepage_html, allowing users more flexibility than they currently have but less than a full custom template would require? I'm not sure how you would most prefer such arguments to be specified (one approach would be to give the argument "suppress_sidebar" which contains a character string or vector of character strings each specifying a section to suppress; another would be separate logical arguments for each section like suppress_license, suppress_developer).

In a similar spirit, a user might want to change the roles that populate the developers list depending on the package's internal organizational structure, so an argument like populate_developers=c("cre", "aut", "fnd", "ctb") might be well taken.

Thanks in advance.

[aaronrudkin]

Having left my issue I contented myself with the idea of doing a custom template in the mean time, only to discover that the sidebar isn't actually in the template, it's constructed entirely in package code and then injected into the template. So I would expand this suggestion to add that the sidebar should at least be generated and injected in chunks so that people can do chunk-level edits if they make custom templates.

[aaronrudkin]

I thought about this for a little while longer, and I think the better method would be to allow users to override this via a new section to the yml. I'll submit a PR next weekend.

[aaronrudkin]

Submitted the PR now #464

[hadley]

Ok, now that I've read through the issue I see your point; this functionality would be useful, and wouldn't add substantial complexity to the code. Are you still interested in working on this? If so, I think it would be best to work in stages, so I can review smaller chunks of code. I think the first step would actually be to eliminate list_with_heading() in favour of an actually meaningful sidebar template. Once that's done, the next step would be to make the sections user controllable.

I don't love the idea of customising populate_developers because I think there are pretty strong existing conventions used widely in the R community. Would you mind expanding on your motivation a little more?

[hadley]

One challenge with using a template is that the badges are currently injected in the right location using html tweaking. Refactoring that code will have to happen first.

[hadley]

For now, I've just added divs around each sidebar section so that you can style/suppress as needed.