TUT Reference

What is TUT?

TUT is a data-driven documentation generator that converts JSON definitions into HTML documentation. It supports two document types: guides (step-by-step tutorials) and reference docs (scrollable topic-based documentation).

Quick Start

Get started generating documentation in seconds.

# List available sources
tut get sources

# Build a document
tut build my-ref

# Generate landing page
tut index

# Preview in browser
tut serve

Environment

TUT uses two environment variables for paths.

Run tut doctor to verify your environment is configured correctly.

tut build

Build documentation from JSON source files.

tut build nh-ref --no-bump

tut init

Create a new document from template.

tut init my-project-ref --type reference

tut serve

Start a local server and preview documentation.

tut serve tut-reference.html

tut index

Generate a landing page for all documents.

tut index

The index page extracts metadata (title, version, type) from each document's meta tags and displays them in a card grid.

tut get

Query sources and generated documents.

• tut get sources List JSON files in available/
• tut get docs List generated HTML files with metadata
• tut get recordings List terminal recordings (.cast files)

Other Commands

• tut validate Validate JSON against schema
• tut doctor Check environment and paths
• tut types Overview of document types
• tut types guide Guide schema and structure
• tut types reference Reference schema and structure
• tut help Show help

paragraph

Simple text block.

{
  "type": "paragraph",
  "text": "Your text content here."
}

command-list

List of commands with descriptions. Ideal for CLI reference.

{
  "type": "command-list",
  "commands": [
    { "code": "cmd arg", "description": "What it does" },
    { "code": "cmd --flag", "description": "Another command" }
  ]
}

Renders as:

• cmd arg What it does
• cmd --flag Another command

code-block

Fenced code with optional language. Click-to-copy is automatic.

{
  "type": "code-block",
  "language": "bash",
  "code": "echo 'Hello World'"
}

module-grid

Grid of cards for displaying modules, features, or options.

{
  "type": "module-grid",
  "modules": [
    { "name": "Module A", "description": "Does X" },
    { "name": "Module B", "description": "Does Y" }
  ]
}

Renders as:

list

Ordered or unordered list.

{
  "type": "list",
  "ordered": false,
  "items": ["First item", "Second item", "Third item"]
}

table

Data table with headers and rows.

{
  "type": "table",
  "headers": ["Name", "Type", "Description"],
  "rows": [
    ["id", "string", "Unique identifier"],
    ["title", "string", "Display title"]
  ]
}

Renders as:

api-endpoint

REST API endpoint documentation with method, path, parameters, and responses.

{
  "email": "user@example.com",
  "name": "John Doe"
}

api-function

Function/method documentation with signature, parameters, returns, and example.

_tut_build nh-ref --no-bump

Reference Structure

Reference documents are organized into groups containing topics.

{
  "metadata": {
    "title": "My Docs",
    "tagline": "Optional subtitle",
    "version": "1.0.0"
  },
  "groups": [
    {
      "id": "getting-started",
      "title": "Getting Started",
      "topics": [
        {
          "id": "install",
          "title": "Installation",
          "description": "How to install...",
          "content": [ ... ]
        }
      ]
    }
  ]
}

Guide Structure

Guides are linear step-by-step tutorials with terminal simulation.

{
  "metadata": {
    "title": "My Guide",
    "difficulty": "beginner",
    "estimatedTime": 15
  },
  "steps": [
    {
      "id": "step-1",
      "title": "Step 1",
      "content": [ ... ],
      "terminal": [
        { "type": "prompt", "content": "$ " },
        { "type": "command", "content": "echo hello" },
        { "type": "output", "content": "hello" }
      ]
    }
  ]
}

File Organization

Design Tokens

TUT uses CSS custom properties for theming. Access the design token editor by adding ?design=true to any document URL.

Design Token Editor

The FAB (Floating Action Button) provides real-time theme editing.

• Add ?design=true to any document URL to enable
• Click the FAB to open the design panel
• Edit colors, fonts, and section styles
• Export theme as tokens.json file
• Import themes from file or localStorage
• Copy CSS variables to clipboard

Themes are saved to localStorage and persist across sessions.

Google Fonts

Add custom fonts by pasting the Google Fonts embed code.

1. Go to fonts.google.com and select fonts
2. Click 'Get embed code'
3. Paste the full embed code into the font input
4. Multi-font suites are supported
5. Mono fonts auto-assign to Code, sans fonts to Heading/Body