@staticbolt/docs 0.0.1-beta.0 → 0.0.1-beta.2

package/README.md

@@ -107,17 +107,17 @@ Copy this as `sources/layouts/document.layout.html` and edit the names:
 
 To change the page structure, copy `node_modules/@staticbolt/docs/sources/parts/document/document.part.html` into the project and point the layout at the copy; it references the other parts by package path, so it works as is.
 
-| Part                  | Role                                                                             |
-| --------------------- | -------------------------------------------------------------------------------- |
-| `document`            | The whole page. `title`, `minHeading`, `maxHeading`, slot `icons`, default slot. |
-| `header`              | Takes `title`. Slot `icons` for the social links.                                |
-| `sidebar`             | Filled by `contentPlugin`. Slot `icons` for the social links.                    |
-| `table-of-content`    | `-desktop` takes `minHeading` and `maxHeading`, `-mobile` none.                  |
-| `pagination-links`    | Previous/next links read from the sidebar.                                       |
-| `callouts`            | Build-time script turning collapsible callouts into accordions.                  |
-| `mermaid`             | Renders ` ```mermaid ` fences. Removes itself from pages without.                |
-| `color-scheme-switch` | Already inside header and sidebar.                                               |
-| `badge`               | Used by the sidebar for `data.badgeText` / `data.badgeVariant`.                  |
+| Part                  | Role                                                                                         |
+| --------------------- | -------------------------------------------------------------------------------------------- |
+| `document`            | The whole page. `title`, `minHeading`, `maxHeading`, `mermaid`, slot `icons`, default slot.  |
+| `header`              | Takes `title`. Slot `icons` for the social links.                                            |
+| `sidebar`             | Filled by `contentPlugin`. Slot `icons` for the social links.                                |
+| `table-of-content`    | `-desktop` takes `minHeading` and `maxHeading`, `-mobile` none.                              |
+| `pagination-links`    | Previous/next links read from the sidebar.                                                   |
+| `callouts`            | Build-time script turning collapsible callouts into accordions.                              |
+| `mermaid`             | Renders ` ```mermaid ` fences. Removes itself from pages without. Needs `mermaid` installed. |
+| `color-scheme-switch` | Already inside header and sidebar.                                                           |
+| `badge`               | Used by the sidebar for `data.badgeText` / `data.badgeVariant`.                              |
 
 ## Styles
 

package/lib/ec-config.mjs

@@ -1,4 +1,4 @@
-import { t as pluginCollapsible } from "./collapsible-plugin-Bwt7dmKE.mjs";
+import { n as pluginCollapsible, t as htmlWithTypeScriptScripts } from "./html-ts-script-lang-DthQZbmB.mjs";
 import { pluginCollapsibleSections } from "@expressive-code/plugin-collapsible-sections";
 import { pluginLineNumbers } from "@expressive-code/plugin-line-numbers";
 import { pluginFileIcons } from "@xt0rted/expressive-code-file-icons";
@@ -17,6 +17,7 @@ const rehypeExpressiveCodeOptions = {
 		collapseStyle: "collapsible-auto"
 	},
 	useDarkModeMediaQuery: false,
