Skip to content

Instantly share code, notes, and snippets.

@sophistifunk

sophistifunk/antora-modules.d.ts

Created August 29, 2019 07:50
Show Gist options
  • Save sophistifunk/7fd33bfeca88cd297d1cdbc23dd0e24d to your computer and use it in GitHub Desktop.
Save sophistifunk/7fd33bfeca88cd297d1cdbc23dd0e24d to your computer and use it in GitHub Desktop.
Download ZIP

Revisions

  1. sophistifunk created this gist Aug 29, 2019.
    469 changes: 469 additions & 0 deletions antora-modules.d.ts
    View file
    Original file line number Diff line number Diff line change
    @@ -0,0 +1,469 @@
    /*
    # TODO:
    - [ ] Not sure about "@antora/types" because there's no physical module for that. Maybe there should be a
    types-only package within the antora lerna tree?
    - [ ] Get Dan to vet names for types, and fill in any props I've missed - particularly AntoraFile
    - [ ] Get Dan to confirm what's optional vs nullable vs required
    - [ ] Do we want to use namespaces for things like the objects within a Playbook?
    Or just code the structures in?
    Or just declare at module level?
    - [ ] Make sure each module decl only imports types it actually needs
    - [ ] Remove all the unknowns, ofc
    */

    declare module "@antora/types" {
    import VinylFile from "vinyl";

    interface AntoraFile {
    asciidoc?: AntoraFile.AsciidocMetadata;
    mediaType?: string | false;
    nav?: { index: number };
    out?: AntoraFile.Destination;
    pub?: AntoraFile.Destination;
    rel?: AntoraFile;
    src?: AntoraFile.Source;
    type?: FileType;
    }

    interface AntoraVinylFile extends AntoraFile, VinylFile {
    _isVinyl: true;
    }

    namespace AntoraFile {
    interface AsciidocMetadata {
    doctitle?: string;
    attributes: AsciidocAttribs;
    }

    interface Destination {
    path?: string;
    basename?: string;
    dirname?: string;
    moduleRootPath?: string;
    rootPath?: string;
    canonicalUrl?: string;
    url?: string;
    }

    interface Source {
    abspath?: string;
    basename: string;
    component: string;
    editUrl?: string;
    extname?: string;
    family: FileFamily;
    mediaType: string | false;
    module: string;
    moduleRootPath?: string;
    origin?: GitOrigin;
    path?: string;
    relative: string;
    stem: string;
    version: string;
    }
    }

    interface GitOrigin {
    branch: string;
    editUrlPattern: string;
    startPath: string;
    type: string;
    url: string;
    worktree?: boolean;
    }

    type FileFamily = "alias" | "attachment" | "example" | "image" | "nav" | "page" | "partial";

    type FileType = "static" | "layout" | "helper" | "partial" | "asset";

    export interface Env {
    [k: string]: string;
    }

    export interface Playbook {
    asciidoc: Playbook.AsciidocConfig;
    content: Playbook.ContentConfig;
    dir: string;
    file: string;
    git: Playbook.GitConfig;
    output: Playbook.OutputConfig;
    runtime: Playbook.RuntimeConfig;
    site: Playbook.SiteConfig;
    ui: Playbook.UIConfig;
    urls: Playbook.URLsConfig;
    }

    namespace Playbook {
    interface AsciidocConfig {
    attributes: AsciidocAttribs;
    extensions: Array<string>;
    }

    interface ContentConfig {
    branches: Array<string>;
    tags: Array<string>;
    sources: Array<ContentSource>;
    }

    interface ContentSource {
    url: string;
    branches: string;
    startPath?: string;
    }

    interface GitConfig {
    credentials: {
    path: string | undefined;
    contents: string | undefined;
    };
    }

    interface OutputConfig {
    clean: boolean;
    dir: string;
    destinations: Array<string> | undefined;
    }

    interface RuntimeConfig {
    cacheDir: string | undefined;
    fetch: boolean;
    pull: boolean | undefined;
    quiet: boolean;
    silent: boolean;
    }

    interface SiteConfig {
    startPage: string | undefined;
    title: string | undefined;
    url: string | undefined;
    keys: { [k: string]: string | undefined };
    }

    interface UIConfig {
    bundle: {
    url: string | null;
    snapshot: boolean;
    startPath: string;
    };
    defaultLayout: string | undefined;
    outputDir: string;
    supplementalFiles: string | Array<AntoraFile> | undefined;
    }

    interface URLsConfig {
    htmlExtensionStyle: HtmlExtensionStyle;
    redirectFacility: "disabled" | "netlify" | "nginx" | "static";
    }
    }

    type HtmlExtensionStyle = "default" | "drop" | "indexify";

    interface AsciidocAttribs {
    [k: string]: any;
    }

    export interface ComponentContent {
    name: string;
    title: string;
    version: string;
    start_page: string;
    nav: Array<string>;
    files: Array<AntoraFile>;
    }

    export interface ContentCatalog {
    htmlUrlExtensionStyle: HtmlExtensionStyle;

    registerComponentVersion(name: string, version: string, options?: ContentCatalog.ComponentOptions): void;
    addFile(file: AntoraFile): void;
    findBy(criteria: ContentCatalog.FileSourceCriteria): Array<AntoraFile>;
    getById(id: ContentCatalog.CompositeDocId): AntoraFile | undefined;
    getByPath(details: ContentCatalog.PathDetails): AntoraFile | undefined;
    getComponent(name: string): ContentCatalog.Component | undefined;
    getComponentVersion(component: string | ContentCatalog.Component, version: string): ContentCatalog.Component | undefined;
    getComponentMap(): ContentCatalog.ComponentMap;
    getComponentMapSortedBy(prop: string): ContentCatalog.ComponentMap;
    getComponents(): Array<ContentCatalog.Component>;
    getComponentsSortedBy(prop: string): Array<ContentCatalog.Component>;
    getFiles(): Array<AntoraFile>;
    getSiteStartPage(): string | undefined;
    registerPageAlias(aliasSpec: string, targetPage: AntoraFile): void;
    resolvePage(spec: string, context: ContentCatalog.Context): AntoraFile | undefined;
    resolveResource(
    spec: string,
    context: ContentCatalog.Context,
    permittedFamilies?: Array<FileFamily>,
    defaultFamily?: FileFamily
    ): AntoraFile | undefined;
    }

    namespace ContentCatalog {
    interface ComponentOptions {
    displayVersion?: string;
    prerelease?: string;
    title?: string;
    startPage?: string;
    }

    type FileSourceCriteria = Partial<AntoraFile>;

    interface CompositeDocId {
    component: string;
    version: string;
    module: string;
    family: FileFamily;
    relative: string;
    }

    interface PathDetails {
    component: string;
    version: string;
    path: string;
    }

    interface Component {
    name: string;
    latest: ComponentVersion;
    versions: Array<ComponentVersion>;
    }

    interface ComponentVersion {
    version: string;
    displayVersion: string;
    title: string;
    url: string;
    }

    interface PageVersion extends ComponentVersion {
    latest?: boolean;
    missing?: boolean;
    }

    interface ComponentMap {
    [k: string]: Component;
    }

    interface Context {
    component: string;
    version: string;
    module: string;
    }
    }

    interface UiCatalog {
    getFiles(): Array<AntoraFile>;
    addFile(file: AntoraFile): void;
    findByType(type: string): Array<AntoraFile>;
    }

    namespace AsciiDoctor {
    interface Config {
    attributes: AsciidocAttribs;
    }

    type Document = unknown; // TODO: figure out something for this
    }

    export interface NavigationCatalog {
    addTree(component: string, version: string, tree: NavigationCatalog.NavItem): Array<NavigationCatalog.NavItem>;
    getNavigation(component: string, version: string): Array<NavigationCatalog.NavItem>;
    }

    namespace NavigationCatalog {
    interface NavItem {
    content?: string;
    items?: Array<NavItem>;
    order?: number;
    root?: boolean;
    url?: string;
    hash?: string;
    urlType?: URLType;
    }

    type URLType = "internal" | "external" | "fragment";
    }

    function composePage(file: AntoraFile, contentCatalog: ContentCatalog, navigationCatalog: NavigationCatalog): AntoraFile;
    type PageComposer = typeof composePage;

    namespace PageComposer {
    interface SiteUiModel {
    title: string;
    path: string;
    url: string;
    components: ContentCatalog.ComponentMap;
    keys: { [k: string]: string };
    ui: {
    url: string;
    defaultLayout: string;
    };
    }

    interface PageUiModel extends NavContext {
    contents: Buffer | NodeJS.ReadableStream | null;
    layout: string;
    title: string;
    url: string;
    description: string;
    keywords: string;
    attributes: AsciidocAttribs;
    component: ContentCatalog.Component;
    version: string;
    displayVersion: string;
    componentVersion: ContentCatalog.ComponentVersion;
    module: string;
    origin?: GitOrigin;
    versions: Array<ContentCatalog.PageVersion>;
    navigation: Array<NavigationCatalog.NavItem>;
    editUrl: string;
    home: boolean;
    latest: ContentCatalog.PageVersion;
    canonicalUrl?: string;
    }

    interface UiModel {
    antoraVersion: string;
    env: Env;
    page: PageUiModel;
    site: SiteUiModel;
    siteRootPath: string;
    uiRootPath: string;
    }

    interface NavContext {
    breadcrumbs: Array<PageNavItem>;
    parent?: PageNavItem;
    previous?: PageNavItem;
    next?: PageNavItem;
    }

    interface PageNavItem extends NavigationCatalog.NavItem {
    current?: PageNavItem;
    ancestors?: PageNavItem;
    previous?: PageNavItem;
    next?: PageNavItem;
    seekNext?: boolean;
    discrete?: boolean;
    }
    }

    interface Catalog {
    getFiles(): Array<AntoraFile>;
    }
    }

    declare module "@antora/playbook-builder" {
    import { Env, Playbook, NavigationCatalog } from "@antora/types";

    function buildPlaybook(args: Array<string>, env: Env): Promise<Playbook>;

    export = buildPlaybook;
    }

    declare module "@antora/content-aggregator" {
    import { Playbook, ComponentContent } from "@antora/types";

    function aggregateContent(playbook: Playbook): Promise<Array<ComponentContent>>;

    export = aggregateContent;
    }

    declare module "@antora/content-classifier" {
    import { Playbook, ComponentContent, ContentCatalog } from "@antora/types";

    function classifyContent(playbook: Playbook, contentAggregate: Array<ComponentContent>): ContentCatalog;

    export = classifyContent;
    }

    declare module "@antora/ui-loader" {
    import { Playbook, UiCatalog } from "@antora/types";

    function loadUi(playbook: Playbook): Promise<UiCatalog>;

    export = loadUi;
    }

    declare module "@antora/asciidoc-loader" {
    import { Playbook, ContentCatalog, AntoraFile, AsciiDoctor } from "@antora/types";

    function loadAsciiDoc(file: AntoraFile, contentCatalog: ContentCatalog, config: AsciiDoctor.Config): AsciiDoctor.Document;

    namespace loadAsciiDoc {
    function resolveConfig(playbook?: Playbook): AsciiDoctor.Config;
    }

    export = loadAsciiDoc;
    }

    declare module "@antora/document-converter" {
    import { ContentCatalog, AsciiDoctor, AntoraFile } from "@antora/types";

    function convertDocuments(contentCatalog: ContentCatalog, asciidocConfig: AsciiDoctor.Config): Array<AntoraFile>;

    namespace convertDocuments {
    function convertDocument(file: AntoraFile, contentCatalog: ContentCatalog, asciidocConfig: AsciiDoctor.Config): AntoraFile;
    }

    export = convertDocuments;
    }

    declare module "@antora/navigation-builder" {
    import { ContentCatalog, AsciiDoctor, AntoraFile, NavigationCatalog } from "@antora/types";

    function buildNavigation(contentCatalog: ContentCatalog, asciidocConfig?: AsciiDoctor.Config): NavigationCatalog;

    export = buildNavigation;
    }

    declare module "@antora/page-composer" {
    import { Playbook, ContentCatalog, UiCatalog, Env, PageComposer, AntoraFile, NavigationCatalog } from "@antora/types";

    function createPageComposer(playbook: Playbook, contentCatalog: ContentCatalog, uiCatalog: UiCatalog, env?: Env): PageComposer;

    namespace createPageComposer {
    function buildSiteUiModel(playbook: Playbook, contentCatalog: ContentCatalog): PageComposer.SiteUiModel;
    function buildPageUiModel(
    file: AntoraFile,
    contentCatalog: ContentCatalog,
    navigationCatalog: NavigationCatalog,
    site: PageComposer.SiteUiModel
    ): PageComposer.PageUiModel;
    function buildUiModel(
    file: AntoraFile,
    contentCatalog: ContentCatalog,
    navigationCatalog: NavigationCatalog,
    site: PageComposer.SiteUiModel,
    env: Env
    ): PageComposer.UiModel;
    }

    export = createPageComposer;
    }

    declare module "@antora/site-mapper" {
    import { Playbook, AntoraFile } from "@antora/types";

    function mapSite(playbook: Playbook, pages: Array<AntoraFile>): Array<AntoraFile>;

    export = mapSite;
    }

    declare module "@antora/redirect-producer" {
    import { Playbook, ContentCatalog, AntoraFile } from "@antora/types";

    function produceRedirects(playbook: Playbook, contentCatalog: ContentCatalog): Array<AntoraFile>;

    export = produceRedirects;
    }

    declare module "@antora/site-publisher" {
    import { Playbook, Catalog, AntoraFile } from "@antora/types";

    function publishSite(playbook: Playbook, catalogs: Array<Catalog>): Promise<void>;

    export = publishSite;
    }