accessible-marp-decks 2.0.0

package/src/core/render.js

@@ -0,0 +1,87 @@
+import matter from 'gray-matter'
+import { createMarpit } from './marpit.js'
+import { resolveThemeCSS, readDocumentCSS } from './themes.js'
+import { buildDocument } from './template.js'
+import { applyTransforms } from './transforms/index.js'
+
+// js-beautify is heavyweight and only needed when prettifying, so it is
+// imported on demand (and cached) rather than at module load.
+let beautifyHTML = null
+
+async function prettifyHTML (html) {
+  if (!beautifyHTML) {
+    const { default: jsBeautify } = await import('js-beautify')
+    beautifyHTML = jsBeautify.html
+  }
+  return beautifyHTML(html, {
+    indent_size: 2,
+    wrap_line_length: 0,
+    preserve_newlines: false,
+    unformatted: ['code', 'pre']
+  }).trim() + '\n'
+}
+
+/**
+ * @typedef {object} RenderOptions
+ * @property {string} [theme] - Bundled theme name (default `"basic"`).
+ * @property {string} [css] - Raw theme CSS, used instead of a bundled theme.
+ * @property {string} [documentCss] - Override the base accessible-layout CSS.
+ * @property {string} [basePath] - Directory to resolve relative image srcs against.
+ *   Required for `inlineAssets`; when omitted, images are left as references.
+ * @property {boolean} [inlineAssets=true] - Base64-inline local images so the
+ *   output is a single self-contained file.
+ * @property {string} [lang='en'] - Document language attribute.
+ * @property {boolean} [runtimeScript=true] - Inline the runtime script that
+ *   scales each slide to the window and refines code-block focus. Set `false`
+ *   for strict-CSP hosts: slides then render at full 1280px size (the page
+ *   scrolls) and every code block stays focusable.
+ * @property {boolean} [prettify=true] - Pretty-print the HTML output.
+ */
+
+/**
+ * Render Marp markdown into a standalone, accessible HTML document.
+ *
+ * @param {string} markdown - Marp markdown, including front matter.
+ * @param {RenderOptions} [options]
+ * @returns {Promise<string>}
+ */
+export async function renderDeck (markdown, options = {}) {
+  const {
+    theme,
+    css,
+    documentCss,
+    basePath,
+    inlineAssets = true,
+    lang = 'en',
+    runtimeScript = true,
+    prettify = true
+  } = options
+
+  const { data: deckInfo } = matter(markdown)
+
+  const marpit = createMarpit()
+  const themeCSS = await resolveThemeCSS(theme ?? deckInfo.theme, css)
+  marpit.themeSet.default = marpit.themeSet.add(themeCSS)
+
+  const { html, css: marpitCSS } = marpit.render(markdown)
+
+  const baseCSS = documentCss ?? await readDocumentCSS()
+  const combinedCSS = `${marpitCSS}${baseCSS}`
+
+  const documentHTML = buildDocument({ html, css: combinedCSS, deckInfo, lang, runtimeScript })
+  const modifiedHTML = await applyTransforms(documentHTML, { basePath, inlineAssets })
+
+  if (!prettify) return modifiedHTML
+  return prettifyHTML(modifiedHTML)
+}
+
+/**
+ * Extract the deck front matter (title, description, theme, …) without
+ * rendering. Useful for tooling around a deck.
+ *
+ * @param {string} markdown
+ * @returns {Record<string, unknown>}
+ */
+export function readDeckInfo (markdown) {
+  return matter(markdown).data
+}

package/src/core/runtime-script.js

