Pkgdown: Adding basic docs about styling?

[maelle]

(sorry if it's already there and I missed it!)

Docs along the line of the "basics of styling pkgdown" section of https://enpiar.com/2017/12/18/integrating-pkgdown-with-your-personal-website/ would be nice. :smile_cat:

[jayhesselberth]

Yes it would probably be have a styling vignette; that link is a good place to start.

[maelle]

Just keeping some notes here, maybe I could make a PR for such a vignette if I get things right.

4 ways to tweak the styling, that could be used in complement of each other (I'd tend to imagine it's correct for Bootswatch theme + tweaks via extra.css/other assets; maybe less so for package+other assets?).

• Easiest solution, used an existing Bootswatch theme. In the config file

template:
  params:
    bootswatch: cerulean

• "For finer-grained control, you can put any custom CSS you want in a pkgdown/extra.css file, and it will override any other styles on the page." from https://enpiar.com/2017/12/18/integrating-pkgdown-with-your-personal-website/ (so you could choose a Bootswatch theme or the default theme, and add your few tweaks).

More advanced, in both cases for things not described by templates/assets, the default or the chosen Bootswatch theme is used. Develop assets and templates and use them in a single package or in many packages by packaging the assets and templates.

• assets and templates used once

template:
  path: path/to/templates
  assets: path/to/assets
  default_assets: false
 ```

* assets and templates packaged up

```yaml
template:
  package: mycustompackage

Examples of packages with pkgdown template

• https://github.com/tidyverse/tidytemplate
• https://github.com/lockedatapublished/lockedatapkg
• https://github.com/ropensci/rotemplate/

[maelle]

To add to further resources of that potential future vignette in my question on RStudio community about pkgdown templates Mara recommended Bootstrap docs since pkgdown uses Bootstrap https://bootswatch.com/ (the link should be added with the mention of the Bootstrap version pkgdown uses).

[maelle]

Maybe I should make a PR of a vignette draft this way I wouldn't open useless issues about things I should have known :woman_facepalming:

[maelle]

Also, if one develops custom CSS/HTML, how does one keep that up to date with the default template.

[maelle]

Theming vs layout. Make it clear what the difference is.