📝 Interactive Documentation System & Enhanced Copy-in CLI Solution

🔄 Project Evolution

The project began with a clear vision for interactive documentation that would serve software projects and educational purposes. The initial inquiry focused on finding solutions that could balance text-based version control with enhanced interactive features. Early discussions considered several static site generators and documentation frameworks (Docusaurus, VitePress, Astro, custom Vite+MDX+React). The focus quickly shifted to maximizing reusability, plug-and-play simplicity, and developer independence. The final solution emerged as a copy-in CLI tool that scaffolds a customizable Vite+MDX+React docs app into any project, allowing users to specify their docs directory and own the codebase.

🌱 Project Genesis & Motivation

The motivation was to empower developers to easily enhance their documentation with custom styling and interactive code snippets, without being locked into a specific tool or package. The inspiration came from the desire for a solution that is as easy to adopt as running a single command, but leaves users in full control—similar to the approach used by shadcn/ui for React components. The core challenge was finding a solution that maintains the benefits of git-based version control while providing rich interactive features like live code execution, syntax highlighting, and media embedding. The goal was to create a system particularly suited for software development education where learners could both read about concepts and experiment with live code examples.

🗂️ Project Overview

Goal: Provide a CLI tool that copies a ready-to-use Vite+MDX+React documentation app into any user’s project.
Audience: Developers who want interactive, styled docs with minimal setup and maximum flexibility.
Key Features:
- Plug-and-play CLI via Shell Script
- User-defined docs directory
- Full code ownership and customizability
- Interactive MDX/React snippets
- Minimal dependencies and clear structure
- Text-based foundation for git compatibility
- Human-readable source in any editor
- Enhanced rendering with rich styling and media embedding
- Live code execution (TypeScript/JavaScript)
- Cross-platform compatibility (browsers, IDEs, SSGs)
- Educational focus
- Framework flexibility (Vite, Astro, Docusaurus, Starlight)

💡 Core Ideas & Features

Copy-in CLI: Scaffolds the docs app into any target directory, with prompts for docs location. This is not a global npm package, but a local tool or script that copies the app-template into the user’s project, inspired by the shadcn/ui approach.
Custom Vite+MDX+React Template: Lightweight, flexible, and easy to maintain.
Configurable Docs Directory: User can specify any folder for their markdown/MDX files.
No Lock-in: Users can fully customize or extend the copied codebase.
Clear Next Steps: CLI prints instructions for install, dev, and build.
Shell/Batch Script: A bash or batch script will be provided to download and configure the app-template interactively.
Text-Based Foundation: Documents authored in Markdown/MDX format for git compatibility
Human-Readable Source: Plain text documents readable in any editor
Enhanced Rendering: Rich styling, syntax highlighting, and media embedding in specialized environments
Live Code Execution: TypeScript/JavaScript code snippets executable within documents
Cross-Platform Compatibility: Works in browsers, IDEs, and static site generators
Educational Focus: Designed specifically for software development learning
Framework Flexibility: Multiple implementation approaches (Vite, Astro, Docusaurus, Starlight)

🏗️ Architecture & Structure

The system architecture consists of several layers:

Content Layer:

Source documents in Markdown/MDX format
Code snippets embedded as executable blocks
Media references and metadata

Processing Layer:

MDX parsing and compilation
Sandpack integration for code execution
Static site generation or runtime rendering

Presentation Layer:

Responsive web interfaces
Interactive code editors
Syntax highlighting and theming

Framework Options:

Vite: Lightweight development server with React and MDX support
Astro: Static site generation with component islands
Docusaurus: Documentation-focused framework with built-in features
Starlight: Astro-based documentation theme with enhanced features

Template App:

package.json, vite.config.ts, src/, public/, README.md, example docs
Configurable docs directory (via config file or CLI prompt) CLI Tool:
Shell Script
Prompts for target and docs directory
Copies app-template, injects config, handles conflicts
Prints next steps

Example File Structure:

app-template/
  package.json
  vite.config.ts
  src/
  public/
  README.md
  docs/
cli/
  setup.sh
  setup.bat
README.md

🧩 Code Snippets & Examples

MDX Document Structure:

import { Sandpack } from "@codesandbox/sandpack-react";

# My Interactive Document

Here's some content with executable code:

<Sandpack template="react-ts" files={{
  "/App.tsx": `export default function App() { 
    return <h1>Hello Interactive Docs!</h1>; 
  }`
}} />

Vite Configuration Example:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import mdx from '@mdx-js/rollup'

export default defineConfig({
  plugins: [react(), mdx()]
})

Sandpack Integration Pattern:

import { Sandpack } from "@codesandbox/sandpack-react";

const InteractiveExample = () => (
  <Sandpack 
    template="vanilla-ts"
    files={{
      "/index.ts": codeString,
      "/index.html": htmlString
    }}
    options={{
      showNavigator: true,
      showTabs: true
    }}
  />
);