@@ -0,0 +1,99 @@
+/**
+ * The single progressive-enhancement script inlined into every rendered deck
+ * (unless `runtimeScript` is disabled). It does two things:
+ *
+ *  1. Uniform scaling — sets `--slide-scale` on each `div.marpit` to
+ *     (container width / 1280) so the CSS `zoom` magnifies each fixed-size slide
+ *     as one rigid unit. Re-run on resize. Without it, slides render at their
+ *     full 1280px design size (the no-JS fallback).
+ *
+ *  2. Code-block focus — code blocks ship with `tabindex="0"` (+ role/label) so
+ *     they are keyboard-scrollable even without JS. This removes those from any
+ *     block that doesn't actually overflow, so only scrollable code stays in the
+ *     tab order. Adapted from the author's blog-v2 (`c-code-block-scrolling`).
+ */
+export const pageScript = `<script>
+  (() => {
+    "use strict";
+
+    const DESIGN_WIDTH = 1280;
+    const OVERFLOW_TOLERANCE = 1;
+
+    // --- 1. Uniform whole-slide scaling ---------------------------------
+    // Fit-to-width alone would cancel browser zoom (Cmd/Ctrl and +): zooming
+    // shrinks the viewport in CSS pixels, so a purely width-derived scale
+    // re-fits and the text never gets bigger. Desktop page zoom shows up as a
+    // devicePixelRatio change, so we multiply the fit scale by the zoom factor
+    // since load — zooming then magnifies the deck (with scrollbars), as
+    // WCAG 1.4.4 expects. Known trade-off: dragging the window to a display
+    // with a different pixel density reads as a zoom until the next reload.
+    const baseDPR = window.devicePixelRatio || 1;
+    const decks = document.querySelectorAll("div.marpit");
+    const scale = (deck) => {
+      const zoomFactor = (window.devicePixelRatio || 1) / baseDPR;
+      const fit = deck.clientWidth / DESIGN_WIDTH;
+      deck.style.setProperty("--slide-scale", fit * zoomFactor);
+    };
+    const scaleAll = () => decks.forEach(scale);
+
+    // --- 2. Focus only genuinely scrollable code blocks -----------------
+    const isOverflowing = (el) => el.scrollWidth - el.clientWidth > OVERFLOW_TOLERANCE;
+    const updateCode = (code) => {
+      if (isOverflowing(code)) {
+        if (!code.hasAttribute("tabindex")) {
+          code.setAttribute("tabindex", "0");
+          code.setAttribute("role", "region");
+          code.setAttribute("aria-label", "Code block, scrollable");
+        }
+      } else if (code.getAttribute("tabindex") === "0") {
+        code.removeAttribute("tabindex");
+        code.removeAttribute("role");
+        code.removeAttribute("aria-label");
+      }
+    };
+    const blocks = document.querySelectorAll("pre > code");
+    const updateAllCode = () => blocks.forEach(updateCode);
+
+    const refresh = () => {
+      scaleAll();
+      updateAllCode();
+    };
+
+    const init = () => {
+      refresh();
+
+      // Fonts can finish loading after first paint and change what overflows.
+      if (document.fonts && document.fonts.ready) {
+        document.fonts.ready.then(refresh);
+      }
+
+      // React to size changes (dynamic content, the slide zoom). Code blocks
+      // are observed directly too: slides are fixed-size, so a block's
+      // overflow can change without the deck's own box ever resizing.
+      if ("ResizeObserver" in window) {
+        const observer = new window.ResizeObserver(() => refresh());
+        decks.forEach((deck) => observer.observe(deck));
+        blocks.forEach((code) => observer.observe(code));
+      }
+
+      // Re-evaluate on window resize, debounced to one call per frame.
+      let frame = null;
+      window.addEventListener("resize", () => {
+        if (frame !== null) {
+          return;
+        }
+
+        frame = window.requestAnimationFrame(() => {
+          frame = null;
+          refresh();
+        });
+      });
+    };
+
+    if (document.readyState === "loading") {
+      document.addEventListener("DOMContentLoaded", init);
+    } else {
+      init();
+    }
+  })();
+</script>`

package/src/core/template.js

@@ -0,0 +1,36 @@
+import { escapeHtml } from './escape.js'
+import { pageScript } from './runtime-script.js'
+
+/**
+ * Build the outer HTML document shell that wraps the rendered slides.
+ *
+ * @param {object} params
+ * @param {string} params.html - Marpit-rendered slide markup.
+ * @param {string} params.css - Combined CSS to inline in the document head.
+ * @param {object} [params.deckInfo] - Front-matter info (`title`, `description`).
+ * @param {string} [params.lang] - Document language. Defaults to `"en"`.
+ * @param {boolean} [params.runtimeScript] - Inline the code-block scrolling
+ *   enhancement script. Defaults to `true`; set `false` for strict-CSP hosts.
+ * @returns {string}
+ */
+export function buildDocument ({ html, css, deckInfo = {}, lang = 'en', runtimeScript = true }) {
+  const title = escapeHtml(deckInfo.title)
+  const description = escapeHtml(deckInfo.description)
+
+  return `<!DOCTYPE html>
+<html lang="${escapeHtml(lang)}">
+  <head>
+    <meta charset="UTF-8">
+    <title>${title}</title>
+    <meta name="description" content="${description}">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <style>${css}</style>
+  </head>
+  <body>
+    <main>
+      ${html}
+    </main>
+    ${runtimeScript ? pageScript : ''}
+  </body>
+</html>`
+}

