@dovenv/docs
Version:
Documentation utils for dovenv
575 lines (563 loc) • 18.1 kB
TypeScript
import { VitePWAOptions } from 'vite-plugin-pwa';
import { transformerTwoslash } from '@shikijs/vitepress-twoslash';
import { groupIconVitePlugin } from 'vitepress-plugin-group-icons';
import { LlmsConfig } from 'vitepress-plugin-llmstxt';
import { TransformContext, DefaultTheme, UserConfig } from 'vitepress';
import { DeepNonNullable, PackageJSON } from '@dovenv/core/utils';
import { RSSOptions } from 'vitepress-plugin-rss';
import * as _dovenv_core from '@dovenv/core';
import { CommandUtils, getCommandUtils } from '@dovenv/core';
type OgImageOpts = {
/** Title for the og image */
title: string;
/** Description for the og image */
desc: string;
/** Text for the og image */
text?: string;
/** Image path for the og image */
image: string;
/**
* Output path for the og image
*
* @default './build/og.png'
*/
output?: string;
/**
* Width for the og image
*
* @default 1200
*/
width?: number;
/**
* Height for the og image
*
* @default 600
*/
height?: number;
/** Colors for the og image */
color?: {
primary?: string;
/** Secondary color for the theme. */
secondary?: string;
/** Tertiary color for the theme. */
terciary?: string;
/** Fourth color for the theme. */
fourth?: string;
text?: string;
bg?: string;
};
/**
* Border radius for the og image
*
* @default '20px'
*/
radius?: string;
/**
* Google Font family name for the og image
*
* @default 'Open+Sans'
* @see https://fonts.google.com/
*/
fontFamily?: string;
};
type Meta = {
/**
* If true, the og|twitter image will be generated from the docs configuration data.
*
* **Default**: true if does not exist 'public/banner.png'
*/
autoImage?: boolean | Partial<Omit<OgImageOpts, 'output'>>;
shared?: {
/** The title of the shared link */
title?: string;
/** A brief description of the content */
description?: string;
image?: string;
url?: string;
};
og?: {
/** Title for the Open Graph metadata. */
title?: string;
/** Description for the Open Graph metadata. */
description?: string;
/** Image URL for the Open Graph metadata. */
image?: string;
/** URL for the site, used in Open Graph metadata. */
url?: string;
/** Type for the Open Graph metadata. */
type?: string;
/** Site name for Open Graph metadata. */
siteName?: string;
} | false;
twitter?: {
/** The title of the shared link */
title?: string;
/** A brief description of the content */
description?: string;
image?: string;
url?: string;
/** Domain name */
domain?: string;
/** The type of Twitter card, such as summary, summary_large_image, or app... */
card?: string;
/**
* Twitter account associated with the site.
*
* @example "@pigeonposse_"
*/
site?: string;
/**
* The Twitter acoount of the content creator
*
* @example "@pigeonposse_"
*/
creator?: string;
} | false;
/**
* Custom metadata
*
* @example
* ```js
* [{ name: 'twitter:label1', content: 'Genre' }]
* // Result:
* <meta name="twitter:label1" content="Genre">
* ```
*/
custom?: {
[key: string]: string;
}[];
onPage?: (data: {
context: TransformContext;
config: RequiredDocsConfig;
}) => (Promise<TransformContext['head'] | void> | TransformContext['head'] | void);
};
type PwaOptions = Partial<VitePWAOptions>;
type Theme = DefaultTheme.Config;
type SocialLink = DefaultTheme.SocialLinkIcon;
type Sidebar = Theme['sidebar'];
type Nav = Theme['nav'];
type SocialLinks = Theme['socialLinks'];
type Link = {
text: string;
desc: string;
/**
* Icons IDs: https://simpleicons.org/.
*/
icon: SocialLink;
link: string;
};
type Links = (Link | {
text: string;
desc: string;
items: Link[];
})[];
type Colors = {
text?: string;
text2?: string;
text3?: string;
bg?: string;
bgAlt?: string;
bgSoft?: string;
bgOpacity?: string;
shadow?: string;
divider?: string;
};
type RequiredDocsConfig = DocsConfig & DeepNonNullable<Pick<DocsConfig, 'input' | 'output' | 'docsPath' | 'logo' | 'favicon' | 'name' | 'desc' | 'styles' | 'lang' | 'titleTemplate'>> & {
license: {
type: string;
};
};
type DocsConfig = {
/**
* Input directory for documentation files.
*
* @default './docs'
*/
input?: string;
/**
* Output directory for the built documentation.
*
* @default './build'
*/
output?: string;
/**
* Logo URL for the documentation site.
*
* @default '/logo.png'
*/
logo?: string;
/**
* Favicon URL for the documentation site.
*
* @default '/favicon.png'
*/
favicon?: string;
/**
* Name of the project or documentation.
*
* @default 'DOVENV'
*/
name?: string;
/**
* titleTemplate for the documentation site.
*/
titleTemplate?: (data: {
title: string;
name: string;
}) => string;
/**
* Short description of the project or documentation.
*
* @default 'Workspace documentation'
*/
/**
* Language code for the documentation, e.g., 'en' for English.
*
* @default 'en'
*/
lang?: string;
/**
* Path to the documentation files. Used for editLink in pages.
*
* @default 'docs'
*/
docsPath?: string;
/** License information for the project. */
license?: {
/**
* Type of license (e.g., MIT, GPL).
*
* @default 'MIT'
*/
type?: string;
/** URL to the full license text. */
url?: string;
};
desc?: string;
/** A shorter version of the description for better display. */
shortDesc?: string;
/** URL of the project or documentation site. */
url?: string;
/** Repository URL for the project. */
repoURL?: string | false;
/** URL for the project's issue tracker or bug reports. */
bugsURL?: string | false;
/** URL for funding or sponsorship of the project. */
fundingURL?: string | false;
/** Additional URL for more resources or links related to the project. */
moreURL?: string | false;
/** NPM package URL for the project. */
npmURL?: string | false;
/** Version of the project. */
/** CHANGELOG url of the project. */
changelogURL?: string | false;
/** Contributing url of the project. */
contributingURL?: string | false;
version?: string;
/** Array of previous versions of the project, each with a name and a URL. */
oldVersions?: {
/** The name or label of the old version, e.g., "v1.0", "Legacy". */
name: string;
/** URL where the old version documentation */
url: string;
}[];
/** Custom styles for the documentation site. */
styles?: {
/** Color scheme for the documentation site. */
color?: {
/** Primary color for the theme. */
primary?: string;
/** Secondary color for the theme. */
secondary?: string;
/** Tertiary color for the theme. */
terciary?: string;
/** Fourth color for the theme. */
fourth?: string;
/** Dark mode colors for the theme. */
dark?: Colors;
/** Light mode colors for the theme. */
light?: Colors;
};
/** Border radius for elements in the theme. */
radius?: string;
};
meta?: Meta;
/**
* Open Graph meta tags for better link previews on social media.
*
* @deprecated
*/
og?: {
/** Description for the Open Graph metadata. */
description?: string;
/** Image URL for the Open Graph metadata. */
image?: string;
/** Title for the Open Graph metadata. */
title?: string;
/** URL for the site, used in Open Graph metadata. */
url?: string;
/** Site name for Open Graph metadata. */
siteName?: string;
/** Twitter account associated with the site. */
twitterAccount?: string;
};
/** Configuration options for RSS feed. */
rss?: RSSOptions;
/** Configuration options for PWA (Progressive Web App) support. */
pwa?: Partial<PwaOptions> | false;
/** Custom CSS for the documentation site. */
css?: string;
/** Footer configuration with links and copyright information. */
footer?: {
/** Links to various social platforms or contact methods. */
links?: {
/** Website link for the project or organization. */
web?: string;
/** Email link for contacting the project or organization. */
email?: string;
/** Twitter link for the project or organization. */
twitter?: string;
/** Instagram link for the project or organization. */
instagram?: string;
/** Medium link for articles or blogs related to the project. */
medium?: string;
};
/** Copyright information for the project. */
copy?: {
/** Name to display in copyright notices. */
name?: string;
/** URL for the copyright holder or organization. */
url?: string;
};
};
/**
* Configuration for LLMs text files.
*
* @see https://llmstxt.org/
*/
llms?: LlmsConfig | false;
/** Sidebar configuration for navigation within the documentation. */
sidebar?: Sidebar;
/** Active or desactivated sidebar autogenerated */
autoSidebar?: {
/**
* Display the "Get started" section in the sidebar.
*
* @default true
*/
intro?: boolean;
/**
* Display the "Reference" section in the sidebar.
*
* @default true
*/
reference?: boolean;
/**
* Display the "Contribute" section in the sidebar.
*
* @default true
*/
contribute?: boolean;
/**
* Display the "About" section in the sidebar.
*
* @default true
*/
about?: boolean;
};
/** Navigation configuration for links at the top of the documentation. */
nav?: Nav;
/**
* Additional navigation links.
* Icons IDs: https://simpleicons.org/.
*/
navLinks?: SocialLinks;
/** Server-related configurations, including file watching settings. */
server?: {
/** Files that trigger a hot reload on changes. */
hotReloadFiles?: string[];
/** Files that trigger a server restart on changes. */
restartFiles?: string[];
};
/** Contributors information including their details and social links. */
contributors?: {
/** Avatar image for the member. */
avatar: string;
/** Name of the member. */
name: string;
/** Title to be shown below member's name (e.g., Developer). */
title?: string;
/** Organization that the member belongs to. */
org?: string;
/** URL for the organization. */
orgLink?: string;
/** Description for the member. */
desc?: string;
/**
* Social links for the member (e.g., GitHub, Twitter).
* Icons IDs: https://simpleicons.org/.
*/
links?: SocialLinks;
/** URL for the sponsor page for the member. */
sponsor?: string;
/** Text for the sponsor link. Defaults to 'Sponsor'. */
actionText?: string;
}[];
/** Additional links to display in a special page. */
links?: Links;
/** Data related to downloads and version releases. */
download?: {
/**
* Optional grouping of download items by category.
* Each key in the object represents a group name and maps to a string label.
*
* @example
* {
* "extension": "extension",
* "app": "app",
* }
*/
groups?: {
[key: string]: string;
};
/**
* Optional list of downloadable items, where each key represents an item identifier.
* Each item includes details such as name, URL, and optionally a logo and type.
*/
items?: {
[key: string]: {
/** Name of the downloadable item */
name: string;
/** URL to access the downloadable item */
url: string;
/** Optional URL for the logo or icon associated with the item */
logo?: string;
/** Optional type/category of the item, e.g., "pdf", "image" */
type?: string;
};
};
};
/** Group icon options */
groupIcon?: Parameters<typeof groupIconVitePlugin>[0] | false;
/** Twoslash options */
twoslash?: Parameters<typeof transformerTwoslash>[0] | false;
/** VitePress user configuration for additional options. */
vitepress?: UserConfig;
/**
* Settings for experimental options.
*
* **Use at your own risk**.
*/
experimental?: {
/**
* Disable temp directory during compilation.
* The temp directory is used to store documentation files in the output directory during the compilation process.
* Used to allow input paths with '../'.
*
* @default false
*/
noTempDirOnBuild?: boolean;
};
};
/**
* Configuration for auto PWA assets generation.
*
* **Requires**: `@vite-pwa/assets-generator`.
*
* @type {PwaOptions['pwaAssets']}
* @example
* const docsConfig = {
* pwa: {
* pwaAssets: autoPWAConfig
* }
* }
*/
declare const autoPWAConfig: PwaOptions['pwaAssets'];
/**
* Defines a configuration object for the dovenv documentation plugin.
*
* @param {( DocsConfig | DocsConfig[] )[]} config - The configuration object.
* @returns {DocsConfig} The defined configuration object.
*/
declare const defineConfig: (...config: (DocsConfig | DocsConfig[])[]) => DocsConfig;
/**
* Extracts and constructs documentation configuration from package JSON data.
*
* @param {PackageJSON} pkgData - The package JSON data object.
* @returns {Promise<DocsConfig>} A promise that resolves to a `DocsConfig` object containing extracted configuration details like funding URL, bugs URL, license, homepage URL, description, name, version, and contributors.
*/
declare const getPkgConfig: (pkgData: PackageJSON) => Promise<DocsConfig>;
type Response<T> = Promise<T> | T;
type Config = DocsConfig | ((utils: CommandUtils) => Response<DocsConfig>);
type DocsParams = {
config?: Config;
utils: CommandUtils;
opts?: {
packageJsonPath?: string;
configPath?: string;
debug?: boolean;
port?: number;
};
};
declare class DocsCore {
#private;
protected utils: DocsParams['utils'];
opts: DocsParams['opts'];
constructor({ utils, opts, }: DocsParams);
/**
* __Starts the development server__.
*
* This command is a wrapper of the `npx vitepress dev` command.
*
* @param {string[]} [flags] - Flags to pass to the underlying `vitepress dev`
* command. The `--force` flag is always passed to ensure the server starts
* without prompting the user.
*/
dev(flags?: string[]): Promise<void>;
/**
* __Builds the documentation site__.
*
* This command is a wrapper of the `npx vitepress build` command.
*
* @param {string[]} [flags] - Flags to pass to the underlying `vitepress build`
* command. This allows for customization and control over the build process.
*/
build(flags?: string[]): Promise<void>;
/**
* __Starts the preview server__.
*
* This command is a wrapper of the `npx vitepress preview` command.
*
* @param {string[]} [flags] - Flags to pass to the underlying `vitepress preview`
* command. This allows for customization and control over the preview process.
*/
preview(flags?: string[]): Promise<void>;
/**
* Generate assets for PWA.
*
* @param {string[]} [flags] - Flags to pass '@vite-pwa/assets-generator' cli.
* @see https://vite-pwa-org.netlify.app/assets-generator/cli.html
*/
generatePWAassets(flags?: string[]): Promise<void>;
publishToCloudflare(opts: {
dir: string;
name: string;
}): Promise<void>;
}
/**
* Creates DOCUMENTATION instance.
*
* @param {Omit<DocsParams, 'utils'>} [args] - Optional arguments excluding 'utils'.
* @param {Parameters<typeof getCommandUtils>[0]} [utils] - Optional utilities parameters.
* @returns {Promise<DocsCore>} A promise that resolves to an instance of DocsCore.
*/
declare const docs: (args?: Omit<DocsParams, "utils">, utils?: Parameters<typeof getCommandUtils>[0]) => Promise<DocsCore>;
/**
* Define a `dovenv` configuration that creates a documentation site for your workspace.
*
* @param {DocsParams['config'] } [config] - The configuration object.
* @returns {DocsParams['utils']['config']} The dovenv configuration object.
*/
declare const docsPlugin: (config?: DocsParams["config"]) => _dovenv_core.Config;
export { autoPWAConfig, docsPlugin as default, defineConfig, docs, docsPlugin, getPkgConfig };
export type { Config, DocsConfig, DocsParams };