Add guide link to H5P activity, enhance skill.js for content types, and improve PDF viewer layout

- Added a guide link for building H5P activities with AI in site.js.
- Updated skill.js to enhance content type handling and improve error messages.
- Refactored pdfjs-viewer.njk to streamline the layout and footer integration.
- Created a new topbar.njk for consistent navigation across pages.
- Introduced a new guide page for creating H5P content with AI, detailing prompts and types.
- Improved site.css for better responsiveness and layout adjustments.
- Enhanced accessibility features in site.js for screen reader announcements.

Author: alekswebnet

src/_data/site.js

@@ -48,6 +48,7 @@ export default {
       name: "Build an H5P activity with AI",
       description: "Describe a lesson to an AI chat and get an H5P activity, from a quiz to a branching scenario: play it, and download a .h5p file for Moodle or any other H5P site. Free, and nothing is uploaded.",
       page: "/h5p/build/",
+      guide: "/h5p/create-with-ai/",
       repo: "https://github.com/missing-elements/missing-elements.github.io/tree/main/src/h5p/build",
     },
   ],

src/_data/skill.js

@@ -15,22 +15,33 @@ const references = readdirSync(`${author}/references`, { recursive: true, withFi
   .sort();
 const types = references.filter((path) => path.startsWith("references/types/"));
 
-// The content types SKILL.md's table offers the user to choose from (its step 1), which the build
-// page counts and links to.
-const offered = [...readFileSync(`${author}/SKILL.md`, "utf8").matchAll(/^\| (H5P\.\w+) \|/gm)].map(([, type]) => type);
-if (!offered.length) throw new Error(`@missing-elements/h5p-author ${version}: SKILL.md has no table of content types`);
+// The rows of SKILL.md's table of the content types it offers the user to choose from (its step 1):
+// a type, and what it is for, with the media it plays in brackets where it needs the user's.
+const rows = [...readFileSync(`${author}/SKILL.md`, "utf8").matchAll(/^\| (H5P\.\w+) \| (.+?) \|$/gm)];
+if (!rows.length) throw new Error(`@missing-elements/h5p-author ${version}: SKILL.md has no table of content types`);
+const sentence = (text) => text[0].toUpperCase() + text.slice(1);
 
 // What a build where npm cannot be reached fetches (SKILL.md's step 3), which vite.config.ts
 // writes to /h5p/bundles/ after this page: the command line, and a bundle per content type, named
 // by the author package's own list of them, the one its `writeBundles` writes from.
 const pack = await openPack();
-let bundles;
+let bundles, titles;
 try {
-  bundles = (await contentTypes(pack)).map((part) => `${part.library.machineName}.zip`);
+  const parts = await contentTypes(pack);
+  bundles = parts.map((part) => `${part.library.machineName}.zip`);
+  // The name H5P's editor gives each type, such as "Fill in the Blanks" for H5P.Blanks.
+  titles = new Map(parts.map(({ library }) => [library.machineName, library.title]));
 } finally {
   await pack.close();
 }
 
+// The types the skill offers, which the build page counts and the guide lists: each by its name in
+// the pack, what it is for, and the media the user gives it, where it needs any ("pictures").
+const offered = rows.map(([, type, text]) => {
+  const [, use, media] = text.match(/^(.+?)(?: \((?:needs )?(.+)\))?$/);
+  return { type, title: titles.get(type) ?? type, use: sentence(use), media };
+});
+
 export default {
   version,
   // What SKILL.md names and the type files, apart, as the page lists them; `files` is every one.

src/_includes/pdfjs-viewer.njk

@@ -10,19 +10,16 @@ bodyClass: docs-page
   {%- endfor %}
 </ol>
 {%- endmacro -%}
+{% include "topbar.njk" %}
+
 <div class="docs">
   <div class="toc">
-    <nav aria-label="Site"><a class="brand toc-home" href="/"><img src="/assets/logo.svg" alt="" width="24" height="24">{{ site.name }}</a></nav>
     <nav aria-label="On this page">{{ tocList(toc) }}</nav>
   </div>
 
   <main class="content" id="main">
     <header class="docs-header">
-      <a class="brand docs-brand" href="/"><img src="/assets/logo.svg" alt="" width="24" height="24">{{ site.name }}</a>
-      <div class="docs-header-row">
-        <h1>pdfjs-viewer</h1>
-        {% include "theme-switch.njk" %}
-      </div>
+      <h1>pdfjs-viewer</h1>
       <p class="lead">A self-hostable PDF viewer web component, based on the <a href="https://mozilla.github.io/pdf.js/web/viewer.html">PDF.js default viewer</a>.</p>
       <ul class="meta">
         <li><a href="{{ pdfjsViewer.npm }}">npm</a></li>
@@ -36,10 +33,6 @@ bodyClass: docs-page
     </header>
 
     {{ content | safe }}
-
-    <footer class="docs-footer">
-      <p>Found a mistake? <a href="https://github.com/missing-elements/missing-elements.github.io/blob/main/{{ page.inputPath | replace('./', '') }}">Edit this page</a> or <a href="{{ pdfjsViewer.repo }}/issues">open an issue</a>.</p>
-    </footer>
   </main>
 
   <div class="preview" id="preview" role="complementary" aria-label="Live preview" data-preview>
@@ -56,4 +49,10 @@ bodyClass: docs-page
   </div>
   <button type="button" class="button preview-open" data-preview-open aria-controls="preview" aria-expanded="false" hidden>Preview</button>
 </div>
+
+<footer class="site-foot">
+  <div class="wrap">
+    <p>Found a mistake? <a href="https://github.com/missing-elements/missing-elements.github.io/blob/main/{{ page.inputPath | replace('./', '') }}">Edit this page</a> or <a href="{{ pdfjsViewer.repo }}/issues">open an issue</a>.</p>
+  </div>
+</footer>
 <script type="module" src="/pdfjs-viewer/docs.js"></script>

src/_includes/theme-switch.njk

@@ -1,4 +1,4 @@
-{#- The theme switch, which site.js wires up. Indented for where pdfjs-viewer.njk includes it, so that page is as it was. -#}
+{#- The theme switch, which site.js wires up, at the end of every page's top bar (topbar.njk). -#}
 <label class="theme-switch" data-theme-toggle hidden>
           <input type="checkbox" role="switch" aria-label="Dark theme">
           <span class="theme-switch-knob" aria-hidden="true"></span>

src/_includes/topbar.njk

@@ -0,0 +1,19 @@
+{#- The bar at the top of every page, as the build page's first was: the site's name, which goes
+    home, then links to the page's own sections where it lists them (`topbarLinks` in its front
+    matter, each `{ href, text }`, shown only to the visitor `topbarLinksClass` names where it names
+    one), and the theme switch. -#}
+<header class="topbar">
+  <div class="wrap topbar-row">
+    <a class="brand" href="/"{% if page.url == "/" %} aria-current="page"{% endif %}><img src="/assets/logo.svg" alt="" width="24" height="24">{{ site.name }}</a>
+    <div class="topbar-end">
+      {%- if topbarLinks %}
+      <nav class="topbar-links{% if topbarLinksClass %} {{ topbarLinksClass }}{% endif %}" aria-label="On this page">
+        {%- for link in topbarLinks %}
+        <a href="{{ link.href }}">{{ link.text }}</a>
+        {%- endfor %}
+      </nav>
+      {%- endif %}
+      {% include "theme-switch.njk" %}
+    </div>
+  </div>
+</header>

src/assets/site.css

@@ -343,8 +343,6 @@ tbody th a:hover code { text-decoration: underline; }
 .brand { display: inline-flex; align-items: center; gap: 0.5rem; color: var(--text); font-weight: 600; text-decoration: none; }
 .brand img { width: 1.5rem; height: 1.5rem; }
 .brand:hover { text-decoration: underline; }
-.toc-home { margin-bottom: 1.25rem; }
-.docs-brand { margin-bottom: 1.25rem; font-size: 0.9375rem; }
 .toc ol, .toc-inline ol { margin: 0; padding: 0; list-style: none; }
 .toc li + li, .toc-inline li + li { margin-top: 0; }
 .toc ol a, .toc-inline a {
@@ -368,7 +366,6 @@ tbody th a:hover code { text-decoration: underline; }
 
 .docs-header { margin-bottom: 2rem; }
 .docs-header h1 { margin: 0; font-size: 2.25rem; letter-spacing: -0.01em; }
-.docs-header-row { display: flex; align-items: center; gap: 1rem; justify-content: space-between; }
 .lead { margin: 0.5rem 0 0.75rem; font-size: 1.125rem; color: var(--muted); }
 .meta { display: flex; flex-wrap: wrap; gap: 0.25rem 1rem; margin: 0 0 1rem; padding: 0; list-style: none; font-size: 0.875rem; color: var(--muted); }
 .meta li + li { margin-top: 0; }
@@ -377,7 +374,6 @@ tbody th a:hover code { text-decoration: underline; }
 .toc-inline summary { padding: 0.5rem 0.75rem; cursor: pointer; font-weight: 600; }
 .toc-inline ol { padding: 0 0.5rem 0.5rem; }
 
-.docs-footer { margin-top: 4rem; padding-top: 1rem; border-top: 1px solid var(--border); font-size: 0.875rem; color: var(--muted); }
 
 /* Theme switch: the knob sits on the sun when light and on the moon when dark. */
 .theme-switch {
@@ -485,7 +481,20 @@ tbody th a:hover code { text-decoration: underline; }
 @media (min-width: 1280px) {
   .docs { grid-template-columns: 15rem minmax(0, 1fr) var(--preview-width); }
   .toc { display: block; }
-  .toc-inline, .docs-brand { display: none; }
+  .toc-inline { display: none; }
+}
+
+/* The docs' three columns take the window's width, so its top bar and footer do too, their
+   contents at the gutter, and at the contents' edge where they are beside it. Where the panes stay
+   in view beside the text, the bar stays above them, and they fill the window under it. */
+.docs-page .wrap { inline-size: auto; margin-inline: var(--gutter); }
+@media (min-width: 1000px) {
+  :root:has(.docs-page) { scroll-padding-top: var(--topbar-size); }
+  .docs-page .topbar { position: sticky; top: 0; z-index: 30; background: var(--bg); }
+  .docs-page :is(.toc, .preview) { top: var(--topbar-size); height: calc(100dvh - var(--topbar-size)); }
+}
+@media (min-width: 1280px) {
+  .docs-page .wrap { margin-inline: 1.5rem; }
 }
 
 /* Below 1000px the preview becomes a full-screen panel opened from a floating button. */
@@ -537,8 +546,11 @@ tbody th a:hover code { text-decoration: underline; }
   .flash { animation: none; }
 }
 
+/* The pages of one column, the org home, the skill page and the guide: in the build page's
+   container, under its top bar. */
+:is(.home, .skill, .guide) { padding-block: clamp(2.5rem, 1.5rem + 4vw, 4.5rem) clamp(3.5rem, 2rem + 5vw, 6rem); }
+
 /* Org home */
-.home { max-width: var(--page-width); margin: 0 auto; padding: 4rem clamp(1rem, 4vw, 3rem); }
 .home h1 { margin: 0 0 0.5rem; font-size: 2rem; }
 .brand-title { display: flex; align-items: center; gap: 0.75rem; }
 .brand-title img { width: 3rem; height: 3rem; }
@@ -563,25 +575,46 @@ tbody th a:hover code { text-decoration: underline; }
 .cards p { margin: 0 0 0.5rem; color: var(--muted); }
 .cards .links { display: flex; gap: 1rem; margin-top: auto; font-size: 0.875rem; }
 /* The home page's footer: where else the elements are, in columns of links. */
-.site-footer { margin-top: 4rem; padding-top: 1.5rem; border-top: 1px solid var(--border); font-size: 0.875rem; }
 .footer-links { display: flex; flex-wrap: wrap; gap: 1.5rem 4rem; }
-.footer-links h2 { margin: 0 0 0.5rem; padding: 0; border: 0; font-size: 0.875rem; }
+.footer-links h2 { margin: 0 0 0.5rem; padding: 0; border: 0; color: var(--text); font-size: 0.875rem; }
 .footer-links ul { margin: 0; padding: 0; list-style: none; }
 .footer-links li + li { margin-top: 0.35rem; }
 .footer-links a { color: var(--muted); text-decoration: none; }
 .footer-links a:hover { color: var(--text); text-decoration: underline; }
 
 /* The skill page: one wide column, its prose at --measure, and its sections as steps. */
-.skill { max-width: var(--page-width); }
-.build-brand { margin-bottom: 1.25rem; font-size: 0.9375rem; }
+.skill > * { max-inline-size: var(--page-width); }
 /* A longer heading than the docs' package names, so it gives way on a phone. */
-.skill .docs-header h1 { font-size: clamp(1.75rem, 1.2rem + 3vw, 2.25rem); }
+:is(.skill, .guide) .docs-header h1 { font-size: clamp(1.75rem, 1.2rem + 3vw, 2.25rem); }
 /* Prose keeps a line a reader can follow; the source, the lists and what plays take the whole width. */
-:is(.build, .skill) p:not(.status, .sample-note) { max-width: var(--measure); }
+:is(.build, .skill, .guide) p:not(.status, .sample-note) { max-width: var(--measure); }
 
 /* The skill page's note for a person who opened it, no wider than its prose and the note's padding. */
 .for-person { max-width: calc(var(--measure) + 2rem); }
 
+/* The guide, /h5p/create-with-ai/: an article on the container's left edge, as the build page's
+   steps are, its steps on the skill page's timeline, its prompts in code blocks to copy, and the
+   types it lists by name and use. */
+.guide > * { max-inline-size: 48rem; }
+.guide a.button { text-decoration: none; }
+.guide h3 + .code { margin-top: 0.75rem; }
+/* A row each, the name beside its use where the list is wide enough for both, over it where not. */
+.type-list {
+  margin: 0 0 1.5rem;
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  background: var(--raised);
+  container-type: inline-size;
+}
+.type-list > div { padding: 0.6rem 0.85rem; }
+.type-list > div + div { border-top: 1px solid var(--border); }
+.type-list dt { font-weight: 600; }
+.type-list dd { margin: 0; color: var(--muted); }
+.type-media { color: var(--text); }
+@container (width >= 30rem) {
+  .type-list > div { display: grid; grid-template-columns: 11rem minmax(0, 1fr); gap: 1rem; }
+}
+
 /* The build page, /h5p/build/: a landing page for a visitor who came with no source, and the build
    at once for one a chat sent with the source in the link. What is said to one alone is not shown
    to the other; the class is on <html> before the page paints (index.njk). */
@@ -592,6 +625,8 @@ tbody th a:hover code { text-decoration: underline; }
   --wide: 85rem;
   --gutter: clamp(1rem, 4vw, 3rem);
   --band-space: clamp(3.5rem, 2rem + 6vw, 7rem);
+  /* The top bar's height, a row and its rule, for what sits under it where it stays (the docs). */
+  --topbar-size: calc(4rem + 1px);
 }
 .wrap { inline-size: min(100% - 2 * var(--gutter), var(--wide)); margin-inline: auto; }
 .band { padding-block: var(--band-space); }

src/assets/site.js

@@ -1,5 +1,9 @@
-// Screen reader announcements through a polite status region.
+// Screen reader announcements through a polite status region. VoiceOver skips a message the same as
+// the last, even with the region emptied between, so a repeat ends in a no-break space, not read.
+let lastAnnounced = ''
 export function announce(message, region = document.querySelector('[data-status="page"]')) {
+  if (message === lastAnnounced) message += ' '
+  lastAnnounced = message
   region.textContent = ''
   // Cleared first so that repeating the same message is announced again.
   setTimeout(() => (region.textContent = message), 50)
@@ -80,17 +84,27 @@ for (const pre of document.querySelectorAll('pre[class*="language-"]')) {
     const copy = document.createElement('button')
     copy.type = 'button'
     copy.className = 'button'
-    copy.textContent = 'Copy'
+    // What it says, and for a screen reader what it copies, where the block says (data-copy-name):
+    // a page of several bare Copy buttons cannot be told apart by ear.
+    const state = document.createElement('span')
+    state.textContent = 'Copy'
+    copy.append(state)
+    if (pre.dataset.copyName) {
+      const name = document.createElement('span')
+      name.className = 'visually-hidden'
+      name.textContent = ` ${pre.dataset.copyName}`
+      copy.append(name)
+    }
     copy.addEventListener('click', async () => {
       try {
         await navigator.clipboard.writeText(pre.textContent)
-        copy.textContent = 'Copied'
+        state.textContent = 'Copied'
         announce('Copied to clipboard')
       } catch {
-        copy.textContent = 'Copy failed'
+        state.textContent = 'Copy failed'
         announce('Copy failed')
       }
-      setTimeout(() => (copy.textContent = 'Copy'), 1500)
+      setTimeout(() => (state.textContent = 'Copy'), 1500)
     })
     bar.append(copy)
   }

src/h5p/build/index.njk

@@ -12,6 +12,12 @@ socialImage:
   width: 1200
   height: 630
   alt: "The build page: its headline, Build an H5P activity with AI, and a course presentation playing beside it."
+# The top bar's links to the page's own sections (topbar.njk), for a visitor who came with no source.
+topbarLinks:
+  - { href: "#make", text: "Make your own" }
+  - { href: "#build-it", text: "Build" }
+  - { href: "#cost", text: "Build cost" }
+topbarLinksClass: when-unlinked
 # The page's only policy: GitHub Pages sends no headers. base.njk writes it first in <head>, and the
 # page's inline scripts, the site's color-scheme script and the one below, are added to script-src
 # by their hashes at build (eleventy.config.js).
@@ -26,19 +32,7 @@ csp: "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' da
     when-unlinked, and site.css shows it by the class this line puts on <html> before the page
     paints; build-page.ts keeps the class in step with the address from then on. -#}
 <script>if (new URLSearchParams(location.hash.slice(1)).has("source")) document.documentElement.classList.add("linked")</script>
-<header class="topbar">
-  <div class="wrap topbar-row">
-    <a class="brand" href="/"><img src="/assets/logo.svg" alt="" width="24" height="24">{{ site.name }}</a>
-    <div class="topbar-end">
-      <nav class="topbar-links when-unlinked" aria-label="On this page">
-        <a href="#make">Make your own</a>
-        <a href="#build-it">Build</a>
-        <a href="#cost">Build cost</a>
-      </nav>
-      {% include "theme-switch.njk" %}
-    </div>
-  </div>
-</header>
+{% include "topbar.njk" %}
 
 {#- The markup build-page.ts wires up, built into /h5p/build/build-page.js by Vite (vite.config.ts). -#}
 <main class="build" id="main">
@@ -47,11 +41,11 @@ csp: "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' da
       <div class="hero-words">
         <h1 id="page-title">Build an H5P activity with AI</h1>
         {#- The types are those the skill's table offers to choose from, in the release the page runs:
-            counted from it (src/_data/skill.js), and linked at its tag. -#}
+            counted from it (src/_data/skill.js), and listed by their names in the guide. -#}
         <p class="lead when-unlinked">
           Describe a lesson to an AI chat, and get an interactive activity for your students: a
           quiz, flash cards, a branching scenario, an interactive book, or any of
-          <a href="https://github.com/missing-elements/h5p-offline-player/blob/author-v{{ skill.version }}/skills/h5p-author/SKILL.md#1-choose-the-content-type-then-the-author-and-licence-with-the-user">{{ skill.offered.length }} H5P types</a>.
+          <a href="/h5p/create-with-ai/#types">{{ skill.offered.length }} H5P types</a>.
         </p>
         <div class="hero-actions when-unlinked">
           <a class="button button-solid button-large" href="#make">Make your own</a>
@@ -96,7 +90,7 @@ csp: "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' da
         <li class="feature">
           <span class="feature-icon icon-browser" aria-hidden="true"></span>
           <h3>Built in your browser</h3>
-          <p>The page builds and plays the activity on your computer, free and with no account. Nothing you make is sent to this site.</p>
+          <p>The page builds and plays the activity on your computer. It is free and <a href="https://github.com/missing-elements/missing-elements.github.io/tree/main/src/h5p/build">open source</a>, needs no account, and sends nothing you make to this site.</p>
         </li>
         <li class="feature">
           <span class="feature-icon icon-school" aria-hidden="true"></span>
@@ -142,6 +136,10 @@ csp: "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' da
           The address in the prompt is <a href="/h5p/skill/">the h5p-author skill's page</a>: the
           instructions that tell a chat how to write an H5P activity, as text anyone can read.
         </p>
+        <p>
+          More prompts, every type, and what to do when something goes wrong:
+          <a href="/h5p/create-with-ai/">how to create H5P content with AI, step by step</a>.
+        </p>
       </div>
     </div>
   </section>