@docpensieve/core 0.4.0-beta.2 → 0.5.0-beta.1

package/src/search-index.js

@@ -9,6 +9,8 @@
  * @module @docpensieve/core/search-index
  */
 
+import { UI_STRINGS, pageCount } from '@docpensieve/shared';
+
 /** Path of the search page within a version. */
 export const SEARCH_SLUG = 'search';
 
@@ -56,21 +58,33 @@ function escapeHtml(value) {
  * @param {{ title: string, url: string, description: string }[]} entries
  *   Pages of the version, in reading order.
  * @param {string} indexUrl URL of the version's index.
+ * @param {import('@docpensieve/shared').UiStrings} [strings] Wording of the page.
+ * @param {string} [lang] Language, which decides the plural of a count.
  * @returns {string}
  */
-export function searchPageContent(entries, indexUrl) {
+export function searchPageContent(entries, indexUrl, strings = UI_STRINGS.en, lang = 'en') {
   const items = entries.map((entry) => {
     const description = entry.description ? `<p>${escapeHtml(entry.description)}</p>` : '';
     return `<li data-url="${escapeHtml(entry.url)}"><a href="${escapeHtml(entry.url)}">${escapeHtml(entry.title)}</a>${description}</li>`;
   });
 
   return [
-    '<h1 id="search">Search</h1>',
-    `<form class="dp-search-page" role="search" data-search-page data-index="${escapeHtml(indexUrl)}">`,
-    '<label for="dp-search-query">Search the documentation</label>',
+    `<h1 id="search">${escapeHtml(strings.searchTitle)}</h1>`,
+    // The script is copied as it is, so its wording travels with the page
+    // rather than inside the file: one script, every language.
+    `<form class="dp-search-page" role="search" data-search-page data-index="${escapeHtml(indexUrl)}" data-strings="${escapeHtml(
+      JSON.stringify({
+        lang,
+        failed: strings.searchIndexFailed,
+        pages: strings.pages,
+        noResultFor: strings.noResultFor,
+        resultsFor: strings.resultsFor,
+      }),
+    )}">`,
+    `<label for="dp-search-query">${escapeHtml(strings.searchTheDocumentation)}</label>`,
     '<input id="dp-search-query" type="search" name="q" autocomplete="off" />',
     '</form>',
-    `<p class="dp-search-status" data-search-status aria-live="polite">${entries.length} pages.</p>`,
+    `<p class="dp-search-status" data-search-status aria-live="polite">${escapeHtml(pageCount(entries.length, strings, lang))}.</p>`,
     `<ol class="dp-search-results" data-search-results>${items.join('')}</ol>`,
   ].join('');
 }

package/templates/header-menu.hbs

@@ -5,7 +5,7 @@ a row on a wide screen, behind a menu button on a narrow one. --}}
 <details class="{{{cls.versions}}}">
   {{!-- The accessible name contains the visible label: when dictated by voice,
   what is read on screen must find this button. --}}