package/src/core/themes.js

@@ -0,0 +1,56 @@
+import { readFile, readdir } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import { dirname, join, resolve } from 'node:path'
+
+const here = dirname(fileURLToPath(import.meta.url))
+
+/** Absolute path to the bundled `themes/` directory. */
+export const themesDir = resolve(here, '..', '..', 'themes')
+
+/**
+ * List the names of the bundled themes (without the `.css` extension).
+ * `document.css` (the injected base) and underscore-prefixed partials such as
+ * `_template.css` are not selectable themes and are excluded.
+ *
+ * @returns {Promise<string[]>}
+ */
+export async function listThemes () {
+  const entries = await readdir(themesDir)
+  return entries
+    .filter(name => name.endsWith('.css') && name !== 'document.css' && !name.startsWith('_'))
+    .map(name => name.replace(/\.css$/, ''))
+    .sort()
+}
+
+/**
+ * Resolve a theme to its CSS string. Accepts either the name of a bundled
+ * theme (e.g. `"basic"`) or, if `css` is provided, uses that instead. Marpit
+ * refuses theme CSS without an `@theme` meta comment, so one is prepended
+ * automatically when the caller's CSS doesn't declare it.
+ *
+ * @param {string} [name] - Bundled theme name.
+ * @param {string} [css] - Raw CSS to use instead of a bundled theme.
+ * @returns {Promise<string>}
+ */
+export async function resolveThemeCSS (name, css) {
+  if (typeof css === 'string') {
+    return /@theme\s+\S/.test(css) ? css : `/* @theme custom */\n${css}`
+  }
+  const themeName = name || 'basic'
+  const available = await listThemes()
+  if (!available.includes(themeName)) {
+    throw new Error(
+      `Theme "${themeName}" does not exist. Available themes: ${available.join(', ')}`
+    )
+  }
+  return readFile(join(themesDir, `${themeName}.css`), 'utf8')
+}
+
+/**
+ * Read the base accessible-layout stylesheet that is always injected.
+ *
+ * @returns {Promise<string>}
+ */
+export async function readDocumentCSS () {
+  return readFile(join(themesDir, 'document.css'), 'utf8')
+}

package/src/core/transforms/_code.js

@@ -0,0 +1,15 @@
+/**
+ * Make code blocks keyboard-scrollable as a safe, no-JS default: mark each as a
+ * labelled region and put it in the tab order. The inlined runtime script (see
+ * `src/core/runtime-script.js`) then *removes* these from any block that does
+ * not actually overflow, so only genuinely scrollable code stays focusable.
+ *
+ * @param {import('cheerio').CheerioAPI} $
+ */
+export function modifyCodeBlocks ($) {
+  $('pre code').each(function () {
+    $(this).attr('role', 'region')
+    $(this).attr('aria-label', 'Code block, scrollable')
+    $(this).attr('tabindex', '0')
+  })
+}

package/src/core/transforms/_img.js

