@forsakringskassan/docs-generator 1.24.0

package/dist/markdown.d.ts

@@ -0,0 +1,243 @@
+/**
+ * @public
+ */
+export declare function createMarkdownRenderer(options: MarkdownOptions): MarkdownRenderer;
+
+/**
+ * @public
+ */
+declare interface Document_2 {
+    /** unique identifier for this document */
+    id: string;
+    /** human-readable pseudo-identifier for this document (consider it unique but there is no contraint enforcing this) */
+    name: string;
+    /** alternative names this document can be referenced by */
+    alias: string[];
+    /** true if document should be visible in menu and similar sources */
+    visible: boolean;
+    attributes: NormalizedDocumentAttributes;
+    body: string;
+    /** Document outline (i.e. the heading structure) */
+    outline: DocumentOutline;
+    /** format of body */
+    format: "markdown" | "html" | "json";
+    tags: string[];
+    template: string;
+    fileInfo: FileInfo;
+}
+export { Document_2 as Document }
+
+/**
+ * @public
+ */
+export declare type DocumentBadge = "success" | "error" | "info";
+
+/**
+ * Represents a document outline (i.e. the heading structure).
+ *
+ * @public
+ */
+export declare type DocumentOutline = DocumentOutlineEntry[];
+
+/**
+ * Represents a single heading (and its subheadings) in a document outline.
+ *
+ * @public
+ */
+export declare interface DocumentOutlineEntry {
+    /** Heading title */
+    title: string;
+    /** Heading rank, e.g. `##` (h2) is rank 2 */
+    rank: number;
+    /** Heading anchor (id or name attribute) */
+    anchor: string;
+    /** Subheadings */
+    subheadings: DocumentOutline;
+}
+
+/**
+ * Represents an example needing compilation.
+ *
+ * The actual compilation is deferred and can be executed by calling
+ * `compile(..)`.
+ *
+ * @public
+ */
+export declare interface ExampleCompiledResult {
+    /** Sourcecode of this example (original or imported) */
+    source: string;
+    /** Language of sourcecode (original or imported) */
+    language: string;
+    /** Associated comments from markdown */
+    comments: string[];
+    /** Tags */
+    tags: string[];
+    /** HTML markup to inject into document */
+    markup: string;
+    /** asset filename */
+    output: string;
+    /** enables running example live in the browser */
+    runtime: true;
+    /** task data for compiler */
+    task: ExampleCompileTask;
+}
+
+/**
+ * Task data shared between main process and worker.
+ *
+ * @public
+ */
+export declare interface ExampleCompileTask {
+    /** output filename (without path) */
+    outputFile: string;
+    /** example sourcecode */
+    sourcecode: string;
+    /** original path to file containing example source */
+    sourceFile: string;
+    /** absolute path to document containing this example */
+    parent: string;
+}
+
+/**
+ * @public
+ */
+export declare type ExampleResult = ExampleCompiledResult | ExampleStaticResult;
+
+/**
+ * Represents an example with static code only, e.g plain HTML.
+ *
+ * @public
+ */
+export declare interface ExampleStaticResult {
+    /** Sourcecode of this example (original or imported) */
+    source: string;
+    /** Language of sourcecode (original or imported) */
+    language: string;
+    /** Associated comments from markdown */
+    comments: string[];
+    /** Tags */
+    tags: string[];
+    /** HTML markup to inject into document */
+    markup: string;
+    /** asset filename */
+    output: null;
+    /** enables/disables running example live in the browser */
+    runtime: boolean;
+}
+
+/**
+ * @public
+ */
+export declare interface FileInfo {
+    /** path relative to configured base */
+    path: string;
+    /** filename without extension */
+    name: string;
+    /** path relative to project root */
+    fullPath: string;
+    /** output filename or `false` to disable writing result to a file */
+    outputName: string | false;
+}
+
+/**
+ * Options for [[createMarkdownRenderer]].
+ *
+ * @public
+ */
+export declare interface MarkdownOptions {
+    /** List of all available documents */
+    readonly docs: Document_2[];
+    /** Callback for adding a static resource */
+    addResource(dst: string, src: string): void;
+    /** Callback when an example should be generated */
+    generateExample(options: {
+        source: string;
+        language: string;
+        filename: string;
+        tags: string[];
+    }): ExampleResult;
+    /**
+     * Handle error which can be recovered from.
+     *
+     * If a string is returned it replaces the intended content but otherwise
+     * continues rendering.
+     *
+     * If the exception is rethrown it will cause the renderer to bail out.
+     *
+     * @param error - The error to be handled.
+     * @returns A replacement string or rethrows error.
+     */
+    handleSoftError(error: SoftErrorType): string;
+}
+
+/**
+ * Markdown renderer.
+ *
+ * @public
+ */
+export declare interface MarkdownRenderer {
+    /**
+     * Render given markdown content to HTML
+     *
+     * @param doc - Document metadata.
+     * @param content - Markdown content to render.
+     * @returns HTML rendered from markdown content.
+     */
+    render(doc: Document_2, content: string): string;
+}
+
+/**
+ * @public
+ */
+export declare interface NormalizedDocumentAttributes {
+    title?: string;
+    layout?: string;
+    status?: string;
+    badge?: DocumentBadge;
+    component?: string[];
+    href?: string;
+    /** normalized sortorder (defaults to Infinity) */
+    sortorder: number;
+}
+
+/**
+ * A soft error than can be recovered from.
+ *
+ * @public
+ */
+export declare class SoftError<T extends SoftErrorCode> extends Error {
+    readonly code: T;
+    readonly details: SoftErrorDetails[T];
+    /* Excluded from this release type: __constructor */
+}
+
+/**
+ * @public
+ */
+export declare type SoftErrorCode = keyof SoftErrorDetails;
+
+/**
+ * @public
+ */
+export declare interface SoftErrorDetails {
+    ELINKTARGET: {
+        key: string;
+        hash: string;
+        title: string;
+    };
+    ELINKFORMAT: undefined;
+    EINCLUDETARGET: {
+        id: string;
+    };
+    EINCLUDERECURSION: undefined;
+    ETAGMISSING: undefined;
+}
+
+/**
+ * @public
+ */
+export declare type SoftErrorType = {
+    [T in SoftErrorCode]: SoftError<T>;
+}[SoftErrorCode];
+
+export { }