@jaamd/jaad 0.11.0 → 1.0.0-rc.1

package/src/docs/integration.ts

@@ -0,0 +1,249 @@
+import type { JaadResolvedConfig } from '../config.ts'
+import type { DocsRoot } from './config.ts'
+import type { AstroIntegration } from 'astro'
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { prefixedLocales } from '../site/locales.ts'
+import { normaliseBasePath } from '../site/urls.ts'
+import { docsRoots } from './config.ts'
+import { rehypeDocLinks, satteriDocLinks } from './link-plugins.ts'
+import { getDocCollectionId, splitDocLocale } from './model/ids.ts'
+import { buildDocsTree, type DocsSource } from './model/tree.ts'
+import { docsPageHref, type DocsUrlOptions } from './urls.ts'
+
+type SetupParams = Parameters<NonNullable<AstroIntegration['hooks']['astro:config:setup']>>[0]
+
+const DOCS_FRAME_ID = 'virtual:jaad/docs-frame'
+const RESOLVED_DOCS_FRAME = '\0' + DOCS_FRAME_ID
+
+/** The frame around every docs page: the project's own, or JAAD's. */
+function docsFrameVirtualPlugin(docsFrame: () => string) {
+    return {
+        name: 'jaad:docs-frame',
+        resolveId: (source: string) => (source === DOCS_FRAME_ID ? RESOLVED_DOCS_FRAME : null),
+        load: (id: string) =>
+            id === RESOLVED_DOCS_FRAME ? `export { default } from ${JSON.stringify(docsFrame())};` : null,
+    }
+}
+
+/** A named url that redirects to its page's canonical one. */
+export interface DocsAlias {
+    locale?: string
+    slug: string
+}
+
+export interface IntegrationState {
+    deploymentBase: string
+    aliases: DocsAlias[]
+    docsFrame: string
+}
+
+const INDEX_PAGE_NAMES = ['index.astro', 'index.md', 'index.mdx', 'index.html', 'index.js', 'index.ts']
+
+const NOT_FOUND_PAGE_NAMES = ['404.astro', '404.md', '404.mdx', '404.html', '404.js', '404.ts']
+
+/** A plugin this integration registered on an earlier setup run. */
+const isDocLinks = (plugin: unknown): boolean =>
+    (typeof plugin === 'function' || (typeof plugin === 'object' && plugin !== null)) &&
+    ['jaad-doc-links', 'jaadDocLinks'].includes((plugin as { name?: string }).name ?? '')
+
+const routeEntrypoint = (file: string) => fileURLToPath(new URL(`./routes/${file}`, import.meta.url))
+
+export function shouldInjectNotFound(docsBase: string, srcDir: URL): boolean {
+    return docsBase === '' && !NOT_FOUND_PAGE_NAMES.some((name) => existsSync(new URL(`pages/${name}`, srcDir)))
+}
+
+/** The two fields that move the first page of the docs or of a section. */
+function readFrontmatter(source: string): { order?: number; draft?: boolean } {
+    const block = /^---\r?\n([\s\S]*?)\r?\n---/.exec(source)
+    if (!block) return {}
+
+    const order = /^order:\s*(-?\d+)\s*$/m.exec(block[1])
+    const draft = /^draft:\s*(true|false)\s*$/m.exec(block[1])
+    return {
+        order: order ? Number(order[1]) : undefined,
+        draft: draft ? draft[1] === 'true' : undefined,
+    }
+}
+
+/** The aliases of every locale. The content collection is not available this
+ *  early, so the pages are read from disk. */
+export function findAliases(roots: DocsRoot[], locales: string[] = []): DocsAlias[] {
+    const sources: DocsSource[] = []
+
+    const visit = (root: DocsRoot, current: string) => {
+        for (const entry of readdirSync(current, { withFileTypes: true }).toSorted((a, b) =>
+            a.name.localeCompare(b.name),
+        )) {
+            const file = join(current, entry.name)
+            if (entry.isDirectory()) visit(root, file)
+            else if (entry.isFile() && entry.name.endsWith('.md')) {
+                const front = readFrontmatter(readFileSync(file, 'utf8'))
+                if (front.draft) continue
+
+                const { locale, id } = splitDocLocale(getDocCollectionId(relative(root.dir, file)), locales)
+                sources.push({
+                    id,
+                    path: id,
+                    locale: locale ?? undefined,
+                    section: root.section,
+                    data: { order: front.order },
+                })
+            }
+        }
+    }
+    for (const root of roots) {
+        if (existsSync(root.dir)) visit(root, root.dir)
+    }
+
+    const sections = roots.flatMap((root) => root.section ?? [])
+    return (locales.length > 0 ? locales : [undefined]).flatMap((locale) => {
+        // The slugs are all that is read: the urls need no mount.
+        const tree = buildDocsTree(
+            sources.filter((source) => source.locale === locale),
+            { sections, urls: { docsBase: '' } },
+        )
+        return tree.pages.flatMap((page) => page.aliases.map((slug) => ({ locale, slug })))
+    })
+}
+
+export function getInjectedRoutes(docsBase: string, locales: string[] = []): [string, string][] {
+    // `[...slug]` already absorbs "it/guide" and "it". Only the two fixed
+    // endpoints need a route of their own, and `[locale]` hands them the code.
+    const perLocale: [string, string][] =
+        locales.length > 0
+            ? [
+                  [`${docsBase}/[locale]/search-index.json`, 'search-index-locale.json.ts'],
+                  [`${docsBase}/[locale]/llms.txt`, 'llms-locale.txt.ts'],
+              ]
+            : []
+
+    return [
+        [docsBase, 'docs-index.astro'],
+        [`${docsBase}/search-index.json`, 'search-index.json.ts'],
+        [`${docsBase}/llms.txt`, 'llms.txt.ts'],
+        ...perLocale,
+        [`${docsBase}/[...slug]`, 'docs-slug.astro'],
+        [`${docsBase}/[...slug].md`, 'docs-slug.md.ts'],
+    ]
+}
+
+export function createIntegrationState(): IntegrationState {
+    return {
+        deploymentBase: '',
+        aliases: [],
+        docsFrame: fileURLToPath(new URL('./layouts/DefaultDocsFrame.astro', import.meta.url)),
+    }
+}
+
+/** Routes, the docs frame, the 404 page, aliases and the link plugins. */
+export function setupDocs(
+    { config: astroConfig, updateConfig, injectRoute, addWatchFile, logger }: SetupParams,
+    config: JaadResolvedConfig,
+    state: IntegrationState,
+    discoverAliases: boolean,
+): void {
+    updateConfig({ vite: { plugins: [docsFrameVirtualPlugin(() => state.docsFrame)] } })
+
+    for (const [pattern, entrypoint] of getInjectedRoutes(
+        config.docs.base,
+        prefixedLocales(config.locales, config.defaultLocale),
+    )) {
+        injectRoute({
+            pattern,
+            entrypoint: routeEntrypoint(entrypoint),
+            prerender: true,
+        })
+    }
+
+    const customDocsFrame = new URL('jaad/DocsFrame.astro', astroConfig.srcDir)
+    if (existsSync(customDocsFrame)) {
+        state.docsFrame = fileURLToPath(customDocsFrame)
+        addWatchFile(customDocsFrame)
+    }
+
+    if (shouldInjectNotFound(config.docs.base, astroConfig.srcDir)) {
+        injectRoute({
+            pattern: '/404',
+            entrypoint: routeEntrypoint('404.astro'),
+            prerender: true,
+        })
+    }
+
+    const root = fileURLToPath(astroConfig.root)
+    const roots = docsRoots(config.docs, root)
+    const locales = config.locales.map((locale) => locale.code)
+
+    const missing = roots.filter(({ dir }) => !existsSync(dir))
+    for (const { dir } of missing) {
+        logger.warn(
+            `${relative(root, dir)} does not exist, so it adds no pages. ` +
+                'Create it, or point docsDir or the section at your markdown.',
+        )
+    }
+    if (discoverAliases && missing.length < roots.length) {
+        state.aliases = findAliases(roots, locales)
+    }
+    for (const { dir } of roots) addWatchFile(pathToFileURL(dir))
+
+    const links = {
+        roots,
+        locales,
+        urls: (locale?: string): DocsUrlOptions => ({
+            docsBase: config.docs.base,
+            deploymentBase: normaliseBasePath(astroConfig.base),
+            locale,
+            defaultLocale: config.defaultLocale,
+        }),
+    }
+    // New arrays: a shared processor would stack duplicates across setup runs.
+    const processor = astroConfig.markdown.processor as {
+        name: string
+        options: { hastPlugins?: unknown[]; rehypePlugins?: unknown[] }
+    }
+    if (processor.name === 'satteri') {
+        processor.options.hastPlugins = [
+            ...(processor.options.hastPlugins ?? []).filter((plugin) => !isDocLinks(plugin)),
+            satteriDocLinks(links),
+        ]
+    } else if (processor.name === 'unified') {
+        processor.options.rehypePlugins = [
+            ...(processor.options.rehypePlugins ?? []).filter((plugin) => !isDocLinks(plugin)),
+            rehypeDocLinks(links),
+        ]
+    }
+
+    if (config.docs.base === '') {
+        const ownIndex = INDEX_PAGE_NAMES.find((name) => existsSync(new URL(`pages/${name}`, astroConfig.srcDir)))
+        if (ownIndex) {
+            logger.warn(
+                `${ownIndex} owns the site root while JAAD docs are mounted there. ` +
+                    'Set routeBase: "/docs" to keep a landing page and mount the docs below it.',
+            )
+        }
+    }
+}
+
+const withoutTrailingSlash = (value: string) => (value.length > 1 ? value.replace(/\/$/, '') : value)
+
+export function createSitemapFilter(
+    docsBase: string,
+    state: Pick<IntegrationState, 'deploymentBase' | 'aliases'>,
+    defaultLocale?: string,
+): (page: string) => boolean {
+    return (page) => {
+        if (state.aliases.length === 0) return true
+
+        const pathname = withoutTrailingSlash(new URL(page).pathname)
+        return !state.aliases.some((alias) => {
+            const urls: DocsUrlOptions = {
+                docsBase,
+                deploymentBase: state.deploymentBase,
+                locale: alias.locale,
+                defaultLocale,
+            }
+            return pathname === withoutTrailingSlash(docsPageHref(alias.slug, urls))
+        })
+    }
+}

