manual.adoc

UTF8DOK User Guide

Table of Contents

• 1. Introduction
  • 1.1. Who Is This For?
• 2. Installation
  • 2.1. CLI Installation
    • 2.1.1. From GitHub Releases
    • 2.1.2. From Cargo
  • 2.2. VS Code Extension
• 3. Quick Start
  • 3.1. Creating a New Project
  • 3.2. Running Your First Audit
  • 3.3. Generating a Dashboard
• 4. Commands Reference
  • 4.1. utf8dok init
    • 4.1.1. Bridge Template
    • 4.1.2. Basic Template
  • 4.2. utf8dok audit
    • 4.2.1. CI/CD Usage
  • 4.3. utf8dok dashboard
  • 4.4. utf8dok check
  • 4.5. utf8dok extract
  • 4.6. utf8dok render
• 5. Configuration Reference
  • 5.1. Workspace Settings
  • 5.2. Bridge Compliance
  • 5.3. Plugins
• 6. Bridge Framework ADRs
  • 6.1. What is an ADR?
  • 6.2. Required Attributes
  • 6.3. ADR Lifecycle
  • 6.4. Compliance Rules
• 7. VS Code Extension
  • 7.1. Features
  • 7.2. Status Bar
  • 7.3. Commands
• 8. Troubleshooting
  • 8.1. "Command not found: utf8dok"
  • 8.2. "Failed to parse config"
  • 8.3. VS Code extension not working
  • 8.4. Audit shows orphaned documents
• 9. Appendix: AsciiDoc Primer
  • 9.1. Document Structure
  • 9.2. Cross-References
  • 9.3. Attributes
  • 9.4. Diagrams

1. Introduction

UTF8DOK is a universal documentation platform that provides:

• Compliance Engine: Validates Architecture Decision Records (ADRs) against the Bridge Framework

• Content Intelligence: Diagram syntax highlighting and writing quality suggestions

• Developer Experience: VS Code extension with real-time feedback

• CI/CD Integration: Automated compliance checks for pull requests

1.1. Who Is This For?

UTF8DOK is designed for:

• Software architects documenting decisions

• Technical writers maintaining large documentation sets

• Teams adopting the Bridge Framework for ADRs

• Organizations requiring documentation governance

2. Installation

2.1. CLI Installation

2.1.1. From GitHub Releases

Download the latest release for your platform:

# Linux (x64)
curl -LO https://github.com/utf8dok/utf8dok/releases/latest/download/utf8dok-linux-x64
chmod +x utf8dok-linux-x64
sudo mv utf8dok-linux-x64 /usr/local/bin/utf8dok

# macOS (Apple Silicon)
curl -LO https://github.com/utf8dok/utf8dok/releases/latest/download/utf8dok-macos-arm64
chmod +x utf8dok-macos-arm64
sudo mv utf8dok-macos-arm64 /usr/local/bin/utf8dok

# macOS (Intel)
curl -LO https://github.com/utf8dok/utf8dok/releases/latest/download/utf8dok-macos-x64
chmod +x utf8dok-macos-x64
sudo mv utf8dok-macos-x64 /usr/local/bin/utf8dok

2.1.2. From Cargo

If you have Rust installed:

cargo install utf8dok-cli

2.2. VS Code Extension

1. Open VS Code

2. Go to Extensions (Ctrl+Shift+X)

3. Search for "UTF8DOK"

4. Click Install

Or install from command line:

code --install-extension utf8dok-vscode.vsix

3. Quick Start

3.1. Creating a New Project

Use utf8dok init to scaffold a new documentation workspace:

# Create a Bridge Framework project (ADR-focused)
utf8dok init my-docs

# Or create a basic AsciiDoc project
utf8dok init my-docs --template basic

This creates:

my-docs/
├── utf8dok.toml                              # Configuration
├── index.adoc                                # Documentation hub
└── adr/                                      # ADR directory (Bridge only)
    └── 0001-record-architecture-decisions.adoc

3.2. Running Your First Audit

cd my-docs
utf8dok audit

Expected output:

utf8dok v0.1.0
Auditing: .
  Found 2 documents

=== Compliance Report ===

Score: 100%
Documents: 2
Errors: 0
Warnings: 0
Info: 0

✓ No compliance violations found

3.3. Generating a Dashboard

Create an HTML compliance report:

utf8dok dashboard --output report.html
open report.html  # macOS
xdg-open report.html  # Linux

4. Commands Reference

4.1. utf8dok init

Scaffold a new documentation workspace.

utf8dok init <path> [OPTIONS]

Arguments:
  <path>  Path for the new workspace

Options:
  -t, --template <TEMPLATE>  Template to use [default: bridge]
                             Possible values: bridge, basic

4.1.1. Bridge Template

Creates an ADR-focused workspace with:

• utf8dok.toml with Bridge compliance rules

• index.adoc linking to ADRs

• Sample ADR with all required sections

4.1.2. Basic Template

Creates a simple AsciiDoc project with:

• utf8dok.toml with basic settings

• index.adoc with starter content

4.2. utf8dok audit

Check documentation compliance for CI/CD pipelines.

utf8dok audit [OPTIONS] [INPUT]

Arguments:
  [INPUT]  Input directory [default: .]

Options:
  -f, --format <FORMAT>  Output format [default: text]
                         Possible values: text, json, markdown
      --strict           Exit with error if violations found
  -c, --config <CONFIG>  Configuration file path

4.2.1. CI/CD Usage

