import { type BookPlacement } from '../book-target.js';
export interface Doc {
    text: string;
    title: string;
    filename: string;
    path: string;
    pin?: 'top' | 'bottom';
    /** sub-order within a pin bucket (lower first); section docs use this */
    order?: number;
    /** parent doc name or slug — groups this doc into a nav section */
    parent?: string;
    /**
     * Not published AT ALL — absent from docs.json, from the generated pages, from every
     * book, and from llms.txt. For incomplete chapters and working notes.
     *
     * Inherited by descendants: hiding a section hides what is inside it. A child cannot
     * un-hide itself, because accidentally publishing one chapter of a withheld section is
     * the failure worth preventing.
     *
     * (`draft: true` in YAML frontmatter sets this.) Previously this only removed a doc
     * from the nav and books while leaving its full text in docs.json AND giving it a
     * pre-rendered public page — so "drafts don't ship" was false twice over.
     */
    hidden?: boolean;
    /**
     * This doc is the site root (`/`) instead of README, which then gets `/readme/`. Set by the
     * site's `home` option, or by the doc's own `{"home": true}`. At most one doc may be home.
     */
    home?: boolean;
    /**
     * `false` drops the site's header bar on this page, as `layout: "full-screen"` drops the
     * nav: for an app page with its own toolbar, above all as an installed PWA, where the bar
     * is the only thing between the app and the whole screen. The page links back to the docs
     * its own way; the builder adds nothing. Unset means the header shows.
     */
    header?: boolean;
    /**
     * Which book(s) this doc binds into. A name, a list of names, or `'none'` to keep it
     * on the site and out of every book. Unset means the default book; `'default'` names
     * the default book so a list can include it — `["default", "appendices"]` binds the
     * doc into both, which is how shared front matter or a glossary works.
     *
     * Inherited down the `parent` chain, nearest declaration winning outright (a list
     * replaces an inherited value rather than adding to it) — so you mark a section, and an
     * individual chapter can still divert, join several volumes, or opt out.
     */
    book?: string | string[];
    /**
     * Where this doc sits in a particular volume, when that differs from the site:
     * `{ "language": { "parent": "for-programmers", "order": 20 } }`. Keyed by `book` name
     * (`"default"` for the main volume); each entry may set `parent`, `order`, `pin` and
     * `title`. Naming a volume here also binds the doc into it. The site nav is unaffected.
     */
    placement?: Record<string, BookPlacement>;
    /**
     * The text a book binds, set by the build only where `{"only": …}` conditional text made
     * it differ from `text` (which is always what the site shows). Never author this.
     */
    bookText?: string;
    /**
     * Opt this page out of the reading column.
     *
     * Prose wants a measure — 44em is roughly the line length people read comfortably, and it is
     * the default for good reason. But a doc site is not only prose: a demo, a dashboard, a wide
     * table or a canvas is *worse* squeezed into a column, and having to choose one habit for the
     * whole site is what makes people build a second site.
     *
     * `'full-width'` keeps the nav and the chrome and drops the measure. Set it the same way as
     * `pin` or `order`: the JSON metadata block in code or markdown, or `layout:` in YAML
     * frontmatter. Unset means the reading column, so nothing changes for a corpus that does not
     * ask.
     *
     * `'full-screen'` drops the measure AND puts the nav away, so the page is the whole viewport —
     * for a demo, a canvas, an embedded app. It needed `<tosi-sidenav navHidden>` to exist first:
     * the nav width and the nav's own `display` are both INLINE styles, so no stylesheet could
     * reach them from out here.
     */
    layout?: 'full-width' | 'full-screen';
    headTitle?: string;
    description?: string;
    keywords?: string | string[];
    image?: string;
    noindex?: boolean;
    bakes?: Array<[string, {
        dialect: string;
        js: string;
    }]>;
    author?: string;
    date?: string;
}
/**
 * Directories a doc site should not publish, excluded by default (tosijs-ui#153).
 *
 * `reviews/` is where this ecosystem's practices tell you to write pre-release review
 * reports — documents that name adopters and carry BLOCK verdicts. A `docPaths: ['docs']`
 * took the directory wholesale and published thirteen of them. Nothing failed; the way you
 * found out was reading the output file list after a successful build.
 *
 * An explicit entry in `docPaths` still wins, so publishing one deliberately remains possible.
 */
export declare const DEFAULT_DOC_IGNORES: string[];
export interface ExtractDocsOptions {
    paths: string[];
    ignore?: string[];
    output?: string;
    /** the doc served at `/` instead of README, by slug or filename (the site's `home`) */
    home?: string;
}
/**
 * The title a markdown file implies, when nothing declares one.
 *
 * It used to be `content.split('\n')[0]` — literally line one. A file that opens with its
 * metadata block, which is the documented way to set `order` or `parent`:
 *
 * ```md
 * <!--{ "order": 2 }-->
 *
 * # Migration
 * ```
 *
 * published under the title `<!--{ "order": 2 }-->` — while `order` itself parsed correctly, so
 * the metadata visibly worked and the title visibly did not (tosijs-ui#100). Hit while adding
 * `CHANGELOG.md` and `Migration.md` to a doc site, which is exactly when a leading metadata
 * comment is most natural.
 *
 * Skips blank lines and leading HTML comments — including multi-line ones, since a metadata
 * block can wrap — and returns the first line with content, heading markers and backticks
 * stripped as before.
 */
export declare function titleFromMarkdown(content: string): string;
/**
 * Parse & strip a leading YAML frontmatter block (`---\n…\n---`). Every prose
 * toolchain (Jekyll/Hugo/Astro/Obsidian/Pandoc) uses it, so authors paste it in;
 * without this the `---` was rendered as content (and became the doc title).
 *
 * A minimal, dependency-free subset: `key: value` lines mapped onto doc metadata
 * (`title`, `order`→number, `author`, `date`, `draft: true`→hidden). Only strips
 * when the block actually parses as ≥1 key/value pair, so a genuine leading `---`
 * horizontal rule is left alone. Frontmatter wins over the JSON-comment metadata.
 */
export declare function parseFrontmatter(content: string): {
    data: Partial<Doc>;
    body: string;
};
export declare const SCRAPED_SOURCE_EXTENSIONS: string[];
export declare function extractDocs(options: ExtractDocsOptions): Doc[];
export declare function saveDocsJSON(docs: Doc[], outputPath: string): void;