Skip to content

Commit c385abc

Browse files
fboschfbosch
committed
docs: README
1 parent 4995d66 commit c385abc

1 file changed

Lines changed: 40 additions & 34 deletions

File tree

‎README.md‎

Lines changed: 40 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -73,40 +73,46 @@ npx docs-cache clean
7373

7474
### Options
7575

76-
| Field | Type | Description |
77-
| ---------- | ------- | ---------------------------------------------------- |
78-
| `cacheDir` | string | Directory for cache, defaults to `.docs` |
79-
| `sources` | array | List of repositories to sync |
80-
| `defaults` | object | Default settings for all sources |
81-
82-
**Default Options:**
83-
84-
All fields in `defaults` apply to all sources unless overridden per-source:
85-
86-
- `ref`: Branch, tag, or commit (default: `"HEAD"`)
87-
- `mode`: Cache mode (default: `"materialize"`)
88-
- `include`: Glob patterns to copy (default: `["**/*.{md,mdx,markdown,mkd,txt,rst,adoc,asciidoc}"]`)
89-
- `targetMode`: `"symlink"` or `"copy"` (default: `"symlink"` on Unix, `"copy"` on Windows)
90-
- `depth`: Git clone depth (default: `1`)
91-
- `required`: Whether missing sources should fail (default: `true`)
92-
- `maxBytes`: Maximum total bytes to materialize (default: `200000000`)
93-
- `maxFiles`: Maximum total files to materialize (optional)
94-
- `allowHosts`: Allowed Git hosts (default: `["github.com", "gitlab.com"]`)
95-
- `toc`: Generate per-source `TOC.md` listing all documentation files (default: `true`)
96-
97-
**Source Options:**
98-
99-
- `repo`: Git URL (required)
100-
- `id`: Unique identifier for the source (required)
101-
- `ref`: Branch, tag, or commit (overrides default)
102-
- `include`: Glob patterns to copy (overrides default)
103-
- `exclude`: Glob patterns to skip
104-
- `targetDir`: Optional path where files should be symlinked/copied to, outside `.docs`
105-
- `targetMode`: `"symlink"` or `"copy"` (overrides default)
106-
- `required`: Whether missing sources should fail (overrides default)
107-
- `maxBytes`: Maximum total bytes to materialize (overrides default)
108-
- `maxFiles`: Maximum total files to materialize (overrides default)
109-
- `toc`: Generate per-source `TOC.md` listing all documentation files (overrides default)
76+
**Top-level**
77+
78+
| Field | Type | Description |
79+
| ---------- | ------ | ---------------------------------------- |
80+
| `cacheDir` | string | Directory for cache, defaults to `.docs` |
81+
| `sources` | array | List of repositories to sync |
82+
| `defaults` | object | Default settings for all sources |
83+
84+
**Default options**
85+
86+
All fields in `defaults` apply to all sources unless overridden per-source.
87+
88+
| Field | Type | Description | Default |
89+
| ------------ | ------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
90+
| `ref` | string | Branch, tag, or commit | `"HEAD"` |
91+
| `mode` | string | Cache mode | `"materialize"` |
92+
| `include` | string[] | Glob patterns to copy | `["**/*.{md,mdx,markdown,mkd,txt,rst,adoc,asciidoc}"]` |
93+
| `targetMode` | `"symlink"\|"copy"` | How to write files into the cache | `"symlink"` on Unix, `"copy"` on Windows |
94+
| `depth` | number | Git clone depth | `1` |
95+
| `required` | boolean | Whether missing sources should fail | `true` |
96+
| `maxBytes` | number | Maximum total bytes to materialize | `200000000` |
97+
| `maxFiles` | number | Maximum total files to materialize | Optional |
98+
| `allowHosts` | string[] | Allowed Git hosts | `["github.com", "gitlab.com"]` |
99+
| `toc` | boolean | Generate per-source `TOC.md` listing all documentation files | `true` |
100+
101+
**Source options**
102+
103+
| Field | Type | Description | Required | Overrides | Default |
104+
| ------------ | ------------------- | ---------------------------------------------------------------------------------------------------------------- | -------- | --------- | -------------------------------------------------------- |
105+
| `repo` | string | Git URL | Yes | No | - |
106+
| `id` | string | Unique identifier for the source | Yes | No | - |
107+
| `ref` | string | Branch, tag, or commit | No | Yes | Inherits from defaults |
108+
| `include` | string[] | Glob patterns to copy | No | Yes | Inherits from defaults |
109+
| `exclude` | string[] | Glob patterns to skip | No | No | - |
110+
| `targetDir` | string | Optional path where files should be symlinked/copied to, outside `.docs` | No | No | - |
111+
| `targetMode` | `"symlink"\|"copy"` | How to write files into the cache | No | Yes | Inherits from defaults |
112+
| `required` | boolean | Whether missing sources should fail | No | Yes | Inherits from defaults |
113+
| `maxBytes` | number | Maximum total bytes to materialize | No | Yes | Inherits from defaults |
114+
| `maxFiles` | number | Maximum total files to materialize | No | Yes | Inherits from defaults |
115+
| `toc` | boolean | Generate per-source `TOC.md` listing all documentation files | No | Yes | Inherits from defaults |
110116

111117
> **Note**: Sources are always downloaded to `.docs/<id>/`. If you provide a `targetDir`, `docs-cache` will create a symlink or copy pointing from the cache to that target directory. The target should be outside `.docs`.
112118

0 commit comments

Comments
 (0)