Skip to content

ssg.ts#

View Markdown

Source

35 documented symbols. Read the signatures first, then expand each item for parameters, return types, and examples.

35 symbols 21 functions 9 interfaces 4 variables 1 modules 65 parameters 51 members 21 returns 1 deprecated

Reference#

fnbuildNavItems(markdownFiles: string[], srcDir: string, base: string, extension: string): NavGroup[]Builds navigation items from markdown files, grouped by directory.4 paramsreturns NavGroup[]

Builds navigation items from markdown files, grouped by directory.

Signature

export function buildNavItems(markdownFiles: string[], srcDir: string, base: string, extension: string): NavGroup[]

View source

Parameters

  • markdownFiles string[]
  • srcDir string
  • base string
  • extension string

Returns

NavGroup[]
fnbuildSsg(options: ResolvedOptions, root: string): Promise<SsgBuildResult>Builds all markdown files to static HTML.2 paramsreturns Promise<SsgBuildResult>

Builds all markdown files to static HTML.

Signature

export async function buildSsg(options: ResolvedOptions, root: string): Promise<SsgBuildResult>

View source

Parameters

Returns

Promise<SsgBuildResult>
fnbuildThemeNavItems(sidebar: SidebarItem[], base: string, extension: string): NavGroup[]Builds navigation items from an explicit theme sidebar tree while retaining loc…3 paramsreturns NavGroup[]

Builds navigation items from an explicit theme sidebar tree while retaining locale-map labels for per-page resolution.

Signature

export function buildThemeNavItems(sidebar: SidebarItem[], base: string, extension: string): NavGroup[]

View source

Parameters

Returns

NavGroup[]
fncanonicalPageUrl(context: BuildSsgContext, urlPath: string): string | undefinedAbsolute URL of a page, or undefined when ssg.siteUrl is not set. Built the sam…2 paramsreturns string | undefined

Absolute URL of a page, or undefined when ssg.siteUrl is not set.

Built the same way get_og_image_url builds the image URL next to it, so the canonical link and og:image always agree about where the page lives.

Signature

function canonicalPageUrl(context: BuildSsgContext, urlPath: string): string | undefined

View source

Parameters

  • context BuildSsgContext
  • urlPath string

Returns

string | undefined
fncollectMarkdownFiles(srcDir: string, extensions: readonly string[] = DEFAULT_MARKDOWN_EXTENSIONS): Promise<string[]>Collects all markdown files from the source directory.2 paramsreturns Promise<string[]>

Collects all markdown files from the source directory.

Signature

export async function collectMarkdownFiles(srcDir: string, extensions: readonly string[] = DEFAULT_MARKDOWN_EXTENSIONS): Promise<string[]>

View source

Parameters

  • srcDir string
  • extensions readonly string[]

    optional · default: DEFAULTMARKDOWNEXTENSIONS

Returns

Promise<string[]>
variableconst DEFAULT_HTML_TEMPLATE = "<!-- ox-content default HTML template is Rust-backed -->"Deprecated compatibility export for consumers that imported the former TypeScri…deprecated

Deprecated compatibility export for consumers that imported the former TypeScript SSG template. HTML generation is Rust-backed now.

Signature

export const DEFAULT_HTML_TEMPLATE = "<!-- ox-content default HTML template is Rust-backed -->"

View source

fnextractTitle(content: string, frontmatter: Record<string, unknown>): stringExtracts title from content or frontmatter.2 paramsreturns string

Extracts title from content or frontmatter.

Signature

export function extractTitle(content: string, frontmatter: Record<string, unknown>): string

View source

Parameters

  • content string
  • frontmatter Record<string, unknown>

Returns

string
fnformatTitle(name: string): stringFormats a file/dir name as a title.1 paramreturns string

Formats a file/dir name as a title.

Signature

export function formatTitle(name: string): string

View source

Parameters

  • name string

Returns

string
fngenerateBareHtmlPage(content: string, title: string): stringGenerates bare HTML page (no navigation, no styles).2 paramsreturns string

Generates bare HTML page (no navigation, no styles).

Signature

export function generateBareHtmlPage(content: string, title: string): string

View source

Parameters

  • content string
  • title string

Returns

string
fngenerateBarePage(page: SsgBarePage): stringGenerates a bare HTML page carrying head metadata and injected markup. Bare mod…1 paramreturns string