-  <summary aria-label="Version {{versionName}}, switch version">{{versionName}}</summary>
+  <summary aria-label="{{ui.versionSwitch}} {{versionName}}, {{ui.switchVersion}}">{{versionName}}</summary>
   <ul class="{{{cls.versionsList}}}">
     {{#each versions}}
     <li><a href="{{url}}"{{#if current}} aria-current="true"{{/if}}>{{name}}</a></li>
@@ -13,6 +13,24 @@ a row on a wide screen, behind a menu button on a narrow one. --}}
   </ul>
 </details>
 {{/if}}
+{{#if languages.length}}
+<details class="{{{cls.languages}}}">
+  <summary aria-label="{{ui.language}}">{{ui.language}}</summary>
+  <ul class="{{{cls.languagesList}}}">
+    {{#each languages}}
+    <li>
+      {{#if url}}
+      <a href="{{url}}"{{#if current}} aria-current="true"{{/if}}>{{label}}</a>
+      {{else}}
+      {{!-- Not translated: shown so that the reader knows the language exists,
+      inert so that they are not sent to a page that does not. --}}
+      <span aria-disabled="true">{{label}}</span>
+      {{/if}}
+    </li>
+    {{/each}}
+  </ul>
+</details>
+{{/if}}
 {{#if headerLinks.length}}
 <ul class="{{{cls.headerLinks}}}">
   {{#each headerLinks}}
@@ -43,6 +61,6 @@ a row on a wide screen, behind a menu button on a narrow one. --}}
 {{!-- A plain form: it leads to the search page, and needs no script. --}}
 {{#if searchUrl}}
 <form class="{{{cls.search}}}" role="search" action="{{searchUrl}}">
-  <input type="search" name="q" placeholder="Search" aria-label="Search the documentation" />
+  <input type="search" name="q" placeholder="{{ui.search}}" aria-label="{{ui.searchTheDocumentation}}" />
 </form>
 {{/if}}

package/templates/layout.hbs

@@ -1,5 +1,5 @@
 <!doctype html>
-<html lang="{{lang}}"{{#if darkModeClass}} class="{{darkModeClass}}"{{/if}}>
+<html lang="{{lang}}" dir="{{dir}}"{{#if darkModeClass}} class="{{darkModeClass}}"{{/if}}>
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
@@ -45,10 +45,22 @@
     {{#each scripts}}
     <script type="module" src="{{this}}"></script>
     {{/each}}
+    {{!-- The other languages of this page, for search engines: a reader
+    looking for the French page must not be sent to the English one. --}}
+    {{#each languages}}
+    {{#if url}}
+    <link rel="alternate" hreflang="{{lang}}" href="{{url}}" />
+    {{#if default}}
+    {{!-- x-default names the address to serve a reader whose language the site
+    does not have: the language it is written in. --}}
+    <link rel="alternate" hreflang="x-default" href="{{url}}" />
+    {{/if}}
+    {{/if}}
+    {{/each}}
     {{{jsonld}}}
   </head>
   <body>
-    <a class="{{{cls.skip}}}" href="#content">Skip to content</a>
+    <a class="{{{cls.skip}}}" href="#content">{{ui.skipToContent}}</a>
 
     {{!-- Target of the back-to-top link: it brings the focus back, not only the
     view. It stays out of the header on purpose — the header is sticky, so it
@@ -56,28 +68,28 @@
     into view scrolled nowhere. --}}
     <div id="top" tabindex="-1"></div>
 
-    <header class="{{{cls.header}}}">
+    <header class="{{#if stickyHeader}}{{{cls.header}}}{{else}}{{{cls.headerStatic}}}{{/if}}">
       {{!-- The logo's alt stays empty: the name that follows already says it. --}}
       <a class="{{{cls.brand}}}" href="{{homeUrl}}">{{#if logoUrl}}<img class="{{{cls.brandLogo}}}" src="{{logoUrl}}" alt="" />{{/if}}{{projectName}}</a>
       {{!-- Shown twice, one at a time: in a row on a wide screen, behind a button
       on a narrow one. The button is a details element, so that the menu opens
       without a script — as the version switcher does. --}}
       {{#if headerMenu}}
-      <nav class="{{{cls.headerNav}}}" aria-label="Site">
+      <nav class="{{{cls.headerNav}}}" aria-label="{{ui.site}}">
         {{> headerMenu}}
       </nav>
       <details class="{{{cls.menu}}}">
-        <summary aria-label="Menu">
+        <summary aria-label="{{ui.menu}}">
           <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true" focusable="false"><path d="M4 7h16M4 12h16M4 17h16" /></svg>
         </summary>
-        <nav class="{{{cls.menuPanel}}}" aria-label="Site">
+        <nav class="{{{cls.menuPanel}}}" aria-label="{{ui.site}}">
           {{> headerMenu}}
         </nav>
       </details>
       {{/if}}
       {{!-- Hidden until its script runs: without JavaScript, it would do nothing. --}}
       {{#if schemeToggle}}
-      <button class="{{{cls.schemeToggle}}}" type="button" data-scheme-toggle hidden aria-label="Switch the colour scheme">
+      <button class="{{{cls.schemeToggle}}}" type="button" data-scheme-toggle hidden aria-label="{{ui.switchScheme}}">
         <svg class="dp-scheme-moon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M21 12.8A9 9 0 1 1 11.2 3a7 7 0 0 0 9.8 9.8z" /></svg>
         <svg class="dp-scheme-sun" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><circle cx="12" cy="12" r="4" /><path d="M12 2v2M12 20v2M4.9 4.9l1.4 1.4M17.7 17.7l1.4 1.4M2 12h2M20 12h2M4.9 19.1l1.4-1.4M17.7 6.3l1.4-1.4" /></svg>
       </button>
@@ -89,12 +101,12 @@
       menu above the content on a narrow one, where a full menu would eat the
       first screen. Only one of the two is displayed at a time. --}}
       {{#if sidebar.length}}
-      <nav class="{{{cls.sidebar}}}" aria-label="Documentation navigation">
+      <nav class="{{{cls.sidebar}}}" aria-label="{{ui.documentationNavigation}}">
         {{> navItems sidebar}}
       </nav>
       <details class="{{{cls.sidebarMenu}}}">
-        <summary>Documentation menu</summary>
-        <nav aria-label="Documentation navigation">
+        <summary>{{ui.documentationMenu}}</summary>
+        <nav aria-label="{{ui.documentationNavigation}}">
           {{> navItems sidebar}}
         </nav>
       </details>
@@ -104,11 +116,11 @@
         {{#if notice}}
         <aside class="{{{cls.notice}}}" role="note">
           {{#if notice.prerelease}}
-          This version is in preparation and may change.
+          {{ui.prereleaseNotice}}
           {{else}}
-          This version is no longer maintained.
+          {{ui.archivedNotice}}
           {{/if}}
-          The current version is <a href="{{notice.url}}">{{notice.name}}</a>.
+          {{ui.currentVersionIs}} <a href="{{notice.url}}">{{notice.name}}</a>.
         </aside>
         {{/if}}
         {{!-- Who wrote the page, and when. Absent when the page says neither,
@@ -139,26 +151,26 @@
         text, they say what it was about. Labels, not links — there is no page
         per tag. None on a home page. --}}
         {{#if tags.length}}
-        <ul class="{{{cls.tags}}}" aria-label="Tags">
+        <ul class="{{{cls.tags}}}" aria-label="{{ui.tags}}">
           {{#each tags}}<li class="{{{@root.cls.tag}}}">{{this}}</li>{{/each}}
         </ul>
         {{/if}}
       </main>
 
       {{#if toc.length}}
-      <nav class="{{{cls.toc}}}" aria-label="On this page">
-        <p class="{{{cls.tocTitle}}}">On this page</p>
+      <nav class="{{{cls.toc}}}" aria-label="{{ui.onThisPage}}">
+        <p class="{{{cls.tocTitle}}}">{{ui.onThisPage}}</p>
         {{> tocItems toc}}
       </nav>
       {{/if}}
     </div>
 
     <footer class="{{{cls.footer}}}">
-      <p>{{projectName}} — version {{versionName}}</p>
+      <p>{{projectName}} — {{ui.versionLabel}} {{versionName}}</p>
     </footer>
 
     {{#if scrollToTop}}
-    <a class="{{{cls.scrollTop}}}" href="#top" aria-label="Back to top">
+    <a class="{{{cls.scrollTop}}}" href="#top" aria-label="{{ui.backToTop}}">
       <svg
         class="{{{cls.scrollTopIcon}}}"
         viewBox="0 0 24 24"

package/types/authors.d.ts

@@ -55,10 +55,11 @@ export type Byline = {
  * @param {unknown} value
  * @param {string} field Name of the field, for the error message.
  * @param {string} where Page the date comes from.
+ * @param {string} [locale] Locale the label is written in. Default: `en-GB`.
  * @returns {{ iso: string, label: string } | null} `null` when absent.
  * @throws {ConfigError} When the value is not a date.
  */
-export declare function readDate(value: unknown, field: string, where: string): {
+export declare function readDate(value: unknown, field: string, where: string, locale?: string): {
     iso: string;
     label: string;
 } | null;
@@ -91,7 +92,8 @@ export declare function resolvePageAuthors(value: unknown, table?: Map<string, A
  * @param {Record<string, any>} frontmatter
  * @param {Map<string, Author>} [table]
  * @param {string} [where] Page named in a date error.
+ * @param {string} [locale] Locale the dates are written in.
  * @returns {Byline | null}
  * @throws {ConfigError} When a date cannot be read.
  */
-export declare function buildByline(frontmatter: Record<string, any>, table?: Map<string, Author>, where?: string): Byline | null;
+export declare function buildByline(frontmatter: Record<string, any>, table?: Map<string, Author>, where?: string, locale?: string): Byline | null;

package/types/config.d.ts

@@ -37,6 +37,12 @@ export type Version = {
      * Favicon of this version, instead of the project's.
      */
     favicon?: string;
+    /**
+     * Folder of each translation,
+     * by language code. The pages of the site language stay at the root of the
+     * version; a translation is served under its code.
+     */
+    translations?: Record<string, string>;
 };
 export type DocPensieveConfig = {
     /**
@@ -97,11 +103,26 @@ export type DocPensieveConfig = {
      * the branch of the page being read.
      */
     foldedSidebar?: boolean;
+    ui?: Record<string, Record<string, string>>;
+    /**
+     * Kinds of admonition the project adds to the ones shipped. `icon` names an
+     * SVG of the version folder, inlined in place of the tone's drawing.
+     */
+    admonitions?: Record<string, {
+        label: string;
+        tone: string;
+        icon?: string;
+    }>;
     globalComponents: boolean;
     /**
      * Back-to-top button on every page.
      */
     scrollToTop: boolean;
+    /**
+     * Header held at the top of the screen.
+     * `false` lets it scroll away with the page.
+     */
+    stickyHeader?: boolean;
     jsonld: {
         enabled: boolean;
     };
@@ -153,6 +174,9 @@ export type DocPensieveConfig = {
  *   reference one. Its pages carry a notice and are not indexed.
  * @property {string} [logo]    Logo of this version, instead of the project's.
  * @property {string} [favicon] Favicon of this version, instead of the project's.
+ * @property {Record<string, string>} [translations] Folder of each translation,
+ *   by language code. The pages of the site language stay at the root of the
+ *   version; a translation is served under its code.
  */
 /**
  * @typedef {object} DocPensieveConfig
@@ -169,8 +193,14 @@ export type DocPensieveConfig = {
  *   `columns` opens a panel of links instead of leading anywhere itself.
  * @property {boolean} [foldedSidebar] Categories of the menu fold, opened on
  *   the branch of the page being read.
+ * @property {Record<string, Record<string, string>>} [ui]
+ * @property {Record<string, { label: string, tone: string, icon?: string }>} [admonitions]
+ *   Kinds of admonition the project adds to the ones shipped. `icon` names an
+ *   SVG of the version folder, inlined in place of the tone's drawing.
  * @property {boolean} globalComponents
  * @property {boolean} scrollToTop Back-to-top button on every page.
+ * @property {boolean} [stickyHeader] Header held at the top of the screen.
+ *   `false` lets it scroll away with the page.
  * @property {{ enabled: boolean }} jsonld
  * @property {string} [logo]        Image beside the project name, in the header.
  * @property {string} [favicon]     Icon of the browser tab: `.ico`, `.png` or `.svg`.

package/types/search-index.d.ts

@@ -24,10 +24,12 @@ export declare function htmlToText(html: string): string;
  * @param {{ title: string, url: string, description: string }[]} entries
  *   Pages of the version, in reading order.
  * @param {string} indexUrl URL of the version's index.
+ * @param {import('@docpensieve/shared').UiStrings} [strings] Wording of the page.
+ * @param {string} [lang] Language, which decides the plural of a count.
  * @returns {string}
  */
 export declare function searchPageContent(entries: {
     title: string;
     url: string;
     description: string;
-}[], indexUrl: string): string;
+}[], indexUrl: string, strings?: import('@docpensieve/shared').UiStrings, lang?: string): string;