package/src/{layouts → docs/layouts}/DefaultDocsFrame.astro

@@ -10,13 +10,12 @@ type Props = DocsFrameProps
     <div class="docs-container">
         <slot name="sidebar" />
 
-        <div class="docs-main docs-main-gutters">
+        <div class="docs-main">
             <main class="docs-page-main">
                 <slot name="mobile-navigation" />
 
                 <article>
                     <slot name="breadcrumbs" />
-                    <slot name="page-actions" />
                     <slot name="content" />
                 </article>
 
@@ -24,8 +23,11 @@ type Props = DocsFrameProps
             </main>
         </div>
 
-        <slot name="table-of-contents" />
-    </div>
+        <aside class="docs-sidebar-right jaad-sidebar">
+            <slot name="table-of-contents" />
+            <slot name="page-actions" />
+        </aside>
 
-    <slot name="footer" />
+        <slot name="footer" />
+    </div>
 </div>

package/src/{layouts → docs/layouts}/Docs.astro

@@ -1,53 +1,53 @@
 ---
-import type { DocsEntry, DocsHeadings } from '../@types/docs.ts'
 import type { DocsFrameProps } from '../advanced.ts'
+import type { DocsSourceEntry } from '../collection.ts'
+import type { DocsPage } from '../model/tree.ts'
 import type { DocsNavigation } from '../navigation.ts'
