Dev-tooling Configuration

Configuring the `docopslab-dev.yml` manifest for DocOps Lab development tooling

This guide pertains to the docopslab-dev environment. For complete documentation, see the project’s README.

The environment described and provided here is not optimized for DocOps Lab applications used in third-party projects. For your own applications of DocOps Labs products like ReleaseHx and Issuer, see DocOps Box for a full-featured docs-focused workspace, runtime, and production environment.

For dev-tooling setup instructions, see DocOps Lab Dev-tooling Setup.

For dev-tooling usage instructions, see DocOps Lab Dev-tooling Usage.

Initialization automatically creates .config/docopslab-dev.yml, which you can edit, or you can create it manually.

source:
  repo: DocOps/lab
  ref: v1
docs:
  - source: docs/agent/skills/*.md
    target: .agent/docs/skills/
    synced: true
  - source: docs/agent/topics/*.md
    target: .agent/docs/topics/
    synced: true
  - source: docs/agent/roles/*.md
    target: .agent/docs/roles/
    synced: true

templates:
  manifest:
    - source: templates/AGENTS.markdown
      target: ./AGENTS.md
    - source: templates/gitignore
      target: .gitignore
    - source: templates/README.asciidoc
      target: README.adoc

tools:
  - tool: rubocop
    files:
      - source: rubocop/base.yml
        target: .config/.vendor/docopslab/rubocop.yml
        synced: true
      - source: rubocop/project.yml
        target: .config/rubocop.yml
        synced: false

  - tool: vale
    files:
      - source: vale/base.ini
        target: .config/.vendor/docopslab/vale.ini
        synced: true
      - source: vale/project.ini
        target: .config/vale.local.ini
        synced: false
    paths:
      lint: ['.']
      skip:
        - build/*
        - specs/*
        - .agent/**/*
        - .config/.vendor/**/*
      exts: ['adoc']

  - tool: htmlproofer
    enabled: false  # Disabled by default, enable per project
    files:
      - source: htmlproofer/base.yml
        target: .config/.vendor/docopslab/htmlproofer.yml
        synced: true
      - source: htmlproofer/project.yml
        target: .config/htmlproofer.yml
        synced: false
    paths:
      lint: docs/_site

  - tool: shellcheck
    files:
      - source: shellcheck/base.shellcheckrc
        target: .config/shellcheckrc
        synced: true
  
  - tool: actionlint
    files:
      - source: actionlint/base.yml
        target: .config/.vendor/docopslab/actionlint.yml
        synced: true
      - source: actionlint/project.yml
        target: .config/actionlint.yml
        synced: false

library:
  enabled: true
  source:
    repo: DocOps/lab
    ref: labdev-library

Tools Properties Reference

The following parameters are available for each record in the tools: block of the manifest.

tool

(Slug, required) Name of the tool, ex:, rubocop, vale, htmlproofer, actionlint, shellcheck.

enabled

(Boolean) Whether to enable this tool’s tasks and git hooks.

manifest

(Array of Maps, required) Listing of files to init or sync for the tool. Each entry supports the following properties:

source: (Path, required) Path within the asset library where the base config is located, e.g., config-packs/rubocop/base.yml.
target: (Path, required) Path in the project where the file should be synced, e.g., .config/.vendor/docopslab/rubocop.yml.

paths

(Map) Repo-specific paths to include or exclude in linting operations for this tool.

lint: (Array) List of paths or glob patterns to lint with this tool.
skip: (Array) List of paths or glob patterns to exclude from linting with this tool.
exts: (Array) List of file extensions to include in linting with this tool.
git_tracked_only: (Boolean) Whether to limit linting to only Git-tracked files.

The docs: block in the manifest is itself a manifest array. Each entry supports the following properties:

source

(Path, required) Source path relative to lib/docopslab/ in the gem. Supports glob patterns (e.g., docs/agent/*.md) or specific files.

target

(Path, required) Target path relative to the project root. Can be a directory (e.g., _docs/) or specific file path (e.g., AGENTS.md).

synced

(Boolean) Whether to update existing files on sync.

true - Always overwrite on sync (keeps docs current with gem updates)
false - Create once, preserve user customizations

The templates: block in the manifest is a Map that nests its own manifest: listing as well as global data ingestion directives in data:.

manifest

(Array) Listing of prime templates and their downstream target files for Sync/Cast operations, optionally passing additional data.

source: (String) The path to the source template file, library relative (resolved via labdev:sync:library).
target: (String) The path in the project where the rendered template should be synced, relative to the project root.
data: (Map) Optional additional data to pass to the template rendering process.
data.variables: (Map) Key-value pairs of variables bearing any value type to pass to the template rendering process, accessible as {{ data.variables.<key> }} in templates.

See tool-specific sections in the various guides, such as for Vale (Documentation Style Guide), RuboCop (Ruby Style Guide), and HTMLProofer.