Generates a bare HTML page carrying head metadata and injected markup.

Bare mode leaves the shell to the consumer, but the metadata here is already computed for the themed page and cannot be recovered afterwards — the generated OG image in particular was only discoverable by guessing at the output directory. A page with none of it set renders exactly what bare mode emitted before, which keeps the no-JS size baseline honest.

Signature

export function generateBarePage(page: SsgBarePage): string

View source

Parameters

Returns

string
fngenerateHtmlPage(pageData: SsgPageData, navGroups: NavGroup[], siteName: string, base: string, ogImage?: string, theme?: ResolvedThemeConfig, locale?: string, availableLocales?: LocaleConfig[], pagination = false, readerChrome: ResolvedReaderChrome = false, breadcrumbs = false, localeSwitcher = false, localePaths?: SsgLocalePath[], a11y: ResolvedA11y = false, team: ResolvedTeamOptions = { enabled: false, members: [] }, pageChrome: boolean = false, breadcrumbRootHref?: string, jsonLd: ResolvedJsonLd = false, siteUrl?: string, headValidation: false | "warn" | "strict" = false, defaultLocale?: string, iconsEnabled = false): Promise<string>Generates HTML page with navigation using Rust NAPI bindings.22 paramsreturns Promise<string>

Generates HTML page with navigation using Rust NAPI bindings.

Signature

export async function generateHtmlPage(pageData: SsgPageData, navGroups: NavGroup[], siteName: string, base: string, ogImage?: string, theme?: ResolvedThemeConfig, locale?: string, availableLocales?: LocaleConfig[], pagination = false, readerChrome: ResolvedReaderChrome = false, breadcrumbs = false, localeSwitcher = false, localePaths?: SsgLocalePath[], a11y: ResolvedA11y = false, team: ResolvedTeamOptions = { enabled: false, members: [] }, pageChrome: boolean = false, breadcrumbRootHref?: string, jsonLd: ResolvedJsonLd = false, siteUrl?: string, headValidation: false | "warn" | "strict" = false, defaultLocale?: string, iconsEnabled = false): Promise<string>

View source

Parameters

  • pageData SsgPageData
  • navGroups NavGroup[]
  • siteName string
  • base string
  • ogImage string

    optional

  • theme ResolvedThemeConfig

    optional

  • locale string

    optional

  • availableLocales LocaleConfig[]

    optional

  • pagination unknown

    optional · default: false

  • readerChrome ResolvedReaderChrome

    optional · default: false

  • breadcrumbs unknown

    optional · default: false

  • localeSwitcher unknown

    optional · default: false

  • localePaths SsgLocalePath[]

    optional

  • a11y ResolvedA11y

    optional · default: false

  • team ResolvedTeamOptions

    optional · default: { enabled: false, members: [] }

  • pageChrome boolean

    optional · default: false

  • breadcrumbRootHref string

    optional

  • jsonLd ResolvedJsonLd

    optional · default: false

  • siteUrl string

    optional

  • headValidation false | "warn" | "strict"

    optional · default: false

  • defaultLocale string

    optional

  • iconsEnabled unknown

    optional · default: false

Returns

Promise<string>
fngetHref(inputPath: string, srcDir: string, base: string, extension: string, routePrefix?: string): stringConverts a markdown file path to an href.5 paramsreturns string

Converts a markdown file path to an href.

Signature

export function getHref(inputPath: string, srcDir: string, base: string, extension: string, routePrefix?: string): string

View source

Parameters

  • inputPath string
  • srcDir string
  • base string
  • extension string
  • routePrefix string

    optional

Returns

string
fngetOutputPath(inputPath: string, srcDir: string, outDir: string, extension: string, routePrefix?: string): stringConverts a markdown file path to its corresponding HTML output path.5 paramsreturns string

Converts a markdown file path to its corresponding HTML output path.

Signature

export function getOutputPath(inputPath: string, srcDir: string, outDir: string, extension: string, routePrefix?: string): string

View source

Parameters

  • inputPath string
  • srcDir string
  • outDir string
  • extension string
  • routePrefix string

    optional

Returns

string
fngetUrlPath(inputPath: string, srcDir: string, routePrefix?: string): stringConverts a markdown file path to a relative URL path.3 paramsreturns string

Converts a markdown file path to a relative URL path.

Signature

export function getUrlPath(inputPath: string, srcDir: string, routePrefix?: string): string

