@pterodoc/core 0.2.0

package/lib/render/images.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Finding and resolving the files a document references.
+ *
+ * Images are found wherever they sit — in a paragraph, behind a reference,
+ * inside raw HTML — because the one place they never sit is at the top level
+ * of a document, which is where an earlier version of this code looked.
+ */
+import { type MarkdownFormat } from './parse';
+/** An image a document points at. */
+export interface ImageReference {
+    /** The URL exactly as written in the source. */
+    url: string;
+    /** Alternative text. */
+    alt: string;
+    /** Title, which becomes a caption. */
+    title?: string | undefined;
+}
+/** Where an image URL actually points. */
+export type ResolvedImage = {
+    kind: 'external';
+    url: string;
+} | {
+    kind: 'file';
+    url: string;
+    file: string;
+} | {
+    kind: 'missing';
+    url: string;
+};
+/** Where to look when resolving a relative or absolute reference. */
+export interface ImageResolutionContext {
+    /** Absolute path of the document's own source file. */
+    sourceAbsolutePath: string;
+    /** The version's content directory. */
+    contentPath: string;
+    /** The localised content directory, preferred when the file exists in both. */
+    contentPathLocalized: string;
+    /** Absolute paths of the site's static directories. */
+    staticDirs: string[];
+    /** The site's base URL, stripped from absolute references when present. */
+    baseUrl: string;
+    /** The Docusaurus site directory, for `@site/` references. */
+    siteDir: string;
+    /** Injected so resolution can be tested without a filesystem. */
+    exists?: (file: string) => boolean;
+}
+/** Every image a document references, including ones behind a reference definition. */
+export declare function collectImages(markdown: string, format?: MarkdownFormat): ImageReference[];
+/**
+ * Work out which file an image URL points at.
+ *
+ * The order matches how Docusaurus itself resolves them: an absolute URL is
+ * left alone, `@site/` is site-relative, a leading slash is served from a
+ * static directory, and anything else is relative to the document — preferring
+ * the localised copy when there is one.
+ */
+export declare function resolveImage(url: string, ctx: ImageResolutionContext): ResolvedImage;
+//# sourceMappingURL=images.d.ts.map

package/lib/render/images.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"images.d.ts","sourceRoot":"","sources":["../../src/render/images.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,SAAS,CAAC;AAI7D,qCAAqC;AACrC,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,wBAAwB;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,sCAAsC;IACtC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAED,0CAA0C;AAC1C,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC3C;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAErC,qEAAqE;AACrE,MAAM,WAAW,sBAAsB;IACrC,uDAAuD;IACvD,kBAAkB,EAAE,MAAM,CAAC;IAC3B,uCAAuC;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,+EAA+E;IAC/E,oBAAoB,EAAE,MAAM,CAAC;IAC7B,uDAAuD;IACvD,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,2EAA2E;IAC3E,OAAO,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;CACpC;AAED,uFAAuF;AACvF,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAE,cAAqB,GAAG,cAAc,EAAE,CAiB/F;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,sBAAsB,GAAG,aAAa,CAkCpF"}

package/lib/render/index.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Rendering a document: parse, resolve, and serialise to blocks.
+ *
+ * This layer is pure. It never reaches the network, never loads Docusaurus and
+ * knows nothing about the target beyond the URLs a resolver hands back.
+ */
+import { type MarkdownFormat } from './parse';
+import { type UnknownPolicy } from './mdx';
+import { type LinkResolver } from './links';
+import type { Theme } from './theme';
+import { IssueCollector } from '../util/issues';
+export { createTheme, DEFAULT_STRINGS } from './theme';
+export type { Theme, Strings, BlockVocabulary } from './theme';
+export { parseMarkdown, detectFormat } from './parse';
+export type { MarkdownFormat } from './parse';
+export { renderBlock, renderBody, createRenderContext } from './renderers';
+export type { RenderContext } from './renderers';
+export { excerptFrom } from './excerpt';
+export { serializeBlock, serializeVoidBlock, serializeAttrs, escapeCode, escapeText, joinBlocks } from './blocks';
+export { renderInline } from './inline';
+export { headingIdFor, createSlugger } from './slug';
+export { resolveReferences } from './references';
+export { rewriteLinks, toInternalPath, isAbsoluteUrl } from './links';
+export type { LinkResolver, ResolvedLink } from './links';
+export { DEFAULT_ADMONITION_KEYWORDS } from './admonitions';
+export { lowerMdx, isTranslatable, KNOWN_COMPONENTS } from './mdx';
+export type { UnknownPolicy } from './mdx';
+export { renderJsxBlock, attribute } from './components';
+export { collectImages, resolveImage } from './images';
+export type { ImageReference, ResolvedImage } from './images';
+export { composePage, DEFAULT_LAYOUT, renderNavigationStub, renderVersionBanner } from './page';
+export type { ComposePageInput, PageLayout, PageLike } from './page';
+/** What to render, and how. */
+export interface RenderDocInput {
+    /** The document body, front matter included or not. */
+    markdown: string;
+    /** Absolute or site-relative path, used for issue positions and format detection. */
+    file?: string;
+    /** Permalink of this document, which relative links resolve against. */
+    permalink: string;
+    /** Which flavour to parse as; detected from `file` when omitted. */
+    format?: MarkdownFormat;
+    /** Class names and strings. */
+    theme: Theme;
+    /** Where each link should point. */
+    resolveLink?: LinkResolver;
+    /** Directive names that mean "admonition" on this site. */
+    admonitionKeywords?: Iterable<string>;
+    /** Whether Docusaurus keeps heading case when generating anchors. */
+    maintainCase?: boolean;
+    /** Drop a leading H1 that repeats the page title. */
+    dedupeTitle?: boolean;
+    /** Uploaded media, keyed by the URL as written in the source. */
+    media?: Map<string, {
+        id: number;
+        url: string;
+    }>;
+    /** What to do about JSX with no translation. */
+    onUnknownJsx?: UnknownPolicy;
+    /** Collector to record issues into; a fresh one is made when omitted. */
+    issues?: IssueCollector;
+}
+/** A rendered document body and what was learned while rendering it. */
+export interface RenderedDoc {
+    /** The block markup. */
+    body: string;
+    /** Tree paths of the pages this document links to. */
+    links: Set<string>;
+    /** Plain text of the first paragraph, for an excerpt. */
+    firstParagraph: string;
+    /** Everything worth telling the user about this document. */
+    issues: IssueCollector;
+}
+/**
+ * Render one document to Gutenberg block markup.
+ */
+export declare function renderDoc(input: RenderDocInput): RenderedDoc;
+/** Build an excerpt from a description, falling back to the opening paragraph. */
+export declare function excerptFor(description: string, firstParagraph: string, max?: number): string;
+//# sourceMappingURL=index.d.ts.map

package/lib/render/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/render/index.ts"],"names":[],"mappings":"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"}