API

ogygia/content/markdown

The markdown pipeline — fences, transformers, staged plugins.

On this page

Auto-generated from the package’s own .d.ts on every build — signatures, JSDoc, and examples straight from the source.

import { … } from 'ogygia/content/markdown';

Exports diff_markers · escape_svelte · highlight · infostring · inline_markers · normalize_shiki · ogygiaPreprocess · ogygiaPresetPreprocess · parseFrontmatter · remarkHeadingId · remarkHeadings · remarkLinks · slash_meta · slugify · wrap_html · extensions · CodeOptions · Fence · FrontmatterResult · Heading · InlineMarkerOptions · MarkdownOptions · MarkdownShikiOptions · MarkdownThemePair · MetaParser · RemarkHeadingsOptions · StagedPlugin · Variant · VariantGenerator

`diff_markers`

function

function diff_markers(): ShikiTransformer;

`escape_svelte`

function

Escape for embedding inside a Svelte {@html \…`}` template (mdsvex highlighter).

function escape_svelte(html: string): string;

`highlight`

function

Highlight a code string. Uses the config from the last configure_shiki / {@link markdown } call, or pass options explicitly.

function highlight(code: string, lang?: string, options?: MarkdownShikiOptions,
rawMeta?: string): Promise<string>;

`infostring`

function

The default fence-meta parser: reads CHROME meta from the infostring after the language — key="value" and key=value pairs (title="app.js" / file="app.js", copy=false, link=false). Booleans coerce; title mirrors to file (the filename-label key).

It DELIBERATELY does not touch line-highlight syntax ({1-3,5}, /word/, // [!code …]) — that is a Shiki transformer's job (@shikijs/transformers, transformerMetaHighlight), fed by the raw infostring which the pipeline passes straight to codeToHtml. Zero config: ```js title="x" just works.

function infostring(): MetaParser;

`inline_markers`

function

function inline_markers(options?: InlineMarkerOptions): ShikiTransformer;

`normalize_shiki`

function

function normalize_shiki(options?: MarkdownShikiOptions): ResolvedShiki;

`ogygiaPreprocess`

function

ogygia's svelte preprocessor — mdsvex (Shiki fences + heading ids) with the island transform composed after it, so islands authored inside .svx / .md become real islands.

Called with no args it reads its config from ogygia({ content: { markdown } }), so all config lives in the one plugin and the svelte config only needs the value-free call:

extensions: ogygia.extensions(),
preprocess: [vitePreprocess(), ...ogygia.preprocess()],

Pass options directly to override (ogygiaPreprocess({ themes })). Synchronous: mdsvex (an optional peer) is loaded and constructed lazily on first use via {@link load_mdsvex }, so importing this module — and calling this — never requires mdsvex to be installed.

function ogygiaPreprocess(options?: MarkdownOptions): PreprocessorGroup;

`ogygiaPresetPreprocess`

function

The preset-aware preprocessor ogygia.preprocess() mounts. Without content presets it IS the plain ogygiaPreprocess (zero regression). With presets, it dispatches per file: an unmarked file compiles through the default pipeline; a ?og_preset= variant (marker-tagged by the plugin) compiles through a lazily-built pipeline whose config is the preset's bag merged over the defaults — depth-2, per setting key. One file under two presets = two variants = two independent compiles; caches stay distinct because each pipeline's config signature differs.

function ogygiaPresetPreprocess(): PreprocessorGroup;

`parseFrontmatter`

function

Minimal --- YAML frontmatter split. Body is unused for glob catalogs (Content comes from the Vite module); data is schema-validated.

function parseFrontmatter(source: string): FrontmatterResult;

`remarkHeadingId`

function

Pandoc-style ## Title {#custom-id} → heading id="custom-id". Runs before mdsvex escapes {…} for Svelte.

function remarkHeadingId(): (tree: {
  type?: string;
  children?: unknown[];
  data?: Record<string, unknown>;
}) => void;

`remarkHeadings`

function

function remarkHeadings(options?: RemarkHeadingsOptions): (tree: MdNode, file: {
  data: Record<string, unknown>;
}) => void;

`remarkLinks`

function

function remarkLinks(): (tree: MdNode, file: {
  data: Record<string, unknown>;
}) => void;

`slash_meta`

function

svelte.dev's magic-comment fence meta: /// file: App.svelte, /// copy: false, /// link: false (also  for Svelte, ### file: …). Reads the keys into meta and STRIPS the comment lines from source so they never render. file also sets meta.file (filename label).

function slash_meta(): MetaParser;

`slugify`

function

GitHub-ish slug: lowercase, strip punctuation, spaces → dashes.

function slugify(text: string): string;

`wrap_html`

function

function wrap_html(html: string, wrapperClass: string | false): string;

`extensions`

const

Default file extensions handled by {@link markdown }.

const extensions: readonly [".svx", ".md"]

`CodeOptions`

type

The CODE fence pipeline config — one bag for the whole fence dialect. Core knows CONTRACTS, not features: each slot takes imported adapter VALUES, never feature flags. (Stages meta and variants arrive in later steps; transformers is the Shiki decoration contract.)

type CodeOptions = {
  transformers?: ShikiTransformer[];
  meta?: MetaParser[];
  variants?: VariantGenerator[];
  cacheSalt?: string;
};

`Fence`

type

One code fence, as the pipeline sees it. raw_meta is the untouched infostring after the lang.

type Fence = {
  lang: string;
  raw_meta: string;
  meta: Record<string, unknown>;
  source: string;
};

`FrontmatterResult`

type

type FrontmatterResult = {
  data: Record<string, unknown>;
  body: string;
};

`Heading`

type

A heading pulled from the markdown pass (h2–h4). Powers on-page TOCs; rides markdown meta.

type Heading = {
  depth: 2 | 3 | 4;
  id: string;
  text: string;
};

`InlineMarkerOptions`

type

type InlineMarkerOptions = {
  classes?: {
    add?: string;
    remove?: string;
  };
};

`MarkdownOptions`

type

type MarkdownOptions = MarkdownShikiOptions & {
  headingIds?: boolean;
  headings?: boolean | RemarkHeadingsOptions;
  overrides?: boolean | {
    tags?: string[];
  };
  containers?: boolean;
  tabs?: boolean;
  headingAnchors?: boolean;
  codeIds?: boolean;
  remark?: Array<StagedPlugin>;
  rehype?: Array<StagedPlugin>;
  code?: CodeOptions;
  extensions?: string[];
  layout?: MdsvexOptions['layout'];
  region?: boolean;
};

`MarkdownShikiOptions`

type

type MarkdownShikiOptions = {
  themes?: MarkdownThemePair;
  langs?: string[];
  wrapperClass?: string | false;
  defaultColor?: string | false;
  transformers?: ShikiTransformer[];
};

`MarkdownThemePair`

type

type MarkdownThemePair = {
  light: MarkdownThemeInput;
  dark: MarkdownThemeInput;
};

`MetaParser`

type

Enriches meta / rewrites source. Parsers LAYER (run in order; later wins on a meta collision).

type MetaParser = (fence: Fence) => Fence;

`RemarkHeadingsOptions`

type

type RemarkHeadingsOptions = {
  minDepth?: 2 | 3 | 4;
  maxDepth?: 2 | 3 | 4;
};

`StagedPlugin`

type

A prose/rehype chain entry, optionally staged Vite-style: a plain entry runs in the default slot; { enforce: 'pre', plugin } runs before the built-in passes ('post' = the default, explicit).

type StagedPlugin = UnifiedEntry | {
  enforce: 'pre' | 'post';
  plugin: UnifiedEntry;
  cache_key?: () => string;
  dependencies?: (filename: string) => string[];
};

`Variant`

type

One rendered version of a fence: a switcher label, a stable value, and its (re-langed) fence.

type Variant = {
  label: string;
  value: string;
  fence: Fence;
};

`VariantGenerator`

type

Turns one authored fence into N labeled variants + the {@link Preference } its switcher binds to, or null when the fence isn't this generator's (the race continues). throw = "mine and broken" (a named build error). cache_key folds an external identity (e.g. the TS version) into the fence cache.

type VariantGenerator = {
  pref: PreferenceSpec;
  generate: (fence: Fence) => Variant[] | null;
  cache_key?: string;
  ready?: () => Promise<void>;
};