socktop-webterm/docs/README.md

# socktop Documentation

This directory contains the source for socktop's comprehensive documentation built with [mdBook](https://rust-lang.github.io/mdBook/) and styled with the Catppuccin Frappe theme.

## Quick Start

```bash
# Install and build documentation
./setup-docs.sh

# Or manually:
cargo install mdbook mdbook-catppuccin
cd docs && mdbook-catppuccin install && mdbook build

# Serve with live reload
mdbook serve --open
```

## What's Included

📚 **6,400+ lines** of comprehensive documentation covering:

- **Installation**: Quick start, prerequisites, Cargo, APT, systemd service, upgrading
- **Usage**: General usage, connection profiles, keyboard controls, configuration  
- **Security**: Authentication tokens, TLS/SSL setup
- **Advanced**: tmux/Zellij integration, agent library, connector API

## Building the Documentation

### Automated Setup (Recommended)

```bash
./setup-docs.sh
```

This script will:
- Check for Rust/Cargo installation
- Install mdbook and mdbook-catppuccin
- Install Catppuccin theme assets
- Build the documentation
- Provide next steps

### Manual Setup

1. **Install tools:**
   ```bash
   cargo install mdbook
   cargo install mdbook-catppuccin
   ```

2. **Install theme:**
   ```bash
   cd docs
   mdbook-catppuccin install
   ```

3. **Build:**
   ```bash
   mdbook build
   ```

4. **Serve locally:**
   ```bash
   mdbook serve
   ```
   Open http://localhost:3000

### Automatic Build (During Compilation)

Documentation builds automatically when compiling the project:

```bash
# From project root
cargo build
```

Built docs are copied to `static/docs/` and served at `/assets/docs/`

## Documentation Structure

```
docs/
├── book.toml              # mdBook configuration with Catppuccin
├── README.md              # This file
├── CONTRIBUTING.md        # Contributor guidelines
├── setup-docs.sh          # Automated setup script
├── .gitignore            # Ignore build artifacts
└── src/
    ├── SUMMARY.md         # Table of contents
    ├── introduction.md    # Project overview
    ├── installation/      # Installation guides (6 pages)
    │   ├── quick-start.md
    │   ├── prerequisites.md
    │   ├── cargo.md
    │   ├── apt.md
    │   ├── agent-service.md
    │   └── upgrading.md
    ├── usage/             # Usage guides (4 pages)
    │   ├── general.md
    │   ├── connection-profiles.md
    │   ├── keyboard-mouse.md
    │   └── configuration.md
    ├── security/          # Security documentation (2 pages)
    │   ├── token.md
    │   └── tls.md
    └── advanced/          # Advanced topics (4 pages)
        ├── tmux.md
        ├── zellij.md
        ├── agent-integration.md
        └── connector.md
```

## Adding New Pages

1. **Create the file** in the appropriate directory:
   ```bash
   touch src/installation/new-guide.md
   ```

2. **Add to SUMMARY.md** in the correct section:
   ```markdown
   # Installation
   - [Quick Start](./installation/quick-start.md)
   - [New Guide](./installation/new-guide.md)  # Add here
   ```

3. **Write content** following the [CONTRIBUTING.md](./CONTRIBUTING.md) guidelines

4. **Test:**
   ```bash
   mdbook serve
   ```

5. **Commit:**
   ```bash
   git add src/installation/new-guide.md src/SUMMARY.md
   git commit -m "docs: Add new installation guide"
   ```

## Writing Guidelines

### Style
- ✅ Clear and concise language
- ✅ Active voice ("Run the command" not "The command should be run")
- ✅ Include working code examples
- ✅ Add `<!-- TODO: -->` comments for incomplete sections
- ✅ Link to related pages

### Code Examples
Always specify the language:

````markdown
```bash
cargo install socktop
```

```rust
use socktop_connector::*;
```

```toml
[profiles.server]
url = "ws://localhost:3000"
```
````

### Structure
Each page should have:
- Clear title
- Brief introduction
- Logical sections with headings
- Code examples
- "Next Steps" section with related links
- TODO comments for future improvements

See [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidelines.

## Catppuccin Theme

The documentation uses the [Catppuccin Frappe](https://github.com/catppuccin/catppuccin) theme to match socktop's TUI color scheme.

**Features:**
- Dark theme optimized for readability
- Syntax highlighting for code blocks
- Beautiful, consistent color palette
- Matches socktop terminal UI

**Installation:**
```bash
mdbook-catppuccin install
```

## Accessing the Documentation

### Via Web Interface
1. Start webterm server: `cargo run`
2. Open http://localhost:8082
3. Click "Docs" button
4. Documentation opens in browser

### Direct File Access
Open `docs/book/index.html` in any browser

### Published Online
- Production: https://socktop.io/docs/ (when deployed)
- Local dev: http://localhost:8082/assets/docs/

## Maintenance

### Update Theme
```bash
cd docs
mdbook-catppuccin install
```

### Clean Build
```bash
rm -rf book/
mdbook build
```

### Check for Broken Links
```bash
mdbook build
# Navigate through all pages in browser
# Click all internal links to verify
```

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed contributor guidelines.

**Quick tips:**
- Focus on TODO-marked sections first
- Test all code examples before committing
- Include screenshots when helpful
- Cross-reference related topics
- Keep examples minimal and focused

## Documentation Statistics

- **Total Pages**: 18 (including SUMMARY and introduction)
- **Total Lines**: 6,400+ lines of Markdown
- **Code Examples**: 200+ code blocks
- **Sections**: 4 major sections
- **Topics**: 31+ distinct topics covered

## Support

- **Questions?** Open a GitHub discussion
- **Found errors?** Open an issue with "documentation" label
- **Want to contribute?** See [CONTRIBUTING.md](./CONTRIBUTING.md)

## Recognition

All documentation contributors are acknowledged in:
- Git commit history
- Contributors list
- Release notes (for significant contributions)

Thank you for helping improve socktop documentation! 🚀