+import type { DocsHeading } from '../types.ts'
 import { ClientRouter } from 'astro:transitions'
 import config from 'virtual:jaad/config'
 import DocsFrame from 'virtual:jaad/docs-frame'
+import Footer from '../../site/components/Footer.astro'
+import Head from '../../site/components/Head.astro'
+import Header from '../../site/components/Header.astro'
+import { DEFAULT_LOCALE, LOCALES } from '../../site/runtime.ts'
 import { getLocaleAlternates } from '../collection.ts'
-import DocsSidebarLeft from '../components/docs/DocsSidebarLeft.astro'
-import StructuredData from '../components/docs/StructuredData.astro'
-import TableOfContents from '../components/docs/TableOfContents.astro'
-import Footer from '../components/Footer.astro'
-import Head from '../components/Head.astro'
-import Header from '../components/Header.astro'
-import { DEFAULT_LOCALE, LOCALES } from '../docs-config.ts'
-import { docTitle, docTranslationKey, extractDescription, getCleanSlug, routedId } from '../utils/docs.ts'
-import '../../dist/jaad.css'
+import DocsSidebarLeft from '../components/DocsSidebarLeft.astro'
+import StructuredData from '../components/StructuredData.astro'
+import TableOfContents from '../components/TableOfContents.astro'
+import { pageDescription } from '../model/rendered.ts'
+import { docsUrls } from '../runtime.ts'
+import { docsPageHref } from '../urls.ts'
+import '../../../dist/jaad.css'
 import '../styles/docs.css'
 import '../styles/jaamd.css'