Shell Script Example (Bash):

#!/bin/bash
echo "Welcome to the Docs Setup!"
read -p "Enter the target directory [docs-app]: " TARGET_DIR
TARGET_DIR=${TARGET_DIR:-docs-app}
read -p "Enter the docs source directory [docs]: " DOCS_DIR
DOCS_DIR=${DOCS_DIR:-docs}
# Download and extract app-template, update config, etc.
curl -L https://github.com/your-org/your-repo/archive/refs/heads/main.tar.gz | tar xz
mv your-repo-main/app-template "$TARGET_DIR"
# Here you would update the config file to set docsDir to $DOCS_DIR
echo "Setup complete! See $TARGET_DIR for your new docs app."

Batch Script Example (Windows):

@echo off
set /p TARGET_DIR=Enter the target directory [docs-app]:
if "%TARGET_DIR%"=="" set TARGET_DIR=docs-app
set /p DOCS_DIR=Enter the docs source directory [docs]:
if "%DOCS_DIR%"=="" set DOCS_DIR=docs
REM Download and extract app-template (requires curl and tar or use PowerShell Expand-Archive)
curl -L https://github.com/your-org/your-repo/archive/refs/heads/main.zip -o app-template.zip
tar -xf app-template.zip
move your-repo-main\app-template %TARGET_DIR%
REM Here you would update the config file to set docsDir to %DOCS_DIR%
echo Setup complete! See %TARGET_DIR% for your new docs app.

❌ Rejected Ideas & Alternatives

Jupyter Notebooks: Rejected for requiring a python environment
Pure Markdown Extensions: Insufficient for the level of interactivity required
Custom IDE Extensions Only: Too limited in scope and accessibility
Gatsby: Dismissed as “not so relevant anymore” and potentially outdated
Next.js: Considered overkill for the specific use case of documentation
Docusaurus: Too opinionated, inflexible directory structure.
VitePress: Vue-based, less flexible for React/MDX, directory config not first-class.
Astro: Flexible but overkill for this use case.
Pure npm package: Would require users to fork or rely on package updates, increasing maintenance burden.

💬 Key Conversation Excerpts

“I want to create interactive documents for software projects and software development education purposes.”

“The documents should be text-based, so they can be versioned by git. The documents should be human-readable in simple text editors.”

“TypeScript based code snippets should not only be visible as code, but also executed within the document itself.”

“I don’t want to use Gatsby or Next.js. Gatsby is not so relevant anymore and Next.js seems overkill for this.”

“What about utilising a light Vite setup? Would that be possible? Besides that I have used Docusaurus in the past, but also Starlight (based on Astro.js) and Astro.js itself could be options, no?”

“I don’t want to be reliable for updating and improving the package beyond my own needs. So maybe a similar distribution strategy as is used for shadcn components could be an option.”

“A custom Vite + MDX + React setup is the best fit for your copy-in CLI, especially with the requirement for arbitrary docs directory support.”

“The solution is plug-and-play, requires minimal setup, and gives users full ownership of the code.”

🏛️ Architecture & Structure (Summary)

Template App:
- package.json, vite.config.ts, src/, public/, README.md, example docs
- Configurable docs directory (via config file or CLI prompt)
CLI Tool:
- Shell Script
- Prompts for target and docs directory
- Copies app-template, injects config, handles conflicts
- Prints next steps

📚 References & Inspirations

MDX Documentation: https://mdxjs.com/
Sandpack by CodeSandbox: https://sandpack.codesandbox.io/
Vite: https://vitejs.dev/
Astro: https://astro.build/
Docusaurus: https://docusaurus.io/
Starlight: https://starlight.astro.build/
Phaser.js: https://phaser.io/ (used as example domain)
shadcn/ui: https://ui.shadcn.com/

❓ Open Questions & Next Steps

Performance Comparison: Which framework provides the best performance for large documents with multiple interactive code blocks?
Maintenance Overhead: How do the different solutions compare in terms of long-term maintenance and updates?
Deployment Flexibility: Which solution offers the most deployment options (static hosting, CDN, etc.)?
Extension Ecosystem: How extensible is each solution for adding custom interactive components?
Learning Curve: What is the developer experience for content creators using each solution?
Should the CLI or script support updating an existing docs app?
What optional features (search, theming) should be offered?
How to best document advanced customization for users?
Should the shell and batch script approaches be officially supported alongside the Node.js CLI?
How to best support Windows users (batch, PowerShell, or WSL)?
What is the best way to communicate security and trust for remote shell scripts?

Immediate Next Steps:

Implement POCs for all four solutions (Vite, Astro, Docusaurus, Starlight)
Use the Amelcraft game document as a common test case
Evaluate each solution against the defined criteria
Create a comparative analysis document
Select the optimal solution based on performance, usability, and maintainability

POC Implementation Directory: ./pocs/ contains detailed instructions for implementing each proof-of-concept with the same source material to enable direct comparison.