diff --git a/.Rbuildignore b/.Rbuildignore index b6ed316..e6251a2 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -4,6 +4,7 @@ ^README\.Rmd$ ^cran-comments\.md$ ^_pkgdown\.yml$ +^index\.md$ ^docs$ ^pkgdown$ ^\.github$ diff --git a/.github/workflows/pkgdown.yaml b/.github/workflows/pkgdown.yaml index 63cbb18..1f089b4 100644 --- a/.github/workflows/pkgdown.yaml +++ b/.github/workflows/pkgdown.yaml @@ -1,35 +1,50 @@ -# Workflow derived from https://github.com/r-lib/actions/tree/master/examples -# Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help +# Workflow derived from https://github.com/r-lib/actions/tree/v2/examples +# Need help debugging build failures? Visit +# https://github.com/r-lib/actions#where-to-find-help on: push: branches: [main, master] + pull_request: release: types: [published] workflow_dispatch: -name: pkgdown +name: pkgdown.yaml + +permissions: read-all jobs: pkgdown: runs-on: ubuntu-latest + # Only restrict concurrency for non-PR jobs + concurrency: + group: pkgdown-${{ github.event_name != 'pull_request' || github.run_id }} env: GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} + permissions: + contents: write steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v4 - - uses: r-lib/actions/setup-pandoc@v1 + - uses: r-lib/actions/setup-pandoc@v2 - - uses: r-lib/actions/setup-r@v1 + - uses: r-lib/actions/setup-r@v2 with: use-public-rspm: true - - uses: r-lib/actions/setup-r-dependencies@v1 + - uses: r-lib/actions/setup-r-dependencies@v2 with: - extra-packages: pkgdown + extra-packages: any::pkgdown, local::. needs: website - - name: Deploy package - run: | - git config --local user.name "$GITHUB_ACTOR" - git config --local user.email "$GITHUB_ACTOR@users.noreply.github.com" - Rscript -e 'pkgdown::deploy_to_branch(new_process = FALSE)' + - name: Build site + run: pkgdown::build_site_github_pages(new_process = FALSE, install = TRUE) + shell: Rscript {0} + + - name: Deploy to GitHub pages πŸš€ + if: github.event_name != 'pull_request' + uses: JamesIves/github-pages-deploy-action@v4.5.0 + with: + clean: false + branch: gh-pages + folder: docs diff --git a/DESCRIPTION b/DESCRIPTION index d543806..b966ddf 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,18 +1,24 @@ Package: greta.pkgdown -Title: 'pkgdown' Templates for 'greta' Packages -Version: 0.0.0.9000 -Authors@R: +Title: Bootstrap 5 'pkgdown' Template for 'greta' Packages +Version: 0.1.0 +Authors@R: person("Nicholas", "Tierney", , "nicholas.tierney@gmail.com", role = c("aut", "cre"), comment = c(ORCID = "https://orcid.org/0000-0003-1460-8722")) -Description: This is a private template for use by 'greta' packages. - Please don't use for your own code. +Description: A shared Bootstrap 5 'pkgdown' template that gives 'greta' + extension packages a consistent look and feel: the greta purple theme, + Roboto typography, tinted code blocks, and a wordmark in the navbar. A + 'greta' package uses it by setting 'template: package: greta.pkgdown' in + its '_pkgdown.yml'. This is an internal template for the 'greta' family + of packages and is not intended for general use. License: MIT + file LICENSE -Suggests: - rmarkdown, - knitr +URL: https://github.com/greta-dev/greta.pkgdown, + https://greta-dev.github.io/greta.pkgdown/ +BugReports: https://github.com/greta-dev/greta.pkgdown/issues +Suggests: + knitr, + rmarkdown Config/testthat/edition: 3 Encoding: UTF-8 -Language: es +Language: en-GB Roxygen: list(markdown = TRUE) RoxygenNote: 7.1.2 -URL: https://greta-dev.github.io/greta.pkgdown diff --git a/NEWS.md b/NEWS.md index 52ee9f6..25ff5b2 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,3 +1,13 @@ +# greta.pkgdown 0.1.0 + +* Modernised greta.pkgdown into a standard Bootstrap 5 pkgdown template + package, following the `tidyverse/tidytemplate` layout. The shared theme now + lives in `inst/pkgdown/BS5/` (bslib purple theme, Roboto fonts, `extra.scss`, + and the navbar wordmark override), and the fork-era `content-*`, `layout-*`, + `footer`, and `pkgdown.css` files have been removed. +* Consuming greta packages opt in with `template: {package: greta.pkgdown, + bootstrap: 5}` in their `_pkgdown.yml`. + # greta.pkgdown 0.0.0.9000 * Added a `NEWS.md` file to track changes to the package. diff --git a/README.md b/README.md index 8c01afa..f53e4e2 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,59 @@ -# greta.pkgdown +# greta.pkgdown - -[![R-CMD-check](https://github.com/greta-dev/greta.pkgdown/workflows/R-CMD-check/badge.svg)](https://github.com/greta-dev/greta.pkgdown/actions) +[![pkgdown](https://github.com/greta-dev/greta.pkgdown/actions/workflows/pkgdown.yaml/badge.svg)](https://github.com/greta-dev/greta.pkgdown/actions/workflows/pkgdown.yaml) -## Overview - -`greta.pkgdown` provides a custom [pkgdown](https://pkgdown.r-lib.org) -template for greta extension packages. Please don’t use it for your own package. +`greta.pkgdown` is the shared Bootstrap 5 [pkgdown](https://pkgdown.r-lib.org) +template for the [greta](https://greta-dev.github.io/greta/) family of packages. +It gives every greta package a consistent look and feel: the greta purple theme, +Roboto typography, tinted code blocks, and the greta wordmark in the navbar. -## Templates +This is an internal template for the greta family of packages. Please don't +depend on it for your own package. -For all sites, ensure that `DESCRIPTION` contains: - - Config/Needs/website: greta-dev/greta.pkgdown +## How to use -### greta packages +In a greta package, add the template to `_pkgdown.yml`: ``` yaml template: package: greta.pkgdown bootstrap: 5 ``` + +and add greta.pkgdown to the website dependencies in `DESCRIPTION` so it is +installed when the site is built: + + Config/Needs/website: greta-dev/greta.pkgdown + +The shared theme, navbar wordmark, and SCSS are then applied automatically. Each +package keeps full control of its own navbar `left:` structure, reference index, +articles, and home page. + +## What's shared + +- **Theme** β€” bslib variables for the greta purple (`#A379CC`), a tinted code + background, and Roboto / Roboto Mono fonts. +- **Navbar wordmark** β€” a `templates/navbar.html` override that swaps the + package-name text for the greta wordmark image. A package can override the + image by shipping its own `name_icon_on_white.png`. +- **SCSS** β€” navbar and code styling plus opt-in scaffolding for a full-width + greta-style home page. + +Favicons, the reference index, articles, and home-page content stay +per-package. + +## Structure + +The template follows the standard pkgdown template-package layout (as used by +`tidyverse/tidytemplate`): + + inst/pkgdown/BS5/ + β”œβ”€β”€ _pkgdown.yml # shared template: theme + navbar defaults + β”œβ”€β”€ extra.scss # shared SCSS + β”œβ”€β”€ assets/ + β”‚ └── name_icon_on_white.png # default navbar wordmark + └── templates/ + └── navbar.html # wordmark-in-navbar override diff --git a/_pkgdown.yml b/_pkgdown.yml index 8c72a0f..cf56451 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -1,73 +1,15 @@ -url: https://greta-dev.github.io/greta.pkgdown +# greta.pkgdown's own site is built with its own template, so this repo also +# serves as a live demo of the shared theme. +url: https://greta-dev.github.io/greta.pkgdown/ + template: - includes: - before_title: '' - before_body: '