+	shiki: { langs: [htmlWithTypeScriptScripts] },
 	styleOverrides: {
 		codeBackground: "var(--sb-code-background)",
 		borderColor: "var(--sb-color-gray-5)",

package/lib/{collapsible-plugin-Bwt7dmKE.mjs → html-ts-script-lang-DthQZbmB.mjs}

@@ -1,5 +1,7 @@
 import { definePlugin } from "@expressive-code/core";
 import { h } from "@expressive-code/core/hast";
+import htmlLangs from "@shikijs/langs/html";
+import tsLangs from "@shikijs/langs/typescript";
 //#region plugins/collapsible-plugin.ts
 /**
 * Collapses opted-in code blocks to a fixed number of preview lines.
@@ -129,4 +131,46 @@ function pluginCollapsible(options = {}) {
 	});
 }
 //#endregion
-export { pluginCollapsible as t };
+//#region plugins/html-ts-script-lang.ts
+const typeAlternation = ["application/x-typescript"].map((t) => t.replace(/[/+.-]/g, String.raw`\$&`)).join("|");
+const typescriptScriptPattern = {
+	begin: String.raw`(?i:(?=type\s*=\s*(["']?)(?:${typeAlternation})["'>\s]))`,
+	end: "((<))(?=/(?i:script))",
+	endCaptures: {
+		"0": { name: "meta.tag.metadata.script.end.html" },
+		"1": { name: "punctuation.definition.tag.begin.html" },
+		"2": { name: "source.ts" }
+	},
+	patterns: [{
+		begin: String.raw`\G`,
+		end: "(>)",
+		endCaptures: { "1": { name: "punctuation.definition.tag.end.html" } },
+		name: "meta.tag.metadata.script.start.html",
+		patterns: [{ include: "#attribute" }]
+	}, {
+		begin: String.raw`(?!\G)`,
+		end: "(?=</(?i:script))",
+		name: "source.ts",
+		patterns: [{ include: "source.ts" }]
+	}]
+};
+/**
+* Shiki's bundled HTML grammar only highlights `<script>` contents when the `type` attribute is a known JavaScript type, leaving
+* TypeScript script blocks unhighlighted. These registrations are a drop-in replacement for the `html` language that also embeds
+* TypeScript.
+*/
+const htmlWithTypeScriptScripts = (() => {
+	const langs = structuredClone(htmlLangs);
+	const html = langs.find((lang) => lang.scopeName === "text.html.basic");
+	if (!html) {
+		console.warn("[html-ts-script-lang] Shiki's HTML grammar was not found; TypeScript script blocks stay unhighlighted.");
+		return [...langs, ...tsLangs];
+	}
+	const scriptTag = html.repository?.["tags-valid"]?.patterns?.[1]?.patterns?.[0]?.patterns?.[0];
+	if (scriptTag?.patterns) scriptTag.patterns.splice(2, 0, typescriptScriptPattern);
+	else console.warn("[html-ts-script-lang] Shiki's HTML script-tag patterns moved; TypeScript script blocks stay unhighlighted.");
+	html.embeddedLangs = [...html.embeddedLangs ?? [], "typescript"];
+	return [...langs, ...tsLangs];
+})();
+//#endregion
+export { pluginCollapsible as n, htmlWithTypeScriptScripts as t };

package/lib/index.d.mts

@@ -2,6 +2,7 @@ import { Plugin } from "@staticbolt/core";
 import { RehypeExpressiveCodeOptions } from "rehype-expressive-code";
 import { ExpressiveCodePlugin } from "@expressive-code/core";
 import { Root } from "hast";
+import { LanguageRegistration } from "shiki";
 import { Plugin as Plugin$1 } from "unified";
 import { Root as Root$1 } from "mdast";
 import { Node } from "unist";
@@ -244,8 +245,11 @@ declare function normalizeTitle(string: string): string;
 //#endregion
 //#region plugins/ec-cache.d.ts
 declare function sha1(input: string): string;
-/** Invalidates all cached entries when the expressive-code version or its configuration changes. */
-declare const ecCacheSalt: string;
+/**
+ * Invalidates all cached entries when the expressive-code version or its configuration changes.\
+ * Functions in the options, plugin hooks included, count by name only.
+ */
+declare function ecCacheSalt(options?: RehypeExpressiveCodeOptions): string;
 declare class PersistentCache {
   private readonly filePath;
   private readonly entries;
@@ -266,6 +270,14 @@ declare function ecCachePlugin(): Plugin;
  */
 declare function cachedRehypeExpressiveCode(this: unknown, options: RehypeExpressiveCodeOptions): (tree: Root, ...rest: unknown[]) => Promise<Root | undefined>;
 //#endregion
+//#region plugins/html-ts-script-lang.d.ts
+/**
+ * Shiki's bundled HTML grammar only highlights `<script>` contents when the `type` attribute is a known JavaScript type, leaving
+ * TypeScript script blocks unhighlighted. These registrations are a drop-in replacement for the `html` language that also embeds
+ * TypeScript.
+ */
+declare const htmlWithTypeScriptScripts: LanguageRegistration[];
+//#endregion
 //#region plugins/katex-fonts-plugin.d.ts
 /**
  * Ships the KaTeX fonts `katex.css` loads. In production, references into the theme's `sources/assets` are rewritten to
@@ -334,6 +346,9 @@ declare module "mdast" {
   interface PhrasingContentMap {
     obsidianTag: ObsidianTagNode;
   }
+  interface RootContentMap {
+    obsidianTag: ObsidianTagNode;
+  }
 }
 /**
  * Remark plugin that renders Obsidian tags.
@@ -368,4 +383,4 @@ declare function pagefindPlugin({ glob }?: PagefindPluginOptions): Plugin;
 //#region plugins/wrap-table.d.ts
 declare function wrapTables(): (tree: Node) => void;
 //#endregion
-export { CollapsiblePluginOptions, HtmlCodeBlockPlugin, PersistentCache, RemarkObsidianCommentsOptions, cachedRehypeExpressiveCode, contentPlugin, ecCachePlugin, ecCacheSalt, katexFontsPlugin, llmsPlugin, normalizeTitle, pagefindPlugin, pluginCollapsible, rehypeMermaidFence, remarkObsidianComments, remarkObsidianTags, sha1, wrapTables };
+export { CollapsiblePluginOptions, HtmlCodeBlockPlugin, PersistentCache, RemarkObsidianCommentsOptions, cachedRehypeExpressiveCode, contentPlugin, ecCachePlugin, ecCacheSalt, htmlWithTypeScriptScripts, katexFontsPlugin, llmsPlugin, normalizeTitle, pagefindPlugin, pluginCollapsible, rehypeMermaidFence, remarkObsidianComments, remarkObsidianTags, sha1, wrapTables };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staticbolt/docs",
-  "version": "0.0.1-beta.0",
+  "version": "0.0.1-beta.2",
   "description": "Documentation theme for staticbolt: layout parts, styles, and plugins shared by every docs site.",
   "author": "Ahmed ALABSI",
   "license": "MIT",
@@ -83,7 +83,7 @@
     "@eslint/markdown": "^8.0.1",
     "@html-eslint/eslint-plugin": "^0.60.0",
     "@html-eslint/parser": "^0.60.0",
-    "@staticbolt/core": "^1.0.0-beta.29",
+    "@staticbolt/core": "beta",
     "@stylistic/stylelint-config": "^5.0.0",
     "@trivago/prettier-plugin-sort-imports": "^6.0.2",
     "@types/hast": "^3.0.5",

package/sources/parts/callouts/callouts.part.html

@@ -1,5 +1,5 @@
 <!-- ::: Collapsible callouts (`> [!note]-`) render as `<details>`; swap them for sv-accordion ::: -->
-<script build-time>
+<script type="application/x-typescript" build-time>
   for (const callout of document.querySelectorAll("details.callout")) {
     const accordion = document.createElement("sv-accordion");
     accordion.setAttribute("data-callout", callout.getAttribute("data-callout"));

package/sources/parts/color-scheme-switch/color-scheme-switch.part.html

@@ -29,13 +29,12 @@
 </div>
 
 <insert selector="head">
-  <script>
-    // @ts-check
+  <script type="application/x-typescript">
     (() => {
       const STORAGE_KEY = "color-scheme";
       const PREFERS_DARK = window.matchMedia("(prefers-color-scheme: dark)");
 
-      let currentScheme = PREFERS_DARK.matches ? "dark" : "light";
+      let currentScheme: "light" | "dark" = PREFERS_DARK.matches ? "dark" : "light";
 
       // Override with stored value
       const stored = window.localStorage.getItem(STORAGE_KEY);
@@ -44,11 +43,7 @@
         document.documentElement.style.colorScheme = stored;
       }
 
-      /**
-       * @param {"light" | "dark"} scheme
-       * @param {NodeListOf<HTMLButtonElement>} buttons
-       */
-      const applyScheme = (scheme, buttons) => {
+      const applyScheme = (scheme: "light" | "dark", buttons: NodeListOf<HTMLButtonElement>) => {
         const isDark = scheme === "dark";
 
         for (const button of buttons) {
@@ -62,8 +57,7 @@
       };
 
       const onReady = () => {
-        /** @type {NodeListOf<HTMLButtonElement>} */
-        const colorSchemeButtons = document.querySelectorAll(".color-scheme-switch");
+        const colorSchemeButtons = document.querySelectorAll<HTMLButtonElement>(".color-scheme-switch");
 
         const isDark = currentScheme === "dark";
 

package/sources/parts/document/document.part.html

@@ -3,6 +3,7 @@
   @attr title - Site name shown in the header.
   @attr minHeading - Lowest heading level in the table of contents. Default 2.
   @attr maxHeading - Highest heading level in the table of contents. Default 3.
+  @attr mermaid - Present to render mermaid fences. Needs the mermaid package.
   @slot - The page content.
   @slot logo - Rendered before the title in the header link.
   @slot icons - Links rendered in the header and the sidebar footer.
@@ -45,10 +46,13 @@
 </div>
 
 <part src="@staticbolt/docs/parts/callouts/callouts.part.html"></part>
+
+{{ $data.mermaid === undefined ? "" : `
 <part src="@staticbolt/docs/parts/mermaid/mermaid.part.html"></part>
+` }}
 
 <!-- ::: Page title and skip link ::: -->
-<script build-time>
+<script type="application/x-typescript" build-time>
   const heading = document.querySelector("h1[id]");
   const title = document.querySelector("title");
   const ogTitle = document.querySelector('meta[property="og:title"]');

package/sources/parts/header/header.part.html

@@ -36,18 +36,14 @@
 </header>
 
 <!-- ::: Toggle the sidebar ::: -->
-<script type="module">
-  // @ts-check
-
+<script type="application/x-typescript" module>
   (() => {
-    /** @type {HTMLButtonElement | null} */
-    const menuTrigger = document.querySelector(".side-menu-trigger-button");
+    const menuTrigger = document.querySelector<HTMLButtonElement>(".side-menu-trigger-button");
     if (!menuTrigger) {
       return;
     }
 
-    /** @type {HTMLDivElement | null} */
-    const sidebar = document.querySelector(".sidebar");
+    const sidebar = document.querySelector<HTMLDivElement>(".sidebar");
     if (!sidebar) {
       menuTrigger.remove();
       return;

package/sources/parts/mermaid/mermaid.part.html

@@ -2,7 +2,7 @@
 <script type="module" data-mermaid-script src="@staticbolt/docs/scripts/mermaid.ts"></script>
 
 <!-- ::: Drop the script from pages without a diagram ::: -->
-<script build-time>
+<script type="application/x-typescript" build-time>
   const mermaidScript = document.querySelector("[data-mermaid-script]");
 
   if (mermaidScript) {

package/sources/parts/pagefind/pagefind.part.html

@@ -11,7 +11,7 @@
 <pagefind-modal></pagefind-modal>
 
 <!-- ::: Path from this page to the Pagefind bundle, so the site works on any subpath ::: -->
-<script type="module" build-time>
+<script type="application/x-typescript" build-time module>
   import { dirname, relative } from "node:path";
 
   const modal = document.querySelector("pagefind-modal");
@@ -21,14 +21,11 @@
 <insert selector="body">
   <link class="pagefind-stylesheet" as="style" bundle href="./pagefind.style.css" rel="preload" />
 
-  <script type="module">
-    // @ts-check
-
+  <script type="application/x-typescript" module>
     (async () => {
       // ::: Lazy-load the Pagefind UI. :::
 
-      /** @type {HTMLLinkElement | null} */
-      const pagefindStyleSheet = document.querySelector(".pagefind-stylesheet");
+      const pagefindStyleSheet = document.querySelector<HTMLLinkElement>(".pagefind-stylesheet");
       if (!pagefindStyleSheet) {
         console.error("Could not find pagefind stylesheet element");
         return;
@@ -53,15 +50,13 @@
 
       // ::: Open the Pagefind modal when the search button is clicked. :::
 
-      /** @type {(HTMLElement & { openModal(): void }) | null} */
-      const pagefindModalTrigger = document.querySelector("pagefind-modal-trigger");
+      const pagefindModalTrigger = document.querySelector<HTMLElement & { openModal(): void }>("pagefind-modal-trigger");
       if (!pagefindModalTrigger) {
         console.error("Could not find pagefind modal trigger element");
         return;
       }
 
-      /** @type {HTMLButtonElement | null} */
-      const triggerModalIconButton = document.querySelector(".pagefind-modal-trigger-button");
+      const triggerModalIconButton = document.querySelector<HTMLButtonElement>(".pagefind-modal-trigger-button");
       if (!triggerModalIconButton) {
         console.error("Could not find pagefind modal trigger button element");
         return;

package/sources/parts/pagination-links/pagination-links.part.html

@@ -25,7 +25,7 @@
 </div>
 
 <!-- This script will run once at build time for each page -->
-<script type="module" build-time>
+<script type="application/x-typescript" build-time module>
   // ::: Get current link and populate previous/next links :::
   import { join, dirname, normalize } from "node:path";
 

package/sources/parts/sidebar/sidebar.part.html

@@ -14,7 +14,7 @@
   </div>
 </div>
 
-<script type="module" build-time>
+<script type="application/x-typescript" build-time module>
   import { join, dirname, normalize } from "node:path";
 
   // ::: Mark current page links as active and expand matching accordions. :::
@@ -42,17 +42,16 @@
 </script>
 
 <!-- ::: Persist sidebar navigation state across page loads. ::: -->
-<script>
+<script type="application/x-typescript">
   (() => {
-    /** @type {NodeListOf<HTMLDivElement>} */
-    const accordions = document.querySelectorAll(".sidebar-accordion");
+    const accordions = document.querySelectorAll<HTMLDivElement>(".sidebar-accordion");
 
     // ::: Restore the accordion's previous open state. :::
     try {
-      const state = JSON.parse(sessionStorage.getItem("sidebar-state") ?? {});
+      const state = JSON.parse(sessionStorage.getItem("sidebar-state") ?? "{}");
 
       for (const [accordionIndex, opened] of Object.entries(state)) {
-        const accordion = /** @type {HTMLDivElement} */ (accordions[accordionIndex]);
+        const accordion = accordions[Number(accordionIndex)];
         if (!accordion) continue;
 
         // Keep accordions containing the active link expanded by default

package/sources/parts/table-of-content/table-of-content-desktop.part.html

@@ -6,7 +6,7 @@
   </div>
 </aside>
 
-<script build-time>
+<script type="application/x-typescript" build-time>
   const tocContents = document.querySelectorAll(".toc-content");
   const headings = document
     .querySelectorAll("h1[id], h2[id], h3[id], h4[id], h5[id], h6[id]")
@@ -65,7 +65,7 @@
   }
 </script>
 
-<script>
+<script type="application/x-typescript">
   (() => {
     // All links in the mobile and desktop TOC
     const links = document.querySelectorAll(".toc-list a");

package/sources/parts/table-of-content/table-of-content-mobile.part.html

@@ -12,7 +12,7 @@
 </div>
 
 <!-- ::: Close the accordion when a link is clicked ::: -->
-<script type="module">
+<script type="application/x-typescript" module>
   const tocAccordion = document.querySelector(".toc-accordion");
   const tocLinks = document.querySelectorAll(".toc-accordion a");