View source

Parameters

  • inputPath string
  • srcDir string
  • routePrefix string

    optional

Returns

string
variableconst localeCodesCache = new WeakMap<LocaleConfig[], string[]>()Per-build cache for the locale-code list passed to getSsgPageLocale. The i18n.l…

Per-build cache for the locale-code list passed to getSsgPageLocale. The i18n.locales reference is stable across a build, so the .map to codes runs once instead of once per page.

Signature

const localeCodesCache = new WeakMap<LocaleConfig[], string[]>()

View source

interfaceNavGroupNavigation group for hierarchical navigation.4 members

Navigation group for hierarchical navigation.

Signature

export interface NavGroup

View source

Members

Properties
NameTypeDescription
variableconst navGroupsForRustCache = new WeakMap<NavGroup[], RustNavGroup[]>()Per-build cache for the Rust-facing nav conversion. navGroups is the same conte…

Per-build cache for the Rust-facing nav conversion. navGroups is the same context.navItems reference for every page in a build, so the deep recursive copy below only needs to run once per build instead of once per page.

Signature

const navGroupsForRustCache = new WeakMap<NavGroup[], RustNavGroup[]>()

View source

fnnormalizeRoutePrefix(value?: string): string | undefinedNormalizes blog / /blog / /blog/ to blog. Empty or unsafe values stay off.1 paramreturns string | undefined

Normalizes blog / /blog / /blog/ to blog. Empty or unsafe values stay off.

Signature

export function normalizeRoutePrefix(value?: string): string | undefined

View source

Parameters

  • value string

    optional

Returns

string | undefined
fnparseSsgPagerOverride(value: unknown): SsgPagerOverride | undefinedParses prev / next frontmatter into a pager override.1 paramreturns SsgPagerOverride | undefined

Parses prev / next frontmatter into a pager override.

Signature

export function parseSsgPagerOverride(value: unknown): SsgPagerOverride | undefined

View source

Parameters

  • value unknown

Returns

SsgPagerOverride | undefined
fnresolveNavigationGroups(navigation: SsgNavigationGroup[] | undefined, base: string, extension: string): NavGroup[] | undefinedResolves manual navigation config to the format used by the built-in SSG render…3 paramsreturns NavGroup[] | undefined

Resolves manual navigation config to the format used by the built-in SSG renderer.

Signature

export function resolveNavigationGroups(navigation: SsgNavigationGroup[] | undefined, base: string, extension: string): NavGroup[] | undefined

View source

Parameters

Returns

NavGroup[] | undefined
fnresolveSsgOptions(ssg: SsgOptions | boolean | undefined): ResolvedSsgOptionsResolves SSG options with defaults.1 paramreturns ResolvedSsgOptions

Resolves SSG options with defaults.

Signature

export function resolveSsgOptions(ssg: SsgOptions | boolean | undefined): ResolvedSsgOptions

View source

Parameters

Returns

ResolvedSsgOptions
interfaceRustLocaleRust-facing locale shape.3 members

Rust-facing locale shape.

Signature

interface RustLocale

View source

Members

Properties
NameTypeDescription
code string
dir string
name string
variableconst rustLocalesCache = new WeakMap<LocaleConfig[], RustLocale[]>()Per-build cache for the Rust-facing locale list. i18n.locales is the same refer…

Per-build cache for the Rust-facing locale list. i18n.locales is the same reference for every page in a build, so this mapping (and the ?? "ltr" default) only runs once per build instead of once per page.

Signature

const rustLocalesCache = new WeakMap<LocaleConfig[], RustLocale[]>()

View source

interfaceRustNavGroupNAPI-facing nav group shape produced from a NavGroup.4 members

NAPI-facing nav group shape produced from a [NavGroup].

Signature

interface RustNavGroup

View source

Members

Properties
NameTypeDescription
collapsedoptional boolean
items SsgNavItem[]
stickyCollapsedoptional boolean
title string
fnshouldGenerateOgImages(options: ResolvedOptions): booleanWhether this build emits one Open Graph image per page. ssg.bare deliberately d…1 paramreturns boolean

Whether this build emits one Open Graph image per page.

ssg.bare deliberately does not turn this off. Bare mode only drops the generated page shell, and bringing your own shell is exactly the case where per-page OG images are still wanted — the images are written to the output tree and the consumer injects the <meta> tags itself. Nothing in the bare HTML references them, because bare output has no <head> to put them in.

