(v3.1.0.9003) Rewrite the manual index on the website for findability: sections ordered by task (cleaning data, interpreting results as SIR, analysing data), titles before function names, a filter field that also finds topics mentioning a term, and colours prepared for dark mode; also make the tidymodels extensions public in the manual and use consistent help page titles

This commit is contained in:
dr. M.S. (Matthijs) Berends committed 2026-10-17 09:36:10 +02:00
1 parent 52d9c4a9e7
commit bd208429cd
22 files changed
+524 -128

No files matched your search

+203 -12
View File
@@ -68,12 +68,56 @@
--bs-dropdown-link-active-color: white !important;
}
/* mode-dependent colours; light mode is enforced in _pkgdown.yml (light-switch: false), the dark values below are prepared for when it is enabled; they are set on :root only, since pkgdown also marks the navbar as dark */
:root {
color-scheme: light;
--amr-code-literal: var(--bs-dark);
--amr-code-muted: var(--bs-gray-600);
--amr-search-text: #0b3d33;
--amr-search-placeholder: rgba(11, 61, 51, 0.65);
--amr-accent: var(--amr-green-dark); /* green for text; --amr-green-dark is the brand colour for backgrounds such as the navbar */
--amr-accent-rgb: var(--amr-green-dark-rgb);
--amr-text-muted: #5b6770;
--amr-ref-border: #e3e8e6;
--amr-filter-border: #c4cdca;
--amr-filter-placeholder: #7b8783;
--amr-filter-icon: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='none' stroke='%237b8783' stroke-width='1.75' stroke-linecap='round'%3E%3Ccircle cx='6.75' cy='6.75' r='5'/%3E%3Cpath d='M10.5 10.5l4 4'/%3E%3C/svg%3E");
--amr-filter-clear: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='none' stroke='%237b8783' stroke-width='1.75' stroke-linecap='round'%3E%3Cpath d='M4 4l8 8M12 4l-8 8'/%3E%3C/svg%3E");
--amr-chip-bg: #f4f6f5;
--amr-chip-border: #dde3e1;
--amr-chip-match-bg: rgba(var(--amr-green-light-rgb), 0.5);
--amr-badge-bg: var(--amr-green-dark);
--amr-badge-text: white;
}
:root[data-bs-theme="dark"] {
color-scheme: dark;
--amr-accent: #4fc3a1;
--amr-accent-rgb: 79, 195, 161;
--bs-link-color: var(--amr-accent) !important;
--bs-link-color-rgb: var(--amr-accent-rgb) !important;
--amr-green-middle: #8fd1c1;
--amr-green-middle-rgb: 143, 209, 193;
--amr-code-literal: var(--bs-gray-300);
--amr-code-muted: var(--bs-gray-500);
--amr-text-muted: var(--bs-gray-400);
--amr-ref-border: rgba(255, 255, 255, 0.1);
--amr-filter-border: rgba(255, 255, 255, 0.25);
--amr-filter-placeholder: var(--bs-gray-500);
--amr-filter-icon: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='none' stroke='%23adb5bd' stroke-width='1.75' stroke-linecap='round'%3E%3Ccircle cx='6.75' cy='6.75' r='5'/%3E%3Cpath d='M10.5 10.5l4 4'/%3E%3C/svg%3E");
--amr-filter-clear: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='none' stroke='%23adb5bd' stroke-width='1.75' stroke-linecap='round'%3E%3Cpath d='M4 4l8 8M12 4l-8 8'/%3E%3C/svg%3E");
--amr-chip-bg: rgba(255, 255, 255, 0.04);
--amr-chip-border: rgba(255, 255, 255, 0.14);
--amr-chip-match-bg: rgba(var(--amr-accent-rgb), 0.25);
}
/* Python page */
body.amr-for-python * {
--amr-green-light: #FFD43B; /* Python yellow */
--amr-green-light-rgb: 255, 212, 59;
--amr-green-dark: #306998; /* Python blue */
--amr-green-dark-rgb: 48, 105, 152;
--amr-accent: var(--amr-green-dark);
--amr-accent-rgb: var(--amr-green-dark-rgb);
--amr-green-middle: #b1bc5e; /* Adjusted middle yellow */
--amr-green-middle-rgb: 177, 188, 94;
--bs-success: var(--amr-green-dark) !important;
@@ -114,13 +158,16 @@ body.amr-for-python * {
opacity: 0.75;
font-size: 0.85em;
}
input[type="search"] {
color: var(--bs-tertiary-bg) !important;
.navbar input[type="search"] {
color: var(--amr-search-text) !important;
background-color: var(--amr-green-light) !important;
max-width: 160px;
max-width: 220px;
border-color: var(--amr-green-dark) !important;
border-radius: 2px !important;
}
.navbar input[type="search"]::placeholder {
color: var(--amr-search-placeholder) !important;
}
.dropdown-item:hover,
.dropdown-item:focus {
background-color: var(--bs-tertiary-bg) !important;
@@ -149,6 +196,8 @@ blockquote {
}
p {
text-align: justify;
/* pkgdown only hyphenates on small screens; justified text needs it on all screens */
hyphens: auto;
}
/*
@@ -167,10 +216,152 @@ this shows on top of every sidebar to the right
padding-bottom: 10px;
}
/* REFERENCE INDEX ('Manual'), see pkgdown/templates/content-reference-index.html */
.template-reference-index {
--amr-navbar-height: 72px; /* set exactly by extra.js */
}
.template-reference-index .section-desc {
font-style: italic;
text-align: justify;
font-size: 16px;
hyphens: auto;
color: var(--amr-text-muted);
margin-bottom: 0.5rem;
}
.template-reference-index h2 {
margin-top: 2.5rem;
padding-bottom: 0.3rem;
border-bottom: 2px solid var(--amr-green-dark);
}
.amr-ref-filter + .section h2 {
margin-top: 1.5rem;
}
.template-reference-index h3 {
margin-top: 1.25rem;
font-size: 1.1rem;
font-weight: bold;
text-transform: uppercase;
letter-spacing: 0.05em;
color: var(--amr-accent);
}
/* while filtering, sub-headings show the title of their section, as the section heading may be far above */
.amr-ref-filtering main h3[data-amr-parent]::before {
content: attr(data-amr-parent) " \203A";
display: block;
font-size: 0.8rem;
font-weight: normal;
text-transform: none;
letter-spacing: normal;
color: var(--amr-text-muted);
}
/* filter field, sticky below the navbar */
.amr-ref-filter {
clear: right; /* start below the package logo, which pkgdown lets hang below the page header */
position: sticky;
top: var(--amr-navbar-height);
z-index: 10;
padding: 0.75rem 0;
background: var(--bs-body-bg);
}
.amr-ref-filter.amr-ref-stuck {
box-shadow: 0 1px 0 var(--amr-ref-border);
}
#amr-ref-filter-input {
width: 100%;
max-width: none;
padding-left: 2.5rem;
color: var(--bs-body-color);
background: var(--bs-body-bg) var(--amr-filter-icon) no-repeat left 0.85rem center / 1rem 1rem;
border: 1px solid var(--amr-filter-border);
border-radius: 2px;
}
#amr-ref-filter-input::-webkit-search-cancel-button {
-webkit-appearance: none;
appearance: none;
width: 1rem;
height: 1rem;
background: var(--amr-filter-clear) no-repeat center / 1rem 1rem;
cursor: pointer;
}
#amr-ref-filter-input::placeholder {
color: var(--amr-filter-placeholder);
}
#amr-ref-filter-input:focus {
border-color: var(--amr-accent);
box-shadow: 0 0 0 1px var(--amr-accent) !important;
}
.amr-ref-filter-status {
font-size: 0.85rem;
padding-top: 0.35rem;
color: var(--amr-text-muted);
}
.amr-ref-filter-status:empty {
display: none;
}
/* topics: title first, function names as chips below */
.amr-ref-list {
margin-bottom: 0;
}
.amr-ref-item {
padding: 0.6rem 0 0.35rem;
border-bottom: 1px solid var(--amr-ref-border);
}
.amr-ref-item dt {
display: flex;
flex-wrap: wrap;
align-items: baseline;
column-gap: 0.5rem;
font-weight: bold !important;
margin-bottom: 0.3rem;
}
.amr-ref-item dt a {
color: var(--bs-body-color);
}
.amr-ref-item dt a:hover {
color: var(--amr-accent);
}
.template-reference-index .amr-ref-item dd {
margin: 0;
padding: 0;
font-size: 0.85rem;
line-height: 1.6;
}
.amr-ref-item dd code {
display: inline-block;
margin: 0 0.25rem 0.3rem 0;
padding: 0 0.4rem;
background: var(--amr-chip-bg);
border: 1px solid var(--amr-chip-border);
border-radius: 2px;
}
.amr-ref-item dd code.amr-ref-match {
background: var(--amr-chip-match-bg);
border-color: var(--amr-accent);
}
.amr-ref-item:not(.amr-ref-expanded) dd code.amr-ref-extra:not(.amr-ref-match) {
display: none;
}
.amr-ref-more {
border: none;
background: none;
padding: 0;
font-size: 0.85rem;
color: var(--amr-accent);
cursor: pointer;
}
.amr-ref-more:hover {
text-decoration: underline;
}
.amr-ref-hidden {
display: none !important;
}
.amr-ref-textmatch dt::after {
content: "mentioned on this page";
padding: 0 0.45rem;
font-weight: bold;
font-size: 0.75rem;
line-height: 1.6;
color: var(--amr-badge-text);
background: var(--amr-badge-bg);
border-radius: 2px;
}
@media (max-width: 575.98px) {
@@ -192,7 +383,7 @@ this shows on top of every sidebar to the right
.template-reference-topic h3,
.template-reference-topic h3 code {
color: var(--amr-green-dark) !important;
color: var(--amr-accent) !important;
}
.template-reference-topic h3 {
font-weight: normal;
@@ -232,11 +423,11 @@ code, .code {
.ot, .dv, .fl, .cn, .at,
.op a {
/* numbers, TRUE/FALSE and operators */
color: var(--bs-dark) !important;
color: var(--amr-code-literal) !important;
}
pre .fu, .fu {
/* functions */
color: var(--amr-green-dark) !important;
color: var(--amr-accent) !important;
}
pre .fu a:hover, .fu a:hover {
/* functions */
@@ -249,18 +440,18 @@ pre .st, .st {
}
pre .co, .co {
/* comments */
color: var(--amr-green-dark) !important;
color: var(--amr-accent) !important;
font-style: italic !important;
}
div.sourceCode  pre .co,
div.sourceCode .co {
/* comments in example sections, since functions are already green too */
color: var(--bs-gray-600) !important;
color: var(--amr-code-muted) !important;
}
pre code .r-out,
pre code .r-msg {
/* output of functions */
color: var(--bs-gray-600) !important;
color: var(--amr-code-muted) !important;
font-style: normal !important;
}
code a[href],
@@ -269,7 +460,7 @@ pre a[href],
a code[href],
a pre[href] {
/* adjusted colour for all real links; having href attribute */
color: var(--amr-green-dark);
color: var(--amr-accent);
text-decoration: none;
}
a[href] {
+188
View File
@@ -64,6 +64,177 @@ $(function () {
document.title = document.title.replace("Package index", "Manual");
}
// reference index ('Manual'): collapse long function lists and filter topics, see pkgdown/templates/content-reference-index.html
if ($(".amr-ref-item").length > 0) {
const maxAliases = 8;
const $body = $(".template-reference-index");
const $input = $("#amr-ref-filter-input");
const $status = $("#amr-ref-filter-status");
const $items = $(".amr-ref-item");
const pageText = {}; // full text per reference page, from search.json
let pageTextLoaded = false;
// keep the sticky filter field directly below the navbar, which hides when scrolling down
const navbar = document.querySelector(".navbar.fixed-top");
const filterBar = document.querySelector(".amr-ref-filter");
function placeFilter() {
const navBottom = navbar ? Math.max(0, navbar.getBoundingClientRect().bottom) : 0;
$body.css("--amr-navbar-height", navBottom + "px");
$(filterBar).toggleClass("amr-ref-stuck", filterBar.getBoundingClientRect().top <= navBottom + 1 && window.scrollY > 0);
}
let placing = false;
$(window).on("scroll resize", function () {
if (placing) return;
placing = true;
// follow the navbar during its slide transition
const start = performance.now();
(function step(now) {
placeFilter();
if (now - start < 400) requestAnimationFrame(step); else placing = false;
})(start);
});
placeFilter();
// headings that are jumped to (e.g. from 'On this page') must end up below the filter field, and below the navbar
// when jumping up, since the navbar only shows when scrolling up
$(document).on("click", 'a[href^="#"]', function () {
const target = document.getElementById(decodeURIComponent($(this).attr("href").slice(1)));
if (!target) return;
const up = target.getBoundingClientRect().top < 0;
document.documentElement.style.scrollPaddingTop = ((up && navbar ? navbar.offsetHeight : 0) + filterBar.offsetHeight + 8) + "px";
});
// the same when opening a link to a section, as the browser jumps before this script runs
if (window.location.hash) {
const target = document.getElementById(decodeURIComponent(window.location.hash.slice(1)));
if (target) {
document.documentElement.style.scrollPaddingTop = (filterBar.offsetHeight + 8) + "px";
target.scrollIntoView();
}
}
function updateMoreButton($item) {
const nHidden = $item.find("code.amr-ref-extra:not(.amr-ref-match)").length;
$item.find(".amr-ref-more").text("+ " + nHidden + " more").toggle(nHidden > 0);
}
$items.each(function () {
const $item = $(this);
const $codes = $item.find("dd code");
// pkgdown puts backticks around non-syntactic names, e.g. `%like%`
$codes.find("a").each(function () {
const name = $(this).text();
if (/^`.+`$/.test(name)) $(this).text(name.slice(1, -1));
});
$item.data("page", $item.find("dt a").attr("href"));
$item.data("text", ($item.find("dt").text() + " " + $item.find("dd").text()).toLowerCase());
// do not offer to show only one or two more
if ($codes.length > maxAliases + 2) {
$codes.slice(maxAliases).addClass("amr-ref-extra");
$item.find("dd").append('<button type="button" class="amr-ref-more"></button>');
updateMoreButton($item);
}
});
let h2Title = "";
$(".template-reference-index main").find("h2, h3").each(function () {
if (this.tagName === "H2") h2Title = $(this).text().trim();
else $(this).attr("data-amr-parent", h2Title);
});
$(".amr-ref-more").on("click", function () {
$(this).closest(".amr-ref-item").addClass("amr-ref-expanded");
$(this).remove();
});
function loadPageText() {
if (pageTextLoaded) return;
pageTextLoaded = true;
$.getJSON($("#search-input").data("search-index") || "../search.json", function (data) {
data.forEach(function (x) {
if (x.dir !== "Reference") return;
const page = x.path.split("/").pop();
pageText[page] = (pageText[page] || "") + " " + (x.what + " " + x.text + " " + x.code).toLowerCase();
});
filter();
});
}
function filter() {
const terms = $.trim($input.val()).toLowerCase().split(/\s+/).filter(Boolean);
$body.toggleClass("amr-ref-filtering", terms.length > 0);
let nDirect = 0;
let nText = 0;
$items.each(function () {
const $item = $(this);
const $codes = $item.find("dd code");
const direct = terms.length > 0 && terms.every(t => $item.data("text").includes(t));
const text = terms.length > 0 && !direct && terms.every(t => (pageText[$item.data("page")] || "").includes(t));
$item.toggleClass("amr-ref-hidden", terms.length > 0 && !direct && !text);
$item.toggleClass("amr-ref-textmatch", text);
// highlight the function names that match, which also reveals them if collapsed
$codes.each(function () {
const name = $(this).text().toLowerCase();
$(this).toggleClass("amr-ref-match", direct && terms.some(t => name.includes(t)));
});
updateMoreButton($item);
if (direct) nDirect++;
if (text) nText++;
});
// hide headings (with their descriptions) that have no visible topic before the next heading of the same or a higher level;
// this follows the document order, since pkgdown puts a heading and its topics in separate sibling blocks
const nVisible = new Map();
let h2 = null;
let h3 = null;
$(".template-reference-index main").find("h2, h3, .amr-ref-item").each(function () {
if (this.tagName === "H2") {
h2 = this;
h3 = null;
nVisible.set(this, 0);
} else if (this.tagName === "H3") {
h3 = this;
nVisible.set(this, 0);
} else if (!$(this).hasClass("amr-ref-hidden")) {
if (h2) nVisible.set(h2, nVisible.get(h2) + 1);
if (h3) nVisible.set(h3, nVisible.get(h3) + 1);
}
});
nVisible.forEach((n, heading) => $(heading).closest(".section").toggleClass("amr-ref-hidden", n === 0));
// blocks that only hold topics
$(".template-reference-index main .section").not(":has(h2, h3)").each(function () {
$(this).toggleClass("amr-ref-hidden", $(this).find(".amr-ref-item:not(.amr-ref-hidden)").length === 0);
});
const topics = n => n + (n === 1 ? " topic" : " topics");
if (terms.length === 0) {
$status.text("");
} else if (nDirect + nText === 0) {
$status.text(pageTextLoaded ? "No topics found" : "Searching...");
} else if (nText === 0) {
$status.text(topics(nDirect) + " found by name or title");
} else if (nDirect === 0) {
$status.text("No topics found by name or title, but " + topics(nText) + " mention it");
} else {
$status.text(topics(nDirect) + " found by name or title, and " + nText + " more mention it");
}
placeFilter();
}
$input.on("input", function () {
loadPageText();
filter();
});
$input.on("keydown", function (e) {
if (e.key === "Escape") {
$input.val("");
filter();
}
});
// press '/' anywhere to focus the filter field
$(document).on("keydown", function (e) {
if (e.key === "/" && !$(e.target).is("input, textarea")) {
e.preventDefault();
$input.trigger("focus");
}
});
}
// remove leading newline in code examples on changelog
if ($("body .template-news").length > 0) {
$("body .template-news").html($("body .template-news").html().replaceAll('sourceCode R">\n<span', 'sourceCode R"><span'));
@@ -160,6 +331,23 @@ $(function () {
// add lines between collaborator types
$('.template-citation-authors li:contains("Contributor")').first().before('<hr>');
$('.template-citation-authors li:contains("Former doctoral advisor")').first().before('<hr>');
// dark variants of figures: list a file name here and put a file with '_dark' before its extension next to it in pkgdown/assets,
// e.g. "logo_umcg.svg" requires "logo_umcg_dark.svg"; images are swapped when the theme is dark, also after switching theme
const darkVariants = [];
function applyDarkVariants() {
const dark = document.documentElement.getAttribute("data-bs-theme") === "dark";
$("img").each(function () {
const src = $(this).attr("src") || "";
const file = src.split(/[?#]/)[0].split("/").pop();
const base = file.replace(/_dark(\.\w+)$/, "$1");
if (!darkVariants.includes(base)) return;
const target = dark ? base.replace(/(\.\w+)$/, "_dark$1") : base;
if (file !== target) $(this).attr("src", src.replace(file, target));
});
}
applyDarkVariants();
new MutationObserver(applyDarkVariants).observe(document.documentElement, { attributes: true, attributeFilter: ["data-bs-theme"] });
});
$('head').append("<!-- Matomo --><script type='text/javascript'> var _paq = _paq || []; /* tracker methods like 'setCustomDimension' should be called before 'trackPageView' */ _paq.push(['setDomains', ['*.amr-for-r.org']]); _paq.push(['enableCrossDomainLinking']); _paq.push(['trackPageView']); _paq.push(['enableLinkTracking']); (function() { var u='https://analyse.uscloud.nl/'; _paq.push(['setTrackerUrl', u+'piwik.php']); _paq.push(['setSiteId', '3']); var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0]; g.type='text/javascript'; g.async=true; g.defer=true; g.src=u+'piwik.js'; s.parentNode.insertBefore(g,s); })();</script><!-- End Matomo Code -->");
@@ -0,0 +1,33 @@
<!-- AMR: adapted from pkgdown's BS5 template, with titles first, function names second, and a filter field (see pkgdown/extra.js) -->
<div class="row">
<main id="main" class="col-md-9">
<div class="page-header">
{{#logo}}<img src="{{logo.src}}" class="logo" alt="" >{{/logo}}
<h1>{{{pagetitle}}}</h1>
</div>
<div class="amr-ref-filter">
<input type="search" id="amr-ref-filter-input" class="form-control" placeholder="Filter, e.g. mo_gramstain or WISCA" aria-label="Filter the manual" autocomplete="off" spellcheck="false">
<div id="amr-ref-filter-status" class="amr-ref-filter-status" aria-live="polite"></div>
</div>
{{#rows}}<div {{#slug}}id="{{.}}"{{/slug}} class="section level2">
{{#title}}<h2>{{{.}}}</h2>{{/title}}
{{#subtitle}}<h3>{{{.}}}</h3>{{/subtitle}}
{{#desc}}<div class="section-desc">{{{desc}}}</div>{{/desc}}
<dl class="amr-ref-list">{{#topics}}
<div class="amr-ref-item">
<dt><a href="{{path}}">{{{title}}}</a>{{#lifecycle}} <span class="badge lifecycle lifecycle-{{.}}">{{.}}</span>{{/lifecycle}}</dt>
<dd>{{#aliases}}<code><a href="{{path}}">{{{.}}}</a></code> {{/aliases}}</dd>
</div>
{{/topics}}</dl>
</div>{{/rows}}
</main>
<aside class="col-md-3">
<nav id="toc" aria-label="{{#translate}}{{toc}}{{/translate}}">
<h2>{{#translate}}{{on_this_page}}{{/translate}}</h2>
</nav>
</aside>
</div>