@@ -0,0 +1,98 @@
+import { readFile } from 'node:fs/promises'
+import { join, extname } from 'node:path'
+
+const MIME_BY_EXT = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.svg': 'image/svg+xml',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.bmp': 'image/bmp',
+  '.ico': 'image/x-icon'
+}
+
+/** Matches the first url(...) token in a CSS value, quoted or bare. */
+const CSS_URL_RE = /url\(\s*(['"]?)([^'")]+)\1\s*\)/
+
+/** A src that already points somewhere self-contained or remote — leave it. */
+function isExternal (src) {
+  return /^(https?:)?\/\//.test(src) || src.startsWith('data:')
+}
+
+/**
+ * Read a local asset and return it as a `data:` URI, or `null` when it can't
+ * be inlined (unknown type, missing or unreadable file).
+ *
+ * Srcs are written as URLs, so before touching the filesystem the query string
+ * and fragment are dropped and percent-escapes decoded — `my%20image.png?v=2`
+ * resolves to `my image.png` on disk.
+ *
+ * @param {string} src - Relative source path from the markup.
+ * @param {string} basePath - Directory to resolve `src` against.
+ * @returns {Promise<string | null>}
+ */
+async function toDataURI (src, basePath) {
+  const cleaned = src.split(/[?#]/)[0]
+  let decoded
+  try {
+    decoded = decodeURIComponent(cleaned)
+  } catch {
+    // Malformed percent-escapes — fall back to the raw path.
+    decoded = cleaned
+  }
+
+  const mime = MIME_BY_EXT[extname(decoded).toLowerCase()]
+  if (!mime) return null
+
+  try {
+    const filePath = join(basePath, decoded.replace(/^\.?\//, ''))
+    const data = await readFile(filePath)
+    return `data:${mime};base64,${data.toString('base64')}`
+  } catch {
+    // Missing/unreadable asset — caller leaves the original reference intact.
+    return null
+  }
+}
+
+/**
+ * Portability pass over the deck's images: base64-inlines local assets into
+ * `data:` URIs (when `basePath` is known and `inlineAssets` is on) so the
+ * rendered deck is a single, self-contained file. Covers both `<img>` elements
+ * and slide background images (Marp's `![bg](…)` becomes a `background-image`
+ * style on the section). Remote and already-inlined sources are left untouched.
+ * Image sizing is left to the theme CSS so images scale with the slide.
+ *
+ * @param {import('cheerio').CheerioAPI} $
+ * @param {object} [options]
+ * @param {string} [options.basePath] - Directory to resolve relative srcs against.
+ * @param {boolean} [options.inlineAssets=true] - Base64-inline local images.
+ */
+export async function modifyImg ($, { basePath, inlineAssets = true } = {}) {
+  if (!inlineAssets || !basePath) return
+
+  for (const el of $('img').toArray()) {
+    const $img = $(el)
+    const src = $img.attr('src')
+    if (!src || isExternal(src)) continue
+
+    const dataURI = await toDataURI(src, basePath)
+    if (dataURI) $img.attr('src', dataURI)
+  }
+
+  // Slide backgrounds: ![bg](…) ends up as url(...) inside the section's
+  // style attribute, which <img>-only inlining would miss.
+  for (const el of $('section[style]').toArray()) {
+    const $section = $(el)
+    const style = $section.attr('style')
+    const match = CSS_URL_RE.exec(style)
+    if (!match) continue
+
+    const src = match[2]
+    if (isExternal(src)) continue
+
+    const dataURI = await toDataURI(src, basePath)
+    if (dataURI) $section.attr('style', style.replace(match[0], `url("${dataURI}")`))
+  }
+}

package/src/core/transforms/_section.js

@@ -0,0 +1,59 @@
+/**
+ * Turn each Marpit `<section>` (a slide) into an accessible landmark:
+ * strips presentational Marpit attributes, adds an `aria-label`, gives the
+ * slide heading a stable id + `aria-describedby`, and appends a footer with
+ * screen-reader pagination. The responsive 16:9 scaling is applied by
+ * `themes/document.css` directly to `div.marpit > section` (so Marpit's
+ * theme scoping is preserved — the section must stay a child of `.marpit`).
+ *
+ * @param {import('cheerio').CheerioAPI} $
+ */
+export function modifySection ($) {
+  $('section').each(function (index) {
+    const $section = $(this)
+    $section.removeAttr('data-theme')
+    $section.removeAttr('data-footer')
+    $section.removeAttr('data-paginate')
+    $section.removeAttr('data-marpit-pagination-total')
+    $section.removeAttr('data-class')
+    $section.removeAttr('style')
+
+    const backgroundImage = $section.attr('data-background-image')
+    if (backgroundImage !== undefined) {
+      $section.css('background-image', backgroundImage)
+      $section.removeAttr('data-background-image')
+    }
+
+    const hasFooter = $section.find('footer').length > 0
+    if (!hasFooter) $section.append('<footer></footer>')
+    const $footer = $section.find('footer')
+
+    // Marpit only sets data-marpit-pagination when `paginate: true`; fall back
+    // to the slide's position so labels never read "Slide undefined".
+    const pageNo = $section.attr('data-marpit-pagination') ?? String(index + 1)
+    $section.removeAttr('data-marpit-pagination')
+
+    // Only the slide's FIRST heading gets the stable id and describedby —
+    // applying them to every heading would emit duplicate ids and concatenate
+    // all heading text into the label.
+    const $heading = $section.find(':header').first()
+    if ($heading.length > 0) {
+      $heading.attr('aria-describedby', `page-number-${pageNo}`)
+      $heading.attr('id', `slide-${pageNo}`)
+      $section.attr('aria-label', `Slide ${pageNo}: ${$heading.text()}`)
+    } else {
+      // No heading to point at: label the slide plainly, with no dangling colon.
+      $section.attr('aria-label', `Slide ${pageNo}`)
+    }
+
+    $footer.append(`
+      <div class="pagination">
+        <p class="visually-hidden">End of slide ${pageNo}</p>
+        <p id="page-number-${pageNo}" aria-hidden="true">
+          <span class="visually-hidden">slide </span>
+          <span>${pageNo}</span>
+        </p>
+      </div>
+    `)
+  })
+}

package/src/core/transforms/index.js

@@ -0,0 +1,23 @@
+import * as cheerio from 'cheerio'
+import { modifySection } from './_section.js'
+import { modifyImg } from './_img.js'
+import { modifyCodeBlocks } from './_code.js'
+
+/**
+ * Apply all accessibility transforms to a full HTML document string.
+ *
+ * @param {string} documentHTML
+ * @param {object} [options]
+ * @param {string} [options.basePath] - Directory for resolving local image srcs.
+ * @param {boolean} [options.inlineAssets] - Base64-inline local images.
+ * @returns {Promise<string>}
+ */
+export async function applyTransforms (documentHTML, options = {}) {
+  const $ = cheerio.load(documentHTML)
+  modifySection($)
+  await modifyImg($, options)
+  modifyCodeBlocks($)
+  return $.html()
+}
+
+export { modifySection, modifyImg, modifyCodeBlocks }

package/src/eleventy.js

@@ -0,0 +1,53 @@
+import { readFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+import { renderDeck, readDeckInfo } from './core/render.js'
+
+/**
+ * @typedef {object} PluginOptions
+ * @property {string} [extension='deck'] - File extension that marks a deck.
+ *   Deck files contain Marp markdown. Defaults to `deck` (e.g. `talk.deck`) so
+ *   it never clobbers your site's normal `.md` files. Set to `md` to treat
+ *   *every* markdown file as a deck (this fully overrides Eleventy's built-in
+ *   markdown rendering).
+ * @property {string} [theme] - Force a theme for all decks. When omitted, each
+ *   deck's own front-matter `theme` (falling back to the default) is used.
+ * @property {string} [lang] - Document language attribute.
+ */
+
+/**
+ * Eleventy plugin: render Marp decks as accessible HTML pages.
+ *
+ * Thin wrapper around {@link renderDeck} — all rendering logic lives in the
+ * core engine; this only wires it into Eleventy's template pipeline.
+ *
+ * @param {import('@11ty/eleventy').UserConfig} eleventyConfig
+ * @param {PluginOptions} [options]
+ */
+export default function accessibleMarpPlugin (eleventyConfig, options = {}) {
+  const {
+    extension = 'deck',
+    theme,
+    lang
+  } = options
+
+  eleventyConfig.addTemplateFormats(extension)
+
+  eleventyConfig.addExtension(extension, {
+    // We read the raw file ourselves so Marp's front-matter directives survive.
+    read: false,
+    getData: async (inputPath) => {
+      const markdown = await readFile(inputPath, 'utf8')
+      return readDeckInfo(markdown)
+    },
+    compile: (_inputContent, inputPath) => async (data) => {
+      const markdown = await readFile(inputPath, 'utf8')
+      return renderDeck(markdown, {
+        theme: theme ?? data?.theme,
+        basePath: dirname(inputPath),
+        lang: lang ?? data?.lang
+      })
+    }
+  })
+}
+
+export { renderDeck, readDeckInfo }

package/src/index.js

@@ -0,0 +1,19 @@
+import { readFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+import { renderDeck, readDeckInfo } from './core/render.js'
+import { listThemes, themesDir } from './core/themes.js'
+
+/**
+ * Render a Marp markdown file into an accessible HTML document. Relative image
+ * srcs are resolved (and inlined) against the file's own directory by default.
+ *
+ * @param {string} path - Path to a `.md` deck file.
+ * @param {import('./core/render.js').RenderOptions} [options]
+ * @returns {Promise<string>}
+ */
+export async function renderDeckFile (path, options = {}) {
+  const markdown = await readFile(path, 'utf8')
+  return renderDeck(markdown, { basePath: dirname(path), ...options })
+}
+
+export { renderDeck, readDeckInfo, listThemes, themesDir }