Contributing to Documentation

LuCLI Documentation Build

This directory contains the source markdown files for LuCLI documentation.

Structure

content/docs/
├── index.md                          # Documentation home page
├── 010_getting-started/              # Installation and quick start
├── 020_core-features/                # Command execution and help
├── 030_server-management/            # Server configuration and management
├── 040_advanced/                     # Advanced topics
├── 050_development/                  # Extending LuCLI
└── 060_reference/                    # Auto-generated command reference
    └── 010_command-reference.md      # ⚠️ Auto-generated - DO NOT EDIT

Naming Convention

Files and folders use numeric prefixes (010_, 020_, etc.) for ordering in the navigation:

  • Zero-padded 3 digits - Ensures correct alphabetical sorting
  • 10-gap spacing - Allows easy insertion of new items
  • Folder names - Become section titles (e.g., 010_getting-started → "Getting Started")
  • File names - Become page titles (e.g., 020_shortcuts.md → "Shortcuts")

Building Documentation

Quick Build

# Regenerate command reference and build docs
./build-docs.sh

Manual Steps

# 1. Build LuCLI
mvn clean package -DskipTests

# 2. Generate command reference from picocli
java -jar target/lucli.jar completion md > content/docs/060_reference/010_command-reference.md

# 3. Build documentation site with markspresso
lucli markspresso build clean

# 4. View documentation
open public/docs/index.html

Watch Mode

# Auto-rebuild on changes
lucli markspresso watch

Command Reference

The command reference (060_reference/010_command-reference.md) is auto-generated from the picocli command structure. Do not edit it manually!

To update the command reference:

  1. Make changes to command definitions in Java code
  2. Run mvn clean package to rebuild LuCLI
  3. Run java -jar target/lucli.jar completion md > content/docs/060_reference/010_command-reference.md
  4. Run lucli markspresso build clean to regenerate the site

Or simply run ./build-docs.sh to do all steps automatically.

Front Matter

Each markdown file requires front matter:

---
title: Page Title
layout: docs
---

# Content goes here

Navigation

The left sidebar navigation is automatically generated from the directory structure:

  • Files and folders are sorted by numeric prefix
  • Folder names become section headers
  • File names become navigation links
  • The current page is highlighted
  • All numeric prefixes are stripped from URLs

Adding New Pages

  1. Choose the appropriate section folder
  2. Pick a numeric prefix (use 10-gap spacing)
  3. Create file: NNN_page-name.md
  4. Add front matter with title and layout
  5. Write content in markdown
  6. Run lucli markspresso build to regenerate

Example:

# Add new page between 020 and 030
touch content/docs/010_getting-started/025_troubleshooting.md

Styling

The documentation uses the custom docs layout (content/layouts/docs.html) with styling from content/assets/css/docs.css.

Features:

  • Dark/light theme support
  • Responsive design
  • Left navigation sidebar
  • Right table of contents (auto-generated by JS)
  • Syntax highlighting for code blocks

Output

Built files are generated to public/docs/ with clean URLs:

  • 010_getting-started/020_shortcuts.md → /docs/getting-started/shortcuts/
  • Numeric prefixes are stripped from URLs
  • Pretty URLs use /page/ format (not /page.html)

Source Documentation

Original documentation files are in /documentation/*.md and were organized into this structure manually. The reference docs should be kept in sync with any updates to those source files.