import { PreviewBannerOptions } from './banner.js'; import { PrintoutInfo } from './printout.js'; import { RevealView } from './reveal.js'; import { PtxSourceMap } from './sourcemap.js'; import { RenderTarget } from './target.js'; import { PreviewTheme } from './theme.js'; export interface RenderOptions { /** Path to the root PreTeXt source file (typically source/main.ptx). */ sourcePath: string; /** * Path to the project's *main* source file — the one holding ``. * Defaults to `sourcePath`, which is correct whenever a complete document is * being rendered. * * PreTeXt anchors the publication file's relative asset directories * (`source/directories/@external|@generated`) at this file's directory, and * so does every `document()` the stylesheets make. Rendering a fragment from * a subdirectory therefore needs it: previewing `source/chapters/ch1.ptx` * must still resolve `../generated-assets/` from `source/`, not from * `source/chapters/`. Without it, generated images silently render empty. */ mainSourcePath?: string; /** * Source text to transform instead of reading `sourcePath` from disk. * `sourcePath` is still used to resolve relative xi:includes. Lets callers * render unsaved editor content. */ sourceContent?: string; /** * Directory served to the transform for xi:includes and relative * references. Defaults to the directory containing `sourcePath`. Set it to * the project root when the publication file or includes live outside the * source directory. Files outside this directory are not readable by the * transform. */ projectDir?: string; /** * Path to a publication file. Its settings are respected except * ``, which the preview forces. */ publicationPath?: string; /** * PreTeXt HTML theme to fall back on, inserted into the publication file * used for the build as ``. * * A default, not an override: it applies only when the project's own * publication file names no theme (neither `@theme` nor the deprecated * `@style`/`@shell`), so a project that has chosen one keeps it. Blank is * ignored, and with no publication file at all it themes the synthesized * minimal one. * * Portable builds load `theme-.min.css` from the CDN, so an * unrecognised name renders an unstyled page. The themes the vendored * stylesheets know are default-modern (PreTeXt's own default), denver, * tacoma, salem, greeley and boulder; `custom` additionally needs a locally * compiled stylesheet, which this renderer cannot produce. * * Distinct from {@link RenderOptions.theme}, which is the light/dark mode * *within* whichever css theme is in force. */ cssTheme?: string; /** * Which conversion to run. Defaults to detecting it from the document: a * `` renders as a reveal.js deck, anything else as ordinary HTML. * Set it explicitly to override the detection — most usefully in fragment * mode, where a lone `
` of slides is ambiguous. */ target?: RenderTarget; /** * How a slideshow is presented: "scroll" for the whole deck as one * continuous page (the useful default for authoring), "slides" for reveal's * ordinary one-slide-at-a-time presentation. Ignored for non-slideshows. * * Switching later needs no re-render: `injectRevealBridge` applies the other * value to the HTML already returned. Defaults to "scroll". */ revealView?: RevealView; /** * How large a deck's content is drawn in the scroll view, as a fraction of * its presented size (0.25 to 1, default 1). * * Zooming out shrinks the *text*, not the slide: the slide stays the same * size on screen and more of its content fits inside it. That is what makes * content overflowing a slide readable at all — reveal clips it, so at full * size there is no way to see what was cut off. Ignored when presenting. */ revealZoom?: number; /** * reveal.js theme to fall back on for slideshows whose publication file * names none, inserted as ``. * A default, not an override, exactly like {@link RenderOptions.cssTheme}. * * These are reveal's own themes, not PreTeXt's — "simple" (reveal's default * here), "white", "black", "league", "night", "moon", and so on — and they * are loaded from the CDN by name, so an unrecognised one renders unstyled. * * Note that {@link RenderOptions.theme} does nothing for a slideshow: a deck * loads none of the PreTeXt javascript that implements light/dark mode. A * dark reveal theme is how an embedder gets a dark deck. */ revealTheme?: string; /** * Additional XSLT string parameters, passed as strings (quoted for you). * These are applied last, so they also override the defaults every render * sets — see DEFAULT_STRING_PARAMS. */ stringParams?: Record; /** Directory of PreTeXt XSL stylesheets. Defaults to the vendored copy. */ xslDir?: string; /** * Allow rendering a file that is not a complete PreTeXt document. After * xi:includes are resolved, a fragment (a lone
, , ...) * is wrapped in a minimal complete document — for * / fragments,
otherwise — and built as * normal. Numbering restarts at the fragment and cross-references leaving the * fragment are unresolved; supply `docinfo` to restore the project's custom * LaTeX macros and settings. Complete documents are unaffected. */ fragment?: boolean; /** * A `` element, as an XML string, to place inside the synthesized * wrapper (before the
/) when a fragment is * rendered. Lets a lone fragment keep the project's LaTeX macros, custom * settings, etc., that live in the real main file's docinfo. Only used in * fragment mode; complete documents carry their own docinfo and ignore this. * Takes precedence over `docinfoSourcePath`. */ docinfo?: string; /** * Path to a complete PreTeXt source file (typically the project's main.ptx) * to lift the `` from for fragment mode, when `docinfo` is not * given. The docinfo is resolved through xi:includes — both a top-level * `` and includes nested inside docinfo — * which is how most projects factor it out. Only the docinfo is read, not * the book's chapters. Only used in fragment mode. */ docinfoSourcePath?: string; /** * Path to the complete document (typically the project's main.ptx) that the * fragment being rendered belongs to. Renders the fragment **in place** in * that document instead of standalone, which is what makes its numbering and * its cross-references match the built book. * * A fragment rendered on its own restarts numbering at 1 and cannot see any * `` target outside itself, so previewing section 3.2 shows "Theorem * 1.1" where the book says "Theorem 3.2.1", and references leaving the * section render as PreTeXt's `[cross-reference to target(s) ... missing]` * placeholder. With this set, the document is pruned to a skeleton — every * division, the previewed fragment verbatim, and the divisions holding the * targets it references — and rendered with upstream's `subtree` parameter, * which emits only the previewed division. See skeleton.ts for why that * numbers identically to rendering the whole document, and for the cost. * * The fragment supplies its own content, so unsaved editor text is what gets * rendered; the document on disk supplies only the structure around it. That * matching is by `@xml:id`: a fragment whose root element has none, or whose * id is not in the document, silently falls back to the standalone wrapper. * * Supersedes `docinfoSourcePath`, since the skeleton carries the document's * real ``. Only used in fragment mode; ignored for whole documents. * Optional when `contextSourceContent` is given — see there — but still * used as the virtual base for xi:include resolution and source-map paths * even then, so pass it whenever a real path is available. */ contextSourcePath?: string; /** * The complete document's source text, used instead of reading * `contextSourcePath` from disk. Lets a browser host that already holds the * whole project in memory place a fragment in its document — with * correct numbering and resolved ``s — without a filesystem or * network round trip, and lets the skeleton see *unsaved* sibling * divisions that a read from disk never would. * * `contextSourcePath` becomes optional when this is given, defaulting to * `sourcePath` as the virtual base for resolving the document's own * xi:includes; pass `contextSourcePath` too when a real one is available, * for more useful source-map/error paths. Exactly parallel to * `sourceContent` vs. `sourcePath`. */ contextSourceContent?: string; /** * Tooltip for links whose target is not on the previewed page — the table of * contents, and cross-references reaching outside the fragment. Those cannot * navigate in a single-page preview, so they are stripped of their `@href` * and given this as an explanation (see xrefs.ts). Defaults to * {@link OFF_PAGE_MESSAGE}. * * Whole-document previews link only within the page, so nothing is affected. */ offPageMessage?: string; /** * Also compute a source map: one entry per element, in document order, * mapping the element's @unique-id (its HTML id, when the page emits one) * to the file/line it was authored in — through xi:includes. Powers * editor/preview sync; the rendered page itself is unchanged. See * sourcemap.ts for the id contract with pretext-assembly.xsl. */ sourceMap?: boolean; /** * Expand born-hidden knowls — solutions, hints, answers, and any block the * publication file elects to hide — instead of leaving them collapsed. * Defaults to **true**, because the pages this package renders are previews: * an author editing a solution needs to see it without re-opening it after * every re-render. * * Set it to false for a page meant to be read rather than authored against, * which is then collapsed exactly as a real PreTeXt build would be. Other * `
` (footnotes, image descriptions) are never affected. See * knowls.ts. */ openKnowls?: boolean; /** * Let the embedding app control the preview's light/dark theme. When set, a * small bridge script is injected into the page that applies this value as * the initial theme and then follows `postMessage`s from the embedder (see * `previewThemeMessage` / theme.ts). Omit to leave the page's native * behaviour (localStorage + `prefers-color-scheme`) untouched — the output * is then byte-identical to a render without this option. */ theme?: PreviewTheme; /** * Show a dismissible warning banner across the top of the page explaining * that this is a live preview, not a real build (see banner.ts). Omit to * leave the page without one — the output is then byte-identical to a * render without this option. * * The message is entirely the caller's: what the preview does not honour * reads differently depending on the embedder's own vocabulary (the VS * Code extension's "publication file" vs. pretext.plus's "build * settings"), so there is no default text here. */ previewBanner?: PreviewBannerOptions; /** * Open the page in the print-preview layout for the printout with this HTML * id — paginated to a paper size, headers and footers, workspaces at their * true height (see printout.ts). The ids to choose from come back as * {@link RenderResult.printouts}; {@link RenderResult.rootPrintout} names the * one worth defaulting to. * * Omit for the ordinary layout, which leaves the output byte-identical to a * render without this option. An embedder that toggles the layout should * re-inject over the rendered HTML instead of re-rendering * (`injectPrintPreview`), which is both instant and — because it states the * *off* case explicitly — the only way to leave print preview in a host that * rewrites its document in place. */ printPreview?: string; } export interface RenderResult { /** Complete standalone HTML page (CDN-hosted css/js/MathJax). */ html: string; /** * The conversion that actually ran — as asked for, or as detected. Lets an * embedder tell a deck from a document without re-inspecting the source, * which is what decides whether slideshow-only UI (the view toggle) applies. */ target: RenderTarget; /** Present when RenderOptions.sourceMap was set. */ sourceMap?: PtxSourceMap; /** * The page's printouts — worksheets, handouts, and projects with a workspace * — in document order, each of which can be shown in the print-preview * layout (see printout.ts). Empty when the document has none, which is also * when the page carries no print controls to drive that layout with. */ printouts: PrintoutInfo[]; /** * The printout to open in print preview by default, set when the rendered * document *is* a printout rather than merely containing some — previewing a * `worksheet.ptx`, whose root element is the `` itself. Undefined * otherwise, meaning the page should open in the ordinary layout. */ rootPrintout?: string; /** * Absolute directories that the `external/` and `generated/` URL prefixes in * `html` refer to, resolved from the publication file against the main * source file's directory. Feed these to `rewriteAssetUrls` to point the * page at assets the host can actually serve (see assets.ts). * * Absent for legacy projects that declare neither directory: those emit bare * or `images/`-prefixed URLs that cannot be identified reliably. */ assetDirs?: { external: string; generated: string; }; } /** * Vendored stylesheets shipped with this package. A directory under Node, a * base URL in the browser build — either way, a mount root (see host.ts). */ export declare function defaultXslDir(): string; export declare function isJspiAvailable(): boolean; /** Quote a string as an XPath 1.0 string literal. */ export declare function xpathStringLiteral(value: string): string; /** * Render a PreTeXt document to a single standalone HTML page. * * Every render pays PreTeXt's fixed assembly cost (~15 full-tree passes) plus * per-section rendering: roughly 100ms for a small article, a few seconds for * a 150-section book. Generated assets (latex-image, sageplot, …) are not * produced — those require the Python toolchain. * * Concurrent calls are safe but not parallel: they queue and run one at a * time (see {@link renderQueue}). */ export declare function renderHtml(options: RenderOptions): Promise;