MediaMetz/gemini-cli
1
0
Fork 0
mirror of https://github.com/google-gemini/gemini-cli.git synced 2026-05-13 05:12:55 -07:00
Code Issues Packages Projects Releases Wiki Activity

Autogenerate docs/cli/settings.md docs/getting-started/configuration.md was already autogenerated but settings.md was not. (#14408)

Browse Source
This commit is contained in:
Jacob Richman
2026-01-09 14:28:09 -08:00
committed by GitHub
parent d74bf9ef2f
commit 1fb55dcb2e
6 changed files with 179 additions and 97 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/cli/settings.md
+67 -54
View File
@@ -18,45 +18,49 @@ Note: Workspace settings override user settings.
Here is a list of all the available settings, grouped by category and ordered as Here is a list of all the available settings, grouped by category and ordered as
they appear in the UI. they appear in the UI.
<!-- SETTINGS-AUTOGEN:START -->
### General ### General
| UI Label | Setting | Description | Default | | UI Label | Setting | Description | Default |
| ------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------- | ----------- | | ------------------------------- | ---------------------------------- | ------------------------------------------------------------- | ------- |
| Preview Features (e.g., models) | `general.previewFeatures` | Enable preview features (e.g., preview models). | `false` | | Preview Features (e.g., models) | `general.previewFeatures` | Enable preview features (e.g., preview models). | `false` |
| Vim Mode | `general.vimMode` | Enable Vim keybindings. | `false` | | Vim Mode | `general.vimMode` | Enable Vim keybindings | `false` |
| Disable Auto Update | `general.disableAutoUpdate` | Disable automatic updates. | `false` | | Disable Auto Update | `general.disableAutoUpdate` | Disable automatic updates | `false` |
| Enable Prompt Completion | `general.enablePromptCompletion` | Enable AI-powered prompt completion suggestions while typing. | `false` | | Enable Prompt Completion | `general.enablePromptCompletion` | Enable AI-powered prompt completion suggestions while typing. | `false` |
| Debug Keystroke Logging | `general.debugKeystrokeLogging` | Enable debug logging of keystrokes to the console. | `false` | | Debug Keystroke Logging | `general.debugKeystrokeLogging` | Enable debug logging of keystrokes to the console. | `false` |
| Session Retention | `general.sessionRetention` | Settings for automatic session cleanup. This feature is disabled by default. | `undefined` | | Enable Session Cleanup | `general.sessionRetention.enabled` | Enable automatic session cleanup | `false` |
| Enable Session Cleanup | `general.sessionRetention.enabled` | Enable automatic session cleanup. | `false` |
### Output ### Output
| UI Label | Setting | Description | Default | | UI Label | Setting | Description | Default |
| ------------- | --------------- | ------------------------------------------------------ | ------- | | ------------- | --------------- | ------------------------------------------------------ | -------- |
| Output Format | `output.format` | The format of the CLI output. Can be `text` or `json`. | `text` | | Output Format | `output.format` | The format of the CLI output. Can be `text` or `json`. | `"text"` |
### UI ### UI
| UI Label | Setting | Description | Default | | UI Label | Setting | Description | Default |
| ------------------------------ | ---------------------------------------- | -------------------------------------------------------------------- | ------- | | ------------------------------ | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| Hide Window Title | `ui.hideWindowTitle` | Hide the window title bar. | `false` | | Hide Window Title | `ui.hideWindowTitle` | Hide the window title bar | `false` |
| Show Status in Title | `ui.showStatusInTitle` | Show Gemini CLI status and thoughts in the terminal window title. | `false` | | Show Status in Title | `ui.showStatusInTitle` | Show Gemini CLI status and thoughts in the terminal window title | `false` |
| Hide Tips | `ui.hideTips` | Hide helpful tips in the UI. | `false` | | Show Home Directory Warning | `ui.showHomeDirectoryWarning` | Show a warning when running Gemini CLI in the home directory. | `true` |
| Hide Banner | `ui.hideBanner` | Hide the application banner. | `false` | | Hide Tips | `ui.hideTips` | Hide helpful tips in the UI | `false` |
| Hide Context Summary | `ui.hideContextSummary` | Hide the context summary (GEMINI.md, MCP servers) above the input. | `false` | | Hide Banner | `ui.hideBanner` | Hide the application banner | `false` |
| Hide CWD | `ui.footer.hideCWD` | Hide the current working directory path in the footer. | `false` | | Hide Context Summary | `ui.hideContextSummary` | Hide the context summary (GEMINI.md, MCP servers) above the input. | `false` |
| Hide Sandbox Status | `ui.footer.hideSandboxStatus` | Hide the sandbox status indicator in the footer. | `false` | | Hide CWD | `ui.footer.hideCWD` | Hide the current working directory path in the footer. | `false` |
| Hide Model Info | `ui.footer.hideModelInfo` | Hide the model name and context usage in the footer. | `false` | | Hide Sandbox Status | `ui.footer.hideSandboxStatus` | Hide the sandbox status indicator in the footer. | `false` |
| Hide Context Window Percentage | `ui.footer.hideContextPercentage` | Hides the context window remaining percentage. | `true` | | Hide Model Info | `ui.footer.hideModelInfo` | Hide the model name and context usage in the footer. | `false` |
| Hide Footer | `ui.hideFooter` | Hide the footer from the UI. | `false` | | Hide Context Window Percentage | `ui.footer.hideContextPercentage` | Hides the context window remaining percentage. | `true` |
| Show Memory Usage | `ui.showMemoryUsage` | Display memory usage information in the UI. | `false` | | Hide Footer | `ui.hideFooter` | Hide the footer from the UI | `false` |
| Show Line Numbers | `ui.showLineNumbers` | Show line numbers in the chat. | `false` | | Show Memory Usage | `ui.showMemoryUsage` | Display memory usage information in the UI | `false` |
| Show Citations | `ui.showCitations` | Show citations for generated text in the chat. | `false` | | Show Line Numbers | `ui.showLineNumbers` | Show line numbers in the chat. | `true` |
| Use Full Width | `ui.useFullWidth` | Use the entire width of the terminal for output. | `true` | | Show Citations | `ui.showCitations` | Show citations for generated text in the chat. | `false` |
| Use Alternate Screen Buffer | `ui.useAlternateBuffer` | Use an alternate screen buffer for the UI, preserving shell history. | `true` | | Show Model Info In Chat | `ui.showModelInfoInChat` | Show the model name in the chat for each model turn. | `false` |
| Disable Loading Phrases | `ui.accessibility.disableLoadingPhrases` | Disable loading phrases for accessibility. | `false` | | Use Full Width | `ui.useFullWidth` | Use the entire width of the terminal for output. | `true` |
| Screen Reader Mode | `ui.accessibility.screenReader` | Render output in plain-text to be more screen reader accessible. | `false` | | Use Alternate Screen Buffer | `ui.useAlternateBuffer` | Use an alternate screen buffer for the UI, preserving shell history. | `false` |
| Incremental Rendering | `ui.incrementalRendering` | Enable incremental rendering for the UI. This option will reduce flickering but may cause rendering artifacts. Only supported when useAlternateBuffer is enabled. | `true` |
| Disable Loading Phrases | `ui.accessibility.disableLoadingPhrases` | Disable loading phrases for accessibility | `false` |
| Screen Reader Mode | `ui.accessibility.screenReader` | Render output in plain-text to be more screen reader accessible | `false` |
### IDE ### IDE
@@ -69,7 +73,7 @@ they appear in the UI.
| UI Label | Setting | Description | Default | | UI Label | Setting | Description | Default |
| ----------------------- | ---------------------------- | -------------------------------------------------------------------------------------- | ------- | | ----------------------- | ---------------------------- | -------------------------------------------------------------------------------------- | ------- |
| Max Session Turns | `model.maxSessionTurns` | Maximum number of user/model/tool turns to keep in a session. -1 means unlimited. | `-1` | | Max Session Turns | `model.maxSessionTurns` | Maximum number of user/model/tool turns to keep in a session. -1 means unlimited. | `-1` |
| Compression Threshold | `model.compressionThreshold` | The fraction of context usage at which to trigger context compression (e.g. 0.2, 0.3). | `0.2` | | Compression Threshold | `model.compressionThreshold` | The fraction of context usage at which to trigger context compression (e.g. 0.2, 0.3). | `0.5` |
| Skip Next Speaker Check | `model.skipNextSpeakerCheck` | Skip the next speaker check. | `true` | | Skip Next Speaker Check | `model.skipNextSpeakerCheck` | Skip the next speaker check. | `true` |
### Context ### Context
@@ -85,31 +89,40 @@ they appear in the UI.
### Tools ### Tools
| UI Label | Setting | Description | Default | | UI Label | Setting | Description | Default |
| -------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------- | ------- | | -------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------- | --------- |
| Enable Interactive Shell | `tools.shell.enableInteractiveShell` | Use node-pty for an interactive shell experience. Fallback to child_process still applies. | `true` | | Enable Interactive Shell | `tools.shell.enableInteractiveShell` | Use node-pty for an interactive shell experience. Fallback to child_process still applies. | `true` |
| Show Color | `tools.shell.showColor` | Show color in shell output. | `false` | | Show Color | `tools.shell.showColor` | Show color in shell output. | `false` |
| Auto Accept | `tools.autoAccept` | Automatically accept and execute tool calls that are considered safe (e.g., read-only operations). | `false` | | Auto Accept | `tools.autoAccept` | Automatically accept and execute tool calls that are considered safe (e.g., read-only operations). | `false` |
| Use Ripgrep | `tools.useRipgrep` | Use ripgrep for file content search instead of the fallback implementation. Provides faster search performance. | `true` | | Use Ripgrep | `tools.useRipgrep` | Use ripgrep for file content search instead of the fallback implementation. Provides faster search performance. | `true` |
| Enable Tool Output Truncation | `tools.enableToolOutputTruncation` | Enable truncation of large tool outputs. | `true` | | Enable Tool Output Truncation | `tools.enableToolOutputTruncation` | Enable truncation of large tool outputs. | `true` |
| Tool Output Truncation Threshold | `tools.truncateToolOutputThreshold` | Truncate tool output if it is larger than this many characters. Set to -1 to disable. | `10000` | | Tool Output Truncation Threshold | `tools.truncateToolOutputThreshold` | Truncate tool output if it is larger than this many characters. Set to -1 to disable. | `4000000` |
| Tool Output Truncation Lines | `tools.truncateToolOutputLines` | The number of lines to keep when truncating tool output. | `100` | | Tool Output Truncation Lines | `tools.truncateToolOutputLines` | The number of lines to keep when truncating tool output. | `1000` |
### Security ### Security
| UI Label | Setting | Description | Default | | UI Label | Setting | Description | Default |
| ----------------------------- | ----------------------------------------------- | --------------------------------------------------------- | ------- | | ------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------- | ------- |
| Disable YOLO Mode | `security.disableYoloMode` | Disable YOLO mode, even if enabled by a flag. | `false` | | Disable YOLO Mode | `security.disableYoloMode` | Disable YOLO mode, even if enabled by a flag. | `false` |
| Blocks extensions from Git | `security.blockGitExtensions` | Blocks installing and loading extensions from Git. | `false` | | Allow Permanent Tool Approval | `security.enablePermanentToolApproval` | Enable the "Allow for all future sessions" option in tool confirmation dialogs. | `false` |
| Folder Trust | `security.folderTrust.enabled` | Setting to track whether Folder trust is enabled. | `false` | | Blocks extensions from Git | `security.blockGitExtensions` | Blocks installing and loading extensions from Git. | `false` |
| Allowed Environment Variables | `security.environmentVariableRedaction.allowed` | Environment variables to always allow (bypass redaction). | `[]` | | Folder Trust | `security.folderTrust.enabled` | Setting to track whether Folder trust is enabled. | `false` |
| Blocked Environment Variables | `security.environmentVariableRedaction.blocked` | Environment variables to always redact. | `[]` | | Enable Environment Variable Redaction | `security.environmentVariableRedaction.enabled` | Enable redaction of environment variables that may contain secrets. | `false` |
### Experimental ### Experimental
| UI Label | Setting | Description | Default | | UI Label | Setting | Description | Default |
| ----------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------ | ------- | | ----------------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------- |
| Enable Codebase Investigator | `experimental.codebaseInvestigatorSettings.enabled` | Enable the Codebase Investigator agent. | `true` | | Agent Skills | `experimental.skills` | Enable Agent Skills (experimental). | `false` |
| Codebase Investigator Max Num Turns | `experimental.codebaseInvestigatorSettings.maxNumTurns` | Maximum number of turns for the Codebase Investigator agent. | `10` | | Enable Codebase Investigator | `experimental.codebaseInvestigatorSettings.enabled` | Enable the Codebase Investigator agent. | `true` |
| Enable CLI Help Agent | `experimental.cliHelpAgentSettings.enabled` | Enable the CLI Help Agent. | `true` | | Codebase Investigator Max Num Turns | `experimental.codebaseInvestigatorSettings.maxNumTurns` | Maximum number of turns for the Codebase Investigator agent. | `10` |
| Agent Skills | `experimental.skills` | Enable Agent Skills (experimental). | `false` | | Use OSC 52 Paste | `experimental.useOSC52Paste` | Use OSC 52 sequence for pasting instead of clipboardy (useful for remote sessions). | `false` |
| Enable CLI Help Agent | `experimental.cliHelpAgentSettings.enabled` | Enable the CLI Help Agent. | `true` |
### Hooks
| UI Label | Setting | Description | Default |
| ------------------ | --------------------- | ------------------------------------------------ | ------- |
| Hook Notifications | `hooks.notifications` | Show visual indicators when hooks are executing. | `true` |
<!-- SETTINGS-AUTOGEN:END -->
docs/get-started/configuration.md
+4 -4
View File
@@ -159,7 +159,7 @@ their corresponding top-level category object in your `settings.json` file.
#### `output` #### `output`
- **`output.format`** (enum): - **`output.format`** (enum):
- **Description:** The format of the CLI output. - **Description:** The format of the CLI output. Can be `text` or `json`.
- **Default:** `"text"` - **Default:** `"text"`
- **Values:** `"text"`, `"json"` - **Values:** `"text"`, `"json"`
@@ -275,7 +275,7 @@ their corresponding top-level category object in your `settings.json` file.
#### `ide` #### `ide`
- **`ide.enabled`** (boolean): - **`ide.enabled`** (boolean):
- **Description:** Enable IDE integration mode - **Description:** Enable IDE integration mode.
- **Default:** `false` - **Default:** `false`
- **Requires restart:** Yes - **Requires restart:** Yes
@@ -579,12 +579,12 @@ their corresponding top-level category object in your `settings.json` file.
- **Default:** `false` - **Default:** `false`
- **`context.fileFiltering.respectGitIgnore`** (boolean): - **`context.fileFiltering.respectGitIgnore`** (boolean):
- **Description:** Respect .gitignore files when searching - **Description:** Respect .gitignore files when searching.
- **Default:** `true` - **Default:** `true`
- **Requires restart:** Yes - **Requires restart:** Yes
- **`context.fileFiltering.respectGeminiIgnore`** (boolean): - **`context.fileFiltering.respectGeminiIgnore`** (boolean):
- **Description:** Respect .geminiignore files when searching - **Description:** Respect .geminiignore files when searching.
- **Default:** `true` - **Default:** `true`
- **Requires restart:** Yes - **Requires restart:** Yes
packages/cli/src/config/settingsSchema.ts
+4 -4
View File
@@ -323,7 +323,7 @@ const SETTINGS_SCHEMA = {
category: 'General', category: 'General',
requiresRestart: false, requiresRestart: false,
default: 'text', default: 'text',
description: 'The format of the CLI output.', description: 'The format of the CLI output. Can be `text` or `json`.',
showInDialog: true, showInDialog: true,
options: [ options: [
{ value: 'text', label: 'Text' }, { value: 'text', label: 'Text' },
@@ -605,7 +605,7 @@ const SETTINGS_SCHEMA = {
category: 'IDE', category: 'IDE',
requiresRestart: true, requiresRestart: true,
default: false, default: false,
description: 'Enable IDE integration mode', description: 'Enable IDE integration mode.',
showInDialog: true, showInDialog: true,
}, },
hasSeenNudge: { hasSeenNudge: {
@@ -854,7 +854,7 @@ const SETTINGS_SCHEMA = {
category: 'Context', category: 'Context',
requiresRestart: true, requiresRestart: true,
default: true, default: true,
description: 'Respect .gitignore files when searching', description: 'Respect .gitignore files when searching.',
showInDialog: true, showInDialog: true,
}, },
respectGeminiIgnore: { respectGeminiIgnore: {
@@ -863,7 +863,7 @@ const SETTINGS_SCHEMA = {
category: 'Context', category: 'Context',
requiresRestart: true, requiresRestart: true,
default: true, default: true,
description: 'Respect .geminiignore files when searching', description: 'Respect .geminiignore files when searching.',
showInDialog: true, showInDialog: true,
}, },
enableRecursiveFileSearch: { enableRecursiveFileSearch: {
packages/cli/src/ui/components/__snapshots__/SettingsDialog.test.tsx.snap
+9 -9
View File
@@ -29,7 +29,7 @@ exports[`SettingsDialog > Initial Rendering > should render settings list with v
│ Enable automatic session cleanup │ │ Enable automatic session cleanup │
│ │ │ │
│ Output Format Text │ │ Output Format Text │
│ The format of the CLI output. │ │ The format of the CLI output. Can be \`text\` or \`json\`. │
│ │ │ │
│ Hide Window Title false │ │ Hide Window Title false │
│ Hide the window title bar │ │ Hide the window title bar │
@@ -75,7 +75,7 @@ exports[`SettingsDialog > Snapshot Tests > should render 'accessibility settings
│ Enable automatic session cleanup │ │ Enable automatic session cleanup │
│ │ │ │
│ Output Format Text │ │ Output Format Text │
│ The format of the CLI output. │ │ The format of the CLI output. Can be \`text\` or \`json\`. │
│ │ │ │
│ Hide Window Title false │ │ Hide Window Title false │
│ Hide the window title bar │ │ Hide the window title bar │
@@ -121,7 +121,7 @@ exports[`SettingsDialog > Snapshot Tests > should render 'all boolean settings d
│ Enable automatic session cleanup │ │ Enable automatic session cleanup │
│ │ │ │
│ Output Format Text │ │ Output Format Text │
│ The format of the CLI output. │ │ The format of the CLI output. Can be \`text\` or \`json\`. │
│ │ │ │
│ Hide Window Title false* │ │ Hide Window Title false* │
│ Hide the window title bar │ │ Hide the window title bar │
@@ -167,7 +167,7 @@ exports[`SettingsDialog > Snapshot Tests > should render 'default state' correct
│ Enable automatic session cleanup │ │ Enable automatic session cleanup │
│ │ │ │
│ Output Format Text │ │ Output Format Text │
│ The format of the CLI output. │ │ The format of the CLI output. Can be \`text\` or \`json\`. │
│ │ │ │
│ Hide Window Title false │ │ Hide Window Title false │
│ Hide the window title bar │ │ Hide the window title bar │
@@ -213,7 +213,7 @@ exports[`SettingsDialog > Snapshot Tests > should render 'file filtering setting
│ Enable automatic session cleanup │ │ Enable automatic session cleanup │
│ │ │ │
│ Output Format Text │ │ Output Format Text │
│ The format of the CLI output. │ │ The format of the CLI output. Can be \`text\` or \`json\`. │
│ │ │ │
│ Hide Window Title false │ │ Hide Window Title false │
│ Hide the window title bar │ │ Hide the window title bar │
@@ -259,7 +259,7 @@ exports[`SettingsDialog > Snapshot Tests > should render 'focused on scope selec
│ Enable automatic session cleanup │ │ Enable automatic session cleanup │
│ │ │ │
│ Output Format Text │ │ Output Format Text │
│ The format of the CLI output. │ │ The format of the CLI output. Can be \`text\` or \`json\`. │
│ │ │ │
│ Hide Window Title false │ │ Hide Window Title false │
│ Hide the window title bar │ │ Hide the window title bar │
@@ -305,7 +305,7 @@ exports[`SettingsDialog > Snapshot Tests > should render 'mixed boolean and numb
│ Enable automatic session cleanup │ │ Enable automatic session cleanup │
│ │ │ │
│ Output Format Text │ │ Output Format Text │
│ The format of the CLI output. │ │ The format of the CLI output. Can be \`text\` or \`json\`. │
│ │ │ │
│ Hide Window Title false* │ │ Hide Window Title false* │
│ Hide the window title bar │ │ Hide the window title bar │
@@ -351,7 +351,7 @@ exports[`SettingsDialog > Snapshot Tests > should render 'tools and security set
│ Enable automatic session cleanup │ │ Enable automatic session cleanup │
│ │ │ │
│ Output Format Text │ │ Output Format Text │
│ The format of the CLI output. │ │ The format of the CLI output. Can be \`text\` or \`json\`. │
│ │ │ │
│ Hide Window Title false │ │ Hide Window Title false │
│ Hide the window title bar │ │ Hide the window title bar │
@@ -397,7 +397,7 @@ exports[`SettingsDialog > Snapshot Tests > should render 'various boolean settin
│ Enable automatic session cleanup │ │ Enable automatic session cleanup │
│ │ │ │
│ Output Format Text │ │ Output Format Text │
│ The format of the CLI output. │ │ The format of the CLI output. Can be \`text\` or \`json\`. │
│ │ │ │
│ Hide Window Title true* │ │ Hide Window Title true* │
│ Hide the window title bar │ │ Hide the window title bar │
schemas/settings.schema.json
+8 -8
View File
@@ -148,8 +148,8 @@
"properties": { "properties": {
"format": { "format": {
"title": "Output Format", "title": "Output Format",
"description": "The format of the CLI output.", "description": "The format of the CLI output. Can be `text` or `json`.",
"markdownDescription": "The format of the CLI output.\n\n- Category: `General`\n- Requires restart: `no`\n- Default: `text`", "markdownDescription": "The format of the CLI output. Can be `text` or `json`.\n\n- Category: `General`\n- Requires restart: `no`\n- Default: `text`",
"default": "text", "default": "text",
"type": "string", "type": "string",
"enum": ["text", "json"] "enum": ["text", "json"]
@@ -362,8 +362,8 @@
"properties": { "properties": {
"enabled": { "enabled": {
"title": "IDE Mode", "title": "IDE Mode",
"description": "Enable IDE integration mode", "description": "Enable IDE integration mode.",
"markdownDescription": "Enable IDE integration mode\n\n- Category: `IDE`\n- Requires restart: `yes`\n- Default: `false`", "markdownDescription": "Enable IDE integration mode.\n\n- Category: `IDE`\n- Requires restart: `yes`\n- Default: `false`",
"default": false, "default": false,
"type": "boolean" "type": "boolean"
}, },
@@ -971,15 +971,15 @@
"properties": { "properties": {
"respectGitIgnore": { "respectGitIgnore": {
"title": "Respect .gitignore", "title": "Respect .gitignore",
"description": "Respect .gitignore files when searching", "description": "Respect .gitignore files when searching.",
"markdownDescription": "Respect .gitignore files when searching\n\n- Category: `Context`\n- Requires restart: `yes`\n- Default: `true`", "markdownDescription": "Respect .gitignore files when searching.\n\n- Category: `Context`\n- Requires restart: `yes`\n- Default: `true`",
"default": true, "default": true,
"type": "boolean" "type": "boolean"
}, },
"respectGeminiIgnore": { "respectGeminiIgnore": {
"title": "Respect .geminiignore", "title": "Respect .geminiignore",
"description": "Respect .geminiignore files when searching", "description": "Respect .geminiignore files when searching.",
"markdownDescription": "Respect .geminiignore files when searching\n\n- Category: `Context`\n- Requires restart: `yes`\n- Default: `true`", "markdownDescription": "Respect .geminiignore files when searching.\n\n- Category: `Context`\n- Requires restart: `yes`\n- Default: `true`",
"default": true, "default": true,
"type": "boolean" "type": "boolean"
}, },
scripts/generate-settings-doc.ts
+87 -18
View File
@@ -30,6 +30,8 @@ const MANUAL_TOP_LEVEL = new Set(['mcpServers', 'telemetry', 'extensions']);
interface DocEntry { interface DocEntry {
path: string; path: string;
type: string; type: string;
label: string;
category: string;
description: string; description: string;
defaultValue: string; defaultValue: string;
requiresRestart: boolean; requiresRestart: boolean;
@@ -46,40 +48,61 @@ export async function main(argv = process.argv.slice(2)) {
'..', '..',
); );
const docPath = path.join(repoRoot, 'docs/get-started/configuration.md'); const docPath = path.join(repoRoot, 'docs/get-started/configuration.md');
const cliSettingsDocPath = path.join(repoRoot, 'docs/cli/settings.md');
const { getSettingsSchema } = await loadSettingsSchemaModule(); const { getSettingsSchema } = await loadSettingsSchemaModule();
const schema = getSettingsSchema(); const schema = getSettingsSchema();
const sections = collectEntries(schema); const allSettingsSections = collectEntries(schema, { includeAll: true });
const generatedBlock = renderSections(sections); const filteredSettingsSections = collectEntries(schema, {
includeAll: false,
});
const doc = await readFile(docPath, 'utf8'); const generatedBlock = renderSections(allSettingsSections);
const generatedTableBlock = renderTableSections(filteredSettingsSections);
await updateFile(docPath, generatedBlock, checkOnly);
await updateFile(cliSettingsDocPath, generatedTableBlock, checkOnly);
}
async function updateFile(
filePath: string,
newContent: string,
checkOnly: boolean,
) {
const doc = await readFile(filePath, 'utf8');
const injectedDoc = injectBetweenMarkers({ const injectedDoc = injectBetweenMarkers({
document: doc, document: doc,
startMarker: START_MARKER, startMarker: START_MARKER,
endMarker: END_MARKER, endMarker: END_MARKER,
newContent: generatedBlock, newContent: newContent,
paddingBefore: '\n', paddingBefore: '\n',
paddingAfter: '\n', paddingAfter: '\n',
}); });
const formattedDoc = await formatWithPrettier(injectedDoc, docPath); const formattedDoc = await formatWithPrettier(injectedDoc, filePath);
if (normalizeForCompare(doc) === normalizeForCompare(formattedDoc)) { if (normalizeForCompare(doc) === normalizeForCompare(formattedDoc)) {
if (!checkOnly) { if (!checkOnly) {
console.log('Settings documentation already up to date.'); console.log(
`Settings documentation (${path.basename(filePath)}) already up to date.`,
);
} }
return; return;
} }
if (checkOnly) { if (checkOnly) {
console.error( console.error(
'Settings documentation is out of date. Run `npm run docs:settings` to regenerate.', 'Settings documentation (' +
path.basename(filePath) +
') is out of date. Run `npm run docs:settings` to regenerate.',
); );
process.exitCode = 1; process.exitCode = 1;
return; return;
} }
await writeFile(docPath, formattedDoc); await writeFile(filePath, formattedDoc);
console.log('Settings documentation regenerated.'); console.log(
`Settings documentation (${path.basename(filePath)}) regenerated.`,
);
} }
async function loadSettingsSchemaModule() { async function loadSettingsSchemaModule() {
@@ -87,7 +110,10 @@ async function loadSettingsSchemaModule() {
return import(modulePath); return import(modulePath);
} }
function collectEntries(schema: SettingsSchemaType) { function collectEntries(
schema: SettingsSchemaType,
options: { includeAll?: boolean } = {},
) {
const sections = new Map<string, DocEntry[]>(); const sections = new Map<string, DocEntry[]>();
const visit = ( const visit = (
@@ -107,7 +133,7 @@ function collectEntries(schema: SettingsSchemaType) {
definition.properties && definition.properties &&
Object.keys(definition.properties).length > 0; Object.keys(definition.properties).length > 0;
if (!hasChildren) { if (!hasChildren && (options.includeAll || definition.showInDialog)) {
if (!sections.has(sectionKey)) { if (!sections.has(sectionKey)) {
sections.set(sectionKey, []); sections.set(sectionKey, []);
} }
@@ -115,6 +141,8 @@ function collectEntries(schema: SettingsSchemaType) {
sections.get(sectionKey)!.push({ sections.get(sectionKey)!.push({
path: newPathSegments.join('.'), path: newPathSegments.join('.'),
type: formatType(definition), type: formatType(definition),
label: definition.label,
category: definition.category,
description: formatDescription(definition), description: formatDescription(definition),
defaultValue: formatDefaultValue(definition.default, { defaultValue: formatDefaultValue(definition.default, {
quoteStrings: true, quoteStrings: true,
@@ -162,12 +190,12 @@ function renderSections(sections: Map<string, DocEntry[]>) {
continue; continue;
} }
lines.push(`#### \`${section}\``); lines.push('#### `' + section + '`');
lines.push(''); lines.push('');
for (const entry of entries) { for (const entry of entries) {
lines.push(`- **\`${entry.path}\`** (${entry.type}):`); lines.push('- **`' + entry.path + '`** (' + entry.type + '):');
lines.push(` - **Description:** ${entry.description}`); lines.push(' - **Description:** ' + entry.description);
if (entry.defaultValue.includes('\n')) { if (entry.defaultValue.includes('\n')) {
lines.push(' - **Default:**'); lines.push(' - **Default:**');
@@ -176,21 +204,21 @@ function renderSections(sections: Map<string, DocEntry[]>) {
lines.push( lines.push(
entry.defaultValue entry.defaultValue
.split('\n') .split('\n')
.map((line) => ` ${line}`) .map((line) => ' ' + line)
.join('\n'), .join('\n'),
); );
lines.push(' ```'); lines.push(' ```');
} else { } else {
lines.push( lines.push(
` - **Default:** \`${escapeBackticks(entry.defaultValue)}\``, ' - **Default:** `' + escapeBackticks(entry.defaultValue) + '`',
); );
} }
if (entry.enumValues && entry.enumValues.length > 0) { if (entry.enumValues && entry.enumValues.length > 0) {
const values = entry.enumValues const values = entry.enumValues
.map((value) => `\`${escapeBackticks(value)}\``) .map((value) => '`' + escapeBackticks(value) + '`')
.join(', '); .join(', ');
lines.push(` - **Values:** ${values}`); lines.push(' - **Values:** ' + values);
} }
if (entry.requiresRestart) { if (entry.requiresRestart) {
@@ -204,6 +232,47 @@ function renderSections(sections: Map<string, DocEntry[]>) {
return lines.join('\n').trimEnd(); return lines.join('\n').trimEnd();
} }
function renderTableSections(sections: Map<string, DocEntry[]>) {
const lines: string[] = [];
for (const [section, entries] of sections) {
if (entries.length === 0) {
continue;
}
let title = section.charAt(0).toUpperCase() + section.slice(1);
if (title === 'Ui') {
title = 'UI';
} else if (title === 'Ide') {
title = 'IDE';
}
lines.push(`### ${title}`);
lines.push('');
lines.push('| UI Label | Setting | Description | Default |');
lines.push('| --- | --- | --- | --- |');
for (const entry of entries) {
const val = entry.defaultValue.replace(/\n/g, ' ');
const defaultVal = '`' + escapeBackticks(val) + '`';
lines.push(
'| ' +
entry.label +
' | `' +
entry.path +
'` | ' +
entry.description +
' | ' +
defaultVal +
' |',
);
}
lines.push('');
}
return lines.join('\n').trimEnd();
}
if (process.argv[1]) { if (process.argv[1]) {
const entryUrl = pathToFileURL(path.resolve(process.argv[1])).href; const entryUrl = pathToFileURL(path.resolve(process.argv[1])).href;
if (entryUrl === import.meta.url) { if (entryUrl === import.meta.url) {