Custom pkgdown theme from template package

[arangaca]

I'd like to make a template package for my pkgdown site. I'm trying to figure out how it works from the tidytemplate repo. From what I understand, I need a base bootstrap template located in /scss and add my custom style in inst/pkgdown/assets. I guess I'm missing a few files to make it work. The tidytemplate repo has a /scss/bootstrap directory and /scss/_bootstrap.scss file.

Where do these come from? When downloading a base bootswatch template, I can only download _bootswatch.scss and _variables.scss. Same on the bootstrap website, I can't seem to find anything similar to _bootstrap.scss/bootstrap files.

[maelle]

I'd recommend reading the article Customise your site, that includes a section on template packages.

If you're customising one site only, you don't need a template package, you can tweak the pkgdown configuration of your package directly. A template package is useful when you want to share those customisations across several packages.

[arangaca]

Thanks for the reply. I've read that article but it's unclear to me how I should make it all work.

I've a lot of experience with css and feel more comfortable to work from css directly than tweaking the bslib which is also less flexible.

I realised that I don't necessarily need the scss folder but I still can't make my css work. It simply doesn't have any effect on the output.

[maelle]

Why not store the rules in pkgdown/extra.css or pkgdown/extra.scss?

rotemplate/extra.scss at master · ropensci-org/rotemplate · GitHub (here it is in inst/ because it is a template package)

[arangaca]

I probably misunderstood the initial purpose of extra.css and thought it'd add new rules to be used with bslib. In the end, pkgdown/extra.css worked fine. Thanks!

What's the purpose of having css files in inst/pkgdown/assets (like in tidytemplate) though?

Edit:
I did a bit more testing.
pkgdown/extra.css works but not inst/pkgdown/extra.css despite adding the following in _pkgdown.yml:

template:
  package: my_template_package
  bootstrap: 5

[maelle]

inst/pkgdown/assets is for template packages, pkgdown/assets is for use for the pkgdown of the same package where those folders live.

Maybe your template package isn't installed by "whatever you used to build your website"? (GitHub Actions?) See dplyr/DESCRIPTION at 8d03ebdf04acb044c5499074c52ef6ca1b10d8d0 · tidyverse/dplyr · GitHub that declares the dependency on the template package and dplyr/pkgdown.yaml at main · tidyverse/dplyr · GitHub that installs it before building the pkgdown website ( needs: website on line 34) (for context R Packages (2e) - 10  DESCRIPTION). You can get this GitHub Actions workflow via running usethis::use_github_action("pkgdown").

[arangaca]

@maelle

inst/pkgdown/assets is for template packages, pkgdown/assets is for use for the pkgdown of the same package where those folders live.

Sorry, I meant the purpose of having the css in assets instead of using extra.css
One can read in the pkgdown documentation ("Template packages" section):

• inst/pkgdown/extra.scss will be added to the bslib ruleset.
• Assets in inst/pkgdown/assets/ will be copied in to the destination directory.

I initially understood the former as "will add rules to be used with the bslib option in _pkgdown.yaml" when it's actually overriding the default css rules. The latter simply doesn't make any sense to me.

@maelle

Maybe your template package isn't installed by "whatever you used to build your website"? (GitHub Actions?) See dplyr/DESCRIPTION at 8d03ebdf04acb044c5499074c52ef6ca1b10d8d0 · tidyverse/dplyr · GitHub that declares the dependency on the template package and dplyr/pkgdown.yaml at main · tidyverse/dplyr · GitHub that installs it before building the pkgdown website ( needs: website on line 34) (for context R Packages (2e) - 10 DESCRIPTION). You can get this GitHub Actions workflow via running usethis::use_github_action("pkgdown").

I did more testing but I'm still unable to make it work.

Here's a test repo with the custom theme: GitHub - arnaudgallou/cygne
I tried it with the inst/pkgdown/extra.css and inst/pkgdown/assets/foo.css. The css simply doesn't have any effect on the output.

[maelle]

Regarding inst/pkgdown/assets/cygne.css

That one is copied to the pkgdown website, however it's not linked from the website head, only extra.css/extra.scss would be. So if you wanted to use inst/pkgdown/assets/cygne.css you would also need a template configuration file in inst/pkgdown/_pkgdown.yml that has

template:
  includes:
    in_header: '<link href="cygne.css" rel="stylesheet">'

I've tried it:

Regarding inst/pkgdown/extra.css

It works if it is renamed to inst/pkgdown/extra.scss or if it stored in pkgdown/extra.cssso that might be a pkgdown docs problem / bug. I opened an issue.

[arangaca]

Yay!

Awesome! The template package works now. I've tried to use it on the other package but got a dependency error when running GitHub actions (saying it can't find the template package):

Summary

ℹ Creating lockfile '.github/pkg.lock'

✔ Updated metadata database: 3.45 MB in 7 files.

ℹ Creating lockfile '.github/pkg.lock'
ℹ Updating metadata database
✔ Updating metadata database ... done

ℹ Creating lockfile '.github/pkg.lock'
✖ Creating lockfile '.github/pkg.lock' [8.7s]

Error: 
! error in pak subprocess
Caused by error: 
! Could not solve package dependencies:
* deps::.: Can't install dependency cygne
* cygne: Can't find package called cygne.
---
Backtrace:
1. pak::lockfile_create(c(deps, extra_deps), lockfile = ".github/pkg.lock", …
2. pak:::remote(function(...) { …
3. err$throw(res$error)
---
Subprocess backtrace:
1. base::withCallingHandlers(cli_message = function(msg) { …
2. get("lockfile_create_internal", asNamespace("pak"))(...)
3. prop$stop_for_solution_error()
4. private$plan$stop_for_solve_error()
5. pkgdepends:::pkgplan_stop_for_solve_error(self, private)
6. base::throw(new_error("Could not solve package dependencies:\n", msg, …
7. | base::signalCondition(cond)
8. global (function (e) …
Execution halted

I do have the following line in the DESCRIPTION:

Config/Needs/website: cygne

Edit: solved by using:

Config/Needs/website: user_name/template_package_name

@maelle

Regarding inst/pkgdown/assets/cygne.css

That one is copied to the pkgdown website, however it's not linked from the website head, only extra.css/extra.scss would be. So if you wanted to use inst/pkgdown/assets/cygne.css you would also need a template configuration file in inst/pkgdown/_pkgdown.yml that has

Thanks for the explanation. The pkgdown documentation would definitely benefit from this IMO.

---

Maybe one last question related to the topic.

I edited css rules from the default theme used by pkgdown. Although unlikely, assuming the default theme changes and uses rules that my custom theme doesn't override, the design of the current site should also change. Is there a way to store the base design within the template package to avoid that?

[maelle]

I edited css rules from the default theme used by pkgdown. Although unlikely, assuming the default theme changes and uses rules that my custom theme doesn't override, the design of the current site should also change. Is there a way to store the base design within the template package to avoid that?

All pkgdown changes are for the better. More seriously, you could

• use a fixed pkgdown version (using renv) see for instance this action
• follow pkgdown development by subscribing to the releases, and reading the changelog (most important changes should be in there). See Configuring notifications - GitHub Docs

But indeed that's a risk. I see that in the pkgdown template package I am a coauthor of, our CSS rules are commented, which might also help future maintenance: rotemplate/inst/pkgdown/extra.scss at main · ropensci-org/rotemplate · GitHub

[arangaca]

Thank you so much for all the help. Might try the renv solution