@staticbolt/docs 0.0.1-beta.0

package/lib/index.d.mts

@@ -0,0 +1,371 @@
+import { Plugin } from "@staticbolt/core";
+import { RehypeExpressiveCodeOptions } from "rehype-expressive-code";
+import { ExpressiveCodePlugin } from "@expressive-code/core";
+import { Root } from "hast";
+import { Plugin as Plugin$1 } from "unified";
+import { Root as Root$1 } from "mdast";
+import { Node } from "unist";
+//#region plugins/code-block-plugin.d.ts
+interface HtmlCodeBlockPlugin {
+  /**
+   * The tag name.
+   *
+   * @default "code-block"
+   */
+  tagName?: string;
+  rehypeExpressiveCodeOptions?: RehypeExpressiveCodeOptions;
+}
+/**
+ * A plugin that uses a custom html element. It takes the code from the tag's text content, or from the `code` attribute, and
+ * replaces the tag with a syntax highlighted code block. Use the `lang` attribute to set the language, and the other attributes
+ * for the rest of the expressive-code metadata.
+ */
+declare function HtmlCodeBlockPlugin(options?: HtmlCodeBlockPlugin): Plugin;
+//#endregion
+//#region plugins/collapsible-plugin.d.ts
+interface CollapsiblePluginOptions {
+  /**
+   * The number of code lines that stay visible while a block is collapsed.
+   *
+   * @default 6
+   */
+  previewLines?: number;
+  /**
+   * The label of the toggle button while the block is collapsed.
+   *
+   * @default "Show code"
+   */
+  expandButtonText?: string;
+  /**
+   * The label of the toggle button while the block is expanded.
+   *
+   * @default "Hide code"
+   */
+  collapseButtonText?: string;
+}
+/**
+ * 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.
+ */
+declare function pluginCollapsible(options?: CollapsiblePluginOptions): ExpressiveCodePlugin;
+//#endregion
+//#region plugins/content-plugin/types.d.ts
+/** Customization overrides for a single sidebar node, keyed by its real filesystem path relative to the project root. */
+interface SidebarNodeCustomization {
+  /**
+   * Overrides the auto-generated display title for this node.\
+   * When omitted the title derived from the file/folder name is used.
+   */
+  label?: string;
+  /**
+   * Overrides whether this directory is collapsed by default.\
+   * Has no effect when applied to a link node.\
+   * When omitted the value from `SidebarDirectory.collapsed` is used.
+   */
+  collapsed?: boolean;
+  /**
+   * Controls the position of this node within its parent's item list.\
+   * Nodes with a lower `order` value appear first. Nodes not listed in `customizations` keep their original filesystem position
+   * relative to one another, after all ordered nodes.
+   *
+   * Every listed node gets an `order` from its position among the entries sharing its parent, so entries only need to be declared
+   * in the order they should appear. Set `order` explicitly to override that.
+   *
+   * NOTE: `order` is 1-based.
+   *
+   * ```ts
+   * contentPlugin({
+   *   customizations: {
+   *     "pages/contents/components/button": {}, // first
+   *     "~/contents/components/accordion": {}, // second - using alias `~` for 'pages'
+   *     "~/contents/components/dialog": { order: 1 }, // explicit, now first
+   *     // everything else keeps their original position
+   *   },
+   * });
+   * ```
+   */
+  order?: number;
+  /**
+   * Arbitrary key/value pairs forwarded as HTML attributes on the directory or link layout tag, e.g. `{ "data-badge": "new" }`.
+   *
+   * Values are HTML-escaped before being written into the markup.
+   */
+  data?: Record<string, string>;
+}
+interface ContentPluginOptions {
+  /**
+   * Glob patterns for files to scan when generating the sidebar.
+   *
+   * @example
+   *   ({ include: ["pages/contents/**\/*.{html,md}"] });
+   */
+  include: string[];
+  /**
+   * Glob patterns for files to exclude from sidebar generation.
+   *
+   * @default [ ]
+   */
+  exclude?: string[];
+  /**
+   * The directory segment that acts as the root of the sidebar tree.\
+   * Everything before this segment in a file path is ignored abd everything after it becomes the tree structure.
+   *
+   * Given `baseDirectory: "contents"`, the file `pages/contents/components/accordion/accordion.md` produces the tree path
+   * `components > accordion > accordion`.
+   *
+   * @example
+   *   ({ baseDirectory: "contents" });
+   */
+  baseDirectory: string;
+  /**
+   * Per-node customizations, keyed by the real filesystem path of the file or directory relative to the project root.
+   *
+   * ```ts
+   * contentPlugin({
+   *   customizations: {
+   *     // Override a directory's title and keep it open by default
+   *     "pages/contents/components/accordion": { title: "Accordion", collapsed: false },
+   *
+   *     // Add a badge attribute to a link layout
+   *     "~/contents/components/button/button.md": { data: { "data-badge": "new" } },
+   *   },
+   * });
+   * ```
+   */
+  customizations?: Record<string, SidebarNodeCustomization>;
+  /**
+   * Directory holding the sidebar icons as `<name>.icon.html` files. Aliases are allowed.\
+   * A node whose `data.icon` is `"form"` renders `<icon src="<icons>/form.icon.html">`.\
+   * When omitted, `data.icon` is ignored.
+   *
+   * @example
+   *   ({ icons: "@parts/sidebar-icons" });
+   */
+  icons?: string;
+  /**
+   * Whether pages without a `publish` front matter key are built and listed in the sidebar.\
+   * A page's own `publish: true` / `publish: false` always wins. Unpublished pages are dropped from the build entirely.
+   *
+   * @default true
+   */
+  publish?: boolean;
+  /**
+   * Whether directories start closed. A node's own `collapsed` customization wins.
+   *
+   * @default true
+   */
+  collapsed?: boolean;
+  /** Defines the layout name/path to be used for markdown files. */
+  layouts: {
+    default: string;
+    [key: string]: string;
+  };
+  /** The layout into which the generated sidebar HTML will be injected. */
+  sidebarLayout?: {
+    /**
+     * Path to the layout file.
+     *
+     * @default the theme's `sidebar.part.html`
+     */
+    path?: string;
+    /**
+     * The custom-element tag name used for this layout.
+     *
+     * If omitted, the tag name will be auto extracted from the layout path
+     */
+    tag?: string;
+    /**
+     * The attribute on the layout tag that holds the source path.
+     *
+     * @default "src"
+     */
+    sourceAttribute?: string;
+    /**
+     * The slot name into which the sidebar is inserted.
+     *
+     * @default "sidebar"
+     */
+    slotName?: string;
+  };
+  /** The layout used to render a collapsible directory node. */
+  directoryLayout?: {
+    /**
+     * Path to the directory layout file.
+     *
+     * @default the theme's `directory.part.html`
+     */
+    path?: string;
+    /**
+     * The custom-element tag name used for this layout.
+     *
+     * If omitted, the tag name will be auto extracted from the layout path
+     */
+    tag?: string;
+    /**
+     * The attribute on the layout tag that holds the source path.
+     *
+     * @default "src"
+     */
+    sourceAttribute?: string;
+  };
+  /** The layout used to render a single navigation link. */
+  linkLayout?: {
+    /**
+     * Path to the link layout file.
+     *
+     * @default the theme's `item.part.html`
+     */
+    path?: string;
+    /**
+     * The custom-element tag name used for this layout.
+     *
+     * If omitted, the tag name will be auto extracted from the layout path
+     */
+    tag?: string;
+    /**
+     * The attribute on the layout tag that holds the source path.
+     *
+     * @default "src"
+     */
+    sourceAttribute?: string;
+  };
+}
+//#endregion
+//#region plugins/content-plugin/content-plugin.d.ts
+declare function contentPlugin(options: ContentPluginOptions): Plugin;
+//#endregion
+//#region plugins/content-plugin/helpers.d.ts
+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;
+declare class PersistentCache {
+  private readonly filePath;
+  private readonly entries;
+  private dirty;
+  constructor(name: string);
+  get(key: string): string | undefined;
+  set(key: string, value: string): void;
+  save(): void;
+}
+/** Saves all persistent expressive-code caches once the build is done. */
+declare function ecCachePlugin(): Plugin;
+/**
+ * Drop-in replacement for `[rehypeExpressiveCode, options]` in a rehype plugin list that caches the transformed tree per document
+ * across builds. Unchanged markdown files skip highlighting entirely.
+ *
+ * The cache is production-only. While serving, every edit hashes to a key that is never read again, and nothing is ever written
+ * back because the caches are persisted at the end of a build, so caching there only costs memory and a hash of every tree.
+ */
+declare function cachedRehypeExpressiveCode(this: unknown, options: RehypeExpressiveCodeOptions): (tree: Root, ...rest: unknown[]) => Promise<Root | undefined>;
+//#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
+ * `packages/@staticbolt/docs/assets/` and the folder is copied there. The dev server serves the files where they are.
+ */
+declare function katexFontsPlugin(): Plugin;
+//#endregion
+//#region plugins/llms-plugin.d.ts
+interface LlmsPluginOptions {
+  /** Absolute base URL of the site. Without one the files are not written, since their links have to be absolute. */
+  siteUrl?: string;
+  /** Heading of both files. */
+  title?: string;
+  /** One-line summary quoted under the heading. */
+  summary?: string;
+}
+/**
+ * Writes `llms.txt` and `llms-full.txt`, plus a copy of every page's markdown beside its HTML.
+ *
+ * `llms.txt` links each page's markdown, grouped by top-level folder. `llms-full.txt` inlines every document so a single fetch
+ * needs no link-following. Nothing is curated by hand.
+ */
+declare function llmsPlugin(options?: LlmsPluginOptions): Plugin;
+//#endregion
+//#region plugins/mermaid-fence.d.ts
+/**
+ * Rehype plugin: converts fenced mermaid code blocks into <pre class="mermaid"> elements.
+ *
+ * Input (hast produced by remark-parse + remark-rehype): <pre><code class="language-mermaid">diagram content</code></pre>
+ *
+ * Output: <pre class="mermaid">diagram content</pre>
+ */
+declare const rehypeMermaidFence: Plugin$1<[], Root>;
+//#endregion
+//#region plugins/obsidian-comments.d.ts
+interface RemarkObsidianCommentsOptions {
+  preservePositions?: boolean;
+}
+/**
+ * Remark plugin that removes Obsidian comments.
+ *
+ * Obsidian comment syntax:
+ *
+ * %% inline comment %%
+ *
+ * %% block comment %%
+ */
+declare const remarkObsidianComments: Plugin$1<[RemarkObsidianCommentsOptions?], Root$1>;
+//#endregion
+//#region plugins/obsidian-tags.d.ts
+interface ObsidianTagNode {
+  type: "obsidianTag";
+  value: string;
+  data: {
+    hName: "span";
+    hProperties: {
+      className: string[];
+    };
+    hChildren: Array<{
+      type: "text";
+      value: string;
+    }>;
+  };
+}
+declare module "mdast" {
+  interface PhrasingContentMap {
+    obsidianTag: ObsidianTagNode;
+  }
+}
+/**
+ * Remark plugin that renders Obsidian tags.
+ *
+ * Supported:
+ *
+ * - #tag
+ * - #tag/subtag
+ * - #tag_123
+ * - #tag-name
+ *
+ * Ignored:
+ *
+ * - Escaped tags: #tag
+ * - Code blocks
+ * - Inline code
+ * - Links
+ */
+declare const remarkObsidianTags: Plugin$1<[], Root$1>;
+//#endregion
+//#region plugins/pagefind-plugin.d.ts
+interface PagefindPluginOptions {
+  /**
+   * Glob, relative to the output directory, selecting the pages to index.
+   *
+   * @default "**\/*.html"
+   */
+  glob?: string;
+}
+declare function pagefindPlugin({ glob }?: PagefindPluginOptions): Plugin;
+//#endregion
+//#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 };