Signature

export function shouldGenerateOgImages(options: ResolvedOptions): boolean

View source

Parameters

Returns

boolean
fnsitePathFromUrlPath(urlPath: string): stringTurns an SSG urlPath (guide or /) into a same-origin dest (/guide).1 paramreturns string

Turns an SSG urlPath (guide or /) into a same-origin dest (/guide).

Signature

function sitePathFromUrlPath(urlPath: string): string

View source

Parameters

  • urlPath string

Returns

string
modulessgSSG (Static Site Generation) module for ox-content

SSG (Static Site Generation) module for ox-content

View source

interfaceSsgBarePageHead metadata and injected markup for a bare page.11 members

Head metadata and injected markup for a bare page.

Signature

export interface SsgBarePage

View source

Members

Properties
NameTypeDescription
bodyEndoptional string
bodyStartoptional string
canonicalUrloptional string
content string
descriptionoptional string
diroptional string
headoptional string
langoptional string
ogImageoptional string
siteNameoptional string
title string
interfaceSsgBuildResultResult of an SSG build.3 members

Result of an SSG build.

Signature

export interface SsgBuildResult

View source

Members

Properties
NameTypeDescription
errors string[]
Per-page failures that did not abort the build.
files string[]
Every file written, HTML pages and generated OG images alike.
ogImages Record<string, string>
Generated OG image URL per source file, keyed by absolute input path.

Bare mode renders these into the page itself, but a consumer
post-processing the output had no way to find them short of probing the
output directory for og-image.png.
interfaceSsgEntryPageConfigEntry page configuration for SSG (passed to Rust).2 members

Entry page configuration for SSG (passed to Rust).

Signature

export interface SsgEntryPageConfig

View source

Members

Properties
NameTypeDescription
featuresoptional FeatureConfig[]
herooptional HeroConfig
interfaceSsgNavItemNavigation item for SSG.6 members

Navigation item for SSG.

Signature

export interface SsgNavItem

View source

Members

Properties
NameTypeDescription
childrenoptional SsgNavItem[]
collapsedoptional boolean
href string
path string
stickyCollapsedoptional boolean
title string
interfaceSsgPageDataPage data for SSG.15 members

Page data for SSG.

Signature

export interface SsgPageData

View source

Members

Properties
NameTypeDescription
breadcrumbsoptional boolean
Frontmatter breadcrumbs: false hides the trail on this page.
chromeoptional PageChromeFlags
Per-page chrome flags. Honored only when ssg.pageChrome is on.
content string
contributorsoptional SsgContributor[]
descriptionoptional string
entryPageoptional SsgEntryPageConfig
Entry page configuration (if layout: entry)
frontmatter Record<string, unknown>
href string
lastUpdatedoptional number
markdownSourceoptional string
Companion URL when ssg.markdownSource.copy is on.
nextoptional SsgPagerOverride
Frontmatter override for the next-page link.
path string
prevoptional SsgPagerOverride
Frontmatter override for the previous-page link.
title string
toc TocEntry[]
interfaceSsgPagerOverrideFrontmatter override for one previous/next pager side.3 members

Frontmatter override for one previous/next pager side.

Signature

export interface SsgPagerOverride

View source

Members

Properties
NameTypeDescription
hiddenoptional boolean
hrefoptional string
textoptional string
fntoRustTocEntry(entry: TocEntry): TocEntryConverts a TocEntry tree into the plain shape the Rust binding expects. Hoisted…1 paramreturns TocEntry

Converts a TocEntry tree into the plain shape the Rust binding expects. Hoisted to module scope so it isn't reallocated for every page; the per-page .map over pageData.toc still runs since the TOC is page-specific.

Signature

function toRustTocEntry(entry: TocEntry): TocEntry

View source

Parameters

Returns

TocEntry
fntoThemePageData(pageResult: PageProcessResult, markdownSource?: string): ThemePageDataMaps an internal page result onto the theme renderer's page shape.2 paramsreturns ThemePageData

Maps an internal page result onto the theme renderer's page shape.

Signature

function toThemePageData(pageResult: PageProcessResult, markdownSource?: string): ThemePageData

View source

Parameters

  • pageResult PageProcessResult
  • markdownSource string

    optional

Returns

ThemePageData

Released under the MIT License.

Copyright © 2024-2026 ubugeeei