From 678b39ed45975f54f09811a30281a16f2656357c Mon Sep 17 00:00:00 2001 From: Artyom Sovetnikov <2056864+elringus@users.noreply.github.com> Date: Sat, 13 Jan 2024 03:52:56 +0300 Subject: [PATCH] update docs (#12) --- .github/workflows/deploy.yml | 1 + docs/.gitignore | 1 + docs/.vitepress/config.ts | 15 +- docs/api/index.md | 10 - docs/api/plugin/astro/functions/default.md | 25 -- docs/api/plugin/astro/index.md | 12 - .../astro/type-aliases/AstroInjector.md | 19 - .../astro/type-aliases/AstroIntegration.md | 41 -- docs/api/plugin/svg/functions/default.md | 21 - docs/api/plugin/svg/index.md | 7 - docs/api/plugin/vite/functions/default.md | 25 -- docs/api/plugin/vite/index.md | 13 - docs/api/plugin/vite/type-aliases/HtmlTag.md | 35 -- .../plugin/vite/type-aliases/VitePlugin.md | 114 ------ .../api/plugin/vite/type-aliases/VitePrefs.md | 37 -- docs/api/plugin/youtube/functions/default.md | 25 -- docs/api/plugin/youtube/index.md | 11 - docs/api/plugin/youtube/type-aliases/Prefs.md | 29 -- docs/api/server/functions/boot.md | 25 -- docs/api/server/functions/configure.md | 19 - docs/api/server/functions/createDefaults.md | 15 - docs/api/server/functions/exit.md | 15 - docs/api/server/functions/resetConfig.md | 15 - docs/api/server/functions/transform.md | 28 -- docs/api/server/index.md | 48 --- docs/api/server/type-aliases/AssetSpec.md | 65 --- docs/api/server/type-aliases/AssetSyntax.md | 54 --- docs/api/server/type-aliases/BuiltAsset.md | 21 - docs/api/server/type-aliases/Cache.md | 46 --- docs/api/server/type-aliases/CacheOptions.md | 23 -- docs/api/server/type-aliases/CapturedAsset.md | 21 - docs/api/server/type-aliases/ContentInfo.md | 45 -- docs/api/server/type-aliases/EncodeOptions.md | 76 ---- docs/api/server/type-aliases/EncodeSpec.md | 53 --- docs/api/server/type-aliases/EncodeSpecMap.md | 11 - docs/api/server/type-aliases/EncodedAsset.md | 21 - .../api/server/type-aliases/EncodedContent.md | 45 -- docs/api/server/type-aliases/FetchOptions.md | 46 --- docs/api/server/type-aliases/FetchedAsset.md | 29 -- .../api/server/type-aliases/FetchedContent.md | 21 - docs/api/server/type-aliases/Options.md | 94 ----- docs/api/server/type-aliases/Platform.md | 383 ------------------ docs/api/server/type-aliases/Plugin.md | 183 --------- .../server/type-aliases/PluginInjection.md | 29 -- docs/api/server/type-aliases/Prefs.md | 11 - docs/api/server/type-aliases/ProbedAsset.md | 21 - docs/api/server/type-aliases/ProbedContent.md | 21 - docs/api/server/type-aliases/ResolvedAsset.md | 29 -- .../server/type-aliases/ResolvedContent.md | 21 - docs/api/server/variables/cache.md | 11 - docs/api/server/variables/cfg.md | 11 - docs/api/server/variables/ctx.md | 45 -- docs/api/server/variables/defaults.md | 11 - docs/api/server/variables/stages.md | 211 ---------- docs/api/server/variables/std.md | 11 - docs/api/typedoc-sidebar.json | 1 - docs/guide/getting-started.md | 2 +- docs/guide/plugins.md | 2 + docs/scripts/api.sh | 1 + src/client/index.ts | 2 + src/client/mutation.ts | 7 +- src/plugin/youtube/client.ts | 4 +- 62 files changed, 26 insertions(+), 2268 deletions(-) delete mode 100644 docs/api/index.md delete mode 100644 docs/api/plugin/astro/functions/default.md delete mode 100644 docs/api/plugin/astro/index.md delete mode 100644 docs/api/plugin/astro/type-aliases/AstroInjector.md delete mode 100644 docs/api/plugin/astro/type-aliases/AstroIntegration.md delete mode 100644 docs/api/plugin/svg/functions/default.md delete mode 100644 docs/api/plugin/svg/index.md delete mode 100644 docs/api/plugin/vite/functions/default.md delete mode 100644 docs/api/plugin/vite/index.md delete mode 100644 docs/api/plugin/vite/type-aliases/HtmlTag.md delete mode 100644 docs/api/plugin/vite/type-aliases/VitePlugin.md delete mode 100644 docs/api/plugin/vite/type-aliases/VitePrefs.md delete mode 100644 docs/api/plugin/youtube/functions/default.md delete mode 100644 docs/api/plugin/youtube/index.md delete mode 100644 docs/api/plugin/youtube/type-aliases/Prefs.md delete mode 100644 docs/api/server/functions/boot.md delete mode 100644 docs/api/server/functions/configure.md delete mode 100644 docs/api/server/functions/createDefaults.md delete mode 100644 docs/api/server/functions/exit.md delete mode 100644 docs/api/server/functions/resetConfig.md delete mode 100644 docs/api/server/functions/transform.md delete mode 100644 docs/api/server/index.md delete mode 100644 docs/api/server/type-aliases/AssetSpec.md delete mode 100644 docs/api/server/type-aliases/AssetSyntax.md delete mode 100644 docs/api/server/type-aliases/BuiltAsset.md delete mode 100644 docs/api/server/type-aliases/Cache.md delete mode 100644 docs/api/server/type-aliases/CacheOptions.md delete mode 100644 docs/api/server/type-aliases/CapturedAsset.md delete mode 100644 docs/api/server/type-aliases/ContentInfo.md delete mode 100644 docs/api/server/type-aliases/EncodeOptions.md delete mode 100644 docs/api/server/type-aliases/EncodeSpec.md delete mode 100644 docs/api/server/type-aliases/EncodeSpecMap.md delete mode 100644 docs/api/server/type-aliases/EncodedAsset.md delete mode 100644 docs/api/server/type-aliases/EncodedContent.md delete mode 100644 docs/api/server/type-aliases/FetchOptions.md delete mode 100644 docs/api/server/type-aliases/FetchedAsset.md delete mode 100644 docs/api/server/type-aliases/FetchedContent.md delete mode 100644 docs/api/server/type-aliases/Options.md delete mode 100644 docs/api/server/type-aliases/Platform.md delete mode 100644 docs/api/server/type-aliases/Plugin.md delete mode 100644 docs/api/server/type-aliases/PluginInjection.md delete mode 100644 docs/api/server/type-aliases/Prefs.md delete mode 100644 docs/api/server/type-aliases/ProbedAsset.md delete mode 100644 docs/api/server/type-aliases/ProbedContent.md delete mode 100644 docs/api/server/type-aliases/ResolvedAsset.md delete mode 100644 docs/api/server/type-aliases/ResolvedContent.md delete mode 100644 docs/api/server/variables/cache.md delete mode 100644 docs/api/server/variables/cfg.md delete mode 100644 docs/api/server/variables/ctx.md delete mode 100644 docs/api/server/variables/defaults.md delete mode 100644 docs/api/server/variables/stages.md delete mode 100644 docs/api/server/variables/std.md delete mode 100644 docs/api/typedoc-sidebar.json diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index aa59ae5..2cdf943 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -21,6 +21,7 @@ jobs: run: | cd docs npm install + npm run docs:api npm run docs:build - uses: actions/configure-pages@v3 - uses: actions/upload-pages-artifact@v2 diff --git a/docs/.gitignore b/docs/.gitignore index 06cf653..e70b8a5 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1 +1,2 @@ cache +api diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 35e3742..e210f70 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -1,4 +1,4 @@ -import { defineConfig } from "vitepress"; +import { defineConfig, DefaultTheme } from "vitepress"; import md from "./md"; import escapeCode from "./escape-code"; import imgit from "imgit/vite"; @@ -71,11 +71,16 @@ export default defineConfig({ ] } ], - "/api/": [{ - text: "Reference", - items: (await import("./../api/typedoc-sidebar.json")).default - }] + "/api/": await getApiSidebar() } }, sitemap: { hostname: "https://imgit.dev" } }); + +async function getApiSidebar(): Promise { + const items = (await import("./../api/typedoc-sidebar.json")).default; + const server = items.find(i => i.text === "server"); + const client = items.find(i => i.text === "client"); + const other = items.filter(i => i !== server && i !== client); + return [{ text: "Reference", items: [server, client, ...other] }]; +} diff --git a/docs/api/index.md b/docs/api/index.md deleted file mode 100644 index e122619..0000000 --- a/docs/api/index.md +++ /dev/null @@ -1,10 +0,0 @@ -# API Reference -Auto-generated with [typedoc-plugin-markdown](https://typedoc-plugin-markdown.org). - -## Modules - -- [plugin/astro](plugin/astro/index.md) -- [plugin/svg](plugin/svg/index.md) -- [plugin/vite](plugin/vite/index.md) -- [plugin/youtube](plugin/youtube/index.md) -- [server](server/index.md) diff --git a/docs/api/plugin/astro/functions/default.md b/docs/api/plugin/astro/functions/default.md deleted file mode 100644 index 4c73791..0000000 --- a/docs/api/plugin/astro/functions/default.md +++ /dev/null @@ -1,25 +0,0 @@ -# default() - -```ts -default(prefs?, platform?): AstroIntegration -``` - -Creates imgit integration instance for astro. - -## Parameters - -• **prefs?**: [`Prefs`](../../../server/type-aliases/Prefs.md) - -Plugin preferences; will use pre-defined defaults when not assigned. - -• **platform?**: [`Platform`](../../../server/type-aliases/Platform.md) - -Runtime APIs to use; will attempt to detect automatically when not assigned. - -## Returns - -[`AstroIntegration`](../type-aliases/AstroIntegration.md) - -## Source - -[plugin/astro.ts:22](https://github.com/Elringus/Imgit/blob/fc320a2/src/plugin/astro.ts#L22) diff --git a/docs/api/plugin/astro/index.md b/docs/api/plugin/astro/index.md deleted file mode 100644 index 2a0859d..0000000 --- a/docs/api/plugin/astro/index.md +++ /dev/null @@ -1,12 +0,0 @@ -# plugin/astro - -## Index - -### Type Aliases - -- [AstroInjector](type-aliases/AstroInjector.md) -- [AstroIntegration](type-aliases/AstroIntegration.md) - -### Functions - -- [default](functions/default.md) diff --git a/docs/api/plugin/astro/type-aliases/AstroInjector.md b/docs/api/plugin/astro/type-aliases/AstroInjector.md deleted file mode 100644 index 99d5b55..0000000 --- a/docs/api/plugin/astro/type-aliases/AstroInjector.md +++ /dev/null @@ -1,19 +0,0 @@ -# AstroInjector - -```ts -type AstroInjector: (stage, content) => void; -``` - -## Parameters - -• **stage**: `"page"` - -• **content**: `string` - -## Returns - -`void` - -## Source - -[plugin/astro.ts:17](https://github.com/Elringus/Imgit/blob/fc320a2/src/plugin/astro.ts#L17) diff --git a/docs/api/plugin/astro/type-aliases/AstroIntegration.md b/docs/api/plugin/astro/type-aliases/AstroIntegration.md deleted file mode 100644 index 187e70a..0000000 --- a/docs/api/plugin/astro/type-aliases/AstroIntegration.md +++ /dev/null @@ -1,41 +0,0 @@ -# AstroIntegration - -```ts -type AstroIntegration: Object; -``` - -## Type declaration - -### hooks - -```ts -hooks: Object; -``` - -### hooks.astro:config:setup? - -```ts -hooks.astro:config:setup?: (options) => void | Promise; -``` - -#### Parameters - -• **options**: `Object` - -• **options\.injectScript**: [`AstroInjector`](AstroInjector.md) - -• **options\.updateConfig**: (`config`) => `void` - -#### Returns - -`void` \| `Promise`\<`void`\> - -### name - -```ts -name: string; -``` - -## Source - -[plugin/astro.ts:6](https://github.com/Elringus/Imgit/blob/fc320a2/src/plugin/astro.ts#L6) diff --git a/docs/api/plugin/svg/functions/default.md b/docs/api/plugin/svg/functions/default.md deleted file mode 100644 index efc2cc8..0000000 --- a/docs/api/plugin/svg/functions/default.md +++ /dev/null @@ -1,21 +0,0 @@ -# default() - -```ts -default(): Plugin -``` - -Adds support for inlining SVG assets with imgit. - -## Returns - -[`Plugin`](../../../server/type-aliases/Plugin.md) - -## Example - -```md - ![](/assets/diagram.svg) - ``` - -## Source - -[plugin/svg.ts:9](https://github.com/Elringus/Imgit/blob/fc320a2/src/plugin/svg.ts#L9) diff --git a/docs/api/plugin/svg/index.md b/docs/api/plugin/svg/index.md deleted file mode 100644 index 36ee6da..0000000 --- a/docs/api/plugin/svg/index.md +++ /dev/null @@ -1,7 +0,0 @@ -# plugin/svg - -## Index - -### Functions - -- [default](functions/default.md) diff --git a/docs/api/plugin/vite/functions/default.md b/docs/api/plugin/vite/functions/default.md deleted file mode 100644 index 30dd444..0000000 --- a/docs/api/plugin/vite/functions/default.md +++ /dev/null @@ -1,25 +0,0 @@ -# default() - -```ts -default(prefs?, platform?): VitePlugin -``` - -Creates imgit plugin instance for vite. - -## Parameters - -• **prefs?**: [`VitePrefs`](../type-aliases/VitePrefs.md) - -Plugin preferences; will use pre-defined defaults when not assigned. - -• **platform?**: [`Platform`](../../../server/type-aliases/Platform.md) - -Runtime APIs to use; will attempt to detect automatically when not assigned. - -## Returns - -[`VitePlugin`](../type-aliases/VitePlugin.md) - -## Source - -[plugin/vite.ts:35](https://github.com/Elringus/Imgit/blob/fc320a2/src/plugin/vite.ts#L35) diff --git a/docs/api/plugin/vite/index.md b/docs/api/plugin/vite/index.md deleted file mode 100644 index 964c6b7..0000000 --- a/docs/api/plugin/vite/index.md +++ /dev/null @@ -1,13 +0,0 @@ -# plugin/vite - -## Index - -### Type Aliases - -- [HtmlTag](type-aliases/HtmlTag.md) -- [VitePlugin](type-aliases/VitePlugin.md) -- [VitePrefs](type-aliases/VitePrefs.md) - -### Functions - -- [default](functions/default.md) diff --git a/docs/api/plugin/vite/type-aliases/HtmlTag.md b/docs/api/plugin/vite/type-aliases/HtmlTag.md deleted file mode 100644 index 3832111..0000000 --- a/docs/api/plugin/vite/type-aliases/HtmlTag.md +++ /dev/null @@ -1,35 +0,0 @@ -# HtmlTag - -```ts -type HtmlTag: Object; -``` - -## Type declaration - -### attrs? - -```ts -attrs?: Record; -``` - -### children? - -```ts -children?: string | HtmlTag[]; -``` - -### injectTo? - -```ts -injectTo?: "head" | "body" | "head-prepend" | "body-prepend"; -``` - -### tag - -```ts -tag: string; -``` - -## Source - -[plugin/vite.ts:25](https://github.com/Elringus/Imgit/blob/fc320a2/src/plugin/vite.ts#L25) diff --git a/docs/api/plugin/vite/type-aliases/VitePlugin.md b/docs/api/plugin/vite/type-aliases/VitePlugin.md deleted file mode 100644 index f79cf7b..0000000 --- a/docs/api/plugin/vite/type-aliases/VitePlugin.md +++ /dev/null @@ -1,114 +0,0 @@ -# VitePlugin - -```ts -type VitePlugin: Object; -``` - -## Type declaration - -### buildEnd - -```ts -buildEnd: (error?) => Promise | void; -``` - -#### Parameters - -• **error?**: `Error` - -#### Returns - -`Promise`\<`void`\> \| `void` - -### buildStart - -```ts -buildStart: (options) => Promise | void; -``` - -#### Parameters - -• **options**: `unknown` - -#### Returns - -`Promise`\<`void`\> \| `void` - -### enforce - -```ts -enforce: "pre" | "post"; -``` - -### name - -```ts -name: string; -``` - -### transform - -```ts -transform: (code, id, options?) => Promise | string; -``` - -#### Parameters - -• **code**: `string` - -• **id**: `string` - -• **options?**: `Object` - -• **options\.ssr?**: `boolean` - -#### Returns - -`Promise`\<`string`\> \| `string` - -### transformIndexHtml - -```ts -transformIndexHtml: Object; -``` - -### transformIndexHtml.handler - -```ts -transformIndexHtml.handler: (html, ctx) => Promise; -``` - -#### Parameters - -• **html**: `string` - -• **ctx**: `Object` - -• **ctx\.filename**: `string` - -#### Returns - -`Promise`\<`Object`\> - -> ##### html -> -> ```ts -> html: string; -> ``` -> -> ##### tags -> -> ```ts -> tags: HtmlTag[]; -> ``` -> - -### transformIndexHtml.order - -```ts -transformIndexHtml.order: "pre" | "post"; -``` - -## Source - -[plugin/vite.ts:12](https://github.com/Elringus/Imgit/blob/fc320a2/src/plugin/vite.ts#L12) diff --git a/docs/api/plugin/vite/type-aliases/VitePrefs.md b/docs/api/plugin/vite/type-aliases/VitePrefs.md deleted file mode 100644 index 2752fb5..0000000 --- a/docs/api/plugin/vite/type-aliases/VitePrefs.md +++ /dev/null @@ -1,37 +0,0 @@ -# VitePrefs - -```ts -type VitePrefs: Prefs & Object; -``` - -Configures vite plugin behaviour. - -## Type declaration - -### inject? - -```ts -inject?: boolean; -``` - -Whether to inject imgit client JavaScript module to index HTML; enabled by default. - -### skip? - -```ts -skip?: (filename) => boolean; -``` - -Specify condition when document shouldn't be transformed by the vite plugin. - -#### Parameters - -• **filename**: `string` - -#### Returns - -`boolean` - -## Source - -[plugin/vite.ts:4](https://github.com/Elringus/Imgit/blob/fc320a2/src/plugin/vite.ts#L4) diff --git a/docs/api/plugin/youtube/functions/default.md b/docs/api/plugin/youtube/functions/default.md deleted file mode 100644 index be35c5f..0000000 --- a/docs/api/plugin/youtube/functions/default.md +++ /dev/null @@ -1,25 +0,0 @@ -# default() - -```ts -default($prefs?): Plugin -``` - -Adds support for embedding YouTube videos with imgit. - -## Parameters - -• **$prefs?**: [`Prefs`](../type-aliases/Prefs.md) - -## Returns - -[`Plugin`](../../../server/type-aliases/Plugin.md) - -## Example - -```md - ![](https://www.youtube.com/watch?v=arbuYnJoLtU) - ``` - -## Source - -[plugin/youtube/server.ts:27](https://github.com/Elringus/Imgit/blob/fc320a2/src/plugin/youtube/server.ts#L27) diff --git a/docs/api/plugin/youtube/index.md b/docs/api/plugin/youtube/index.md deleted file mode 100644 index fa3c918..0000000 --- a/docs/api/plugin/youtube/index.md +++ /dev/null @@ -1,11 +0,0 @@ -# plugin/youtube - -## Index - -### Type Aliases - -- [Prefs](type-aliases/Prefs.md) - -### Functions - -- [default](functions/default.md) diff --git a/docs/api/plugin/youtube/type-aliases/Prefs.md b/docs/api/plugin/youtube/type-aliases/Prefs.md deleted file mode 100644 index ef9c147..0000000 --- a/docs/api/plugin/youtube/type-aliases/Prefs.md +++ /dev/null @@ -1,29 +0,0 @@ -# Prefs - -```ts -type Prefs: Object; -``` - -YouTube plugin preferences. - -## Type declaration - -### banner? - -```ts -banner?: boolean; -``` - -Whether to show "Watch on YouTube" banner; enabled by default. - -### title? - -```ts -title?: boolean; -``` - -Whether to show captured alt syntax as video title; enabled by default. - -## Source - -[plugin/youtube/server.ts:5](https://github.com/Elringus/Imgit/blob/fc320a2/src/plugin/youtube/server.ts#L5) diff --git a/docs/api/server/functions/boot.md b/docs/api/server/functions/boot.md deleted file mode 100644 index 3824053..0000000 --- a/docs/api/server/functions/boot.md +++ /dev/null @@ -1,25 +0,0 @@ -# boot() - -```ts -boot(prefs?, platform?): Promise -``` - -Initializes build context with specified options. - -## Parameters - -• **prefs?**: [`Prefs`](../type-aliases/Prefs.md) - -Build preferences; will use pre-defined defaults when not assigned. - -• **platform?**: [`Platform`](../type-aliases/Platform.md) - -Runtime APIs to use; will attempt to detect automatically when not assigned. - -## Returns - -`Promise`\<`void`\> - -## Source - -[server/index.ts:17](https://github.com/Elringus/Imgit/blob/fc320a2/src/server/index.ts#L17) diff --git a/docs/api/server/functions/configure.md b/docs/api/server/functions/configure.md deleted file mode 100644 index 9ff6bfe..0000000 --- a/docs/api/server/functions/configure.md +++ /dev/null @@ -1,19 +0,0 @@ -# configure() - -```ts -configure(prefs): void -``` - -Specifies current build configuration. - -## Parameters - -• **prefs**: [`Prefs`](../type-aliases/Prefs.md) - -## Returns - -`void` - -## Source - -[server/config/index.ts:14](https://github.com/Elringus/Imgit/blob/fc320a2/src/server/config/index.ts#L14) diff --git a/docs/api/server/functions/createDefaults.md b/docs/api/server/functions/createDefaults.md deleted file mode 100644 index 37d6ab0..0000000 --- a/docs/api/server/functions/createDefaults.md +++ /dev/null @@ -1,15 +0,0 @@ -# createDefaults() - -```ts -createDefaults(): Readonly -``` - -Creates default build server configuration. - -## Returns - -`Readonly`\<[`Options`](../type-aliases/Options.md)\> - -## Source - -[server/config/defaults.ts:7](https://github.com/Elringus/Imgit/blob/fc320a2/src/server/config/defaults.ts#L7) diff --git a/docs/api/server/functions/exit.md b/docs/api/server/functions/exit.md deleted file mode 100644 index 13e8268..0000000 --- a/docs/api/server/functions/exit.md +++ /dev/null @@ -1,15 +0,0 @@ -# exit() - -```ts -exit(): Promise -``` - -Resets build context and caches results. - -## Returns - -`Promise`\<`void`\> - -## Source - -[server/index.ts:24](https://github.com/Elringus/Imgit/blob/fc320a2/src/server/index.ts#L24) diff --git a/docs/api/server/functions/resetConfig.md b/docs/api/server/functions/resetConfig.md deleted file mode 100644 index 8ee9dcf..0000000 --- a/docs/api/server/functions/resetConfig.md +++ /dev/null @@ -1,15 +0,0 @@ -# resetConfig() - -```ts -resetConfig(): void -``` - -Resets the configuration to defaults. - -## Returns - -`void` - -## Source - -[server/config/index.ts:20](https://github.com/Elringus/Imgit/blob/fc320a2/src/server/config/index.ts#L20) diff --git a/docs/api/server/functions/transform.md b/docs/api/server/functions/transform.md deleted file mode 100644 index 12943c2..0000000 --- a/docs/api/server/functions/transform.md +++ /dev/null @@ -1,28 +0,0 @@ -# transform() - -```ts -transform(content, id?): Promise -``` - -Transforms source document (eg, `.md`, `.jsx` or `.html`) - with specified content replacing configured asset syntax with optimized HTML. - -## Parameters - -• **content**: `string` - -Text content of the document to transform. - -• **id?**: `string` - -Document's file name or another identifier in the context of build procedure. - -## Returns - -`Promise`\<`string`\> - -Transformed content of the document. - -## Source - -[server/transform/index.ts:25](https://github.com/Elringus/Imgit/blob/fc320a2/src/server/transform/index.ts#L25) diff --git a/docs/api/server/index.md b/docs/api/server/index.md deleted file mode 100644 index 6c3cf3b..0000000 --- a/docs/api/server/index.md +++ /dev/null @@ -1,48 +0,0 @@ -# server - -## Index - -### Type Aliases - -- [AssetSpec](type-aliases/AssetSpec.md) -- [AssetSyntax](type-aliases/AssetSyntax.md) -- [BuiltAsset](type-aliases/BuiltAsset.md) -- [Cache](type-aliases/Cache.md) -- [CacheOptions](type-aliases/CacheOptions.md) -- [CapturedAsset](type-aliases/CapturedAsset.md) -- [ContentInfo](type-aliases/ContentInfo.md) -- [EncodeOptions](type-aliases/EncodeOptions.md) -- [EncodeSpec](type-aliases/EncodeSpec.md) -- [EncodeSpecMap](type-aliases/EncodeSpecMap.md) -- [EncodedAsset](type-aliases/EncodedAsset.md) -- [EncodedContent](type-aliases/EncodedContent.md) -- [FetchOptions](type-aliases/FetchOptions.md) -- [FetchedAsset](type-aliases/FetchedAsset.md) -- [FetchedContent](type-aliases/FetchedContent.md) -- [Options](type-aliases/Options.md) -- [Platform](type-aliases/Platform.md) -- [Plugin](type-aliases/Plugin.md) -- [PluginInjection](type-aliases/PluginInjection.md) -- [Prefs](type-aliases/Prefs.md) -- [ProbedAsset](type-aliases/ProbedAsset.md) -- [ProbedContent](type-aliases/ProbedContent.md) -- [ResolvedAsset](type-aliases/ResolvedAsset.md) -- [ResolvedContent](type-aliases/ResolvedContent.md) - -### Variables - -- [cache](variables/cache.md) -- [cfg](variables/cfg.md) -- [ctx](variables/ctx.md) -- [defaults](variables/defaults.md) -- [stages](variables/stages.md) -- [std](variables/std.md) - -### Functions - -- [boot](functions/boot.md) -- [configure](functions/configure.md) -- [createDefaults](functions/createDefaults.md) -- [exit](functions/exit.md) -- [resetConfig](functions/resetConfig.md) -- [transform](functions/transform.md) diff --git a/docs/api/server/type-aliases/AssetSpec.md b/docs/api/server/type-aliases/AssetSpec.md deleted file mode 100644 index 717d896..0000000 --- a/docs/api/server/type-aliases/AssetSpec.md +++ /dev/null @@ -1,65 +0,0 @@ -# AssetSpec - -```ts -type AssetSpec: Object; -``` - -Per-asset specifications assigned by the user. - -## Type declaration - -### class? - -```ts -class?: string; -``` - -When specified, adds specified class attribute to generated HTML container. - -### eager? - -```ts -eager?: boolean; -``` - -When set to `true` the asset will be loaded eagerly (instead of default lazy). - Use for above the fold content, ie initially visible w/o scrolling, such as hero image. - -### media? - -```ts -media?: string; -``` - -Media attribute to specify for applicable source tag. Can be used with the "merge" spec - for art direction. Example below will show "wide.png" when window width is 800px or more - and switch to "narrow.png" when the window width is equal to or below 799px. - -#### Example - -```md - ![?media=(min-width:800px)](/wide.png) - ![?media=(max-width:799px)&merge](/narrow.png) - ``` - -### merge? - -```ts -merge?: boolean; -``` - -When set to `true` syntax will be merged with the previous one in the document. - Can be used to specify multiple sources with different specs for a single asset. - -### width? - -```ts -width?: number; -``` - -Width threshold for the asset content, in pixels. - Overrides global `width` parameter. - -## Source - -[server/asset.ts:37](https://github.com/Elringus/Imgit/blob/fc320a2/src/server/asset.ts#L37) diff --git a/docs/api/server/type-aliases/AssetSyntax.md b/docs/api/server/type-aliases/AssetSyntax.md deleted file mode 100644 index 0075645..0000000 --- a/docs/api/server/type-aliases/AssetSyntax.md +++ /dev/null @@ -1,54 +0,0 @@ -# AssetSyntax - -```ts -type AssetSyntax: Object; -``` - -Asset syntax captured from transformed document. - -## Type declaration - -### alt? - -```ts -alt?: string; -``` - -Optional alternate text from captured syntax. - -### index - -```ts -index: number; -``` - -First index of the captured syntax text inside transformed document content. - -### spec? - -```ts -spec?: string; -``` - -Optional raw (un-parsed) user-defined asset specifications from captured syntax. - -### text - -```ts -text: string; -``` - -Full text of the captured syntax. - -### url - -```ts -url: string; -``` - -URL from captured syntax; may be direct location of the asset's source content (eg, image link) - or endpoint for resolving the content, such as REST API or YouTube link. - -## Source - -[server/asset.ts:8](https://github.com/Elringus/Imgit/blob/fc320a2/src/server/asset.ts#L8) diff --git a/docs/api/server/type-aliases/BuiltAsset.md b/docs/api/server/type-aliases/BuiltAsset.md deleted file mode 100644 index 827d430..0000000 --- a/docs/api/server/type-aliases/BuiltAsset.md +++ /dev/null @@ -1,21 +0,0 @@ -# BuiltAsset - -```ts -type BuiltAsset: EncodedAsset & Object; -``` - -Final product of asset transformation with associated HTML. - -## Type declaration - -### html - -```ts -html: string; -``` - -Transformed asset syntax in HTML form. - -## Source - -[server/asset.ts:117](https://github.com/Elringus/Imgit/blob/fc320a2/src/server/asset.ts#L117) diff --git a/docs/api/server/type-aliases/Cache.md b/docs/api/server/type-aliases/Cache.md deleted file mode 100644 index 492898c..0000000 --- a/docs/api/server/type-aliases/Cache.md +++ /dev/null @@ -1,46 +0,0 @@ -# Cache - -```ts -type Cache: Record & Object; -``` - -Cached results of the build operations. Each property is persisted as a - standalone JSON file between build runs. Custom properties can be added. - -## Type declaration - -### covers - -```ts -covers: Record; -``` - -Base64-encoded generated cover images mapped by asset's syntax URL. - -### probes - -```ts -probes: Record; -``` - -Results of the asset source content probing, mapped by content URL. - -### sizes - -```ts -sizes: Record; -``` - -Sizes of the asset source content in bytes, mapped by content URL. - -### specs - -```ts -specs: Record; -``` - -Encode specifications used for the last encode pass, mapped by content URL. - -## Source - -[server/cache.ts:7](https://github.com/Elringus/Imgit/blob/fc320a2/src/server/cache.ts#L7) diff --git a/docs/api/server/type-aliases/CacheOptions.md b/docs/api/server/type-aliases/CacheOptions.md deleted file mode 100644 index 7155c4e..0000000 --- a/docs/api/server/type-aliases/CacheOptions.md +++ /dev/null @@ -1,23 +0,0 @@ -# CacheOptions - -```ts -type CacheOptions: Object; -``` - -Configures server cache. - -## Type declaration - -### root - -```ts -root: string; -``` - -Local directory where the build cache files are stored. When building static apps (SPA) on CI, - consider checking-in the cache directory to boost remote build processes; - `./public/imgit` by default. - -## Source - -[server/config/options.ts:35](https://github.com/Elringus/Imgit/blob/fc320a2/src/server/config/options.ts#L35) diff --git a/docs/api/server/type-aliases/CapturedAsset.md b/docs/api/server/type-aliases/CapturedAsset.md deleted file mode 100644 index ccb814a..0000000 --- a/docs/api/server/type-aliases/CapturedAsset.md +++ /dev/null @@ -1,21 +0,0 @@ -# CapturedAsset - -```ts -type CapturedAsset: Object; -``` - -Asset captured from transformed document. - -## Type declaration - -### syntax - -```ts -syntax: AssetSyntax; -``` - -Syntax of the captured asset. - -## Source - -[server/asset.ts:2](https://github.com/Elringus/Imgit/blob/fc320a2/src/server/asset.ts#L2) diff --git a/docs/api/server/type-aliases/ContentInfo.md b/docs/api/server/type-aliases/ContentInfo.md deleted file mode 100644 index 0dd9d16..0000000 --- a/docs/api/server/type-aliases/ContentInfo.md +++ /dev/null @@ -1,45 +0,0 @@ -# ContentInfo - -```ts -type ContentInfo: Object; -``` - -Result of probing a content file. - -## Type declaration - -### alpha? - -```ts -alpha?: boolean; -``` - -Whether the media content has alpha channel (transparency). - -### height - -```ts -height: number; -``` - -Height of the media content, in pixels. - -### type - -```ts -type: string; -``` - -MIME type of the media content. - -### width - -```ts -width: number; -``` - -Width of the media content, in pixels. - -## Source - -[server/asset.ts:87](https://github.com/Elringus/Imgit/blob/fc320a2/src/server/asset.ts#L87) diff --git a/docs/api/server/type-aliases/EncodeOptions.md b/docs/api/server/type-aliases/EncodeOptions.md deleted file mode 100644 index 159098f..0000000 --- a/docs/api/server/type-aliases/EncodeOptions.md +++ /dev/null @@ -1,76 +0,0 @@ -# EncodeOptions - -```ts -type EncodeOptions: Object; -``` - -Configures assets encoding. - -## Type declaration - -### cover - -```ts -cover: Object | null; -``` - -Configure cover generation. By default, a tiny blurred webp cover is generated from source - content and embedded as base64-encoded data for image HTML, which is shown while the source - content is lazy-loading; specify `null` to disable cover generation. - -### dense - -```ts -dense: Object | null; -``` - -Configure dense files generation, that is variants with x the resolution of the main content - shown on high-dpi displays. Dense variants are generated when either global or per-asset spec - "width" option is specified with value less than the source content width by x or more; - x is configured via 'factor' parameter; assign `null` to disable dense generation. - -### main - -```ts -main: Object; -``` - -Configure main encoded file generation, ie file to replace source content in the built HTML. - -### main.specs - -```ts -main.specs: EncodeSpecMap; -``` - -Encode parameters mapped by source content MIME type; matched in order. - -### main.suffix - -```ts -main.suffix: string; -``` - -Tag to append to the names of generated main files; `@main` by default. - -### root - -```ts -root: string; -``` - -Local directory to store encoded content and generated files, such as covers; - `./public/imgit/encoded` by default. - -### safe - -```ts -safe: Object | null; -``` - -Configure safe files generation, that is fallbacks used in case source content is not considered - compatible with legacy or any browsers, such as AVIF or PSD; specify `null` to disable. - -## Source - -[server/config/options.ts:56](https://github.com/Elringus/Imgit/blob/fc320a2/src/server/config/options.ts#L56) diff --git a/docs/api/server/type-aliases/EncodeSpec.md b/docs/api/server/type-aliases/EncodeSpec.md deleted file mode 100644 index 373c676..0000000 --- a/docs/api/server/type-aliases/EncodeSpec.md +++ /dev/null @@ -1,53 +0,0 @@ -# EncodeSpec - -```ts -type EncodeSpec: Object; -``` - -Configures transformation to use when encoding. - -## Type declaration - -### blur? - -```ts -blur?: number; -``` - -Apply blur with intensity in 0.0 to 1.0 range. - -### codec? - -```ts -codec?: string; -``` - -Video codec to use; detects automatically based on container when not specified. - -### ext - -```ts -ext: string; -``` - -Media container to use in format of out file extension, w/o dot; eg, `mp4`. - -### scale? - -```ts -scale?: number; -``` - -Scale to the specified ratio preserving the aspect. - -### select? - -```ts -select?: number; -``` - -Select frame with specified index (0-based) instead of encoding full stream. - -## Source - -[server/config/options.ts:105](https://github.com/Elringus/Imgit/blob/fc320a2/src/server/config/options.ts#L105) diff --git a/docs/api/server/type-aliases/EncodeSpecMap.md b/docs/api/server/type-aliases/EncodeSpecMap.md deleted file mode 100644 index e2fd59f..0000000 --- a/docs/api/server/type-aliases/EncodeSpecMap.md +++ /dev/null @@ -1,11 +0,0 @@ -# EncodeSpecMap - -```ts -type EncodeSpecMap: [string | Readonly, Readonly][]; -``` - -Encode parameters mapped by source content MIME type or regex of the type. - -## Source - -[server/config/options.ts:119](https://github.com/Elringus/Imgit/blob/fc320a2/src/server/config/options.ts#L119) diff --git a/docs/api/server/type-aliases/EncodedAsset.md b/docs/api/server/type-aliases/EncodedAsset.md deleted file mode 100644 index 17534a6..0000000 --- a/docs/api/server/type-aliases/EncodedAsset.md +++ /dev/null @@ -1,21 +0,0 @@ -# EncodedAsset - -```ts -type EncodedAsset: ProbedAsset & Object; -``` - -Asset with all the applicable encoded/generated content available on local file system. - -## Type declaration - -### content - -```ts -content: EncodedContent; -``` - -Source content of the asset. - -## Source - -[server/asset.ts:99](https://github.com/Elringus/Imgit/blob/fc320a2/src/server/asset.ts#L99) diff --git a/docs/api/server/type-aliases/EncodedContent.md b/docs/api/server/type-aliases/EncodedContent.md deleted file mode 100644 index 5230249..0000000 --- a/docs/api/server/type-aliases/EncodedContent.md +++ /dev/null @@ -1,45 +0,0 @@ -# EncodedContent - -```ts -type EncodedContent: ProbedContent & Object; -``` - -Optimized source of an asset with optional generated content. - -## Type declaration - -### cover? - -```ts -cover?: string; -``` - -Generated variant of the source content to cover loading process, when applicable. - -### dense? - -```ts -dense?: string; -``` - -Generated variant of the source content for high-dpi displays, when applicable. - -### encoded - -```ts -encoded: string; -``` - -Full path to the asset's encoded/optimized content file on local file system. - -### safe? - -```ts -safe?: string; -``` - -Generated variant of the source content for compatibility/fallback, when applicable. - -## Source - -[server/asset.ts:105](https://github.com/Elringus/Imgit/blob/fc320a2/src/server/asset.ts#L105) diff --git a/docs/api/server/type-aliases/FetchOptions.md b/docs/api/server/type-aliases/FetchOptions.md deleted file mode 100644 index d54aa2f..0000000 --- a/docs/api/server/type-aliases/FetchOptions.md +++ /dev/null @@ -1,46 +0,0 @@ -# FetchOptions - -```ts -type FetchOptions: Object; -``` - -Configures remote assets downloading behaviour. - -## Type declaration - -### delay - -```ts -delay: number; -``` - -How long to wait before restarting a failed download, in seconds; 6 by default. - -### retries - -```ts -retries: number; -``` - -How many times to restart the download when request fails; 3 by default. - -### root - -```ts -root: string; -``` - -Local directory to store downloaded remote content files; - `./public/imgit/fetched` by default. - -### timeout - -```ts -timeout: number; -``` - -How long to wait when downloading remote asset, in seconds; 30 by default. - -## Source - -[server/config/options.ts:43](https://github.com/Elringus/Imgit/blob/fc320a2/src/server/config/options.ts#L43) diff --git a/docs/api/server/type-aliases/FetchedAsset.md b/docs/api/server/type-aliases/FetchedAsset.md deleted file mode 100644 index bcb007a..0000000 --- a/docs/api/server/type-aliases/FetchedAsset.md +++ /dev/null @@ -1,29 +0,0 @@ -# FetchedAsset - -```ts -type FetchedAsset: ResolvedAsset & Object; -``` - -Asset with all the applicable source content files available on the local file system. - -## Type declaration - -### content - -```ts -content: FetchedContent; -``` - -Source content of the asset. - -### dirty? - -```ts -dirty?: boolean; -``` - -Whether any of the source content files were modified since last build. - -## Source - -[server/asset.ts:61](https://github.com/Elringus/Imgit/blob/fc320a2/src/server/asset.ts#L61) diff --git a/docs/api/server/type-aliases/FetchedContent.md b/docs/api/server/type-aliases/FetchedContent.md deleted file mode 100644 index d7c95c7..0000000 --- a/docs/api/server/type-aliases/FetchedContent.md +++ /dev/null @@ -1,21 +0,0 @@ -# FetchedContent - -```ts -type FetchedContent: ResolvedContent & Object; -``` - -Fetched source content of an asset. - -## Type declaration - -### local - -```ts -local: string; -``` - -Full path to the asset's source content file on local file system. - -## Source - -[server/asset.ts:69](https://github.com/Elringus/Imgit/blob/fc320a2/src/server/asset.ts#L69) diff --git a/docs/api/server/type-aliases/Options.md b/docs/api/server/type-aliases/Options.md deleted file mode 100644 index 2f97885..0000000 --- a/docs/api/server/type-aliases/Options.md +++ /dev/null @@ -1,94 +0,0 @@ -# Options - -```ts -type Options: Object; -``` - -Configures server behaviour. - -## Type declaration - -### build - -```ts -build: "html" | "jsx"; -``` - -The type of syntax to build; html by default. - -### cache - -```ts -cache: CacheOptions | null; -``` - -Configure build artifacts caching; assign `null` to disable caching. - -### cover? - -```ts -cover?: string | null; -``` - -Image source to show while content is loading. When per-asset cover generation is enabled - in encode options, will use specified source as a fallback for legacy browsers (lacking avif support), - otherwise will use the source for all covers; assign `null` to disable covers completely. - -### encode - -```ts -encode: EncodeOptions; -``` - -Configure content encoding. - -### fetch - -```ts -fetch: FetchOptions; -``` - -Configure remote content fetching. - -### plugins - -```ts -plugins: Plugin[]; -``` - -External imgit extensions; use to override or extend server behaviour. - -### regex - -```ts -regex: RegExp[]; -``` - -Regular expressions to use for capturing transformed assets syntax. - Expects ``, `` and `` capture groups (alt and spec are optional). - By default, captures Markdown image syntax with spec defined as query params after alt: - `!\[(?.*?)(?\?\S+?)?]\((?\S+?)\)` - -### root - -```ts -root: string; -``` - -Local directory under which project's static files are stored. Required to resolve - file paths of relative content sources; `./public` by default. - -### width - -```ts -width: number | null; -``` - -Default width threshold for the transformed assets, in pixels. When source asset is larger, - will downscale it while preserving the original aspect. In case the source is 2x or larger, - will as well generate additional "dense" variant that will be shown on high-dpi displays. - This option is ignored when asset has width explicitly assigned via spec syntax. - -## Source - -[server/config/options.ts:4](https://github.com/Elringus/Imgit/blob/fc320a2/src/server/config/options.ts#L4) diff --git a/docs/api/server/type-aliases/Platform.md b/docs/api/server/type-aliases/Platform.md deleted file mode 100644 index 2a76921..0000000 --- a/docs/api/server/type-aliases/Platform.md +++ /dev/null @@ -1,383 +0,0 @@ -# Platform - -```ts -type Platform: Record & Object; -``` - -Platform-specific APIs used in build operations. - -## Type declaration - -### base64 - -```ts -base64: (data) => Promise; -``` - -Encodes specified binary data to base64 string. - -#### Parameters - -• **data**: `Uint8Array` - -#### Returns - -`Promise`\<`string`\> - -### exec - -```ts -exec: (cmd) => Promise; -``` - -Executes specified command in system shell. - -#### Parameters - -• **cmd**: `string` - -#### Returns - -`Promise`\<`Object`\> - -> ##### err? -> -> ```ts -> err?: Error; -> ``` -> -> ##### out -> -> ```ts -> out: string; -> ``` -> - -### fetch - -```ts -fetch: (url, abort?) => Promise; -``` - -Fetches a remote resource with specified url. - -#### Parameters - -• **url**: `string` - -• **abort?**: `AbortSignal` - -#### Returns - -`Promise`\<`Response`\> - -### fs - -```ts -fs: Object; -``` - -Local file system access APIs. - -### fs.exists - -```ts -fs.exists: (path) => Promise; -``` - -Returns whether directory or file with specified path exists. - -#### Parameters - -• **path**: `string` - -#### Returns - -`Promise`\<`boolean`\> - -### fs.mkdir - -```ts -fs.mkdir: (path) => Promise; -``` - -Creates directory with specified path (recursive). - -#### Parameters - -• **path**: `string` - -#### Returns - -`Promise`\<`void`\> - -### fs.read - -```ts -fs.read: (path, encoding) => Promise; -``` - -Returns content of the file with specified path and encoding. - -#### Type parameters - -• **T** extends `"bin"` \| `"utf8"` - -#### Parameters - -• **path**: `string` - -• **encoding**: `T` - -#### Returns - -`Promise`\<`T` extends `"bin"` ? `Uint8Array` : `string`\> - -### fs.remove - -```ts -fs.remove: (path) => Promise; -``` - -Deletes file with specified path. - -#### Parameters - -• **path**: `string` - -#### Returns - -`Promise`\<`void`\> - -### fs.size - -```ts -fs.size: (path) => Promise; -``` - -Returns size of the file with specified path, in bytes. - -#### Parameters - -• **path**: `string` - -#### Returns - -`Promise`\<`number`\> - -### fs.write - -```ts -fs.write: (path, content) => Promise; -``` - -Writes binary array or UTF-8 encoded string to the file with specified path. - -#### Parameters - -• **path**: `string` - -• **content**: `Uint8Array` \| `string` - -#### Returns - -`Promise`\<`void`\> - -### log - -```ts -log: Object; -``` - -Logging and reporting APIs. - -### log.err - -```ts -log.err: (msg) => void; -``` - -Logs error message. - -#### Parameters - -• **msg**: `string` - -#### Returns - -`void` - -### log.info - -```ts -log.info: (msg) => void; -``` - -Logs informational message. - -#### Parameters - -• **msg**: `string` - -#### Returns - -`void` - -### log.tty - -```ts -log.tty: (msg) => void; -``` - -Clears current line and writes to stdout when text terminal is available, - ignores otherwise; used for reporting build progress. - -#### Parameters - -• **msg**: `string` - -#### Returns - -`void` - -### log.warn - -```ts -log.warn: (msg) => void; -``` - -Logs warning message. - -#### Parameters - -• **msg**: `string` - -#### Returns - -`void` - -### path - -```ts -path: Object; -``` - -File system path APIs. All results are expected with forward slashes (even on Windows). - -### path.basename - -```ts -path.basename: (path) => string; -``` - -Extracts file name with extension from specified path. - -#### Parameters - -• **path**: `string` - -#### Returns - -`string` - -### path.dirname - -```ts -path.dirname: (path) => string; -``` - -Extracts directory name from specified path and normalizes the result. - -#### Parameters - -• **path**: `string` - -#### Returns - -`string` - -### path.fileUrlToPath - -```ts -path.fileUrlToPath: (url) => string; -``` - -Converts specified file URL (usually `import.meta.url`) to local file path. - -#### Parameters - -• **url**: `string` - -#### Returns - -`string` - -### path.join - -```ts -path.join: (...paths) => string; -``` - -Joins specified path parts and normalizes the result. - -#### Parameters - -• ...**paths**: `string`[] - -#### Returns - -`string` - -### path.relative - -```ts -path.relative: (from, to) => string; -``` - -Builds relative path from specified 'from' path to 'to' path. - -#### Parameters - -• **from**: `string` - -• **to**: `string` - -#### Returns - -`string` - -### path.resolve - -```ts -path.resolve: (...paths) => string; -``` - -Builds absolute path from specified parts and normalizes the result. - -#### Parameters - -• ...**paths**: `string`[] - -#### Returns - -`string` - -### wait - -```ts -wait: (seconds) => Promise; -``` - -Returns promise resolved after specified number of seconds. - -#### Parameters - -• **seconds**: `number` - -#### Returns - -`Promise`\<`void`\> - -## Source - -[server/platform/platform.ts:2](https://github.com/Elringus/Imgit/blob/fc320a2/src/server/platform/platform.ts#L2) diff --git a/docs/api/server/type-aliases/Plugin.md b/docs/api/server/type-aliases/Plugin.md deleted file mode 100644 index 1c7339c..0000000 --- a/docs/api/server/type-aliases/Plugin.md +++ /dev/null @@ -1,183 +0,0 @@ -# Plugin - -```ts -type Plugin: Object; -``` - -External imgit extension. - -## Type declaration - -### build? - -```ts -build?: (asset, merges?) => boolean | Promise; -``` - -Custom asset HTML builder. Given encoded asset(s), build HTML (in-place for all the input - assets) to replace captured syntax in the transformed document. May include additional merged - assets when associated syntax were joined via "merge" spec. Return false when the builder can't - handle the assets, in which case they'll be handled by next builders in the plugin chain. - -#### Parameters - -• **asset**: [`BuiltAsset`](BuiltAsset.md) - -• **merges?**: [`BuiltAsset`](BuiltAsset.md)[] - -#### Returns - -`boolean` \| `Promise`\<`boolean`\> - -### capture? - -```ts -capture?: (content, assets, id?) => boolean | Promise; -``` - -Custom procedure to capture asset syntax. Given id (filename) and content (text) of transformed document - populate provided assets array and return true or return false when can't handle the document, - in which case it'll be handled by next procedures in the plugin chain. - -#### Parameters - -• **content**: `string` - -• **assets**: [`CapturedAsset`](CapturedAsset.md)[] - -• **id?**: `string` - -#### Returns - -`boolean` \| `Promise`\<`boolean`\> - -### encode? - -```ts -encode?: (asset) => boolean | Promise; -``` - -Custom content encoder. Given probed asset, encodes and assigns full file paths to the encoded content - files (in-place). Return false when the implementation can't encode the asset, - in which case it'll be handled by next encoders in the plugin chain. - -#### Parameters - -• **asset**: [`EncodedAsset`](EncodedAsset.md) - -#### Returns - -`boolean` \| `Promise`\<`boolean`\> - -### fetch? - -```ts -fetch?: (asset) => boolean | Promise; -``` - -Custom asset downloader. Given resolved asset, fetches source content and assigns file's full path on - local file system to the asset (in-place). Return false when the fetcher can't handle the asset, - in which case it'll be handled by next fetchers in the plugin chain. - -#### Parameters - -• **asset**: [`FetchedAsset`](FetchedAsset.md) - -#### Returns - -`boolean` \| `Promise`\<`boolean`\> - -### inject? - -```ts -inject?: () => PluginInjection[]; -``` - -When specified, will inject specified client-side content when plugged to bundlers. - -#### Returns - -[`PluginInjection`](PluginInjection.md)[] - -### probe? - -```ts -probe?: (asset) => boolean | Promise; -``` - -Custom content info resolver. Given fetched asset, resolves and assigns media content - information (in-place). Return false when the implementation can't or shouldn't handle the asset, - in which case it'll be handled by next probe handlers in the plugin chain. - -#### Parameters - -• **asset**: [`ProbedAsset`](ProbedAsset.md) - -#### Returns - -`boolean` \| `Promise`\<`boolean`\> - -### resolve? - -```ts -resolve?: (asset) => boolean | Promise; -``` - -Custom asset resolver. Given captured asset syntax, resolves asset type, - content locations and specs (in-place). Return false when the resolver can't - handle the asset, in which case it'll be handled by next resolvers in the plugin chain. - -#### Parameters - -• **asset**: [`ResolvedAsset`](ResolvedAsset.md) - -#### Returns - -`boolean` \| `Promise`\<`boolean`\> - -### rewrite? - -```ts -rewrite?: (content, assets, id?) => string | null | Promise; -``` - -Custom procedure to rewrite captured assets syntax with built HTML. Given id (filename) and - content (text) of transformed document return overwritten content or false when can't handle the case, - in which case it'll be handled by next procedures in the plugin chain. - -#### Parameters - -• **content**: `string` - -• **assets**: [`BuiltAsset`](BuiltAsset.md)[] - -• **id?**: `string` - -#### Returns - -`string` \| `null` \| `Promise`\<`string` \| `null`\> - -### serve? - -```ts -serve?: (path, asset) => null | Promise; -``` - -Custom asset server. Given full path to a content file and associated asset info, - return URL under which the file will be served and prepare the file to be served (eg, copy to - the static assets dir or upload to a CDN). Return null when the server can't - handle the asset, in which case it'll be handled by next servers in the plugin chain. - -#### Parameters - -• **path**: `string` - -• **asset**: `Readonly`\<[`BuiltAsset`](BuiltAsset.md)\> - -#### Returns - -`null` \| `Promise`\<`string` \| `null`\> - -## Source - -[server/config/plugin.ts:4](https://github.com/Elringus/Imgit/blob/fc320a2/src/server/config/plugin.ts#L4) diff --git a/docs/api/server/type-aliases/PluginInjection.md b/docs/api/server/type-aliases/PluginInjection.md deleted file mode 100644 index 46ae6b7..0000000 --- a/docs/api/server/type-aliases/PluginInjection.md +++ /dev/null @@ -1,29 +0,0 @@ -# PluginInjection - -```ts -type PluginInjection: Object; -``` - -Used to inject client-side content for a plugin. - -## Type declaration - -### src - -```ts -src: string; -``` - -Full path to the injected file on local file system. - -### type - -```ts -type: "module" | "css"; -``` - -Whether injected content is a JS module or CSS stylesheet. - -## Source - -[server/config/plugin.ts:44](https://github.com/Elringus/Imgit/blob/fc320a2/src/server/config/plugin.ts#L44) diff --git a/docs/api/server/type-aliases/Prefs.md b/docs/api/server/type-aliases/Prefs.md deleted file mode 100644 index 6f862c6..0000000 --- a/docs/api/server/type-aliases/Prefs.md +++ /dev/null @@ -1,11 +0,0 @@ -# Prefs - -```ts -type Prefs: { [P in keyof Options]?: Partial }; -``` - -User-defined build preferences. - -## Source - -[server/config/index.ts:8](https://github.com/Elringus/Imgit/blob/fc320a2/src/server/config/index.ts#L8) diff --git a/docs/api/server/type-aliases/ProbedAsset.md b/docs/api/server/type-aliases/ProbedAsset.md deleted file mode 100644 index 84c47e8..0000000 --- a/docs/api/server/type-aliases/ProbedAsset.md +++ /dev/null @@ -1,21 +0,0 @@ -# ProbedAsset - -```ts -type ProbedAsset: FetchedAsset & Object; -``` - -Asset with identified source content. - -## Type declaration - -### content - -```ts -content: ProbedContent; -``` - -Source content of the asset. - -## Source - -[server/asset.ts:75](https://github.com/Elringus/Imgit/blob/fc320a2/src/server/asset.ts#L75) diff --git a/docs/api/server/type-aliases/ProbedContent.md b/docs/api/server/type-aliases/ProbedContent.md deleted file mode 100644 index 7fc4b19..0000000 --- a/docs/api/server/type-aliases/ProbedContent.md +++ /dev/null @@ -1,21 +0,0 @@ -# ProbedContent - -```ts -type ProbedContent: FetchedContent & Object; -``` - -Identified source content of an asset. - -## Type declaration - -### info - -```ts -info: ContentInfo; -``` - -Media info about the probed source content. - -## Source - -[server/asset.ts:81](https://github.com/Elringus/Imgit/blob/fc320a2/src/server/asset.ts#L81) diff --git a/docs/api/server/type-aliases/ResolvedAsset.md b/docs/api/server/type-aliases/ResolvedAsset.md deleted file mode 100644 index 437f429..0000000 --- a/docs/api/server/type-aliases/ResolvedAsset.md +++ /dev/null @@ -1,29 +0,0 @@ -# ResolvedAsset - -```ts -type ResolvedAsset: CapturedAsset & Object; -``` - -Asset with resolved source content locations and specs. - -## Type declaration - -### content - -```ts -content: ResolvedContent; -``` - -Source content of the asset. - -### spec - -```ts -spec: AssetSpec; -``` - -Optional user-defined asset specifications resolved (parsed) from captured syntax. - -## Source - -[server/asset.ts:23](https://github.com/Elringus/Imgit/blob/fc320a2/src/server/asset.ts#L23) diff --git a/docs/api/server/type-aliases/ResolvedContent.md b/docs/api/server/type-aliases/ResolvedContent.md deleted file mode 100644 index c79e570..0000000 --- a/docs/api/server/type-aliases/ResolvedContent.md +++ /dev/null @@ -1,21 +0,0 @@ -# ResolvedContent - -```ts -type ResolvedContent: Object; -``` - -Source content of an asset resolved from captured syntax. - -## Type declaration - -### src - -```ts -src: string; -``` - -Location (absolute or relative URL) of the source content file. - -## Source - -[server/asset.ts:31](https://github.com/Elringus/Imgit/blob/fc320a2/src/server/asset.ts#L31) diff --git a/docs/api/server/variables/cache.md b/docs/api/server/variables/cache.md deleted file mode 100644 index 230d32d..0000000 --- a/docs/api/server/variables/cache.md +++ /dev/null @@ -1,11 +0,0 @@ -# cache - -```ts -const cache: Cache = empty; -``` - -Cached results of the build operations. - -## Source - -[server/cache.ts:21](https://github.com/Elringus/Imgit/blob/fc320a2/src/server/cache.ts#L21) diff --git a/docs/api/server/variables/cfg.md b/docs/api/server/variables/cfg.md deleted file mode 100644 index d6ccc6c..0000000 --- a/docs/api/server/variables/cfg.md +++ /dev/null @@ -1,11 +0,0 @@ -# cfg - -```ts -cfg: Readonly; -``` - -Current build configuration. - -## Source - -[server/config/index.ts:11](https://github.com/Elringus/Imgit/blob/fc320a2/src/server/config/index.ts#L11) diff --git a/docs/api/server/variables/ctx.md b/docs/api/server/variables/ctx.md deleted file mode 100644 index 389c85b..0000000 --- a/docs/api/server/variables/ctx.md +++ /dev/null @@ -1,45 +0,0 @@ -# ctx - -```ts -const ctx: Object; -``` - -Shared mutable state of the current build operation. - -## Type declaration - -### encodes - -```ts -encodes: Map>; -``` - -Encode operations mapped by source content location (URL) + encode target. - -### fetches - -```ts -fetches: Map>; -``` - -Fetched remote content mapped by source location (URL). - -### probes - -```ts -probes: Map>; -``` - -Probing operations mapped by source content location (URL). - -### retries - -```ts -retries: Map; -``` - -Fetch retry count mapped by fetched content location (URL). - -## Source - -[server/context.ts:4](https://github.com/Elringus/Imgit/blob/fc320a2/src/server/context.ts#L4) diff --git a/docs/api/server/variables/defaults.md b/docs/api/server/variables/defaults.md deleted file mode 100644 index 31106b0..0000000 --- a/docs/api/server/variables/defaults.md +++ /dev/null @@ -1,11 +0,0 @@ -# defaults - -```ts -const defaults: Readonly; -``` - -Default build server configuration. - -## Source - -[server/config/defaults.ts:4](https://github.com/Elringus/Imgit/blob/fc320a2/src/server/config/defaults.ts#L4) diff --git a/docs/api/server/variables/stages.md b/docs/api/server/variables/stages.md deleted file mode 100644 index 8fa260d..0000000 --- a/docs/api/server/variables/stages.md +++ /dev/null @@ -1,211 +0,0 @@ -# stages - -```ts -const stages: Object; -``` - -Individual document transformation stages. - -## Type declaration - -### build - -```ts -build: Object; -``` - -### build.CONTAINER\_ATTR - -```ts -build.CONTAINER_ATTR: string; -``` - -### build.asset - -```ts -build.asset: (asset, merges?) => Promise = build; -``` - -Default HTML builder for supported asset types (images and video). - -#### Parameters - -• **asset**: [`BuiltAsset`](../type-aliases/BuiltAsset.md) - -• **merges?**: [`BuiltAsset`](../type-aliases/BuiltAsset.md)[] - -#### Returns - -`Promise`\<`void`\> - -### build.source - -```ts -build.source: (path) => string = buildContentSource; -``` - -Builds serve url for content file with specified full path based on configured root option. - -#### Parameters - -• **path**: `string` - -#### Returns - -`string` - -### capture - -```ts -capture: Object; -``` - -### capture.assets - -```ts -capture.assets: (content, assets) => void = capture; -``` - -Uses regexp defined in options to capture the assets syntax. - -#### Parameters - -• **content**: `string` - -• **assets**: [`CapturedAsset`](../type-aliases/CapturedAsset.md)[] - -#### Returns - -`void` - -### encode - -```ts -encode: Object; -``` - -### encode.asset - -```ts -encode.asset: (asset) => Promise = encodeAsset; -``` - -Encodes asset content with ffmpeg. - -#### Parameters - -• **asset**: [`EncodedAsset`](../type-aliases/EncodedAsset.md) - -#### Returns - -`Promise`\<`void`\> - -### fetch - -```ts -fetch: Object; -``` - -### fetch.asset - -```ts -fetch.asset: (asset) => Promise = fetch; -``` - -Fetches asset's source content. - -#### Parameters - -• **asset**: [`FetchedAsset`](../type-aliases/FetchedAsset.md) - -#### Returns - -`Promise`\<`void`\> - -### probe - -```ts -probe: Object; -``` - -### probe.asset - -```ts -probe.asset: (asset) => Promise = probe; -``` - -Probes asset content with ffprobe. - -#### Parameters - -• **asset**: [`ProbedAsset`](../type-aliases/ProbedAsset.md) - -#### Returns - -`Promise`\<`void`\> - -### resolve - -```ts -resolve: Object; -``` - -### resolve.asset - -```ts -resolve.asset: (asset) => void = resolve; -``` - -Resolves asset types supported by default. - -#### Parameters - -• **asset**: [`ResolvedAsset`](../type-aliases/ResolvedAsset.md) - -#### Returns - -`void` - -### resolve.spec - -```ts -resolve.spec: (query) => AssetSpec = resolveSpec; -``` - -Resolves spec formatted as URL query parameters. - -#### Parameters - -• **query**: `string` - -#### Returns - -[`AssetSpec`](../type-aliases/AssetSpec.md) - -### rewrite - -```ts -rewrite: Object; -``` - -### rewrite.content - -```ts -rewrite.content: (content, assets) => string = rewrite; -``` - -Default rewrite procedure. - -#### Parameters - -• **content**: `string` - -• **assets**: [`BuiltAsset`](../type-aliases/BuiltAsset.md)[] - -#### Returns - -`string` - -## Source - -[server/transform/index.ts:10](https://github.com/Elringus/Imgit/blob/fc320a2/src/server/transform/index.ts#L10) diff --git a/docs/api/server/variables/std.md b/docs/api/server/variables/std.md deleted file mode 100644 index 0ee901f..0000000 --- a/docs/api/server/variables/std.md +++ /dev/null @@ -1,11 +0,0 @@ -# std - -```ts -const std: Readonly; -``` - -Platform-specific APIs. - -## Source - -[server/platform/index.ts:5](https://github.com/Elringus/Imgit/blob/fc320a2/src/server/platform/index.ts#L5) diff --git a/docs/api/typedoc-sidebar.json b/docs/api/typedoc-sidebar.json deleted file mode 100644 index 44c74e5..0000000 --- a/docs/api/typedoc-sidebar.json +++ /dev/null @@ -1 +0,0 @@ -[{"text":"plugin/astro","link":"/api/plugin/astro/index.md","collapsed":true,"items":[{"text":"Type Aliases","collapsed":true,"items":[{"text":"AstroInjector","link":"/api/plugin/astro/type-aliases/AstroInjector.md"},{"text":"AstroIntegration","link":"/api/plugin/astro/type-aliases/AstroIntegration.md"}]},{"text":"Functions","collapsed":true,"items":[{"text":"default","link":"/api/plugin/astro/functions/default.md"}]}]},{"text":"plugin/svg","link":"/api/plugin/svg/index.md","collapsed":true,"items":[{"text":"Functions","collapsed":true,"items":[{"text":"default","link":"/api/plugin/svg/functions/default.md"}]}]},{"text":"plugin/vite","link":"/api/plugin/vite/index.md","collapsed":true,"items":[{"text":"Type Aliases","collapsed":true,"items":[{"text":"HtmlTag","link":"/api/plugin/vite/type-aliases/HtmlTag.md"},{"text":"VitePlugin","link":"/api/plugin/vite/type-aliases/VitePlugin.md"},{"text":"VitePrefs","link":"/api/plugin/vite/type-aliases/VitePrefs.md"}]},{"text":"Functions","collapsed":true,"items":[{"text":"default","link":"/api/plugin/vite/functions/default.md"}]}]},{"text":"plugin/youtube","link":"/api/plugin/youtube/index.md","collapsed":true,"items":[{"text":"Type Aliases","collapsed":true,"items":[{"text":"Prefs","link":"/api/plugin/youtube/type-aliases/Prefs.md"}]},{"text":"Functions","collapsed":true,"items":[{"text":"default","link":"/api/plugin/youtube/functions/default.md"}]}]},{"text":"server","link":"/api/server/index.md","collapsed":true,"items":[{"text":"Type Aliases","collapsed":true,"items":[{"text":"AssetSpec","link":"/api/server/type-aliases/AssetSpec.md"},{"text":"AssetSyntax","link":"/api/server/type-aliases/AssetSyntax.md"},{"text":"BuiltAsset","link":"/api/server/type-aliases/BuiltAsset.md"},{"text":"Cache","link":"/api/server/type-aliases/Cache.md"},{"text":"CacheOptions","link":"/api/server/type-aliases/CacheOptions.md"},{"text":"CapturedAsset","link":"/api/server/type-aliases/CapturedAsset.md"},{"text":"ContentInfo","link":"/api/server/type-aliases/ContentInfo.md"},{"text":"EncodeOptions","link":"/api/server/type-aliases/EncodeOptions.md"},{"text":"EncodeSpec","link":"/api/server/type-aliases/EncodeSpec.md"},{"text":"EncodeSpecMap","link":"/api/server/type-aliases/EncodeSpecMap.md"},{"text":"EncodedAsset","link":"/api/server/type-aliases/EncodedAsset.md"},{"text":"EncodedContent","link":"/api/server/type-aliases/EncodedContent.md"},{"text":"FetchOptions","link":"/api/server/type-aliases/FetchOptions.md"},{"text":"FetchedAsset","link":"/api/server/type-aliases/FetchedAsset.md"},{"text":"FetchedContent","link":"/api/server/type-aliases/FetchedContent.md"},{"text":"Options","link":"/api/server/type-aliases/Options.md"},{"text":"Platform","link":"/api/server/type-aliases/Platform.md"},{"text":"Plugin","link":"/api/server/type-aliases/Plugin.md"},{"text":"PluginInjection","link":"/api/server/type-aliases/PluginInjection.md"},{"text":"Prefs","link":"/api/server/type-aliases/Prefs.md"},{"text":"ProbedAsset","link":"/api/server/type-aliases/ProbedAsset.md"},{"text":"ProbedContent","link":"/api/server/type-aliases/ProbedContent.md"},{"text":"ResolvedAsset","link":"/api/server/type-aliases/ResolvedAsset.md"},{"text":"ResolvedContent","link":"/api/server/type-aliases/ResolvedContent.md"}]},{"text":"Variables","collapsed":true,"items":[{"text":"cache","link":"/api/server/variables/cache.md"},{"text":"cfg","link":"/api/server/variables/cfg.md"},{"text":"ctx","link":"/api/server/variables/ctx.md"},{"text":"defaults","link":"/api/server/variables/defaults.md"},{"text":"stages","link":"/api/server/variables/stages.md"},{"text":"std","link":"/api/server/variables/std.md"}]},{"text":"Functions","collapsed":true,"items":[{"text":"boot","link":"/api/server/functions/boot.md"},{"text":"configure","link":"/api/server/functions/configure.md"},{"text":"createDefaults","link":"/api/server/functions/createDefaults.md"},{"text":"exit","link":"/api/server/functions/exit.md"},{"text":"resetConfig","link":"/api/server/functions/resetConfig.md"},{"text":"transform","link":"/api/server/functions/transform.md"}]}]}] \ No newline at end of file diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md index 7245626..54bee82 100644 --- a/docs/guide/getting-started.md +++ b/docs/guide/getting-started.md @@ -120,4 +120,4 @@ Find minimal sample on using imgit directly with Deno runtime on GitHub: https:/ ::: -Find available configuration options in the API reference. For available extension points (hooks), check out [plugins guide](/guide/plugins). +Find available configuration options in the [API reference](/api/server/type-aliases/Options.md). For available extension points (hooks), check out [plugins guide](/guide/plugins). diff --git a/docs/guide/plugins.md b/docs/guide/plugins.md index f3e2485..99aa595 100644 --- a/docs/guide/plugins.md +++ b/docs/guide/plugins.md @@ -53,3 +53,5 @@ import plugin from "./plugin.ts"; // Inject plugin object. await boot({ plugins: [plugin] }); ``` + +Find more about available plugin options in the [API reference](/api/server/type-aliases/Plugin). diff --git a/docs/scripts/api.sh b/docs/scripts/api.sh index f336715..1d5636b 100644 --- a/docs/scripts/api.sh +++ b/docs/scripts/api.sh @@ -3,6 +3,7 @@ echo '{ "entryPoints": [ "../src/server/index.ts", + "../src/client/index.ts", "../src/plugin/youtube/index.ts", "../src/plugin/svg.ts", "../src/plugin/astro.ts", diff --git a/src/client/index.ts b/src/client/index.ts index b5b7663..e13dc47 100644 --- a/src/client/index.ts +++ b/src/client/index.ts @@ -1,3 +1,5 @@ import { observeMutations } from "./mutation.js"; +export * as mutation from "./mutation.js"; + observeMutations(); diff --git a/src/client/mutation.ts b/src/client/mutation.ts index 893a93a..5b14d4d 100644 --- a/src/client/mutation.ts +++ b/src/client/mutation.ts @@ -3,17 +3,22 @@ import { observeVideo, unobserveVideo } from "./intersection.js"; const IMAGE_LOADED_EVENT = "load"; const VIDEO_LOADED_EVENT = "loadeddata"; -/** External mutation handlers. */ +/** External mutation handler. First tuple hook is invoked when an element is added + * to HTML document; second one — when removed. */ export type Handler = [(added: Element) => void, (removed: Element) => void]; const observer = canObserve() ? new MutationObserver(handleMutations) : undefined; const handlers: Array = []; +/** Starts observing HTML document for changes. Required by imgit to lazy-load + * elements added dynamically, eg in single-page apps (SPA). */ export function observeMutations() { observer?.observe(document.body, { childList: true, subtree: true }); if (canObserve()) handleAdded(document.body); } +/** Adds custom handler for HTML document changes. Can be used by plugins + * to share the imgit observer instance. */ export function addHandler(handler: Handler) { handlers.push(handler); } diff --git a/src/plugin/youtube/client.ts b/src/plugin/youtube/client.ts index 969ff46..e83f198 100644 --- a/src/plugin/youtube/client.ts +++ b/src/plugin/youtube/client.ts @@ -1,6 +1,6 @@ -import { addHandler } from "../../client/mutation.js"; +import { mutation } from "../../client/index.js"; -addHandler([handleAdded, handleRemoved]); +mutation.addHandler([handleAdded, handleRemoved]); typeof document === "object" && handleAdded(document.body); function handleAdded(added: Element) {