SST Docs Core

Core runtime for the Shadow Shard Tools documentation stack. This package ships shared themes, configuration helpers, navigation utilities, typed content models, and browser-friendly helpers used by the site and generator projects.

What�s inside

• configs: Tailwind-friendly theme wiring plus code-language metadata (CODE_LANGUAGE_CONFIG).
• data: File-system/HTTP drivers for loading doc versions, trees, and item payloads (loadVersions, loadVersionData, buildTree, etc.).
• themes: Prebuilt StyleTheme presets (currently default) used by the Tailwind bridge.
• types: Source-of-truth TypeScript contracts for doc content, theme structures, and provider interfaces.
• utilities: DOM, validation, string, and file helpers shared by the site and exporters (e.g. slugify, withBasePath, isValidImageUrl).

Install

npm install @shadow-shard-tools/docs-core

Basic usage

import {
  defaultTheme,
  loadVersions,
  loadVersionData,
  slugify,
  type Content,
  type Version,
} from "@shadow-shard-tools/docs-core";

// Or import a focused module:
import { CODE_LANGUAGE_CONFIG } from "@shadow-shard-tools/docs-core/configs/index.js";

Everything ships as native ESM with TypeScript declarations in dist/. CommonJS consumers can require the same subpaths via the conditional exports (built into dist/cjs).

API map (common imports)

| Domain | Import from | Common exports | | --- | --- | --- | | Configs | @shadow-shard-tools/docs-core/configs | loadSstDocsConfig, buildClientVisibleConfig, serializeClientConfigForBrowser, exposeClientConfig, readClientConfig, CODE_LANGUAGE_CONFIG | | Data | @shadow-shard-tools/docs-core/data | loadVersions, loadVersionData, buildTree, FsDataProvider, HttpDataProvider | | Themes | @shadow-shard-tools/docs-core/themes | defaultTheme, getThemePreset, AVAILABLE_THEME_PRESET_NAMES, StyleTheme | | Utilities | @shadow-shard-tools/docs-core/utilities | slugify, withBasePath, normalizeSystemPath, isValidImageUrl, createLogger | | Types | @shadow-shard-tools/docs-core/types | Content, Version, StyleTheme, SstDocsConfigFile, ResolvedSstDocsConfig, ClientVisibleSstDocsConfig |

Quickstart recipes

Load config and expose client config

import {
  buildClientVisibleConfig,
  exposeClientConfig,
  loadSstDocsConfig,
  readClientConfig,
  serializeClientConfigForBrowser,
} from "@shadow-shard-tools/docs-core/configs";

const config = await loadSstDocsConfig();
const clientConfig = buildClientVisibleConfig(config);

// Server-side: embed into HTML (pretty for readability while debugging)
const clientScript = serializeClientConfigForBrowser(clientConfig, { pretty: true });
// -> <script>{clientScript}</script>

// Browser-side: attach and read from the global name (__SST_DOCS_CONFIG__ by default)
exposeClientConfig(clientConfig);
const cfg = readClientConfig();

Load docs from FS/HTTP and build a tree

import path from "node:path";
import {
  FsDataProvider,
  HttpDataProvider,
  loadVersionData,
  loadVersions,
} from "@shadow-shard-tools/docs-core/data";

// Local filesystem
const fsProvider = new FsDataProvider();
const dataRoot = path.resolve("./public/SST-Docs/data");
const versions = await loadVersions(fsProvider, dataRoot);
const versionRoot = `${dataRoot}/${versions[0]?.version ?? "current"}`;
const { tree, items, standaloneDocs } = await loadVersionData(fsProvider, versionRoot);

// Remote HTTP (e.g., CDN-hosted data)
const httpProvider = new HttpDataProvider();
const remoteRoot = "https://cdn.example.com/SST-Docs/data";
const remoteVersions = await loadVersions(httpProvider, remoteRoot);
const remoteVersionRoot = `${remoteRoot}/${remoteVersions[0]?.version ?? "current"}`;
const { tree: remoteTree } = await loadVersionData(httpProvider, remoteVersionRoot);

Config example

Create sst-docs.config.json in your project root. Set PRODUCT_VERSIONING to true when your data root contains product subfolders (see below); leave it false to use the single-product layout.

{
  "FS_DATA_PATH": "./public/SST-Docs/data",
  "PRODUCT_VERSIONING": true,
  "HEADER_BRANDING": {
    "logoText": "SST Docs"
  },
  "HTML_GENERATOR_SETTINGS": {
    "OUTPUT_DIRECTORY": "./dist/html",
    "THEME": "default",
    "SEPARATE_BUILD_FOR_HTML_GENERATOR": false
  }
}

When product versioning is enabled, place a products.json file at the data root and nest per-product versions under each product folder, e.g. public/SST-Docs/data/Product_1/versions.json and public/SST-Docs/data/Product_1/v1.0/index.json.

Load and expose a browser-friendly subset:

import { loadSstDocsConfig, buildClientVisibleConfig, serializeClientConfigForBrowser } from "@shadow-shard-tools/docs-core/configs";

const config = await loadSstDocsConfig();
const clientConfig = buildClientVisibleConfig(config);
const script = serializeClientConfigForBrowser(clientConfig); // inject into HTML to populate window.__SST_DOCS_CONFIG__

Development

npm install
npm run build

tsc compiles everything under src/ into dist/ with source and declaration maps. Build before publishing or updating dependents so the published artifacts stay in sync.