package/package.json

@@ -0,0 +1,113 @@
+{
+  "name": "@staticbolt/docs",
+  "version": "0.0.1-beta.0",
+  "description": "Documentation theme for staticbolt: layout parts, styles, and plugins shared by every docs site.",
+  "author": "Ahmed ALABSI",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    "./plugins": {
+      "types": "./lib/index.d.mts",
+      "default": "./lib/plugins.mjs"
+    },
+    "./ec-config": {
+      "types": "./lib/ec.config.d.mts",
+      "default": "./lib/ec-config.mjs"
+    },
+    "./parts/*": "./sources/parts/*",
+    "./styles/*": "./sources/styles/*",
+    "./scripts/*": "./sources/scripts/*",
+    "./assets/*": "./sources/assets/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "sources"
+  ],
+  "engines": {
+    "node": ">=22.18"
+  },
+  "keywords": [
+    "staticbolt",
+    "documentation",
+    "theme"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "watch": "tsdown --watch",
+    "prepack": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint --config ./eslint.config.mjs .",
+    "lint:css": "stylelint \"sources/**/*.{css,html}\" \"docs/sources/**/*.{css,html}\" \"docs/pages/**/*.html\"",
+    "fix": "npm run lint -- --fix; npm run lint:css -- --fix",
+    "publish-docs": "node scripts/publish-docs.ts"
+  },
+  "browserslist": [
+    "last 2 Chrome versions",
+    "last 2 Firefox versions",
+    "last 2 Safari versions",
+    "last 2 Edge versions",
+    "not op_mini all"
+  ],
+  "peerDependencies": {
+    "@staticbolt/core": "beta",
+    "@staticview/ui": ">=1.0.0-beta.0",
+    "mermaid": "^11.15.0"
+  },
+  "peerDependenciesMeta": {
+    "mermaid": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@expressive-code/core": "^0.42.0",
+    "@expressive-code/plugin-collapsible-sections": "^0.42.0",
+    "@expressive-code/plugin-line-numbers": "^0.42.0",
+    "@pagefind/component-ui": "^1.5.2",
+    "@xt0rted/expressive-code-file-icons": "^1.0.0",
+    "expressive-code": "^0.42.0",
+    "hast-util-select": "^6.0.2",
+    "hast-util-to-html": "^9.0.5",
+    "pagefind": "^1.5.2",
+    "rehype-expressive-code": "^0.42.0",
+    "unified": "^11.0.5",
+    "unist-util-visit": "^5.0.0",
+    "yaml": "^2.9.0"
+  },
+  "overrides": {
+    "expressive-code": "^0.42.0",
+    "@expressive-code/core": "^0.42.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@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",
+    "@stylistic/stylelint-config": "^5.0.0",
+    "@trivago/prettier-plugin-sort-imports": "^6.0.2",
+    "@types/hast": "^3.0.5",
+    "@types/node": "^24.0.0",
+    "@types/unist": "^3.0.3",
+    "eslint": "^10.3.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-compat": "^7.0.2",
+    "eslint-plugin-prettier": "^5.5.5",
+    "eslint-plugin-unicorn": "^64.0.0",
+    "globals": "^17.6.0",
+    "mermaid": "^11.15.0",
+    "postcss-html": "^1.8.1",
+    "prettier": "3.8.3",
+    "prettier-plugin-jsdoc": "^1.8.0",
+    "prettier-plugin-markdown-html": "^1.4.1",
+    "stylelint": "^17.11.0",
+    "stylelint-config-recess-order": "^7.7.0",
+    "stylelint-config-standard": "^40.0.0",
+    "stylelint-define-config": "^17.11.0",
+    "stylelint-no-unsupported-browser-features": "^8.1.1",
+    "stylelint-use-logical": "^2.1.3",
+    "tsdown": "^0.22.14",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.59.3"
+  }
+}

package/sources/parts/badge/badge.part.html

@@ -0,0 +1,3 @@
+<span class="badge {{ $data.variant ?? 'note'  }}" title="{{ $data.title ?? '' }}">
+  {{ $data.text ?? $data.variant?.toUpperCase() ?? 'NOTE' }}
+</span>