-import '@jaamd/jaamd/styles.css'
+import '@jaamd/astro/styles.css'
 import 'virtual:jaad/theme.css'
 import 'virtual:jaad/bridge.css'
 import 'virtual:jaad/user.css'
 import 'virtual:jaad/tailwind.css'
 
 interface Props {
+    /** The `<title>` before the site name. Left out on the opening page. */
     title?: string
-    chapter?: string
-    entry?: DocsEntry
-    headings?: DocsHeadings[]
+    page: DocsPage<DocsSourceEntry>
+    headings?: DocsHeading[]
     navigation: DocsNavigation
 }
 
-const { title, chapter, entry, headings = [], navigation } = Astro.props
+const { title, page, headings = [], navigation } = Astro.props
 
 const pageTitle = title ? `${title} | ${config.title}` : config.title
 
-// The opening page gets no `title`; resolve it from the entry.
-const entryTitle = entry ? docTitle(entry) : (title ?? '')
+const description =
+    page.data.description ?? pageDescription(page.source.rendered, page.title) ?? config.description ?? config.title
 
-const pageDescription =
-    entry?.data.description ??
-    (entry ? extractDescription(entry.body || '', entryTitle) : null) ??
-    config.description ??
-    config.title
-
-const locale = entry?.locale ?? DEFAULT_LOCALE
+const locale = page.locale ?? DEFAULT_LOCALE
 const language = LOCALES.find((known) => known.code === locale)?.tag ?? config.lang
 
-const switcherAlternates = await getLocaleAlternates(entry ? docTranslationKey(entry) : '')
+const indexUrl = docsPageHref('search-index.json', docsUrls(locale))
+
+const switcherAlternates = await getLocaleAlternates(page.translationKey)
 
 // x-default is a landing place, so it takes the fallback when this page has no
 // translation into the default locale.