simple and scalable statistical modelling in R

' + package: greta.pkgdown bootstrap: 5 - bslib: - bg: "white" - fg: "#A379CC" - primary: "#A379CC" - navbar-brand-font-size: "2rem" - navbar-light-color: "white" - navbar-light-brand-color: "white" - navbar-light-brand-hover-color: "white" - text-muted: "white" - navbar-light-hover-color: "white" - gray-300: "#dee2e6" - border-radius: 0.5rem - btn-border-radius: 0.25rem home: - sidebar: FALSE - title: An R package Simple and Scalable Statistical Modelling - description: > - Write statistical models in R and fit them by MCMC and optimisation on CPUs - and GPUs, using Google TensorFlow. greta lets you write your own model - like in BUGS, JAGS and Stan, except that you write models right in R, it - scales well to massive datasets, and it's easy to extend and build on. See - the website for more information, including tutorials, examples, package - documentation, and the greta forum. + sidebar: false navbar: structure: - left: [get_started, docs, examples, analyses, more] - right: [forum, twitter, github] - components: - get_started: - text: get started - href: articles/get_started.html - examples: - text: examples - href: articles/example_models.html - analyses: - text: analyses - menu: - - text: example analysis - href: articles/analyses/example.html - docs: - text: docs - href: reference/index.html - more: - text: more - menu: - - text: why 'greta'? - href: articles/webpages/why_greta.html - twitter: - icon: fa-twitter - href: https://twitter.com/greta_stats - aria-label: Twitter - forum: - icon: fa-comments - href: https://forum.greta-stats.org/ - aria-label: Forum - github: - icon: fa-github - href: https://github.com/greta-dev/greta - aria-label: GitHub - reference: - text: Reference - href: reference/index.html - news: - text: Changelog - href: news/index.html + left: [reference, news] + right: [search, github] diff --git a/index.md b/index.md index 57875af..e12eb58 100644 --- a/index.md +++ b/index.md @@ -1,11 +1,44 @@ - +# greta.pkgdown + +`greta.pkgdown` is the shared [pkgdown](https://pkgdown.r-lib.org) template for +the [greta](https://greta-dev.github.io/greta/) family of packages. It builds on +Bootstrap 5 and gives every greta package a consistent look and feel: the greta +purple theme, Roboto typography, tinted code blocks, and the greta wordmark in +the navbar. + +This is an internal template for the greta family of packages. You are welcome +to read it for inspiration, but please don't depend on it for your own package. + +## How to use + +In a greta package, add the template to `_pkgdown.yml`: + +``` yaml +template: + package: greta.pkgdown + bootstrap: 5 +``` + +and add greta.pkgdown to the website dependencies in `DESCRIPTION` so it is +installed when the site is built: + + Config/Needs/website: greta-dev/greta.pkgdown + +That's it. The shared theme, navbar wordmark, and SCSS are applied +automatically. A package keeps full control of its own navbar `left:` +structure, reference index, articles, and home page. + +## What's shared + +- **Theme** β€” bslib variables for the greta purple (`#A379CC`), tinted code + background, and Roboto / Roboto Mono fonts. +- **Navbar wordmark** β€” a `templates/navbar.html` override that swaps the + package-name text for the greta wordmark image. A package can override the + image by shipping its own `name_icon_on_white.png`. +- **SCSS** β€” navbar and code styling plus opt-in scaffolding for a full-width + greta-style home page. + +## What stays per-package + +Favicons, the reference index, articles, and home-page content are specific to +each package and are not provided by this template. diff --git a/inst/pkgdown/BS5/_pkgdown.yml b/inst/pkgdown/BS5/_pkgdown.yml new file mode 100644 index 0000000..a4148f5 --- /dev/null +++ b/inst/pkgdown/BS5/_pkgdown.yml @@ -0,0 +1,35 @@ +# Shared pkgdown configuration for greta packages. +# +# This file is merged into a consuming package's own `_pkgdown.yml` when it +# sets `template: {package: greta.pkgdown}`. Only put things here that are +# genuinely shared across greta packages. Package-specific navbar entries, +# reference indexes, and home-page content belong in each consumer's own +# `_pkgdown.yml`. + +template: + # Default social-media card. A consumer can override this by setting its own + # `template: opengraph: image:` pointing at one of its own figures. + opengraph: + image: + src: man/figures/name_icon_on_purple.png + alt: "greta" + # The shared greta look: purple primary, tinted code background, Roboto. + bslib: + primary: "#A379CC" + code-bg: "#f4f0f9" + base_font: {google: "Roboto"} + heading_font: {google: "Roboto"} + code_font: {google: "Roboto Mono"} + +# Shared right-hand navbar entries. `search` and `github` are pkgdown +# built-ins (github is auto-derived from the package URL/BugReports); `forum` +# points at the shared greta community forum. Consumers keep their own +# `left:` structure and are free to override `right:` if needed. +navbar: + structure: + right: [search, forum, github] + components: + forum: + icon: fa-comments + href: https://forum.greta-stats.org + aria-label: greta forum diff --git a/inst/pkgdown/BS5/assets/name_icon_on_white.png b/inst/pkgdown/BS5/assets/name_icon_on_white.png new file mode 100644 index 0000000..aebaa19 Binary files /dev/null and b/inst/pkgdown/BS5/assets/name_icon_on_white.png differ diff --git a/inst/pkgdown/BS5/extra.scss b/inst/pkgdown/BS5/extra.scss new file mode 100644 index 0000000..a00f629 --- /dev/null +++ b/inst/pkgdown/BS5/extra.scss @@ -0,0 +1,142 @@ +// Shared SCSS for greta packages, layered on top of the Bootstrap 5 pkgdown +// template. This is compiled together with the bslib variables from +// `_pkgdown.yml` when a consumer sets `template: {package: greta.pkgdown}`. +// +// The file has two kinds of rules: +// +// 1. SHARED CHROME (always active): navbar wordmark sizing, navbar link +// colours, and code tinting. These apply to every greta site. +// +// 2. HOME-PAGE SCAFFOLDING (opt-in): styling for a full-width greta-style +// home page built from a handful of ids (#head, #main-icon, #bullets, +// #panel1, #example). These rules only take effect if a consumer's +// `index.md` actually contains those ids, so they are harmless defaults +// for packages that don't. See greta's own home page for an example of +// the expected markup. + +// =========================================================================== +// SHARED CHROME +// =========================================================================== + +// --- navbar brand logo (see templates/navbar.html override) ---------------- +.navbar-logo { + height: 30px; + width: auto; + margin-right: 0.4rem; + vertical-align: middle; +} + +// --- navbar menu items ------------------------------------------------------ +// Keep the navbar links a neutral grey like a standard menu bar, rather than +// falling back to the purple link colour. +.navbar-nav .nav-link { + color: rgba(0, 0, 0, 0.65); +} +.navbar-nav .nav-link:hover, +.navbar-nav .nav-link:focus { + color: rgba(0, 0, 0, 0.85); +} +.navbar-nav .nav-link.active, +.navbar-nav .nav-link.show, +.navbar-nav .show > .nav-link { + color: rgba(0, 0, 0, 0.9); +} + +// =========================================================================== +// HOME-PAGE SCAFFOLDING (opt-in; requires matching ids in index.md) +// =========================================================================== + +// Full-width home page. `home: sidebar: false` stops pkgdown generating the +// sidebar content, but the template still emits an empty