Skip to content

config-file.md

Latest commit

 

History

History
785 lines (627 loc) · 19.7 KB

config-file.md

File metadata and controls

785 lines (627 loc) · 19.7 KB

Configuration File

WriteChoice Mint CLI supports an optional config.json file for setting default values and avoiding repetitive CLI arguments.

Quick Start

Generate Config File

The easiest way to create a config.json is using the config command:

writechoice config

This creates a template file with all available options. Then edit the placeholder values:

# Edit config.json and update:
# - source: Your production documentation URL
# - target: Your validation environment URL

Manual Creation

Alternatively, create a config.json file manually in your project root:

{
  "source": "https://docs.example.com",
  "target": "http://localhost:3000"
}

Now you can run commands without arguments:

# Uses source from config.json
writechoice check links

# Uses source and target from config.json
writechoice check links

Configuration Priority

Configuration values are merged with the following priority (highest to lowest):

  1. CLI arguments - Values passed directly to the command
  2. Command-specific config - Settings in links, parse, etc.
  3. Global config - Top-level settings in config.json
  4. Built-in defaults - Hardcoded fallback values

Example

{
  "source": "https://docs.example.com",
  "links": {
    "concurrency": 50
  }
}
# Uses source from config, concurrency: 50 from links config
writechoice check links

# Uses concurrency: 100 from CLI (overrides config's 50)
writechoice check links -c 100

Complete Configuration Reference

Global Settings

Settings that apply to all commands:

{
  "source": "https://docs.example.com",
  "target": "http://localhost:3000"
}
Field Type Description Used By
source string Base URL for production documentation check links
target string Base URL for validation environment check links
preview string Base URL for a deployed preview — shared default for live checkers check pages, check images, check katex

Links Command Configuration

Settings specific to writechoice check links:

{
  "links": {
    "file": null,
    "dir": null,
    "output": "links_report",
    "dry-run": false,
    "quiet": false,
    "concurrency": 25,
    "headless": true
  }
}
Field Type Description Default
file string Validate links in a single MDX file null
dir string Validate links in a specific directory null
output string Base name for report files (without extension) links_report
dry-run boolean Extract and show links without validating false
quiet boolean Suppress terminal output false
concurrency number Number of concurrent browser tabs 25
headless boolean Run browser in headless mode true

Parse Command Configuration

Settings specific to writechoice check parse:

{
  "parse": {
    "file": null,
    "dir": null,
    "quiet": false
  }
}
Field Type Description Default
file string Validate a single MDX file null
dir string Validate MDX files in specific directory null
quiet boolean Suppress terminal output false

Pages Command Configuration

Settings specific to writechoice check pages:

{
  "pages": {
    "url": null,
    "docs": "docs.json",
    "output": "pages_report.json",
    "concurrency": 50,
    "quiet": false
  }
}
Field Type Description Default
url string Base URL for this command (overrides global preview) null
docs string Path to docs.json docs.json
output string Output file for the failure report pages_report.json
concurrency number Number of parallel HTTP requests 50
quiet boolean Suppress terminal output false

Image Check Command Configuration

Settings specific to writechoice check images:

{
  "imageCheck": {
    "url": null,
    "docs": "docs.json",
    "output": "images_report.json",
    "concurrency": 10,
    "quiet": false
  }
}
Field Type Description Default
url string Base URL for this command (overrides global preview) null
docs string Path to docs.json docs.json
output string Output file for the failure report images_report.json
concurrency number Parallel requests per phase (page fetch and image check) 10
quiet boolean Suppress terminal output false

KaTeX Command Configuration

Settings specific to writechoice check katex:

{
  "katex": {
    "url": null,
    "reportFile": "katex_errors.json"
  }
}
Field Type Description Default
url string Base URL for scan mode (overrides global preview) null
reportFile string Report file read by recheck mode (--file) katex_errors.json
docs string Path to docs.json docs.json
output string Output file for the error report katex_errors.json
concurrency number Number of parallel HTTP requests 50
quiet boolean Suppress terminal output false

Codeblocks Command Configuration

Settings specific to writechoice fix codeblocks:

{
  "codeblocks": {
    "file": null,
    "dir": null,
    "dry-run": false,
    "quiet": false,
    "threshold": 15,
    "expandable": true,
    "lines": null,
    "wrap": null
  }
}
Field Type Description Default
file string Fix a single MDX file null
dir string Fix MDX files in a specific directory null
dry-run boolean Preview changes without writing files false
quiet boolean Suppress terminal output false
threshold number Line count threshold for expandable 15
expandable boolean Enable expandable threshold processing true
lines "add" | "remove" | null Add or remove lines from all code blocks null
wrap "add" | "remove" | null Add or remove wrap from all code blocks null