For GitHub Actions:

- name: Documentation Audit
  run: utf8dok audit docs/ --strict --format markdown >> $GITHUB_STEP_SUMMARY

4.3. utf8dok dashboard

Generate an HTML compliance dashboard.

utf8dok dashboard [OPTIONS] [INPUT]

Arguments:
  [INPUT]  Input directory [default: .]

Options:
  -o, --output <OUTPUT>  Output file [default: compliance-dashboard.html]
  -c, --config <CONFIG>  Configuration file path

4.4. utf8dok check

Validate a single AsciiDoc file.

utf8dok check <input> [OPTIONS]

Arguments:
  <input>  Input AsciiDoc file

Options:
  -f, --format <FORMAT>  Output format [default: text]
                         Possible values: text, json
  -p, --plugin <PLUGIN>  Rhai plugin script for custom rules

4.5. utf8dok extract

Extract AsciiDoc from a DOCX file.

utf8dok extract <input> [OPTIONS]

Arguments:
  <input>  Input DOCX file

Options:
  -o, --output <OUTPUT>  Output directory [default: output]
      --force-parse      Force parsing even if embedded source exists

4.6. utf8dok render

Render AsciiDoc to DOCX using a template.

utf8dok render <input> [OPTIONS]

Arguments:
  <input>  Input AsciiDoc file

Options:
  -o, --output <OUTPUT>    Output DOCX file
  -t, --template <TEMPLATE>  Template DOTX file

5. Configuration Reference

UTF8DOK is configured via utf8dok.toml.

5.1. Workspace Settings

[workspace]
root = "."                           # Documentation root directory
entry_points = ["index.adoc", "README.adoc"]  # Entry point documents

5.2. Bridge Compliance

[compliance.bridge]
orphans = "error"           # Documents must be reachable
superseded_status = "error" # Superseded ADRs need correct status
missing_status = "warning"  # Warn if :status: is missing
missing_date = "warning"    # Warn if :date: is missing

Severity levels:

• error - Fails CI/CD in strict mode

• warning - Reported but doesn’t fail

• info - Informational only

• off - Disabled

5.3. Plugins

[plugins]
writing_quality = true   # Enable weasel word detection
diagrams = true          # Enable diagram validation

# Optional: Custom words to flag
custom_weasel_words = ["obviously", "clearly", "simply"]

6. Bridge Framework ADRs

6.1. What is an ADR?

An Architecture Decision Record (ADR) documents a significant architectural decision. Each ADR includes:

• Unique identifier (e.g., adr-0001)

• Status (Proposed, Accepted, Deprecated, Superseded)

• Context explaining why the decision is needed

• The decision itself

• Consequences (positive and negative)

6.2. Required Attributes

[[adr-0001]]
= ADR 0001: Use PostgreSQL for Persistence
:status: Accepted
:date: 2025-01-15

Optional attributes:

• :relates-to: - Links to related ADRs (e.g., adr-0002, adr-0003)

• :supersedes: - The ADR this one replaces (e.g., adr-0000)

6.3. ADR Lifecycle

1. Proposed: Under discussion

2. Accepted: Decision made and implemented

3. Deprecated: No longer relevant

4. Superseded: Replaced by another ADR (use :supersedes:)

6.4. Compliance Rules

UTF8DOK validates:

Rule	Description
BRIDGE001	Superseded ADRs must have status Deprecated or Superseded
BRIDGE002	ADRs should have required sections (Context, Decision, Consequences)
BRIDGE003	Documents must be reachable from entry points

7. VS Code Extension

7.1. Features

• Real-time validation: See compliance issues as you type

• Quick fixes: One-click fixes for common problems

• Diagram preview: Syntax highlighting for Mermaid, PlantUML

• Compliance dashboard: View workspace-wide status

7.2. Status Bar

The status bar shows:

• ✓ Ready - All documents compliant

• ⚠ 3 issues - Warnings/errors found

• ⏳ Loading - Analyzing workspace

Click the status bar to open the compliance dashboard.

7.3. Commands

• UTF8DOK: Show Dashboard - Open compliance panel

• UTF8DOK: Run Audit - Run full workspace audit

• UTF8DOK: Fix All - Apply all available quick fixes

• UTF8DOK: Restart Server - Restart the language server

8. Troubleshooting

8.1. "Command not found: utf8dok"

Ensure the binary is in your PATH:

which utf8dok
# Should output: /usr/local/bin/utf8dok (or similar)

8.2. "Failed to parse config"

Check your utf8dok.toml syntax:

cat utf8dok.toml | head -20
# Look for missing quotes or brackets

8.3. VS Code extension not working

1. Check the Output panel (View → Output)

2. Select "UTF8DOK" from the dropdown

3. Look for error messages

8.4. Audit shows orphaned documents

Documents must be linked from an entry point. Add a cross-reference:

// In index.adoc
* <<path/to/document.adoc#,Document Title>>

9. Appendix: AsciiDoc Primer

9.1. Document Structure

= Document Title
:toc: left
:author: Your Name

== Section

Paragraph text.

=== Subsection

More text.

9.2. Cross-References

// Define an anchor
[[my-section]]
== My Section

// Reference it
See <<my-section>> for details.

// Reference another file
See <<other-file.adoc#,Other Document>>.

9.3. Attributes

:status: Accepted    // Document attribute
:date: 2025-01-15    // Another attribute

9.4. Diagrams

[mermaid]

graph TD A[Start] -→ B[End]