Configuration

Configuration File

Create .docs-coderefrc.json in your project root:

{
  "projectRoot": ".",
  "docsDir": "docs",
  "ignoreFile": ".gitignore",
  "ignorePatterns": ["**/*.draft.md"],
  "verbose": false
}

Configuration Sources

The tool loads configuration from multiple sources with the following precedence (highest to lowest):

Programmatic options - Passed directly to the API
Environment variables - DOCS_CODEREF_* prefixed variables
.docs-coderefrc.json - Configuration file in project root
package.json - "docs-coderef" field
Default values - Built-in defaults

Configuration Options

Base Configuration (CodeRefConfig)

`projectRoot`

Type: string
Default: process.cwd() (current working directory)
Description: Root directory of your project. All paths are resolved relative to this directory.

{
  "projectRoot": "."
}

`docsDir`

Type: string
Default: "docs"
Description: Directory containing your documentation files, relative to projectRoot.

{
  "docsDir": "documentation"
}

`ignoreFile`

Type: string (optional)
Default: undefined
Description: Path to ignore file relative to projectRoot. The file follows .gitignore syntax.

{
  "ignoreFile": ".gitignore"
}

Note: Prior to version 0.2.0, the default value was .docsignore. If you want to continue using .docsignore, explicitly set ignoreFile: '.docsignore' in your configuration.

`ignorePatterns`

Type: string[] (optional)
Default: undefined
Description: Additional glob patterns to ignore, complementing the ignore file.

{
  "ignorePatterns": ["**/*.draft.md", "**/temp/**", "**/*.backup.md"]
}

`verbose`

Type: boolean (optional)
Default: false
Description: Enable verbose logging for detailed output.

{
  "verbose": true
}

`targets`

Type: string[] (optional)
Default: undefined
Description: Specific files or directories to validate, relative to docsDir. If not specified, all markdown files in docsDir are validated.

{
  "targets": ["README.md", "guides/"]
}

Fix Command Configuration (CodeRefFixConfig)

The fix command extends the base configuration with additional options:

`dryRun`

Type: boolean (optional)
Default: false
Description: Show what would be fixed without modifying files (simulation mode).

{
  "dryRun": true
}

`auto`

Type: boolean (optional)
Default: false
Description: Automatically apply all fixes without prompting for confirmation.

{
  "auto": true
}

`backup`

Type: boolean (optional)
Default: true
Description: Create backup files (.backup extension) before applying fixes.

{
  "backup": false
}

Configuration Examples

Basic Configuration

Minimal configuration for a standard project:

{
  "projectRoot": ".",
  "docsDir": "docs"
}

Advanced Configuration

Configuration with custom ignore patterns and verbose output:

{
  "projectRoot": ".",
  "docsDir": "documentation",
  "ignoreFile": ".gitignore",
  "ignorePatterns": ["**/*.draft.md", "**/archive/**", "**/_*.md"],
  "verbose": true
}

Monorepo Configuration

Configuration for a monorepo with multiple documentation directories:

{
  "projectRoot": "packages/my-package",
  "docsDir": "docs",
  "ignoreFile": "../../.gitignore"
}

Environment Variables

You can override configuration using environment variables:

# Set project root
export DOCS_CODEREF_PROJECT_ROOT=/path/to/project

# Set docs directory
export DOCS_CODEREF_DOCS_DIR=documentation

# Set ignore file
export DOCS_CODEREF_IGNORE_FILE=.customignore

# Enable verbose mode
export DOCS_CODEREF_VERBOSE=true

# Run validation
npx docs-coderef validate

package.json Configuration

Alternatively, you can define configuration in package.json:

{
  "name": "my-package",
  "version": "1.0.0",
  "docs-coderef": {
    "docsDir": "documentation",
    "verbose": true
  }
}

Ignore Files

Ignore File Syntax

The ignore file follows the same syntax as .gitignore:

# Ignore draft files
**/*.draft.md

# Ignore temporary directories
**/temp/
**/tmp/

# Ignore specific files
notes.md
TODO.md

# Negative patterns (don't ignore)
!important.draft.md

Common Ignore Patterns

# Build artifacts
**/dist/
**/build/

# Temporary files
**/*.tmp
**/*.backup

# Version control
**/.git/

# Node modules
**/node_modules/

# Editor files
**/.vscode/
**/.idea/

Programmatic Usage

You can also configure the tool programmatically when using the API:

import { validate, fix } from 'docs-coderef';

// Validate with custom configuration
await validate({
  projectRoot: '.',
  docsDir: 'docs',
  verbose: true,
  ignorePatterns: ['**/*.draft.md'],
});

// Fix with custom configuration
await fix({
  projectRoot: '.',
  docsDir: 'docs',
  auto: true,
  backup: true,
});

FilesExpand file tree

configuration.md

Latest commit

History