JSON Formatter Integration with Continuous Documentation Tools

In modern software development, APIs and configurations often rely heavily on JSON. Providing clear, accurate, and consistently formatted JSON examples in your documentation is crucial for developers consuming your tools or services. However, manually maintaining the format and accuracy of JSON snippets across potentially hundreds or thousands of documentation files can quickly become a burden and a source of errors.

Integrating JSON formatters directly into your documentation workflow, especially within a "Continuous Documentation" approach, can automate this process, ensuring examples are always clean, readable, and syntactically correct. This article explores why this integration is valuable and how you can achieve it using various tools and techniques.

Why Integrate JSON Formatting into Docs?

Documentation serves as the primary interface between your code and its users (other developers). Inconsistent or poorly formatted code examples can significantly hinder understanding and developer experience. Specifically for JSON:

• Readability: Unformatted JSON (e.g., a single long line) is difficult to parse visually. Proper indentation, spacing, and line breaks make it easy to read nested structures.
• Consistency: Different contributors might use different formatting styles (e.g., spaces vs. tabs, quote styles). Automation enforces a single, consistent style.
• Accuracy: While formatting doesn't guarantee semantic correctness, validating and formatting often catches basic syntax errors before they are published.
• Maintainability: Automating formatting reduces the manual effort required during documentation updates.

Continuous Documentation & JSON

Continuous Documentation treats documentation as an integral part of the software development lifecycle. It's version-controlled alongside code, built and deployed automatically, and reviewed through standard processes (like pull requests). Tools commonly used in this space include:

• Static Site Generators (e.g., Hugo, Jekyll, Next.js, VuePress, MkDocs) for building documentation websites from Markdown or other source files.
• API Documentation Generators (e.g., Swagger UI, OpenAPI Generator, Postman documentation).
• Git repositories (GitHub, GitLab, Bitbucket) for version control and collaboration.
• CI/CD pipelines (GitHub Actions, GitLab CI, Jenkins, CircleCI) for automation.

Within this ecosystem, JSON examples often live inside code blocks within Markdown files (or similar formats). Integrating a JSON formatter means these code blocks are automatically processed at some point in the workflow.

Integration Methods

There are several points in the documentation workflow where JSON formatting can be integrated:

1. Git Hooks (Pre-commit or Pre-push)

This is one of the most effective methods for maintaining code style, including JSON formatting. You can set up scripts that run automatically before a commit is created or before code is pushed to the remote repository.

Popular tools for managing Git hooks in JavaScript/TypeScript projects include Husky and lint-staged. `lint-staged` allows you to run formatters/linters only on the files staged for commit, making the hooks fast.

You can configure tools like Prettier (which supports JSON out-of-the-box) or ESLint (with plugins) to automatically format or check JSON files (`.json`) and potentially JSON code blocks within documentation files (e.g., Markdown).

{
  "name": "my-docs-repo",
  "version": "1.0.0",
  "scripts": {
    "format": "prettier --write \"**/*.{js,ts,json,md}\"",
    "lint": "eslint \"**/*.{js,ts}\" --fix",
    "lint:json": "eslint \"**/*.json\" --fix"
    // Add script to format/lint JSON in markdown if needed
  },
  "devDependencies": {
    "husky": "^8.0.0",
    "lint-staged": "^13.0.0",
    "prettier": "^2.0.0",
    "eslint": "^8.0.0",
    "eslint-plugin-json": "^2.1.2" // Example JSON plugin
  },
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  },
  "lint-staged": {
    "*.{js,ts}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.json": [
      "eslint --fix", // Uses eslint-plugin-json if configured
      "prettier --write"
    ],
    "*.md": [
      "prettier --write" // Prettier formats code blocks in markdown
    ]
  }
}

2. CI/CD Pipelines

Even if Git hooks are used, integrating formatting and linting checks into your CI pipeline provides a safety net. If any unformatted or invalid JSON makes it past the local checks, the CI build can fail, preventing it from being merged or deployed.

In your CI configuration (e.g., `.github/workflows/docs.yml` for GitHub Actions, `.gitlab-ci.yml` for GitLab CI), you can add steps to run formatters and linters across your documentation source files.

name: Documentation CI

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:
  build-and-lint:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install dependencies
        run: npm install # Or yarn install

      - name: Check JSON formatting and linting
        # Use the check command instead of write to fail on errors
        run: |
          npx prettier --check "**/*.{js,ts,json,md}"
          npx eslint "**/*.{js,ts}"
          npx eslint "**/*.json"

      - name: Build Documentation (Example)
        run: npm run docs:build # Replace with your doc build command

      # Add deployment steps if applicable