@@ -64,11 +64,12 @@ const alternates = switcherAlternates
 
 const frameProps: DocsFrameProps = {
     page: {
-        id: entry?.id ?? '',
-        slug: entry ? getCleanSlug(routedId(entry)) : '',
-        title: entryTitle,
-        chapter,
-        data: entry?.data ?? { draft: false, keywords: [] },
+        id: page.id,
+        slug: page.slug,
+        title: page.title,
+        section: page.section,
+        chapter: page.chapter,
+        data: page.data,
     },
     headings,
     navigation,
@@ -80,22 +81,22 @@ const frameProps: DocsFrameProps = {
     <head>
         <Head
             title={pageTitle}
-            description={pageDescription}
-            keywords={entry?.data.keywords}
-            author={entry?.data.author}
-            image={entry?.data.ogImage}
-            modified={entry?.data.lastUpdated}
+            description={description}
+            keywords={page.data.keywords}
+            author={page.data.author}
+            image={page.data.ogImage}
+            modified={page.data.lastUpdated}
             language={language}
             {alternates}
             {xDefault}
         />
         <StructuredData
-            title={entryTitle || config.title}
-            description={pageDescription}
-            chapter={chapter}
-            keywords={entry?.data.keywords}
-            author={entry?.data.author}
-            modified={entry?.data.lastUpdated}
+            title={page.title || config.title}
+            description={description}
+            chapter={page.chapter}
+            keywords={page.data.keywords}
+            author={page.data.author}
+            modified={page.data.lastUpdated}
             {language}
             {locale}
         />
@@ -103,8 +104,8 @@ const frameProps: DocsFrameProps = {
     </head>
     <body data-docs class="jaad-body">
         <DocsFrame {...frameProps}>
-            <Header slot="header" inDocs {locale} alternates={switcherAlternates} />
-            <DocsSidebarLeft slot="sidebar" sections={navigation.sections} {locale} />
+            <Header slot="header" {locale} alternates={switcherAlternates} search={{ indexUrl, prominent: true }} />
+            <DocsSidebarLeft slot="sidebar" groups={navigation.groups} {locale} />
             <slot name="mobile-navigation" slot="mobile-navigation" />
             <slot name="breadcrumbs" slot="breadcrumbs" />
             <slot name="page-actions" slot="page-actions" />

package/src/docs/layouts/Page.astro

@@ -0,0 +1,18 @@
+---
+import type { ComponentProps } from 'astro/types'
+import Shell from '../../site/layouts/Shell.astro'
+import { DEFAULT_LOCALE } from '../../site/runtime.ts'
+import { getLocaleAlternates } from '../collection.ts'
+import { docsUrls } from '../runtime.ts'
+import { docsPageHref } from '../urls.ts'
+
+type Props = Omit<ComponentProps<typeof Shell>, 'header'>
+
+// A page of the project's own has no translations: offer each locale's opener.
+const alternates = await getLocaleAlternates('')
+const indexUrl = docsPageHref('search-index.json', docsUrls(DEFAULT_LOCALE))
+---
+
+<Shell {...Astro.props} header={{ alternates, search: { indexUrl } }}>
+    <slot />
+</Shell>

package/src/docs/link-plugins.ts

@@ -0,0 +1,52 @@
+import type { DocLinkContext } from './links.ts'
+import { fileURLToPath } from 'node:url'
+import { resolveDocLink } from './links.ts'
+
+interface HastNode {
+    type: string
+    tagName?: string
+    properties?: Record<string, unknown>
+    children?: HastNode[]
+}
+
+/** rehype: rewrites relative links to markdown files into page urls. */
+export function rehypeDocLinks(context: DocLinkContext) {
+    return function jaadDocLinks() {
+        return (tree: HastNode, file: { path?: string }) => {
+            const from = file.path
+            if (!from) return
+
+            const visit = (node: HastNode) => {
+                const href = node.tagName === 'a' ? node.properties?.href : undefined
+                if (typeof href === 'string') {
+                    const resolved = resolveDocLink(href, from, context)
+                    if (resolved) node.properties!.href = resolved
+                }
+                node.children?.forEach(visit)
+            }
+            visit(tree)
+        }
+    }
+}
+
+interface SatteriContext {
+    fileURL: URL | undefined
+    setProperty(node: HastNode, name: string, value: string): void
+}
+
+/** Sätteri: rewrites relative links to markdown files into page urls. */
+export function satteriDocLinks(context: DocLinkContext) {
+    return {
+        name: 'jaad-doc-links',
+        element: {
+            filter: ['a'],
+            visit(node: HastNode, ctx: SatteriContext) {
+                const href = node.properties?.href
+                if (typeof href !== 'string' || !ctx.fileURL) return
+
+                const resolved = resolveDocLink(href, fileURLToPath(ctx.fileURL), context)
+                if (resolved) ctx.setProperty(node, 'href', resolved)
+            },
+        },
+    }
+}

package/src/docs/links.ts

@@ -0,0 +1,42 @@
+import type { DocsRoot } from './config.ts'
+import type { DocsUrlOptions } from './urls.ts'
+import { existsSync } from 'node:fs'
+import { dirname, relative, resolve, sep } from 'node:path'
+import { getDocCollectionId, namedSlug, splitDocLocale } from './model/ids.ts'
+import { docsPageHref } from './urls.ts'
+
+export interface DocLinkContext {
+    roots: DocsRoot[]
+    locales: string[]
+    urls: (locale?: string) => DocsUrlOptions
+}
+
+/**
+ * The url of the page a relative link to a markdown file points at, or null
+ * when the link is not one: absolute, external, or to a file outside the docs.
+ */
+export function resolveDocLink(href: string, fromFile: string, context: DocLinkContext): string | null {
+    if (/^([a-z][a-z\d+.-]*:|\/|#)/i.test(href)) return null
+
+    const [path, hash = ''] = href.split('#', 2)
+    if (!path.endsWith('.md')) return null
+
+    let decoded: string
+    try {
+        decoded = decodeURI(path)
+    } catch {
+        return null
+    }
+
+    const target = resolve(dirname(fromFile), decoded)
+    const root = context.roots.find(({ dir }) => target.startsWith(dir + sep))
+    if (!root) return null
+
+    if (!existsSync(target)) {
+        throw new Error(`jaad: ${fromFile} links to ${href}, which does not exist`)
+    }
+
+    const { locale, id } = splitDocLocale(getDocCollectionId(relative(root.dir, target)), context.locales)
+    const slug = namedSlug(id, root.section)
+    return docsPageHref(slug, context.urls(locale ?? undefined)) + (hash ? `#${hash}` : '')
+}

package/src/{locale-tree.ts → docs/locale-tree.ts}

@@ -1,6 +1,6 @@
 import { existsSync, readdirSync } from 'node:fs'
 import { join } from 'node:path'
-import { isLocale } from './locales.ts'
+import { isLocale } from '../site/locales.ts'
 
 function hasMarkdown(dir: string): boolean {
     return readdirSync(dir, { withFileTypes: true }).some((entry) =>

package/src/docs/model/ids.ts

@@ -0,0 +1,87 @@
+import { slug as githubSlug } from 'github-slugger'
+import { ucfirst } from '../../site/helpers.ts'
+
+/** A numeric order prefix, e.g. "01-" or "123-". */
+const NUMBERED_PREFIX_RE = /^(\d+)-(.+)$/
+
+/** What a page's path says: its file order, its chapter and its own name. */
+export interface ParsedDocPath {
+    /** The file name without its order prefix. */
+    slug: string
+    order: number
+    /** The chapter directory without its order prefix. */
+    chapter?: string
+    orderChapter?: number
+}
+
+export function parseDocPath(path: string): ParsedDocPath {
+    const parts = path.split('/')
+    const name = NUMBERED_PREFIX_RE.exec(parts[parts.length - 1])
+    const directory = parts.length >= 2 ? parts[parts.length - 2] : undefined
+    const chapter = directory ? NUMBERED_PREFIX_RE.exec(directory) : null
+
+    return {
+        slug: name ? name[2] : parts[parts.length - 1],
+        order: name ? parseInt(name[1], 10) : 999,
+        chapter: chapter ? chapter[2] : directory,
+        orderChapter: chapter ? parseInt(chapter[1], 10) : undefined,
+    }
+}
+
+/** "01-chapter/02-section" → "chapter/section" */
+export function getCleanSlug(id: string): string {
+    return id
+        .split('/')
+        .map((part) => part.replace(NUMBERED_PREFIX_RE, '$2'))
+        .join('/')
+}
+
+/** A page's named url below the docs mount: its section, then its clean path. */
+export function namedSlug(path: string, section?: string): string {
+    const slug = getCleanSlug(path)
+    return section ? `${section}/${slug}` : slug
+}
+
+/** "it/02-guides/01-setup" becomes locale "it" and "02-guides/01-setup". */
+export function splitDocLocale(id: string, locales: string[]): { locale: string | null; id: string } {
+    const slash = id.indexOf('/')
+    if (slash === -1) return { locale: null, id }
+
+    const first = id.slice(0, slash)
+    if (!locales.includes(first)) return { locale: null, id }
+    return { locale: first, id: id.slice(slash + 1) }
+}
+
+/** Match the ids produced by Astro's glob loader, independently of the OS. */
+export function getDocCollectionId(filePath: string): string {
+    return filePath
+        .replace(/\.md$/, '')
+        .split(/[\\/]/)
+        .map((part) => githubSlug(part))
+        .join('/')
+}
+
+/** The collection holding the docs, or the pages of one section. */
+export function collectionName(section?: string): string {
+    return section ? `docsPages-${section}` : 'docsPages'
+}
+
+/** The id of a file given relative to its docs directory: its locale, the
+ *  section that directory is, then its path. */
+export function collectionIdFor(filePath: string, section: string | undefined, locales: string[]): string {
+    const { locale, id } = splitDocLocale(getDocCollectionId(filePath), locales)
+    return [locale, section, id].filter(Boolean).join('/')
+}
+
+/** Decodes percent-escapes, so "detail_%26_summary" → "Detail & Summary". */
+export function slugToTitle(slug: string): string {
+    return slug
+        .split(/[-_]+/)
+        .map((word) => ucfirst(decodeURIComponent(word)))
+        .join(' ')
+}
+
+export function formatChapterTitle(chapter: string | undefined): string | null {
+    if (!chapter) return null
+    return slugToTitle(chapter)
+}