docs: improve docs (#79)

* docs: builder

* tweaks

* docs: release module

* tweaks

Author: northword

docs/src/.vitepress/config.ts

@@ -10,15 +10,32 @@ export default defineConfig({
     // https://vitepress.dev/reference/default-theme-config
     nav: [
       { text: "Home", link: "/" },
+      { text: "Docs", link: "/quick-start" },
     ],
 
     sidebar: [
-      { text: "Why", link: "/why" },
-      { text: "Quick Start", link: "/quick-start" },
-      { text: "Serve", link: "/serve" },
-      { text: "Build", link: "/build" },
-      { text: "Test", link: "/test" },
-      { text: "Release", link: "/release" },
+      {
+        text: "Introduction",
+        items: [
+          { text: "Why", link: "/why" },
+          { text: "Quick Start", link: "/quick-start" },
+        ],
+      },
+      {
+        text: "Modules",
+        items: [
+          { text: "Serve", link: "/serve" },
+          { text: "Build", link: "/build" },
+          { text: "Test", link: "/test" },
+          { text: "Release", link: "/release" },
+        ],
+      },
+      {
+        text: "Presets",
+        items: [
+          { text: "ESLint", link: "/eslint" },
+        ],
+      },
     ],
 
     socialLinks: [

docs/src/build.md

@@ -1,48 +1,298 @@
 # Build
 
-This `Build` class in your Node.js project encapsulates the process of building, packaging, and preparing a Zotero plugin for release. Below is a brief overview of its key features and functionality:
+This module provides the capability to compile and package plugins, with built-in bundlers such as "copy," "replace," and "bundling" for quickly configuring your plugin's build process.
 
-## 构建流程
+It also offers a set of hooks for customizing the build process.
 
-### 复制资产
+## Information of Plugin
 
-使用 `assets` 来定义需要复制的资产。
+```ts twoslash
+import { defineConfig } from "zotero-plugin-scaffold";
+// ---cut---
+export default defineConfig({
+  name: "Your Plugin Name",
+  id: "Your Plugin ID",
+  namespace: "Your Plugin Namespace",
+});
+```
 
-### 定义
+## Built-in Builders
 
-Configurable via the define option.
+The built-in builders run sequentially in the following order.
 
-This feature provides a way to replace global identifiers with constant expressions.
+### Make Directory
 
-替换在复制资产完成后立即发生。
+This step creates a new build storage folder.
 
-Replaces placeholders (`__PLACEHOLDER__`) in files with values defined in the build configuration.
+Configured via the `dist` option:
+
+```ts twoslash
+import { defineConfig } from "zotero-plugin-scaffold";
+// ---cut---
+export default defineConfig({
+  dist: ".scaffold/build",
+});
+```
+
+If the target folder already exists, it will be cleared before creating the new one.
+
+::: details The file structure of `dist`
+
+- `addon` contains the plugin code after the build process but before packaging.
+- `*.xpi` represents the packaged plugin files.
+- `update*.json` are update manifest.
+
+```text {4,10,12}
+.
+|-- .scaffold
+|   |-- build
+|   |   |-- addon
+|   |   |   |-- bootstrap.js
+|   |   |   |-- content
+|   |   |   |-- locale
+|   |   |   |-- manifest.json
+|   |   |   `-- prefs.js
+|   |   |-- linter-for-zotero.xpi
+|   |   |-- update-beta.json
+|   |   `-- update.json
+|   `-- cache
+`-- zotero-plugin.config.ts
+```
+
+:::
+
+### Copy Assets
+
+This step copies static assets from the source directory to the build directory.
+
+Configure the assets to be copied using `build.assets`:
+
+```ts twoslash
+import { defineConfig } from "zotero-plugin-scaffold";
+// ---cut---
+export default defineConfig({
+  build: {
+    assets: ["addon"],
+  },
+});
+```
+
+This is a glob list that supports negation patterns using `!`. For more details, refer to [tinyglobby](https://github.com/SuperchupuDev/tinyglobby).
+
+### Define
+
+This feature allows you to replace global identifiers with constant expressions.
+
+Configurable via the `build.define` option:
+
+```ts twoslash
+import { defineConfig } from "zotero-plugin-scaffold";
+// ---cut---
+export default defineConfig({
+  build: {
+    define: {
+      placeholder: "placeholderValue",
+    },
+  },
+});
+```
+
+::: warning
+
+Replacement occurs immediately after copying assets and applies only to all assets in `config.dist` under the current state.
+
+For non-asset files such as `README.md`, use the Scaffold utility `replaceInFile` (see: [Utilities](#utils)).
+
+For JavaScript constant replacement, use `esbuild.define` (see: [Script Bundling](#script-bundling)).
+
+:::
+
+During replacement, the placeholder `placeholder` is converted into the regular expression `/__placeholder__/g` for replacement (instead of `/placeholder/g`).
+
+This option provides built-in placeholders such as `version` and `buildTime`. See `Context.templateData` for details.
 
 ### Manifest Generation
 
-Merges user-supplied manifest data with required fields (e.g., `id`, `updateURL`) to create a complete `manifest.json` (`makeManifest`).
+Automatically updates fields in `manifest.json`, including `version`, `id`, `update_url`, and more.
+
+This feature is enabled by default and can be disabled by setting `makeManifest` to `false`.
+
+The `version` is sourced from `package.json`, while other values can be configured in the configuration file:
+
+```ts twoslash
+import { defineConfig } from "zotero-plugin-scaffold";
+// ---cut---
+export default defineConfig({
+  name: "Your Plugin Name",
+  id: "Your Plugin ID",
+  updateURL: "Your update.json Path",
+  build: {
+    makeManifest: {
+      enable: true,
+    },
+  },
+});
+```
+
+When `manifest.json` already exists in `dist/addon`, the values will always be deeply merged with the existing content, with priority given to the existing entries.
 
 ### Locale File Handling
 
-Processes Fluent `.ftl` files, adding a namespace prefix and ensuring HTML references (`data-l10n-id`) are consistent with Fluent messages.
+Handles localization files to prevent conflicts.
+
+Configured via `build.fluent`.
+
+#### Add Prefix to FTL File Names
+
+```ts twoslash
+import { defineConfig } from "zotero-plugin-scaffold";
+// ---cut---
+export default defineConfig({
+  namespace: "Your Plugin Namespace",
+  build: {
+    fluent: {
+      prefixLocaleFiles: true,
+    },
+  },
+});
+```
+
+#### Add Prefix to FTL Messages
+
+Processes Fluent `.ftl` files by adding a namespace prefix and ensuring HTML references (`data-l10n-id`) align with Fluent messages.
+
+```ts twoslash
+import { defineConfig } from "zotero-plugin-scaffold";
+// ---cut---
+export default defineConfig({
+  namespace: "Your Plugin Namespace",
+  build: {
+    fluent: {
+      prefixFluentMessages: true,
+    },
+  },
+});
+```
+
+#### Generate Type Definitions for FTL Messages
+
+> In development.
 
 ### Preference Management
 
+> In development.
+
 - Supports prefixing preference keys in `prefs.js` with a custom namespace.
 - Optionally generates TypeScript declaration files (`.d.ts`) for preferences.
 
 ### Script Bundling
 
-Uses `esbuild` to bundle JavaScript files with options defined in the configuration (`esbuild`).
+Uses `esbuild` to compile and bundle your JavaScript/TypeScript code.
+
+Configure it using `build.esbuild`:
+
+```ts twoslash
+import { defineConfig } from "zotero-plugin-scaffold";
+// ---cut---
+export default defineConfig({
+  build: {
+    esbuildOptions: [],
+  },
+});
+```
+
+Since `esbuild` only compiles and bundles code without type checking, you need to run `tsc` manually for type checking.
 
 ### Plugin Packing
 
 Creates a `.xpi` archive for the plugin using `AdmZip`.
 
+```ts twoslash
+import { defineConfig } from "zotero-plugin-scaffold";
+// ---cut---
+export default defineConfig({
+  xpiName: "Your Plugin Built XPI Name",
+});
+```
+
+This step executes only in the `production` environment.
+
 ### Update Manifest
 
 Generates `update.json` and `update-beta.json` with versioning and compatibility information for Zotero plugin updates.
 
-## Extensibility
+Configured via `build.makeUpdateJson`:
+
+```ts twoslash
+import { defineConfig } from "zotero-plugin-scaffold";
+// ---cut---
+export default defineConfig({
+  build: {
+    makeUpdateJson: {
+      updates: [
+        {
+          version: "0.9.9",
+          update_link: "https://example.com/plugin-for-older-zotero.xpi",
+          applications: {
+            zotero: {
+              strict_min_version: "5.9.9",
+              strict_max_version: "6.9.9",
+            },
+          },
+        },
+      ],
+      hash: true,
+    },
+  },
+});
+```
+
+This step executes only in the `production` environment.
+
+When the version number includes a `-` (pre-release), only `update-beta.json` is generated. Otherwise, both `update.json` and `update-beta.json` are generated. After installing a pre-release version, users will automatically update to the next pre-release version until the official release. Installing the next pre-release version still requires manual installation.
+
+For different plugin versions targeting different Zotero versions, specify the Zotero version and corresponding plugin version in `build.makeUpdateJson.updates`. Refer to: [Zotero 7 for developers](https://www.zotero.org/support/dev/zotero_7_for_developers#updaterdf_updatesjson).
+
+## Hooks
+
+> Documentation in progress.
+
+## Utils
+
+Scaffold exports utilities and third-party dependencies for use. Import them from `zotero-plugin-scaffold/vendor`.
+
+### replaceInFile
+
+```ts
+import { replaceInFile } from "zotero-plugin-scaffold/vendor";
+
+replaceInFile({
+  files: ["README.md", "**/README.md"],
+  from: [/from/g],
+  to: ["to"],
+});
+```
+
+### fs-extra
+
+> Node.js: Extra methods for the `fs` object like `copy()`, `remove()`, `mkdirs()`.
+
+Refer to the [fs-extra documentation](https://github.com/jprichardson/node-fs-extra).
+
+```ts
+import { fse } from "zotero-plugin-scaffold/vendor";
+
+fse.copy("a.txt", "b.txt");
+```
+
+### es-toolkit
+
+> es-toolkit: State-of-the-art JavaScript utility library
+
+Refer to the [es-toolkit documentation](https://es-toolkit.slash.page/).
+
+```ts
+import { esToolkit } from "zotero-plugin-scaffold/vendor";
 
-- The use of hooks allows custom behaviors to be injected at various stages of the build process.
+esToolkit.isNotNil(null);
+```

docs/src/eslint.md

@@ -0,0 +1,3 @@
+# ESLint Config Preset
+
+尚未实现。

docs/src/quick-start.md

@@ -6,10 +6,10 @@
 
 ```bash
 # Using npm
-npx zotero-plugin create
+npm create zotero-plugin
 
 # Using pnpm
-pnpm dlx zotero-plugin create
+pnpm create zotero-plugin
 ```
 
 :::
@@ -41,7 +41,7 @@ zotero-plugin.config.ts  # Also supported: *.js, *.mjs, *.cjs, *.ts
 
 You can use the `defineConfig` helper to enable type hints. Optional properties will default to predefined values if not explicitly specified.
 
-```ts
+```ts twoslash {4-6}
 import { defineConfig } from "zotero-plugin-scaffold";
 
 export default defineConfig({