@docpensieve/core 0.1.3 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docpensieve/core",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "DocPensieve engine: loading, MDX compilation, structured data, site generation",
   "type": "module",
   "license": "MIT",
@@ -20,7 +20,7 @@
     "types"
   ],
   "dependencies": {
-    "@docpensieve/shared": "0.1.3",
+    "@docpensieve/shared": "0.1.5",
     "@mdx-js/mdx": "^3.1.1",
     "@shikijs/rehype": "^4.4.3",
     "gray-matter": "^4.0.3",

package/src/config.js

@@ -40,6 +40,9 @@ import {
  * @property {boolean} globalComponents
  * @property {boolean} scrollToTop Back-to-top button on every 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`.
+ * @property {string} [socialImage] Preview of a shared page. Needs `siteUrl`.
  * @property {string} [rootDir]   Project root, set by `loadConfig`.
  * @property {string} [configFile] Path of the configuration file, set by `loadConfig`.
  * @property {string} [lang]      Document language, `'en'` by default.
@@ -65,8 +68,31 @@ export const DEFAULT_CONFIG = Object.freeze({
   globalComponents: true,
   scrollToTop: true,
   jsonld: { enabled: true },
+  logo: '',
+  favicon: '',
+  socialImage: '',
 });
 
+/**
+ * Extensions accepted for each project image, and what to do otherwise.
+ *
+ * @type {Record<'logo' | 'favicon' | 'socialImage', { extensions: string[], hint: string }>}
+ */
+const IMAGE_KINDS = {
+  logo: {
+    extensions: ['.svg', '.png', '.jpg', '.jpeg', '.webp', '.gif', '.avif'],
+    hint: 'Give an image the browser displays: SVG, PNG, JPEG, WebP, GIF or AVIF.',
+  },
+  favicon: {
+    extensions: ['.ico', '.png', '.svg'],
+    hint: 'Browser tabs show .ico, .png and .svg icons.',
+  },
+  socialImage: {
+    extensions: ['.png', '.jpg', '.jpeg', '.webp', '.gif'],
+    hint: 'Social networks read neither SVG nor AVIF: export a PNG or a JPEG, 1200 × 630 pixels.',
+  },
+};
+
 /**
  * Identity over the config, used only for autocompletion and type checking
  * in the editor.
@@ -208,6 +234,29 @@ export function normalizeConfig(userConfig) {
     '/',
   );
 
+  // The project's images: paths from the root, checked here for their kind.
+  // Whether they exist is checked when the build copies them.
+  for (const field of /** @type {const} */ (['logo', 'favicon', 'socialImage'])) {
+    const value = config[field];
+    if (value === undefined || value === '') continue;
+    const { extensions, hint } = IMAGE_KINDS[field];
+    if (typeof value !== 'string') {
+      throw new ConfigError(`${field} must be the path of an image, from the project root.`, {
+        hint,
+      });
+    }
+    if (!extensions.includes(path.extname(value).toLowerCase())) {
+      throw new ConfigError(`${field} must be a ${extensions.join(', ')} file: "${value}".`, {
+        hint,
+      });
+    }
+  }
+  if (config.socialImage && !config.siteUrl) {
+    throw new ConfigError('socialImage needs siteUrl.', {
+      hint: 'Social networks only read an absolute address: set siteUrl, the public address of the site.',
+    });
+  }
+
   if (!THEME_FRAMEWORKS.includes(config.theme.framework)) {
     throw new ConfigError(`Unknown theme framework: "${config.theme.framework}".`, {
       hint: `Accepted values: ${THEME_FRAMEWORKS.join(', ')}.`,

package/src/generator.js

@@ -31,6 +31,22 @@ const TEMPLATE_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..
 /** Path of the stylesheet written into every version. */
 const STYLESHEET = 'assets/docpensieve.css';
 
+/**
+ * Where each project image is written in a version, before its extension.
+ * @type {Record<'logo' | 'favicon' | 'socialImage', string>}
+ */
+const IMAGE_FILES = {
+  logo: 'assets/logo',
+  favicon: 'assets/favicon',
+  socialImage: 'assets/social-image',
+};
+
+/**
+ * Type announced to the browser, by favicon extension.
+ * @type {Record<string, string>}
+ */
+const FAVICON_TYPES = { '.ico': 'image/x-icon', '.png': 'image/png', '.svg': 'image/svg+xml' };
+
 /** Collects the values of the `class` attributes of an HTML document. */
 const CLASS_ATTRIBUTE = /class="([^"]*)"/g;
 
@@ -191,6 +207,10 @@ export class SiteGenerator {
       [path.join(target, ...STYLESHEET.split('/')), 'the theme stylesheet'],
     ]);
 
+    // The project's images go into every version: each one stands on its
+    // own, down to the orphan branch it is published on.
+    const images = await this.#copyImages(target, versionBase, written);
+
     for (const doc of docs) {
       const url = pageUrl(doc);
 
@@ -215,6 +235,7 @@ export class SiteGenerator {
         breadcrumbTitles,
         basePath: versionBase,
         dirUrl,
+        logo: images.logo,
       }).toScriptTag();
 
       // A home page has neither menu nor table of contents: those are reading
@@ -232,6 +253,19 @@ export class SiteGenerator {
         homeUrl: versionBase,
         currentUrl: url,
         cssHref: joinUrl(versionBase, path.dirname(STYLESHEET)) + path.basename(STYLESHEET),
+        logoUrl: images.logo ?? '',
+        favicon: images.favicon
+          ? {
+              href: images.favicon,
+              type: FAVICON_TYPES[path.extname(images.favicon).toLowerCase()],
+            }
+          : null,
+        // Social networks only read an absolute address: normalisation
+        // refuses a preview image without siteUrl.
+        socialImage:
+          images.socialImage && this.config.siteUrl
+            ? new URL(images.socialImage, this.config.siteUrl).href
+            : '',
         cls: classes,
         versions: this.#versionLinks(version.slug),
         // A switcher offering a single choice is not a switcher.
@@ -270,6 +304,52 @@ export class SiteGenerator {
     return { pages: docs.length, outDir: target };
   }
 
+  /**
+   * Copies the project's images into a version's assets.
+   *
+   * @param {string} target Output folder of the version.
+   * @param {string} versionBase URL of the version.
+   * @param {Map<string, string>} written Files already written, for collisions.
+   * @returns {Promise<Partial<Record<keyof typeof IMAGE_FILES, string>>>} URL
+   *   of each declared image.
+   * @throws {GeneratorError} When a declared image does not exist.
+   */
+  async #copyImages(target, versionBase, written) {
+    const rootDir = this.config.rootDir ?? process.cwd();
+    /** @type {Partial<Record<keyof typeof IMAGE_FILES, string>>} */
+    const urls = {};
+
+    for (const field of /** @type {(keyof typeof IMAGE_FILES)[]} */ (Object.keys(IMAGE_FILES))) {
+      const declared = this.config[field];
+      if (!declared) continue;
+
+      const file = `${IMAGE_FILES[field]}${path.extname(declared).toLowerCase()}`;
+      const destination = path.join(target, ...file.split('/'));
+      written.set(destination, `the ${field} image`);
+
+      try {
+        await mkdir(path.dirname(destination), { recursive: true });
+        await copyFile(path.resolve(rootDir, declared), destination);
+      } catch (cause) {
+        const missing = /** @type {NodeJS.ErrnoException} */ (cause).code === 'ENOENT';
+        throw new GeneratorError(
+          missing
+            ? `The ${field} image does not exist: "${declared}".`
+            : `Could not copy the ${field} image "${declared}".`,
+          {
+            cause,
+            hint: missing
+              ? `The path starts from the project root, ${rootDir}.`
+              : 'Check the permissions on the file and on the output folder.',
+          },
+        );
+      }
+      urls[field] = joinUrl(versionBase, path.posix.dirname(file)) + path.posix.basename(file);
+    }
+
+    return urls;
+  }
+
   /**
    * Generates every declared version, plus `versions.json` and a root that
    * redirects to the current version.

package/src/structured-data.js

@@ -87,7 +87,7 @@ export class StructuredDataBuilder {
    * @param {Record<string, any>} frontmatter Page frontmatter.
    * @param {string} url Page URL on the site (`'/guide/install/'`).
    * @param {Record<string, any>} config Normalised project config.
-   * @param {{ breadcrumbTitles?: Record<string, string>, basePath?: string, dirUrl?: string }} [options]
+   * @param {{ breadcrumbTitles?: Record<string, string>, basePath?: string, dirUrl?: string, logo?: string }} [options]
    *   `breadcrumbTitles` maps a folder slug to its real title, so that the
    *   breadcrumb shows “Café Guide” rather than “Cafe guide”. `basePath` is
    *   the site root from which crumbs are counted: the generator sets
@@ -103,6 +103,8 @@ export class StructuredDataBuilder {
     this.breadcrumbTitles = options.breadcrumbTitles ?? {};
     this.basePath = options.basePath ?? '/';
     this.dirUrl = options.dirUrl;
+    // URL of the project's logo, once the generator has copied it.
+    this.logo = options.logo;
   }
 
   /**
@@ -196,6 +198,7 @@ export class StructuredDataBuilder {
       name: this.config.projectName,
     };
     if (this.config.siteUrl) node.url = this.config.siteUrl;
+    if (this.logo) node.logo = this.#absolute(this.logo);
     return node;
   }
 

package/templates/layout.hbs

@@ -13,6 +13,22 @@
     {{#if canonical}}
     <link rel="canonical" href="{{canonical}}" />
     {{/if}}
+    {{#if favicon}}
+    <link rel="icon" href="{{favicon.href}}" type="{{favicon.type}}" />
+    {{/if}}
+    {{!-- What a social network shows of a shared page. Only with a preview
+    image: without one, the title and description alone are read anyway. --}}
+    {{#if socialImage}}
+    <meta property="og:type" content="website" />
+    <meta property="og:site_name" content="{{projectName}}" />
+    <meta property="og:title" content="{{title}}" />
+    {{#if description}}
+    <meta property="og:description" content="{{description}}" />
+    {{/if}}
+    <meta property="og:url" content="{{canonical}}" />
+    <meta property="og:image" content="{{socialImage}}" />
+    <meta name="twitter:card" content="summary_large_image" />
+    {{/if}}
     {{#each preloads}}
     <link rel="preload" as="{{as}}" href="{{href}}" />
     {{/each}}
@@ -24,7 +40,8 @@
 
     {{!-- Target of the back-to-top link: bring the focus back, not only the view. --}}
     <header class="{{{cls.header}}}" id="top" tabindex="-1">
-      <a class="{{{cls.brand}}}" href="{{homeUrl}}">{{projectName}}</a>
+      {{!-- 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>
       {{#if showVersions}}
       <details class="{{{cls.versions}}}">
         {{!-- The accessible name contains the visible label: when dictated by

package/types/config.d.ts

@@ -70,6 +70,18 @@ export type DocPensieveConfig = {
     jsonld: {
         enabled: boolean;
     };
+    /**
+     * Image beside the project name, in the header.
+     */
+    logo?: string;
+    /**
+     * Icon of the browser tab: `.ico`, `.png` or `.svg`.
+     */
+    favicon?: string;
+    /**
+     * Preview of a shared page. Needs `siteUrl`.
+     */
+    socialImage?: string;
     /**
      * Project root, set by `loadConfig`.
      */
@@ -105,6 +117,9 @@ export type DocPensieveConfig = {
  * @property {boolean} globalComponents
  * @property {boolean} scrollToTop Back-to-top button on every 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`.
+ * @property {string} [socialImage] Preview of a shared page. Needs `siteUrl`.
  * @property {string} [rootDir]   Project root, set by `loadConfig`.
  * @property {string} [configFile] Path of the configuration file, set by `loadConfig`.
  * @property {string} [lang]      Document language, `'en'` by default.

package/types/structured-data.d.ts

@@ -13,15 +13,17 @@ export declare class StructuredDataBuilder {
         breadcrumbTitles?: Record<string, string>;
         basePath?: string;
         dirUrl?: string;
+        logo?: string;
     };
     breadcrumbTitles: Record<string, string>;
     basePath: string;
     dirUrl: string | undefined;
+    logo: string | undefined;
     /**
      * @param {Record<string, any>} frontmatter Page frontmatter.
      * @param {string} url Page URL on the site (`'/guide/install/'`).
      * @param {Record<string, any>} config Normalised project config.
-     * @param {{ breadcrumbTitles?: Record<string, string>, basePath?: string, dirUrl?: string }} [options]
+     * @param {{ breadcrumbTitles?: Record<string, string>, basePath?: string, dirUrl?: string, logo?: string }} [options]
      *   `breadcrumbTitles` maps a folder slug to its real title, so that the
      *   breadcrumb shows “Café Guide” rather than “Cafe guide”. `basePath` is
      *   the site root from which crumbs are counted: the generator sets
@@ -33,6 +35,7 @@ export declare class StructuredDataBuilder {
         breadcrumbTitles?: Record<string, string>;
         basePath?: string;
         dirUrl?: string;
+        logo?: string;
     });
     /**
      * Builds the page's schema.org graph.