create-eziwiki 0.2.0 → 0.3.0

package/template/package-lock.json

@@ -12,6 +12,7 @@
         "@shikijs/rehype": "^4.3.1",
         "ajv": "^8.12.0",
         "ajv-formats": "^3.0.1",
+        "beautiful-mermaid": "^1.1.3",
         "github-slugger": "^2.0.0",
         "gray-matter": "^4.0.3",
         "hast-util-to-string": "^3.0.1",
@@ -2655,6 +2656,28 @@
         "baseline-browser-mapping": "dist/cli.js"
       }
     },
+    "node_modules/beautiful-mermaid": {
+      "version": "1.1.3",
+      "resolved": "https://registry.npmjs.org/beautiful-mermaid/-/beautiful-mermaid-1.1.3.tgz",
+      "integrity": "sha512-TItrtrAyHp1vwFfFVYauWGrquouk/6SS21Aq3RsxindSYZODcN4xYrPZD6BiZRU+o5mKJzDPz9MUSMvELdylyg==",
+      "license": "MIT",
+      "dependencies": {
+        "elkjs": "^0.11.0",
+        "entities": "^7.0.1"
+      }
+    },
+    "node_modules/beautiful-mermaid/node_modules/entities": {
+      "version": "7.0.1",
+      "resolved": "https://registry.npmjs.org/entities/-/entities-7.0.1.tgz",
+      "integrity": "sha512-TWrgLOFUQTH994YUyl1yT4uyavY5nNB5muff+RtWaqNVCAK408b5ZnnbNAUEWLTCpum9w6arT70i1XdQ4UeOPA==",
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=0.12"
+      },
+      "funding": {
+        "url": "https://github.com/fb55/entities?sponsor=1"
+      }
+    },
     "node_modules/binary-extensions": {
       "version": "2.3.0",
       "resolved": "https://registry.npmjs.org/binary-extensions/-/binary-extensions-2.3.0.tgz",
@@ -3244,6 +3267,12 @@
       "dev": true,
       "license": "ISC"
     },
