Types

Public TypeScript types exported from sdocs.

import type {
  SdocsConfig,
  ResolvedSdocsConfig,
  DocEntry,
  SdocMeta,
  ComponentData,
  ParsedProp,
  ParsedMethod,
  ParsedState,
  ParsedCssProp,
  ExtractedSnippet,
  TocHeading,
} from 'sdocs';

Fields that can be absent are typed as required-but-nullable (string | null), not TypeScript-optional — check for null, not for the key's presence.

SdocsConfig

The user-facing config type — every field optional. This is the shape sdocs.config.js is checked against; see the configuration reference for what each field means and what it defaults to.

interface SdocsConfig {
  include?: string | string[];
  port?: number;
  open?: boolean;
  css?: string | Record<string, string>;
  static?: string;
  title?: string;
  logo?: string | false;
  favicon?: string;
  sections?: ({ slug: string; title?: string; order?: string[] } | { type: 'divider' })[];
  home?: string;
  routing?: 'history' | 'hash';
  base?: string;
  mcp?: boolean;
  components?: string | string[];
  axes?: { id: string; label?: string; values: string[] }[];
  scale?: { min?: number; max?: number; default?: number; step?: number; var?: string; label?: string };
  content?: {
    doc?: ContentSizing & { toc?: boolean; contentX?: string };
    page?: ContentSizing & { contentX?: string };
    showcase?: ContentSizing & { direction?: string; gap?: string; background?: string; minHeight?: string; contentX?: string; contentY?: string };
    layout?: ContentSizing & { background?: string; minHeight?: string };
  };
}

Sidebar order lives on the section that owns it — sections[].order — rather than in a config key of its own. There is no top-level sidebar option.

ResolvedSdocsConfig

What the loader returns: the same shape with every default applied, so nothing downstream has to re-derive one. include is always an array, css is null rather than absent when unset, and content carries a complete sizing block for all four entity kinds.

SdocMeta

The shape of the meta object exported from a .sdoc file.

interface SdocMeta {
  component?: unknown;
  title: string;
  description?: string;
  args?: Record<string, unknown>;
  settings?: Record<string, unknown>;
}

Only title is required. For component docs, component is also effectively required (needed for prop extraction and controls).

DocEntry

Each discovered .sdoc file becomes one DocEntry. These are what virtual:sdocs exports as docs.

interface DocEntry {
  kind: 'component' | 'page' | 'layout';
  filePath: string;                     // absolute path to the .sdoc file
  componentPath: string | null;         // absolute path to the documented component
  meta: SdocMeta;
  componentData: ComponentData | null;  // for kind === 'component'
  snippets: ExtractedSnippet[];         // Default + named
  highlightedSource: string | null;     // highlighted component source HTML
  toc?: TocHeading[];                   // for kind === 'page'
}

interface TocHeading {
  text: string;
  level: number;
  id: string;
}

ComponentData

The extracted public API of a Svelte component.

interface ComponentData {
  props: ParsedProp[];
  methods: ParsedMethod[];
  state: ParsedState[];
  cssProps: ParsedCssProp[];
}

Events and snippets are not separate arrays — they live in props, tagged by ParsedProp.category, and are split out at render time.

ParsedProp

interface ParsedProp {
  name: string;
  type: string | null;
  default: string | null;
  description: string | null;
  required: boolean;
  category: 'prop' | 'event' | 'snippet';
}

ParsedMethod

interface ParsedMethod {
  name: string;
  params: string;              // parameter list source
  returnType: string | null;
  description: string | null;
}

ParsedState

interface ParsedState {
  name: string;
  type: string | null;
  description: string | null;
}

ParsedCssProp

interface ParsedCssProp {
  name: string;             // e.g. "--bg"
  type: string | null;      // from @cssvar, e.g. "color" or "dimension"
  default: string | null;
  description: string | null;
}

ExtractedSnippet

interface ExtractedSnippet {
  name: string;             // preview label, example title, or 'Content'
  slug: string;             // URL-safe id, unique within the entity
  role: 'preview' | 'example' | 'content';
  body: string;             // block body source
  highlightedHtml?: string; // highlighted body HTML
  previewUrl?: string;      // preview iframe URL (added by the virtual module)
}

See also

• Prop extraction — what gets populated into these types
• Embedded usage — consuming virtual:sdocs