socktop-webterm/docs

socktop Documentation

This directory contains the source for socktop's comprehensive documentation built with mdBook and styled with the Catppuccin Frappe theme.

Quick Start

# 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)

./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:

   cargo install mdbook
   cargo install mdbook-catppuccin
   

2. Install theme:

   cd docs
   mdbook-catppuccin install
   

3. Build:

   mdbook build
   

4. Serve locally:

   mdbook serve
   

   Open http://localhost:3000

Automatic Build (During Compilation)

Documentation builds automatically when compiling the project:

# 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:

   touch src/installation/new-guide.md
   

2. Add to SUMMARY.md in the correct section:

   # Installation
   - [Quick Start](./installation/quick-start.md)
   - [New Guide](./installation/new-guide.md)  # Add here
   

3. Write content following the CONTRIBUTING.md guidelines

4. Test:

   mdbook serve
   

5. Commit:

   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:

```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 for detailed guidelines.

Catppuccin Theme

The documentation uses the Catppuccin Frappe 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:

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

cd docs
mdbook-catppuccin install

Clean Build

rm -rf book/
mdbook build

Check for Broken Links

mdbook build
# Navigate through all pages in browser
# Click all internal links to verify

Contributing

See 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

Recognition

All documentation contributors are acknowledged in:

• Git commit history
• Contributors list
• Release notes (for significant contributions)

Thank you for helping improve socktop documentation! 🚀