npm - @staticbolt/docs - Versions diffs - 0.0.1-beta.0 - Mend

@staticbolt/docs 0.0.1-beta.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (94) hide show

package/LICENSE ADDED Viewed

@@ -0,0 +1,22 @@
+MIT License
+Copyright (c) 2025 Ahmed Alabsi
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md ADDED Viewed

@@ -0,0 +1,148 @@
+# @staticbolt/docs
+The parts, styles, and plugins every staticbolt docs site shares.
+The project keeps its own `.staticbolt.ts`, layout, social icons, colors, and any page-specific parts.
+## Install
+```shellscript
+npm install @staticbolt/docs @staticview/ui
+```
+`@staticview/ui` provides `sv-accordion`, used by the sidebar, the mobile table of contents, and collapsible callouts.
+The layout has to load it.
+## Config
+```ts
+import { defineConfig } from "@staticbolt/core";
+import * as plugins from "@staticbolt/core/plugins";
+import { rehypeExpressiveCodeOptions } from "@staticbolt/docs/ec-config";
+import * as theme from "@staticbolt/docs/plugins";
+import rehypeCallouts from "rehype-callouts";
+import rehypeKatex from "rehype-katex";
+import remarkMath from "remark-math";
+export default defineConfig({
+  plugins: [
+    theme.contentPlugin({
+      include: ["pages/**/*.{html,md}"],
+      baseDirectory: "pages",
+      layouts: { default: "@layouts/document.layout.html" },
+      icons: "@parts/sidebar-icons",
+    }),
+    plugins.htmlLayoutPlugin({ tags: ["layout", "part", "icon"] }),
+    theme.HtmlCodeBlockPlugin({ rehypeExpressiveCodeOptions }),
+    theme.katexFontsPlugin(),
+    theme.pagefindPlugin(),
+    theme.llmsPlugin({ siteUrl: "https://example.com" }),
+    plugins.coreMarkdownPlugin({
+      allowDangerousHtml: true,
+      remarkPlugins: [remarkMath],
+      rehypePlugins: [
+        [rehypeKatex, { output: "mathml" }],
+        theme.wrapTables,
+        rehypeCallouts,
+        theme.rehypeMermaidFence,
+        [theme.cachedRehypeExpressiveCode, rehypeExpressiveCodeOptions],
+      ],
+    }),
+    theme.ecCachePlugin(),
+  ],
+});
+```
+`tags` must include `"icon"` when `icons` is set.
+Callouts, math, and diagrams are opt-in. The project installs what it uses:
+| Feature  | Install                       | Config                                                         |
+| -------- | ----------------------------- | -------------------------------------------------------------- |
+| Callouts | `rehype-callouts`             | `rehypeCallouts`, the `callouts` part                          |
+| Math     | `remark-math`, `rehype-katex` | `remarkMath`, `rehypeKatex`, `katexFontsPlugin()`, `katex.css` |
+| Diagrams | `mermaid`                     | `theme.rehypeMermaidFence`, the `mermaid` part                 |
+Needs `@staticbolt/core` with the two fixes from 2026-08-20: sources inside a `node_modules` part resolve,
+and `url()` references move with bundled stylesheets.
+## Layout
+The project owns the layout: the `<head>` plus the theme's `document` part, which is the whole docs page.
+Copy this as `sources/layouts/document.layout.html` and edit the names:
+```html
+<!doctype html>
+<html dir="ltr" lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta content="light dark" name="color-scheme" />
+    <meta content="width=device-width, initial-scale=1.0" name="viewport" />
+    <link bundle href="@styles/docs.css" rel="stylesheet" />
+    <link type="image/svg" href="@assets/favicon.svg" rel="icon" />
+    <meta content="Documentation for My Project." name="description" />
+    <meta content="website" property="og:type" />
+    <meta content="My Project" property="og:site_name" />
+    <meta content="My Project" property="og:title" />
+    <meta content="Documentation for My Project." property="og:description" />
+    <meta content="summary" name="twitter:card" />
+    <title>My Project</title>
+  </head>
+  <body>
+    <part
+      maxHeading="{{ $data.maxHeading ?? 3 }}"
+      minHeading="{{ $data.minHeading ?? 2 }}"
+      src="@staticbolt/docs/parts/document/document.part.html"
+      title="My Project"
+    >
+      <part slot="icons" src="@parts/social-icons/social-icons.part.html"></part>
+      <slot />
+    </part>
+  </body>
+</html>
+```
+`sources/parts/social-icons/social-icons.part.html` is the project's own part, one `<a>` per link.
+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`.                  |
+## Styles
+`docs.css` in the project:
+```css
+@import url("@staticbolt/docs/styles/docs.css");
+@import url("@staticbolt/docs/styles/katex.css");
+@import url("@parts/social-icons/social-icons.style.css");
+@import url("@styles/theme.css");
+```
+`katex.css` is only needed with `rehypeKatex`.
+`theme.css` overrides the palette:
+```css
+:root {
+  --sb-hue-accent: 85;
+  --sb-hue-base: 305;
+}
+```
+Any `--sb-*` variable from `global.css` can be overridden the same way.
+## Overriding a part
+Copy it from `node_modules/@staticbolt/docs/sources/parts/` into the project and point the layout at the copy.
+For the sidebar parts pass the copy through `contentPlugin`'s `sidebarLayout`, `directoryLayout`, or `linkLayout`.

package/lib/collapsible-plugin-Bwt7dmKE.mjs ADDED Viewed

@@ -0,0 +1,132 @@
+import { definePlugin } from "@expressive-code/core";
+import { h } from "@expressive-code/core/hast";
+//#region plugins/collapsible-plugin.ts
+/**
+* Collapses opted-in code blocks to a fixed number of preview lines.
+*
+* Add the `collapsible` meta flag to collapse a block, or `collapsible=N` to override the number of preview lines for that block.
+* Blocks with no more lines than the preview size are left untouched.
+*
+* The collapsed height is expressed in `lh` units of the rendered code, so blocks render at their final size on first paint
+* without any JavaScript measurements or layout shifts.
+*/
+function pluginCollapsible(options = {}) {
+	const defaultPreviewLines = options.previewLines ?? 6;
+	const expandButtonText = options.expandButtonText ?? "Show code";
+	const collapseButtonText = options.collapseButtonText ?? "Hide code";
+	return definePlugin({
+		name: "Collapsible",
+		baseStyles: ({ cssVar }) => `
+      .ec-collapsible {
+        position: relative;
+        display: grid;
+        grid-template-columns: minmax(0, 1fr);
+      }
+      .ec-collapsible > * {
+        grid-area: 1 / 1;
+      }
+      .ec-collapsible:not(.ec-collapsible-expanded) pre > code {
+        box-sizing: content-box;
+        max-block-size: calc(var(--ec-collapsible-lines) * 1lh);
+        padding-block-end: 0;
+        overflow-y: clip;
+      }
+      .ec-collapsible:not(.ec-collapsible-expanded)::after {
+        position: absolute;
+        inset: ${cssVar("borderWidth")};
+        content: "";
+        pointer-events: none;
+        background: linear-gradient(to bottom, transparent, ${cssVar("codeBackground")});
+        border-radius: ${cssVar("borderRadius")};
+      }
+      .ec-collapsible-toggle {
+        z-index: 1;
+        align-self: end;
+        justify-self: center;
+        display: flex;
+        align-items: center;
+        margin-block-end: 1.2em;
+        padding: 0.45em 1.2em;
+        font-family: var(--sb-md-font);
+        font-size: var(--sb-text-xs);
+        font-weight: 500;
+        line-height: 1.5;
+        color: var(--sb-color-accent-high);
+        cursor: pointer;
+        background-color: color-mix(in srgb, var(--sb-color-accent) 6%, var(--sb-code-background));
+        border: 1px solid color-mix(in srgb, var(--sb-color-accent) 45%, transparent);
+        border-radius: 999px;
+        transition:
+          background-color 200ms ease,
+          border-color 200ms ease;
+      }
+      .ec-collapsible-expanded .ec-collapsible-toggle {
+        position: sticky;
+        inset-block-end: 0.875em;
+      }
+      .ec-collapsible-toggle:hover {
+        background-color: color-mix(in srgb, var(--sb-color-accent) 14%, var(--sb-code-background));
+        border-color: var(--sb-color-accent);
+      }
+      .ec-collapsible-toggle:focus-visible {
+        outline: 2px solid var(--sb-color-accent-high);
+        outline-offset: 2px;
+      }
+      .ec-collapsible-hide-label,
+      .ec-collapsible-expanded .ec-collapsible-show-label {
+        display: none;
+      }
+      .ec-collapsible-expanded .ec-collapsible-hide-label {
+        display: inline;
+      }
+    `,
+		hooks: { postprocessRenderedBlock: (context) => {
+			const metaOptions = context.codeBlock.metaOptions;
+			let previewLines = metaOptions.getInteger("collapsible");
+			if (previewLines === void 0 && metaOptions.getBoolean("collapsible")) previewLines = defaultPreviewLines;
+			if (previewLines === void 0 || previewLines < 1) return;
+			if (context.codeBlock.getLines().length <= previewLines) return;
+			const toggle = h("button", {
+				class: "ec-collapsible-toggle",
+				type: "button",
+				"aria-expanded": "false"
+			}, [h("span", { class: "ec-collapsible-show-label" }, expandButtonText), h("span", { class: "ec-collapsible-hide-label" }, collapseButtonText)]);
+			context.renderData.blockAst = h("div", {
+				class: "ec-collapsible",
+				style: `--ec-collapsible-lines: ${previewLines}`
+			}, [context.renderData.blockAst, toggle]);
+		} },
+		jsModules: [`
+      if (!window.ecCollapsibleInit) {
+        window.ecCollapsibleInit = true;
+        document.addEventListener("click", (event) => {
+          const toggle = event.target instanceof Element ? event.target.closest(".ec-collapsible-toggle") : null;
+          if (!toggle) return;
+          const block = toggle.closest(".ec-collapsible");
+          if (!block) return;
+          const isExpanded = block.classList.toggle("ec-collapsible-expanded");
+          toggle.setAttribute("aria-expanded", String(isExpanded));
+          if (isExpanded || block.getBoundingClientRect().top >= 0) return;
+          const reduceMotion = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+          block.scrollIntoView({ behavior: reduceMotion ? "instant" : "smooth", block: "start" });
+        });
+      }
+      `]
+	});
+}
+//#endregion
+export { pluginCollapsible as t };

package/lib/ec-config.mjs ADDED Viewed

@@ -0,0 +1,59 @@
+import { t as pluginCollapsible } from "./collapsible-plugin-Bwt7dmKE.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";
+//#region ec.config.ts
+const rehypeExpressiveCodeOptions = {
+	themes: ["plastic", "kanagawa-lotus"],
+	plugins: [
+		pluginLineNumbers(),
+		pluginFileIcons(),
+		pluginCollapsibleSections(),
+		pluginCollapsible({ previewLines: 3 })
+	],
+	defaultProps: {
+		wrap: false,
+		showLineNumbers: false,
+		collapseStyle: "collapsible-auto"
+	},
+	useDarkModeMediaQuery: false,
+	styleOverrides: {
+		codeBackground: "var(--sb-code-background)",
+		borderColor: "var(--sb-color-gray-5)",
+		borderWidth: "1px",
+		gutterHighlightForeground: "var(--sb-color-accent-high)",
+		collapsibleSections: {
+			openBackgroundColorCollapsible: "var(--sb-color-gray-7)",
+			closedBackgroundColor: "var(--sb-color-gray-6)",
+			closedTextColor: "var(--sb-color-gray-1)"
+		},
+		frames: {
+			shadowColor: "transparent",
+			editorBackground: "var(--sb-code-background)",
+			editorTabBarBackground: "var(--sb-code-background)",
+			terminalBackground: "var(--sb-code-background)",
+			terminalTitlebarBackground: "var(--sb-code-background)",
+			terminalTitlebarDotsForeground: "var(--sb-color-accent-high)",
+			terminalTitlebarBorderBottomColor: "var(--sb-color-gray-5)",
+			editorTabBarBorderBottomColor: "var(--sb-color-gray-5)",
+			editorActiveTabBackground: "transparent",
+			editorActiveTabIndicatorBottomColor: "var(--sb-color-gray-2)",
+			editorActiveTabIndicatorTopColor: "transparent",
+			editorActiveTabForeground: "var(--sb-color-gray-0)",
+			inlineButtonForeground: "var(--sb-color-accent-high)",
+			tooltipSuccessBackground: "var(--sb-color-accent)"
+		},
+		textMarkers: {
+			markBackground: "var(--sb-color-gray-7)",
+			markBorderColor: "var(--sb-color-accent-high)",
+			insBackground: "light-dark(#2da44e1f, #26561c80)",
+			insBorderColor: "light-dark(#2da44e59, #4e7e41d0)",
+			insDiffIndicatorColor: "light-dark(#1a7f37, #7eb070d0)",
+			delBackground: "light-dark(#cf222e14, #81322b80)",
+			delBorderColor: "light-dark(#cf222e4d, #ae594fd0)",
+			delDiffIndicatorColor: "light-dark(#cf222e, #e68a7ed0)"
+		}
+	}
+};
+//#endregion
+export { rehypeExpressiveCodeOptions };

package/lib/ec.config.d.mts ADDED Viewed

@@ -0,0 +1,5 @@
+import { RehypeExpressiveCodeOptions } from "rehype-expressive-code";
+//#region ec.config.d.ts
+declare const rehypeExpressiveCodeOptions: RehypeExpressiveCodeOptions;
+//#endregion
+export { rehypeExpressiveCodeOptions };