3. Documentation Generator Plugins or Custom Scripts

Some documentation tools might offer plugins that can process code blocks during the documentation build process. For example, a Markdown renderer might be extended to pipe `json` code blocks through a formatter.

Alternatively, you could write a custom script that:

1. Finds all documentation files (e.g., `.md`, `.adoc`).
2. Parses each file to locate JSON code blocks (e.g., lines starting with ` ```json ` and ending with ` ``` `).
3. Extracts the JSON content from the block.
4. Uses a JSON formatter (like a programmatic Prettier API, or a command-line tool like `jq`) to reformat the content.
5. Replaces the original content in the code block with the formatted version.

This script could be run manually, as part of a Git hook, or as a step in your CI pipeline before the documentation build starts.

#!/bin/bash

DOC_FILE="path/to/your/doc.md"
TEMP_JSON_FILE="/tmp/temp.json"

# A very basic example: extract JSON from a specific block, format, and replace
# NOTE: This requires advanced text manipulation (sed/awk) or a proper parser
# This example is illustrative only, not a robust solution.

# Example: Find a line containing '\`\`\`json', assume the next lines until '\`\`\`' are JSON
# Extract JSON content (highly simplified)
# sed -n '/\`\`\`json/{:a;n;/^\`\`\`/!{p;ba}}' "$DOC_FILE" > "$TEMP_JSON_FILE"

# If JSON extraction was successful, format it
# if [ -s "$TEMP_JSON_FILE" ]; then
#   jq '.' "$TEMP_JSON_FILE" > "$TEMP_JSON_FILE.formatted"
  # Now, somehow replace the original JSON block in DOC_FILE with the content of $TEMP_JSON_FILE.formatted
  # This replacement step is complex and error-prone with simple shell tools.
  # A Node.js script with a markdown parser would be more robust.
# fi

echo "Conceptual script ran. A real implementation needs robust parsing and replacement."
echo "Using Prettier for .md files is often simpler as it handles code blocks automatically."

# Clean up temp file
# rm "$TEMP_JSON_FILE" "$TEMP_JSON_FILE.formatted" 2>/dev/null

Benefits of Automation

• Improved Developer Experience: Users of your documentation find examples easier to read and copy.
• Reduced Errors: Automated checks catch syntax issues early.
• Faster Writing/Review Cycles: Authors don't spend time manually formatting; reviewers focus on content accuracy, not style.
• Guaranteed Consistency: All JSON examples adhere to the same style rules.
• "Source of Truth" Sync: If your JSON examples are generated or derived from code/schemas, formatting keeps them clean.

Potential Challenges

• Tooling Complexity: Setting up Git hooks or CI can have a learning curve.
• Documentation Format Parsing: Correctly identifying and extracting JSON from various documentation formats (Markdown, AsciiDoc, etc.) requires careful implementation if not using a tool like Prettier that supports it.
• Ignoring Specific Blocks: You might need ways to mark certain JSON blocks to be excluded from formatting (e.g., if they intentionally demonstrate malformed JSON).
• Large Repositories: Running formatters on every file on every commit can be slow if not optimized (hence `lint-staged` for Git hooks).

Choosing the Right Tool(s)

The best approach often involves a combination of tools:

• Prettier: Excellent for automatic formatting of `.json` files and JSON code blocks within Markdown. Easy to set up via CLI or API.
• ESLint: Powerful for linting and finding syntactic/semantic issues. Can be extended with plugins for JSON-specific rules.
• `jq` / `jsonlint`: Command-line tools useful for basic validation and reformatting in scripts, though less flexible than Prettier for complex scenarios or embedding in files.
• Husky & lint-staged: Standard tools for integrating formatters/linters into Git workflow.
• CI Provider Tools: Leverage GitHub Actions, GitLab CI, etc., to enforce checks remotely.

For most modern documentation projects using Markdown or similar text formats in a Git repository, integrating Prettier with Husky and a CI check provides a robust and relatively simple solution for ensuring JSON examples are consistently formatted.

Conclusion

Integrating JSON formatters into your continuous documentation workflow transforms a tedious manual task into an automated, reliable process. By leveraging tools like Prettier, Git hooks, and CI pipelines, you can significantly improve the quality, consistency, and maintainability of your documentation's JSON examples, ultimately leading to a better experience for the developers who rely on your work. Start by choosing a formatter that supports your documentation file types and integrate it at the most appropriate point in your existing development and documentation pipeline.