Documenting

Automatic Documentation Generation

env-sentinel can automatically generate comprehensive markdown documentation from your annotated schema files. This feature helps teams stay aligned by providing a single source of truth for all environment variables.

Why Documentation Matters

Proper documentation of environment variables:

• Speeds up onboarding - New team members understand configuration quickly
• Reduces mistakes - Clear descriptions prevent misconfiguration
• Improves collaboration - Everyone knows what each variable does
• Maintains consistency - Documentation stays in sync with validation rules
• Enhances security - Sensitive variables are clearly marked

Basic Usage

Generate documentation from your schema file:

Copy
npx env-sentinel docs

This creates a CONFIGURATION.md file with a complete reference of all your environment variables.

Custom Output

Specify custom schema and output files:

Copy
npx env-sentinel docs --schema .env-sentinel --output CONFIG.md

Options:

• --schema <path> - Schema file to document (default: .env-sentinel)
• --output <path> - Output markdown file (default: CONFIGURATION.md)

Annotating Your Schema

To generate rich documentation, add special comment tags to your schema file:

Available Tags

Example Annotated Schema

Copy
# ============================================================================
# @section Application
# @description Core application settings and behavior.
# These variables control the fundamental application configuration
# and must be properly set before deployment.
# ============================================================================

# @var Application name displayed in logs and UI
# @example MyAwesomeApp
APP_NAME=required

# @var Application environment mode
# @example production
APP_ENV=required|enum:development,staging,production

# @var Enable debug mode with verbose logging
APP_DEBUG=boolean|default:"false"

# @var Port number for the application server
APP_PORT=number|min:1|max:65535|default:"3000"

# ============================================================================
# @section Database
# @description Database connection and configuration settings.
# All database-related variables including connection pooling.
# Make sure to use secure passwords and proper SSL configuration in production.
# ============================================================================

# @var Database server hostname or IP address
# @example localhost
DB_HOST=required

# @var Database server port number
# @example 5432
DB_PORT=required|number|min:1|max:65535

# @var Database password (keep secure!)
DB_PASSWORD=required|secure|min:8

Generated Documentation Structure

The generated markdown includes:

1. Table of Contents

Automatically generated with links to each section:

Copy
## Table of Contents

- [Application](#application)
- [Database](#database)
- [Cache](#cache)

2. Section Headers

Each section gets a clear header with its description:

Copy
## Application

Core application settings and behavior.
These variables control the fundamental application configuration
and must be properly set before deployment.

3. Variable Tables

Variables are organized in tables with complete information:

4. Automatic Features

The documentation generator automatically:

• Extracts type information - From validation rules (number, boolean, enum, etc.)
• Shows constraints - Min/max values, enum options
• Highlights secure variables - Marked with 🔒 icon
• Includes default values - From default:"value" rules
• Supports multi-line descriptions - For detailed explanations
• Creates section anchors - For easy navigation

Multi-line Descriptions

Both section descriptions and variable descriptions support multiple lines:

Copy
# @section Security
# @description Authentication and security settings.
# Critical security configuration for user authentication and session management.
# All secret values must be kept secure and rotated regularly.

# @var Secret key for JWT token signing (keep secure!).
# Must be at least 32 characters long with high entropy.
# Never commit this value to version control.
JWT_SECRET=required|secure|min:32

This generates comprehensive documentation with all the details your team needs.

Integration with CI/CD

Generate documentation automatically in your CI pipeline:

GitHub Actions

Copy
- name: Generate environment docs
  run: npx env-sentinel docs --schema .env-sentinel-example --output docs/CONFIGURATION.md
  
- name: Commit documentation
  uses: stefanzweifel/git-auto-commit-action@v4
  with:
    commit_message: "docs: update environment variables documentation"
    file_pattern: docs/CONFIGURATION.md

GitLab CI

Copy
generate-docs:
  script:
    - npx env-sentinel docs
    - git add CONFIGURATION.md
    - git commit -m "docs: update environment variables documentation" || true

Best Practices

1. Keep Documentation in Sync

Run npx env-sentinel docs after every schema change to keep documentation updated.

2. Use Descriptive Comments

Write clear, concise descriptions that explain:

• What the variable does
• Why it's needed
• How it should be configured
• When to change default values

3. Organize with Sections

Group related variables into logical sections:

• Application settings
• Database configuration
• Third-party APIs
• Security credentials
• Development tools

4. Mark Sensitive Variables

Always use the secure validator for passwords and API keys - they'll be automatically highlighted with 🔒 in the documentation.

5. Provide Examples

Use the @example tag to show realistic values:

Copy
# @var Base URL of the application
# @example https://myapp.com
APP_URL=required

See also

• Learn about Validation to enforce variable types and constraints.
• Explore Linting to catch formatting issues.
• Get started with the Quickstart Guide.

With env-sentinel, your team always has up-to-date, accurate, and comprehensive environment variable documentation.