+    "node_modules/elkjs": {
+      "version": "0.11.1",
+      "resolved": "https://registry.npmjs.org/elkjs/-/elkjs-0.11.1.tgz",
+      "integrity": "sha512-zxxR9k+rx5ktMwT/FwyLdPCrq7xN6e4VGGHH8hA01vVYKjTFik7nHOxBnAYtrgYUB1RpAiLvA1/U2YraWxyKKg==",
+      "license": "EPL-2.0"
+    },
     "node_modules/emoji-regex": {
       "version": "9.2.2",
       "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-9.2.2.tgz",

package/template/package.json

@@ -24,6 +24,7 @@
     "@shikijs/rehype": "^4.3.1",
     "ajv": "^8.12.0",
     "ajv-formats": "^3.0.1",
+    "beautiful-mermaid": "^1.1.3",
     "github-slugger": "^2.0.0",
     "gray-matter": "^4.0.3",
     "hast-util-to-string": "^3.0.1",

package/template/scripts/check-links.ts

@@ -1,40 +1,82 @@
 #!/usr/bin/env tsx
 
 /**
- * Reports links that point at no page.
+ * Reports on the shape of the link graph.
  *
- * Runs as part of the build and reports rather than fails: a dangling link in
- * one page is not a reason to block a deploy of the other twenty, and content
- * is often written before the page it references exists. Pass `--strict` in CI
- * to make it an error.
+ * Two kinds of finding, treated differently. An unresolved link is an error in
+ * the content and `--strict` makes it fail the build, which is what CI passes.
+ * A page nothing links to, or nothing links on from, is not an error — a
+ * correct wiki can have either — so those are reported and never fail. They are
+ * the shapes a set of documents falls into as it stops being a wiki, and
+ * neither is visible from inside a single page.
+ *
+ * Reporting rather than failing on unresolved links by default is deliberate
+ * too: a dangling link in one page is not a reason to block a deploy of the
+ * other twenty, and content is often written before the page it references.
  */
 
 import { getLinkGraph } from '../lib/graph/build';
+import { getWikiHealth } from '../lib/graph/health';
+import type { GraphNode } from '../lib/graph/build';
 
 const strict = process.argv.includes('--strict');
 const { broken, nodes, edges } = getLinkGraph();
 
-if (broken.length === 0) {
-  console.log(`🔗 Links OK — ${edges.length} links across ${nodes.length} pages\n`);
-  process.exit(0);
+/**
+ * Prints a list of pages under a heading, or nothing when there are none.
+ *
+ * @param label - What the pages have in common, singular and plural
+ * @param explanation - Why it is worth knowing
+ * @param pages - The pages found
+ */
+function report(
+  label: { one: string; many: string },
+  explanation: string,
+  pages: GraphNode[],
+): void {
+  if (pages.length === 0) return;
+
+  const noun = pages.length === 1 ? label.one : label.many;
+
+  console.log(`⚠️  ${pages.length} ${noun} — ${explanation}`);
+  for (const page of pages) console.log(`     content/${page.path}.md`);
+  console.log();
 }
 
-console.log(`\n🔗 ${broken.length} unresolved link${broken.length === 1 ? '' : 's'}:\n`);
+if (broken.length > 0) {
+  console.log(`\n🔗 ${broken.length} unresolved link${broken.length === 1 ? '' : 's'}:\n`);
 
-for (const link of broken) {
-  console.log(`  content/${link.from}.md`);
+  for (const link of broken) {
+    console.log(`  content/${link.from}.md`);
 
-  if (link.reason === 'ambiguous') {
-    console.log(`    [[${link.target}]] is ambiguous — matches ${link.candidates?.join(', ')}`);
-    console.log('    Use the full path to disambiguate.');
-  } else {
-    console.log(`    [[${link.target}]] matches no page`);
+    if (link.reason === 'ambiguous') {
+      console.log(`    [[${link.target}]] is ambiguous — matches ${link.candidates?.join(', ')}`);
+      console.log('    Use the full path to disambiguate.');
+    } else {
+      console.log(`    [[${link.target}]] matches no page`);
+    }
   }
+
+  console.log();
+} else {
+  console.log(`\n🔗 Links OK — ${edges.length} links across ${nodes.length} pages\n`);
 }
 
-console.log();
+const { orphans, deadEnds } = getWikiHealth();
+
+report(
+  { one: 'orphaned page', many: 'orphaned pages' },
+  'nothing links here, so a reader can only arrive from the sidebar',
+  orphans,
+);
+
+report(
+  { one: 'dead end', many: 'dead ends' },
+  'no links out, so a reader arrives with nowhere to go',
+  deadEnds,
+);
 
-if (strict) {
+if (broken.length > 0 && strict) {
   console.error('❌ Failing because --strict was passed.\n');
   process.exit(1);
 }

package/template/styles/markdown.css

@@ -239,3 +239,160 @@ html.dark .ezw-broken-link {
     }
   }
 }
+
+/* Callouts from `> [!NOTE]`, GitHub's and Obsidian's shared syntax.
+   Distinguished by a coloured edge and a heading rather than an icon: no glyph
+   to load, and the meaning survives when colour alone is not perceived. */
+.ezw-callout {
+  --ezw-callout-accent: var(--color-text-muted);
+  margin: 1.5rem 0;
+  padding: 0.875rem 1.125rem;
+  border: 1px solid var(--color-border);
+  border-left: 3px solid var(--ezw-callout-accent);
+  border-radius: 0.375rem;
+  background: var(--color-sidebar-bg);
+}
+
+.ezw-callout__title {
+  margin: 0 0 0.5rem;
+  font-size: 0.8125rem;
+  font-weight: 600;
+  letter-spacing: 0.01em;
+  color: var(--ezw-callout-accent);
+}
+
+/* The body's first block sits against the title, and the last against the
+   floor, so a one-paragraph callout is not padded twice over. */
+.ezw-callout > :nth-child(2) {
+  margin-top: 0;
+}
+
+.ezw-callout > :last-child {
+  margin-bottom: 0;
+}
+
+/* A foldable callout is a <details>; the marker is dropped in favour of the
+   title carrying the affordance, and the cursor says it is interactive. */
+summary.ezw-callout__title {
+  cursor: pointer;
+  list-style: none;
+}
+
+summary.ezw-callout__title::-webkit-details-marker {
+  display: none;
+}
+
+summary.ezw-callout__title::before {
+  content: '▸';
+  display: inline-block;
+  /* A trailing space in `content` collapses, leaving the marker against the
+     title, so the gap is a margin. */
+  margin-right: 0.4em;
+  transition: transform 120ms ease;
+}
+
+details[open] > summary.ezw-callout__title::before {
+  transform: rotate(90deg);
+}
+
+details.ezw-callout:not([open]) > summary.ezw-callout__title {
+  margin-bottom: 0;
+}
+
+.ezw-callout--note {
+  --ezw-callout-accent: #1d4ed8;
+}
+
+.ezw-callout--tip {
+  --ezw-callout-accent: #047857;
+}
+
+.ezw-callout--important {
+  --ezw-callout-accent: #6d28d9;
+}
+
+.ezw-callout--warning {
+  --ezw-callout-accent: #b45309;
+}
+
+.ezw-callout--caution {
+  --ezw-callout-accent: #b91c1c;
+}
+
+.dark .ezw-callout--note {
+  --ezw-callout-accent: #93c5fd;
+}
+
+.dark .ezw-callout--tip {
+  --ezw-callout-accent: #6ee7b7;
+}
+
+.dark .ezw-callout--important {
+  --ezw-callout-accent: #c4b5fd;
+}
+
+.dark .ezw-callout--warning {
+  --ezw-callout-accent: #fcd34d;
+}
+
+.dark .ezw-callout--caution {
+  --ezw-callout-accent: #fca5a5;
+}
+
+/* A link on each heading pointing at itself, so a section can be shared
+   without reading the id out of the address bar. */
+.ezw-heading {
+  position: relative;
+}
+
+.ezw-heading__anchor {
+  margin-left: 0.4em;
+  font-weight: 400;
+  color: var(--color-text-muted);
+  text-decoration: none;
+  /* Hidden until wanted, but only visually: it stays in the accessible tree
+     and in the tab order, so a keyboard or screen reader user can reach it. */
+  opacity: 0;
+  transition: opacity 120ms ease;
+}
+
+.ezw-heading:hover .ezw-heading__anchor,
+.ezw-heading__anchor:focus-visible {
+  opacity: 1;
+}
+
+.ezw-heading__anchor:hover {
+  color: var(--color-text);
+}
+
+/* A pointer is not always available. On touch the anchor is simply shown,
+   since there is no hover to reveal it with. */
+@media (hover: none) {
+  .ezw-heading__anchor {
+    opacity: 0.5;
+  }
+}
+
+/* Diagrams from ```mermaid fences, drawn during the build.
+   The SVG refers to --bg and --fg but no longer fixes them inline, so the
+   colours come from here and follow the theme — the same arrangement the
+   syntax highlighter uses for code. */
+.ezw-mermaid {
+  --bg: transparent;
+  --fg: var(--color-text);
+  --line: var(--color-text-muted);
+  --accent: var(--color-primary, #2563eb);
+  --muted: var(--color-text-muted);
+  --surface: var(--color-code-bg);
+  --border: var(--color-border);
+  margin: 1.5rem 0;
+  /* A wide diagram scrolls inside its own box rather than widening the page. */
+  overflow-x: auto;
+}
+
+.ezw-mermaid svg {
+  display: block;
+  max-width: 100%;
+  height: auto;
+  margin-inline: auto;
+}