Images Command Configuration

Settings specific to writechoice fix images:

{
  "images": {
    "file": null,
    "dir": null,
    "dry-run": false,
    "quiet": false
  }
}
Field Type Description Default
file string Fix a single MDX file null
dir string Fix MDX files in a specific directory null
dry-run boolean Preview changes without writing files false
quiet boolean Suppress terminal output false

Inline Images Command Configuration

Settings specific to writechoice fix inlineimages:

{
  "inlineimages": {
    "file": null,
    "dir": null,
    "dry-run": false,
    "quiet": false
  }
}
Field Type Description Default
file string Fix a single MDX file null
dir string Fix MDX files in a specific directory null
dry-run boolean Preview changes without writing files false
quiet boolean Suppress terminal output false

H1 Command Configuration

Settings specific to writechoice fix h1:

{
  "h1": {
    "file": null,
    "dir": null,
    "dry-run": false,
    "quiet": false
  }
}
Field Type Description Default
file string Fix a single MDX file null
dir string Fix MDX files in a specific directory null
dry-run boolean Preview changes without writing files false
quiet boolean Suppress terminal output false

Metadata Command Configuration

Settings specific to writechoice metadata. The base URL is read from the top-level source field:

{
  "metadata": {
    "file": null,
    "dir": null,
    "concurrency": 15,
    "tags": [
      "og:title",
      "og:description",
      "og:image",
      "og:url",
      "twitter:title",
      "twitter:description",
      "twitter:image"
    ],
    "dry-run": false,
    "quiet": false
  }
}
Field Type Description Default
file string Process a single MDX file null
dir string Process MDX files in a specific directory null
concurrency number Number of parallel HTTP requests 15
tags string[] Meta tags to fetch (overrides default list) (7 defaults)
dry-run boolean Preview changes without writing files false
quiet boolean Suppress terminal output false

Complete Example

Here's a full example showing all available options:

{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "description": "Configuration file for WriteChoice Mint CLI",

  "source": "https://docs.example.com",
  "target": "http://localhost:3000",
  "preview": "https://preview.docs.example.com",

  "links": {
    "file": null,
    "dir": null,
    "output": "links_report",
    "dry-run": false,
    "quiet": false,
    "concurrency": 25,
    "headless": true
  },

  "parse": {
    "file": null,
    "dir": null,
    "quiet": false
  },

  "pages": {
    "url": null,
    "docs": "docs.json",
    "output": "pages_report.json",
    "concurrency": 50,
    "quiet": false
  },

  "imageCheck": {
    "url": null,
    "docs": "docs.json",
    "output": "images_report.json",
    "concurrency": 10,
    "quiet": false
  },

  "katex": {
    "url": null,
    "reportFile": "katex_errors.json"
  },

  "codeblocks": {
    "file": null,
    "dir": null,
    "dry-run": false,
    "quiet": false,
    "threshold": 15,
    "expandable": true,
    "lines": null,
    "wrap": null
  },

  "images": {
    "file": null,
    "dir": null,
    "dry-run": false,
    "quiet": false
  },

  "inlineimages": {
    "file": null,
    "dir": null,
    "dry-run": false,
    "quiet": false
  },

  "h1": {
    "file": null,
    "dir": null,
    "dry-run": false,
    "quiet": false
  },

  "metadata": {
    "file": null,
    "dir": null,
    "concurrency": 15,
    "tags": [
      "og:title",
      "og:description",
      "og:image",
      "og:url",
      "twitter:title",
      "twitter:description",
      "twitter:image"
    ],
    "dry-run": false,
    "quiet": false
  }
}

Common Configurations

Production Environment

For validating against production:

{
  "source": "https://docs.example.com",
  "target": "https://docs.example.com",
  "links": {
    "concurrency": 10,
    "quiet": true
  }
}

Usage:

# Validates against production for both source and target
writechoice check links

Local Development

For local validation during development:

{
  "source": "https://docs.example.com",
  "target": "http://localhost:3000",
  "links": {
    "headless": false,
    "concurrency": 5
  }
}

Usage:

# Shows browser window and uses lower concurrency
writechoice check links

CI/CD Pipeline

For continuous integration:

{
  "source": "https://docs.example.com",
  "target": "https://staging.example.com",
  "links": {
    "quiet": true,
    "concurrency": 50
  },
  "parse": {
    "quiet": true
  }
}

Usage:

# Quiet mode with high concurrency for faster CI runs
writechoice check links
writechoice check parse

Specific Directory Validation

For validating only specific parts of your docs:

{
  "source": "https://docs.example.com",
  "target": "http://localhost:3000",
  "links": {
    "dir": "docs/api"
  },
  "parse": {
    "dir": "docs/api"
  }
}

Usage:

# Only validates files in docs/api directory
writechoice check links
writechoice check parse

Validation and Fixing Workflow

{
  "source": "https://docs.example.com",
  "target": "http://localhost:3000",
  "links": {
    "output": "links_report"
  }
}

Usage:

# 1. Run validation (generates links_report.json and links_report.md)
writechoice check links

# 2. Review the markdown report
cat links_report.md

# 3. Fix broken links automatically
writechoice fix links

# 4. Re-validate to confirm fixes
writechoice check links

For more details on fixing links, see the Fix Links Command documentation.

Environment-Specific Configs

You can maintain different config files for different environments:

# Development
cp config.dev.json config.json
writechoice check links

# Staging
cp config.staging.json config.json
writechoice check links

# Production
cp config.prod.json config.json
writechoice check links

Or use different config files based on environment variables:

# Using config based on NODE_ENV
if [ "$NODE_ENV" = "production" ]; then
  cp config.prod.json config.json
else
  cp config.dev.json config.json
fi
writechoice check links

Configuration Validation

The CLI will validate your configuration and show helpful errors:

Missing Required Fields

{
  "target": "http://localhost:3000"
}
$ writechoice check links
✗ Error: Missing required configuration: baseUrl must be provided either
via CLI argument or in config.json (as "source")

Usage:
  CLI:        check links <baseUrl>
  config.json: { "source": "https://docs.example.com" }

Invalid Values

If you provide invalid configuration values, the CLI will use sensible defaults and may show warnings.

File Location

The config.json file must be in the current working directory where you run the command.

# Looks for ./config.json
cd /path/to/your/docs
writechoice check links

# Won't find config.json in parent directory
cd /path/to/your/docs/subdirectory
writechoice check links  # No config.json found here

Schema Support

The config file supports JSON schema for IDE autocompletion and validation:

{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "description": "Configuration file for WriteChoice Mint CLI",
  "source": "https://docs.example.com"
}

In VS Code and other editors, this enables:

  • Autocompletion of field names
  • Inline documentation
  • Type validation
  • Error highlighting

Best Practices

1. Use Config for Defaults, CLI for Overrides

Set common defaults in config.json:

{
  "source": "https://docs.example.com",
  "target": "http://localhost:3000",
  "links": {
    "concurrency": 25
  }
}

Override when needed:

# Use staging for validation
writechoice check links https://docs.example.com https://staging.example.com

# Use higher concurrency for this run
writechoice check links -c 50

2. Keep Config in Version Control

Add config.json or config.example.json to git:

git add config.example.json
git commit -m "Add WriteChoice CLI configuration template"

But add reports to .gitignore:

# .gitignore
config.json
links_report.json
links_report.md
mdx_errors_report.json
mdx_errors_report.md
katex_errors.json
pages_report.json
images_report.json

3. Document Your Config

Add comments using the description field:

{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "description": "WriteChoice CLI config for MyProject documentation",
  "source": "https://docs.myproject.com",
  "target": "http://localhost:3000"
}

4. Use Quiet Mode in CI

{
  "links": {
    "quiet": true
  },
  "parse": {
    "quiet": true
  }
}

This generates reports without cluttering CI logs.

5. Optimize Concurrency

Test different concurrency values for your system:

# Try different values
writechoice check links -c 10
writechoice check links -c 25
writechoice check links -c 50
writechoice check links -c 100

Find the sweet spot and set it in config.json.

Troubleshooting

Config Not Being Used

Problem: CLI doesn't seem to use config.json values

Solutions:

  1. Verify config.json is in current working directory (pwd)
  2. Check for JSON syntax errors (use a JSON validator)
  3. Ensure field names match exactly (case-sensitive)
  4. Check that you're not passing CLI args that override config

Invalid JSON

Problem: JSON parsing errors

Solution: Validate your JSON:

# Using Node.js
node -e "JSON.parse(require('fs').readFileSync('config.json'))"

# Using Python
python -m json.tool config.json

# Using jq
jq . config.json

Unexpected Behavior

Problem: CLI behaves differently than expected

Solution: Use --help to see current defaults:

writechoice check links --help

Check which config values are being used by reviewing the report configuration section.

See Also