Skip to content

Commit 0eb7753

Browse files
fboschfbosch
committed
docs: reformat options in README
1 parent c385abc commit 0eb7753

1 file changed

Lines changed: 47 additions & 35 deletions

File tree

‎README.md‎

Lines changed: 47 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -75,55 +75,67 @@ npx docs-cache clean
7575

7676
**Top-level**
7777

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 |
78+
| Field | Details | Required |
79+
| ---------- | -------------------------------------- | -------- |
80+
| `cacheDir` | Directory for cache. Default: `.docs`. | Optional |
81+
| `sources` | List of repositories to sync. | Required |
82+
| `defaults` | Default settings for all sources. | Optional |
8383

84-
**Default options**
84+
<details>
85+
<summary>Show default and source options</summary>
86+
87+
### Default options
8588

8689
All fields in `defaults` apply to all sources unless overridden per-source.
8790

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 |
91+
| Field | Details |
92+
| ------------ | --------------------------------------------------------------------------------------------------------- |
93+
| `ref` | Branch, tag, or commit. Default: `"HEAD"`. |
94+
| `mode` | Cache mode. Default: `"materialize"`. |
95+
| `include` | Glob patterns to copy. Default: `["**/*.{md,mdx,markdown,mkd,txt,rst,adoc,asciidoc}"]`. |
96+
| `targetMode` | How to link or copy from the cache to the destination. Default: `"symlink"` on Unix, `"copy"` on Windows. |
97+
| `depth` | Git clone depth. Default: `1`. |
98+
| `required` | Whether missing sources should fail. Default: `true`. |
99+
| `maxBytes` | Maximum total bytes to materialize. Default: `200000000`. |
100+
| `maxFiles` | Maximum total files to materialize. |
101+
| `allowHosts` | Allowed Git hosts. Default: `["github.com", "gitlab.com"]`. |
102+
| `toc` | Generate per-source `TOC.md` listing all documentation files. Default: `true`. |
103+
104+
### Source options
105+
106+
#### Required
107+
108+
| Field | Details |
109+
| ------ | --------------------------------- |
110+
| `repo` | Git URL. |
111+
| `id` | Unique identifier for the source. |
112+
113+
#### Optional
114+
115+
| Field | Details |
116+
| ------------ | ---------------------------------------------------------------- |
117+
| `ref` | Branch, tag, or commit. |
118+
| `include` | Glob patterns to copy. |
119+
| `exclude` | Glob patterns to skip. |
120+
| `targetDir` | Path where files should be symlinked/copied to, outside `.docs`. |
121+
| `targetMode` | How to link or copy from the cache to the destination. |
122+
| `required` | Whether missing sources should fail. |
123+
| `maxBytes` | Maximum total bytes to materialize. |
124+
| `maxFiles` | Maximum total files to materialize. |
125+
| `toc` | Generate per-source `TOC.md` listing all documentation files. |
116126

117127
> **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`.
118128
129+
</details>
130+
119131
## NPM Integration
120132

121133
Use `postinstall` to ensure documentation is available locally immediately after installation:
122134

123135
```json
124136
{
125137
"scripts": {
126-
"postinstall": "npx docs-cache sync"
138+
"postinstall": "npx docs-cache sync --prune"
127139
}
128140
}
129141
```

0 commit comments

Comments
 (0)