docula 1.7.0 → 1.9.0

package/dist/docula.d.ts

@@ -2,6 +2,48 @@ import fs from 'node:fs';
 import http from 'node:http';
 export { Writr } from 'writr';
 
+declare class DoculaConsole {
+    quiet: boolean;
+    log(message: string): void;
+    error(message: string): void;
+    warn(message: string): void;
+    success(message: string): void;
+    info(message: string): void;
+    step(message: string): void;
+    fileBuilt(filePath: string): void;
+    fileCopied(filePath: string): void;
+    serverLog(method: string, url: string, statusCode: number, durationMs?: number): void;
+    banner(message: string): void;
+    printHelp(): void;
+    parseProcessArgv(argv: string[]): DoculaConsoleProcess;
+    getCommand(argv: string[]): string | undefined;
+    getArguments(argv: string[]): DoculaConsoleArguments;
+}
+type DoculaConsoleProcess = {
+    argv: string[];
+    command: string | undefined;
+    args: DoculaConsoleArguments;
+};
+type DoculaConsoleArguments = {
+    sitePath: string | undefined;
+    templatePath: string | undefined;
+    template: string | undefined;
+    output: string | undefined;
+    watch: boolean;
+    clean: boolean;
+    build: boolean;
+    port: number | undefined;
+    typescript: boolean;
+    javascript: boolean;
+    overwrite: boolean;
+    downloadTarget: string;
+};
+
+type GithubData = {
+    releases: Record<string, unknown>;
+    contributors: Record<string, unknown>;
+};
+
 type ApiSchemaProperty = {
     name: string;
     type: string;
@@ -87,43 +129,97 @@ type ApiSpecData = {
     securitySchemes: ApiSecurityScheme[];
 };
 
-declare class DoculaConsole {
-    log(message: string): void;
-    error(message: string): void;
-    warn(message: string): void;
-    success(message: string): void;
-    info(message: string): void;
-    step(message: string): void;
-    fileBuilt(filePath: string): void;
-    fileCopied(filePath: string): void;
-    serverLog(method: string, url: string, statusCode: number, durationMs?: number): void;
-    banner(message: string): void;
-    printHelp(): void;
-    parseProcessArgv(argv: string[]): DoculaConsoleProcess;
-    getCommand(argv: string[]): string | undefined;
-    getArguments(argv: string[]): DoculaConsoleArguments;
-}
-type DoculaConsoleProcess = {
-    argv: string[];
-    command: string | undefined;
-    args: DoculaConsoleArguments;
+type DoculaChangelogEntry = {
+    title: string;
+    date: string;
+    formattedDate: string;
+    tag?: string;
+    tagClass?: string;
+    slug: string;
+    content: string;
+    generatedHtml: string;
+    preview: string;
+    previewImage?: string;
+    urlPath: string;
+    lastModified: string;
 };
-type DoculaConsoleArguments = {
-    sitePath: string | undefined;
-    templatePath: string | undefined;
-    template: string | undefined;
-    output: string | undefined;
-    watch: boolean;
-    clean: boolean;
-    build: boolean;
-    port: number | undefined;
-    typescript: boolean;
-    javascript: boolean;
+type DoculaData = {
+    siteUrl: string;
+    siteTitle: string;
+    siteDescription: string;
+    sitePath: string;
+    templatePath: string;
+    output: string;
+    githubPath?: string;
+    github?: GithubData;
+    templates?: DoculaTemplates;
+    hasDocuments?: boolean;
+    hasChangelog?: boolean;
+    sections?: DoculaSection[];
+    documents?: DoculaDocument[];
+    sidebarItems?: DoculaSection[];
+    announcement?: string;
+    openApiUrl?: string;
+    hasApi?: boolean;
+    apiSpec?: ApiSpecData;
+    changelogEntries?: DoculaChangelogEntry[];
+    hasReadme?: boolean;
+    themeMode?: string;
+    cookieAuth?: {
+        loginUrl: string;
+        logoutUrl?: string;
+        authCheckUrl?: string;
+        authCheckMethod?: string;
+        authCheckUserPath?: string;
+    };
+    headerLinks?: Array<{
+        label: string;
+        url: string;
+        icon?: string;
+    }>;
+    enableLlmsTxt?: boolean;
+    hasFeed?: boolean;
+    lastModified?: string;
+    baseUrl: string;
+    docsPath: string;
+    apiPath: string;
+    changelogPath: string;
+    docsUrl: string;
+    apiUrl: string;
+    changelogUrl: string;
+    editPageUrl?: string;
+    openGraph?: DoculaOpenGraph;
 };
-
-type GithubData = {
-    releases: Record<string, unknown>;
-    contributors: Record<string, unknown>;
+type DoculaTemplates = {
+    home: string;
+    docPage?: string;
+    api?: string;
+    changelog?: string;
+    changelogEntry?: string;
+};
+type DoculaSection = {
+    name: string;
+    order?: number;
+    path: string;
+    children?: DoculaSection[];
+};
+type DoculaDocument = {
+    title: string;
+    navTitle: string;
+    description: string;
+    order?: number;
+    section?: string;
+    keywords: string[];
+    content: string;
+    markdown: string;
+    generatedHtml: string;
+    documentPath: string;
+    urlPath: string;
+    isRoot: boolean;
+    lastModified: string;
+    ogTitle?: string;
+    ogDescription?: string;
+    ogImage?: string;
 };
 
 type DoculaCookieAuth = {
@@ -138,11 +234,25 @@ type DoculaHeaderLink = {
     url: string;
     icon?: string;
 };
+type DoculaOpenGraph = {
+    title?: string;
+    description?: string;
+    image?: string;
+    url?: string;
+    type?: string;
+    siteName?: string;
+    twitterCard?: string;
+};
 type DoculaCacheOptions = {
     github: {
         ttl: number;
     };
 };
+type DoculaAIOptions = {
+    provider: string;
+    model?: string;
+    apiKey: string;
+};
 declare class DoculaOptions {
     /**
      * Name of the built-in template to use (e.g., "modern", "classic")
@@ -214,6 +324,16 @@ declare class DoculaOptions {
      * site directory's .gitignore file if not already present.
      */
     autoUpdateIgnores: boolean;
+    /**
+     * When true, automatically copies the project root README.md into the site
+     * directory if one does not already exist. The package.json name field is
+     * used to prepend a title heading when the README lacks one.
+     */
+    autoReadme: boolean;
+    /**
+     * When true, suppresses all non-error console output during the build.
+     */
+    quiet: boolean;
     /**
      * Base URL path prefix for all generated paths (e.g., "/docs").
      * When set, all asset and navigation URLs are prefixed with this path.
@@ -232,6 +352,19 @@ declare class DoculaOptions {
      * Output subdirectory and URL segment for changelog pages.
      */
     changelogPath: string;
+    /**
+     * Base URL for "Edit this page" links on documentation pages.
+     * When set, an edit link is shown at the bottom of each doc page.
+     * The document's relative path is appended to this URL.
+     * Example: "https://github.com/owner/repo/edit/main/site/docs"
+     */
+    editPageUrl?: string;
+    /**
+     * OpenGraph meta tags for social sharing. When set, og: and twitter:
+     * meta tags are rendered in the page head. Fields fall back to
+     * siteTitle / siteDescription / siteUrl when omitted.
+     */
+    openGraph?: DoculaOpenGraph;
     /**
      * Cookie-based authentication. When set, shows a Login/Logout button
      * in the header based on whether a JWT cookie is present.
@@ -243,9 +376,11 @@ declare class DoculaOptions {
      */
     headerLinks?: DoculaHeaderLink[];
     /**
-     * File extensions to copy as assets from docs/ and changelog/ directories.
-     * Override in docula.config to customize.
+     * AI-powered metadata enrichment configuration. When set, uses AI to fill
+     * missing OpenGraph and HTML meta tag fields during the build.
+     * Requires provider name and API key. Omit to disable AI enrichment.
      */
+    ai?: DoculaAIOptions;
     /**
      * Cache settings. Controls caching of external data (e.g., GitHub API responses)
      * in the .cache directory within the site path.
@@ -260,103 +395,21 @@ declare class DoculaOptions {
     parseOptions(options: Record<string, any>): void;
 }
 
-type DoculaChangelogEntry = {
-    title: string;
-    date: string;
-    formattedDate: string;
-    tag?: string;
-    tagClass?: string;
-    slug: string;
-    content: string;
-    generatedHtml: string;
-    preview: string;
-    previewImage?: string;
-    urlPath: string;
-    lastModified: string;
-};
-type DoculaData = {
-    siteUrl: string;
-    siteTitle: string;
-    siteDescription: string;
-    sitePath: string;
-    templatePath: string;
-    output: string;
-    githubPath?: string;
-    github?: GithubData;
-    templates?: DoculaTemplates;
-    hasDocuments?: boolean;
-    hasChangelog?: boolean;
-    sections?: DoculaSection[];
-    documents?: DoculaDocument[];
-    sidebarItems?: DoculaSection[];
-    announcement?: string;
-    openApiUrl?: string;
-    hasApi?: boolean;
-    apiSpec?: ApiSpecData;
-    changelogEntries?: DoculaChangelogEntry[];
-    hasReadme?: boolean;
-    themeMode?: string;
-    cookieAuth?: {
-        loginUrl: string;
-        logoutUrl?: string;
-        authCheckUrl?: string;
-        authCheckMethod?: string;
-        authCheckUserPath?: string;
-    };
-    headerLinks?: Array<{
-        label: string;
-        url: string;
-        icon?: string;
-    }>;
-    enableLlmsTxt?: boolean;
-    hasFeed?: boolean;
-    lastModified?: string;
-    baseUrl: string;
-    docsPath: string;
-    apiPath: string;
-    changelogPath: string;
-    docsUrl: string;
-    apiUrl: string;
-    changelogUrl: string;
-};
-type DoculaTemplates = {
-    home: string;
-    docPage?: string;
-    api?: string;
-    changelog?: string;
-    changelogEntry?: string;
-};
-type DoculaSection = {
-    name: string;
-    order?: number;
-    path: string;
-    children?: DoculaSection[];
-};
-type DoculaDocument = {
-    title: string;
-    navTitle: string;
-    description: string;
-    order?: number;
-    section?: string;
-    keywords: string[];
-    content: string;
-    markdown: string;
-    generatedHtml: string;
-    documentPath: string;
-    urlPath: string;
-    isRoot: boolean;
-    lastModified: string;
-};
+type DoculaBuilderOptions = {
+    console?: DoculaConsole;
+} & DoculaOptions;
 declare class DoculaBuilder {
     private readonly _options;
     private readonly _ecto;
     private readonly _console;
     private readonly _hash;
     onReleaseChangelog?: (entries: DoculaChangelogEntry[], console: DoculaConsole) => Promise<DoculaChangelogEntry[]> | DoculaChangelogEntry[];
-    constructor(options?: DoculaOptions, engineOptions?: any);
+    get console(): DoculaConsole;
+    constructor(options?: DoculaBuilderOptions, engineOptions?: any);
     get options(): DoculaOptions;
     build(): Promise<void>;
     validateOptions(options: DoculaOptions): void;
+    autoReadme(): Promise<void>;
     getGithubData(githubPath: string): Promise<GithubData>;
     getTemplates(templatePath: string, hasDocuments: boolean, hasChangelog?: boolean): Promise<DoculaTemplates>;
     getTemplateFile(path: string, name: string): Promise<string | undefined>;
@@ -365,22 +418,16 @@ declare class DoculaBuilder {
     buildFeedPage(data: DoculaData): Promise<void>;
     buildChangelogFeedJson(data: DoculaData): Promise<void>;
     buildChangelogLatestFeedJson(data: DoculaData): Promise<void>;
-    private writeChangelogFeedJson;
     buildLlmsFiles(data: DoculaData): Promise<void>;
-    private generateLlmsIndexContent;
-    private generateLlmsFullContent;
-    private buildUrlPath;
-    private buildAbsoluteSiteUrl;
-    private normalizePathForUrl;
-    private escapeXml;
-    private summarizeMarkdown;
-    private isRemoteUrl;
-    private resolveOpenApiSpecUrl;
-    private resolveLocalOpenApiPath;
-    private getSafeSiteOverrideFileContent;
-    private getSafeLocalOpenApiSpec;
-    private isPathWithinBasePath;
-    private toPosixPath;
+    resolveOpenGraphData(data: DoculaData, pageUrl: string, pageData?: Partial<DoculaDocument> & {
+        previewImage?: string;
+        preview?: string;
+    }): Record<string, string | undefined>;
+    resolveJsonLd(pageType: "home" | "docs" | "api" | "changelog" | "changelog-entry", data: DoculaData, pageUrl: string, pageData?: Partial<DoculaDocument> & {
+        date?: string;
+        preview?: string;
+        previewImage?: string;
+    }): string;
     buildIndexPage(data: DoculaData): Promise<void>;
     buildDocsHomePage(data: DoculaData): Promise<void>;
     buildReadmeSection(data: DoculaData): Promise<string>;
@@ -402,36 +449,6 @@ declare class DoculaBuilder {
     getSections(sitePath: string, doculaOptions: DoculaOptions): DoculaSection[];
     mergeSectionWithOptions(section: DoculaSection, options: DoculaOptions): DoculaSection;
     parseDocumentData(documentPath: string): DoculaDocument;
-    private hasTableOfContents;
-    private directoryContainsMarkdown;
-    private mergeTemplateOverrides;
-    private ensureCacheInGitignore;
-    private getChangedOverrides;
-    private hashFile;
-    private listFilesRecursive;
-    private copyDirectory;
-    private copyPublicFolder;
-    private copyPublicDirectory;
-    private copyDocumentSiblingAssets;
-    private listContentAssets;
-    private loadBuildManifest;
-    private saveBuildManifest;
-    private hashOptions;
-    private hashTemplateDirectory;
-    private loadCachedDocuments;
-    private saveCachedDocuments;
-    private loadCachedChangelog;
-    private saveCachedChangelog;
-    private hashSourceFiles;
-    private recordsEqual;
-    private hasAssetsChanged;
-    /**
-     * Hashes the source file, records it in currentAssets, and returns
-     * whether the copy can be skipped (unchanged from previous build).
-     */
-    private hashAssetAndCheckSkip;
-    private copyDirectoryWithHashing;
-    private copyContentAssets;
 }
 
 declare class Docula {
@@ -440,6 +457,7 @@ declare class Docula {
     private _configFileModule;
     private _server;
     private _watcher;
+    get console(): DoculaConsole;
     /**
      * Initialize the Docula class
      * @param {DoculaOptions} options
@@ -503,6 +521,26 @@ declare class Docula {
      * @returns {void}
      */
     generateInit(sitePath: string, typescript?: boolean): void;
+    /**
+     * Copy the template's variables.css to the site directory.
+     * If the file already exists and overwrite is false, prints an error.
+     * @param {string} sitePath
+     * @param {string} templatePath
+     * @param {string} templateName
+     * @param {boolean} overwrite
+     * @returns {void}
+     */
+    downloadVariables(sitePath: string, templatePath: string, templateName: string, overwrite?: boolean): void;
+    /**
+     * Copy the full template directory to {sitePath}/templates/{outputName}/.
+     * If the directory already exists and overwrite is false, prints an error.
+     * @param {string} sitePath
+     * @param {string} templatePath
+     * @param {string} templateName
+     * @param {boolean} overwrite
+     * @returns {void}
+     */
+    downloadTemplate(sitePath: string, templatePath: string, templateName: string, overwrite?: boolean): void;
     /**
      * Get the version of the package
      * @returns {string}
@@ -530,4 +568,4 @@ declare class Docula {
     serve(options: DoculaOptions): Promise<http.Server>;
 }
 
-export { type DoculaCacheOptions, type DoculaChangelogEntry, DoculaConsole, type DoculaCookieAuth, type DoculaHeaderLink, DoculaOptions, Docula as default };
+export { type DoculaAIOptions, type DoculaCacheOptions, type DoculaChangelogEntry, DoculaConsole, type DoculaCookieAuth, type DoculaHeaderLink, DoculaOptions, Docula as default };