Skip to content

docs: Comprehensive documentation restructure and README improvements#300

Merged
ck3mp3r merged 10 commits intomainfrom
docs/update-readme-and-docs
Nov 27, 2025
Merged

docs: Comprehensive documentation restructure and README improvements#300
ck3mp3r merged 10 commits intomainfrom
docs/update-readme-and-docs

Conversation

@ck3mp3r
Copy link
Owner

@ck3mp3r ck3mp3r commented Nov 27, 2025

Overview

This PR comprehensively restructures the documentation and updates the README to improve discoverability, clarity, and user onboarding.

Documentation Changes

Restructured Documentation Organization

The documentation has been reorganized into four focused sections:

  1. Getting Started - Streamlined onboarding experience

    • Quick Start guide for immediate hands-on experience
    • Your First Session tutorial for understanding core concepts
    • Installation instructions
  2. Configuration - Deep dive into configuration options

    • Layouts: Flexbox-inspired layout system with examples
    • Lifecycle: Startup/shutdown hooks and script management
    • YAML Reference: Complete configuration schema
  3. Workflow - Day-to-day usage patterns

    • Managing Configs: Global vs local configuration strategies
    • Local Configs: Project-specific setup
    • Session Export: Converting existing tmux sessions
  4. Reference - Command-line interface documentation

    • CLI Commands: Complete command reference with examples

Removed Content

  • Deleted redundant "Basics" and "Advanced" pages that overlapped with new structure
  • Consolidated information into focused, task-oriented guides

Content Improvements

  • Added Nushell completion examples alongside bash/zsh/fish
  • Fixed split terminology to accurately describe horizontal vs vertical splits
  • Removed trailing whitespace from all markdown files
  • Used proper Nushell syntax in code examples
  • Consolidated shell completion examples into single, clearer code blocks

README Updates

Enhanced Feature List

Expanded from bullet points to descriptive features:

  • Flexbox-inspired layouts
  • Session lifecycle management
  • Dual configuration modes
  • Session serialization
  • Focus & zoom control
  • Environment & shell customization
  • Tmux native with experimental Zellij support

Improved Structure

  • Clearer Quick Start section
  • Better organized Installation instructions
  • Added link to full documentation site
  • More descriptive feature descriptions

Development Infrastructure

Pre-commit Hook

Added automated whitespace management to the development environment:

File: nix/devenv/developer.nix

Added a pre-commit git hook that automatically:

  • Detects trailing whitespace in staged files
  • Fixes whitespace issues using sed
  • Re-stages cleaned files
  • Runs on every commit

This ensures consistent formatting across all files going forward.

Impact

These changes significantly improve:

  • Discoverability - Better organization helps users find what they need
  • Onboarding - Quick Start and tutorial provide clear entry points
  • Clarity - Focused sections reduce cognitive load
  • Maintainability - Automated whitespace fixes prevent formatting drift
  • Completeness - Reference section provides comprehensive command documentation

Testing

  • All documentation builds successfully
  • Links between pages work correctly
  • Code examples use correct syntax
  • Pre-commit hook tested and working
  • No trailing whitespace remains

… usage

- README: Add developer-focused content with build/test/dev setup
- README: Add feature highlights and enhanced YAML examples
- README: Document all CLI flags and session lifecycle features
- docs: Update homepage with feature highlights (v0.15.0)
- docs/basics: Add session export, stop flags, shell completions
- docs/basics: Add comprehensive YAML field reference
- docs/advanced: Add focus/zoom features, config management
- docs/advanced: Add session export caveats about wrapper commands
- docs/advanced: Add minimal Zellij experimental support mention
**New Structure:**
- getting-started/ - Quick start and first session guides
- configuration/ - YAML reference, layouts, lifecycle hooks
- workflow/ - Managing configs, local configs, session export
- reference/ - Complete CLI command reference

**New Pages:**
- getting-started/quick-start.md - Minimal getting started guide
- getting-started/your-first-session.md - Create first config walkthrough
- configuration/yaml-reference.md - Complete field documentation
- configuration/layouts.md - Flexbox layouts, focus, zoom
- configuration/lifecycle.md - Startup/shutdown hooks and scripts
- workflow/managing-configs.md - Create, edit, validate, delete
- workflow/local-configs.md - Project .laio.yaml workflow
- workflow/session-export.md - Export sessions with caveats
- reference/cli-commands.md - All commands with examples

**Updated Pages:**
- basics.md - Streamlined with links to detailed sections
- advanced.md - Condensed with references to new pages

Improves navigation, reduces page length, better content organization.
The content from basics.md and advanced.md is now properly
distributed across focused pages:

- Command reference -> reference/cli-commands.md
- Config management -> workflow/managing-configs.md
- Local configs -> workflow/local-configs.md
- Session export -> workflow/session-export.md
- YAML examples -> configuration/yaml-reference.md
- Layouts -> configuration/layouts.md
- Known limitations -> reference/cli-commands.md
- Session switching -> reference/cli-commands.md

getting-started/ now contains only:
- installing.md - Installation instructions
- quick-start.md - Minimal getting started
- your-first-session.md - First config walkthrough

This eliminates redundancy and creates a cleaner navigation structure.
Corrected the split terminology throughout documentation:

- Vertical split = split line runs vertically = panes side-by-side (left/right)
- Horizontal split = split line runs horizontally = panes stacked (top/bottom)

In laio (following CSS Flexbox convention):
- flex_direction: row → vertical split (side-by-side)
- flex_direction: column → horizontal split (stacked)

Previous docs incorrectly said "horizontal splits (panes side-by-side)"
which was contradictory. Now consistently describes splits by the
orientation of the split line itself.

Also corrected default from 'column' to 'row' based on code.
Added nushell shell completion support with installation example.
Nushell is supported via clap_complete_nushell dependency.
Changed nushell completion example to use proper nushell syntax
with pipe and 'save' command instead of bash redirect.
Moved nushell completion back into the main bash code block
with a comment noting it uses nushell syntax. Keeps examples
together and easier to read.
Use $env.HOME and path join instead of tilde expansion for
nushell completion example to follow nushell best practices.
Used sed to remove trailing whitespace from 5 documentation files
without altering content.
- Implement fix-whitespace git hook for staged files
- Integrate hook using gnused and shell script in pre-commit stage
@ck3mp3r ck3mp3r merged commit b16c926 into main Nov 27, 2025
2 checks passed
@ck3mp3r ck3mp3r deleted the docs/update-readme-and-docs branch November 27, 2025 13:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant