From cd643672a42ff70e15137f8f8c896de7b6a19e5c Mon Sep 17 00:00:00 2001
From: zce <w@zce.me>
Date: Sun, 26 Nov 2023 14:14:09 +0800
Subject: [PATCH] docs: update docs

---
 docs/reference/config.md | 145 +++++++++++++++++++++++++++++++--------
 1 file changed, 116 insertions(+), 29 deletions(-)

diff --git a/docs/reference/config.md b/docs/reference/config.md
index 2a952fa..39b3f8f 100644
--- a/docs/reference/config.md
+++ b/docs/reference/config.md
@@ -1,10 +1,6 @@
 # Configuration
 
-This documentation is still being written. Please check back later.
-
-<!-- When running vite from the command line, Vite will automatically try to resolve a config file named vite.config.js inside project root (other JS and TS extensions are also supported).
-
-The most basic config file looks like this:
+When running `velite` from the command line, Velite will automatically try to resolve a config file named `velite.config.js` inside project root (other JS and TS extensions are also supported).
 
 ## Velite Config File
 
@@ -12,44 +8,135 @@ Velite uses `velite.config.js` as the config file. You can create it in the root
 
 ```js
 // velite.config.js
-module.exports = {
+export default {
   // ...
 }
 ```
 
 ::: tip
-Config file supports TypeScript & ESM, so you can use the full power of TypeScript to write your config file.
+Config file supports TypeScript & ESM & CommonJS. you can use the full power of TypeScript to write your config file, and it's recommended strongly.
 :::
 
-## Config Schema
+## Typed Config
 
-The config file is a commonjs module that exports a function that returns a config object.
+For the better experience, Velite provides a `defineConfig` identity function to define the config file type.
 
 ```js
-// velite.config.js
-module.exports = () => ({
+import { defineConfig } from 'velite'
+
+export default defineConfig({
   // ...
 })
 ```
 
-The config object is a plain object that contains the following properties:
+In addition, Velite also provides a `UserConfig` type to describe the config file type.
 
-- `contentDir`: The directory where the content files are located. Default to `content`.
-- `outDir`: The directory where the built content files are located. Default to `.velite`.
-- `schemas`: The schemas of the content files. Default to `{}`.
+```ts
+import type { UserConfig } from 'velite'
 
-```js
-// velite.config.js
-module.exports = () => ({
-  contentDir: 'content',
-  outDir: '.velite',
-  schemas: {
-    posts: {
-      // ...
-    },
-    others: {
-      // ...
-    }
+const config: UserConfig = {
+  // ...
+}
+
+export default config
+```
+
+And other identity functions to help you define the config file type:
+
+- `defineCollection`: define collection options
+- `defineLoader`: define a file loader
+
+## Config Options
+
+The config object is a plain object that contains the following properties:
+
+```ts
+interface UserConfig<C extends Collections = Collections> {
+  /**
+   * resolved config file path
+   */
+  configPath: string
+  /**
+   * The root directory of the contents
+   * @default 'content'
+   */
+  root: string
+  /**
+   * Output configuration
+   */
+  output: {
+    /**
+     * The output directory of the data
+     * @default '.velite'
+     */
+    data: string
+    /**
+     * The output directory of the static assets,
+     * should be served statically by the app
+     * @default 'public'
+     */
+    static: string
+    /**
+     * The public base path of the static files.
+     * Must include one level of directory, otherwise `--clean` will automatically clear the static root dir,
+     * this means that other files in the static dir will also be cleared together
+     * @default '/static/[name]-[hash:8].[ext]'
+     */
+    filename: `/${string}/${string}`
+    /**
+     * The ext blacklist of the static files, such as ['md', 'yml']
+     * @default []
+     */
+    ignoreFileExtensions: string[]
+    /**
+     * Whether to clean the output directories before build
+     * @default false
+     */
+    clean: boolean
   }
-})
-``` -->
+  /**
+   * Collections
+   */
+  collections: C
+  /**
+   * File loaders
+   * @default [] (built-in loaders: 'json', 'yaml', 'markdown')
+   */
+  loaders: Loader[]
+  /**
+   * Global markdown options
+   */
+  markdown: MarkdownOptions
+  /**
+   * Global MDX options
+   */
+  mdx: MdxOptions
+  /**
+   * Data prepare hook, before write to file
+   * @description
+   * You can apply additional processing to the output data, such as modify them, add missing data, handle relationships, or write them to files.
+   * return false to prevent the default output to a file if you wanted
+   */
+  prepare?: (data: {
+    [name in keyof C]: C[name]['single'] extends true ? C[name]['schema']['_output'] : Array<C[name]['schema']['_output']>
+  }) => Promisable<void | false>
+  /**
+   * Build success hook
+   * @description
+   * You can do anything after the build is complete, such as print some tips or deploy the output files.
+   */
+  complete?: () => Promisable<void>
+}
+```
+
+<!-- ### `root`
+
+- Type: `string`
+- Default: `'content'`
+
+The directory where the content files are located.
+
+### `output`
+
+- Type: `object`
+- Default: `{ dir: '.velite' }` -->