Skip to content

Instantly share code, notes, and snippets.

@sophistifunk
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.
/*
# 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;
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment