docs

elringus · Dec 29, 2023 · 6b1421e · 6b1421e
1 parent ef76ef8
commit 6b1421e
Show file tree

Hide file tree

Showing 16 changed files with 122 additions and 18 deletions.
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
@@ -24,7 +24,7 @@ export default defineConfig({
     ],
     themeConfig: {
         logo: { src: "/favicon.svg" },
-        logoLink: "https://imgit.dev",
+        logoLink: "/",
         socialLinks: [{ icon: "github", link: "https://github.com/elringus/imgit" }],
         search: { provider: "local" },
         lastUpdated: { text: "Updated", formatOptions: { dateStyle: "medium" } },
@@ -52,23 +52,29 @@ export default defineConfig({
                 {
                     text: "Guide",
                     items: [
-                        { text: "Introduction", link: "/guide/" },
+                        { text: "Introduction", link: "/guide/introduction" },
                         { text: "Getting Started", link: "/guide/getting-started" },
                         { text: "GPU Acceleration", link: "/guide/gpu-acceleration" },
+                        { text: "Plugins", link: "/guide/plugins" }
                     ]
                 },
                 {
                     text: "Integrations",
                     items: [
-                        { text: "Vite", link: "/guide/vite" },
-                        { text: "Astro", link: "/guide/astro" }
+                        { text: "Vite", link: "/guide/integrations/vite" },
+                        { text: "Astro", link: "/guide/integrations/astro" },
+                        { text: "Nuxt", link: "/guide/integrations/nuxt" },
+                        { text: "Remix", link: "/guide/integrations/remix" },
+                        { text: "SolidStart", link: "/guide/integrations/solid" },
+                        { text: "SvelteKit", link: "/guide/integrations/svelte" },
+                        { text: "VitePress", link: "/guide/integrations/vitepress" }
                     ]
                 },
                 {
                     text: "Plugins",
                     items: [
-                        { text: "YouTube", link: "/guide/youtube" },
-                        { text: "SVG", link: "/guide/svg" }
+                        { text: "YouTube", link: "/guide/plugins/youtube" },
+                        { text: "SVG", link: "/guide/plugins/svg" }
                     ]
                 }
             ]

diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md
@@ -44,12 +44,80 @@ bun add -D imgit
 
 :::
 
-When using any of the supported integrations continue on the dedicated page:
-
- - [Vite]()
- - [Astro]()
- - [Nuxt]()
- - [Remix]()
- - [SolidStart]()
- - [SvelteKit]()
- - [VitePress]()
+When using any of the supported web frameworks continue on the dedicated page:
+
+ - [Astro](/guide/integrations/astro)
+ - [Nuxt](/guide/integrations/nuxt)
+ - [Remix](/guide/integrations/remix)
+ - [SolidStart](/guide/integrations/solid)
+ - [SvelteKit](/guide/integrations/svelte)
+ - [VitePress](/guide/integrations/vitepress)
+
+In case your framework is not on the list, but supports Vite plugins, continue on [Vite](/guide/integrations/vite).
+
+Otherwise, use imgit directly to transform source documents. For example, giving following `./index.html` file:
+
+```html
+<html lang="en">
+
+<head>
+    <!-- Import imgit CSS (usually bundled with other stylesheets). -->
+    <link rel="stylesheet" type="text/css"
+          href="https://unpkg.com/imgit/dist/client/styles.css">
+</head>
+
+<body>
+<!-- Specify media content as markdown images (syntax is configurable). -->
+![](https://github.com/elringus/imgit/raw/main/samples/assets/png.png)
+![](https://github.com/elringus/imgit/raw/main/samples/assets/mp4.mp4)
+![](https://www.youtube.com/watch?v=arbuYnJoLtU)
+<!-- Import imgit module (usually bundled with other client-side JS). -->
+<script type="module" src="https://unpkg.com/imgit/dist/client"></script>
+</body>
+
+</html>
+```
+
+Run following script:
+
+```js
+import { boot, transform, exit } from "imgit/server";
+import fs from "node:fs/promises";
+
+// Configure imgit server. In this case we're setting width threshold
+// to 800px, so that when content is larger it'll be scaled down,
+// while high-res original will still be shown on high-dpi displays.
+await boot({ width: 800 });
+
+// Read sample HTML document with images and video referenced
+// via markdown image tags: ![](url). The format can be changed
+// in boot config, for example to capture custom JSX tags instead.
+const input = await fs.readFile("./index.html", { encoding: "utf8" });
+
+// Run the imgit transformations over sample HTML content.
+// This will capture images and video syntax, fetch the remote files,
+// encode them to AV1/AVIF, generate covers, dense and safe variants
+// when necessary, serve generated files (in this minimal case we just
+// write them to 'public' directory; usually you'd upload to a CDN) and
+// return transformed content where captured syntax is replaced with
+// <picture> and <video> HTML tags referencing generated files.
+const output = await transform(input);
+
+// Write the transformed HTML under 'public' directory.
+await fs.writeFile("./public/index.html", output);
+
+// Shutdown imgit server. Will cache the results of the transform
+// operations, such as probing results, encoding profiles, generated covers
+// and parameters of the source files. On consequent runs the server will
+// skip most operations in case the cache is valid and source file is not
+// modified. Cache files are written under 'public/imgit' directory (can be
+// changed in boot config).
+await exit();
+```
+
+::: tip Example
+Find minimal sample on using imgit directly with Deno runtime on GitHub: https://github.com/elringus/imgit/tree/main/samples/minimal.
+:::
+
+
+Find available configuration options in the API reference. For available extension points (hooks), check out [plugins guide](/guide/plugins).
diff --git a/docs/guide/gpu-acceleration.md b/docs/guide/gpu-acceleration.md
@@ -1,3 +1,31 @@
 # GPU Acceleration
 
-test
+Encoding is performed on CPU by default. While ffmpeg uses available CPU instructions to speed up the process, it's still much slower compared to encoding directly on GPU, sometimes in order of magnitude.
+
+Given you have a GPU capable of encoding AV1 (NVIDIA GeForce RTX 450+), specify `av1_nvenc` codec in imgit configuration under encoding options to utilize it. Following sample configuration will make imgit use GPU acceleration when encoding main content files, as well as dense and cover variants:
+
+```js
+imgit({
+    encode: {
+        main: {
+            specs: [
+                [/^image\/.+/, { ext: "avif", codec: "av1_nvenc" }],
+                [/^video\/.+/, { ext: "mp4", codec: "av1_nvenc" }]
+            ]
+        },
+        dense: {
+            specs: [
+                [/^image\/.+/, { ext: "avif", codec: "av1_nvenc" }]
+            ]
+        },
+        cover: {
+            specs: [[/.*/, {
+                ext: "avif", select: 0, scale: 0.05, blur: 0.4,
+                codec: "av1_nvenc"
+            }]]
+        }
+    },
+});
+```
+
+Consult NVIDIA docs for available encode options: https://docs.nvidia.com/video-technologies/video-codec-sdk/12.0/ffmpeg-with-nvidia-gpu.
diff --git a/docs/guide/astro.md → docs/guide/integrations/astro.md b/docs/guide/astro.md → docs/guide/integrations/astro.md
diff --git a/docs/guide/nuxt.md → docs/guide/integrations/nuxt.md b/docs/guide/nuxt.md → docs/guide/integrations/nuxt.md
diff --git a/docs/guide/integrations/remix.md b/docs/guide/integrations/remix.md
diff --git a/docs/guide/integrations/solid.md b/docs/guide/integrations/solid.md
diff --git a/docs/guide/integrations/svelte.md b/docs/guide/integrations/svelte.md
diff --git a/docs/guide/vite.md → docs/guide/integrations/vite.md b/docs/guide/vite.md → docs/guide/integrations/vite.md
diff --git a/docs/guide/integrations/vitepress.md b/docs/guide/integrations/vitepress.md
diff --git a/docs/guide/index.md → docs/guide/introduction.md b/docs/guide/index.md → docs/guide/introduction.md
diff --git a/docs/guide/plugins.md b/docs/guide/plugins.md
@@ -0,0 +1 @@
+# Plugins
diff --git a/docs/guide/svg.md → docs/guide/plugins/svg.md b/docs/guide/svg.md → docs/guide/plugins/svg.md
diff --git a/docs/guide/youtube.md → docs/guide/plugins/youtube.md b/docs/guide/youtube.md → docs/guide/plugins/youtube.md
diff --git a/docs/index.md b/docs/index.md
@@ -10,7 +10,7 @@ hero:
   actions:
     - theme: brand
       text: Get Started
-      link: /guide/
+      link: /guide/introduction
     - theme: alt
       text: View on GitHub
       link: https://github.com/elringus/imgit

diff --git a/docs/tsconfig.json b/docs/tsconfig.json
@@ -3,5 +3,6 @@
         "module": "esnext",
         "target": "esnext",
         "moduleResolution": "bundler"
-    }
+    },
+    "include": [".vitepress/**/*"]
 }