Dory

🐟 A lightweight static site generator for technical documentation.

Dory is a lightweight static site generator built for developers who want fast, clean, and customizable documentation — without the overhead of server-side rendering, complex CI/CD setups, or cloud-specific constraints.

Built with Preact, Vite, Tailwind CSS, Mermaid, and TypeScript.

🚀 Why Dory?

We created Dory while building a documentation platform and getting frustrated by bloated frameworks, slow build times, and cryptic deployment errors.

Dory is:

• 🧠 Simple — Drop in .mdx files and configure one dory.json.
• ⚡ Fast — Instant hot reload in dev, quick static builds for prod.
• 🌐 Portable — No SSR, no lock-in, deploy anywhere.
• 🧩 Flexible — Hackable theme, readable codebase, minimal magic.

🎬 Quick Demo

https://github.com/user-attachments/assets/5a2840ce-a0b9-41fd-8d15-3ee1d2356f07

✨ Features

• 📄 Write docs in .mdx (Markdown + JSX)
• 🧭 Configure site structure with a single dory.json
• 🧪 Built-in components for layout, navigation, and code highlighting
• 🔁 Instant hot-reload during development
• 📊 Mermaid support for diagrams and flows
• 🎨 Customizable via Tailwind and minimal theme overrides
• 🌍 Deploy to Netlify, Vercel, S3, GitHub Pages — your call
• 🌐 HTTP client for testing API endpoints (automatic inference from openapi.json)

📦 CLI Installation

Install Dory globally to use the CLI tool:

npm install -g @clidey/dory

CLI Usage

Once installed, you can use the dory command:

dory build

Builds your documentation site:

• Checks for dory.json in current directory
• Clears and prepares the docs folder
• Copies configuration to docs folder
• Runs the build process
• Creates dist folder with build output

dory build

dory preview

Previews the built documentation site:

• Requires dist folder (run dory build first)
• Starts a local preview server

dory preview

dory verify:content

Verifies that MDX content compiles without errors:

• Silent on success (no output means no errors)
• Shows detailed error messages on failure
• Uses the same preprocessing as the main build
• Perfect for automated testing and debugging

# Verify content directly
dory verify:content --content "# Hello World\n\nThis is a test."

# Verify content from file (recommended for complex content)
dory verify:content --file content.mdx

# Development repository usage:
pnpm exec tsx bin/dory.ts verify:content --file content.mdx

dory help

Shows CLI usage information:

dory help

🧑‍💻 Development Setup

Follow these steps to set up and preview the documentation locally, as well as build a static site for deployment.

1️⃣ Clone the Repository

Clone the repository to your local machine:

git clone https://github.com/clidey/dory.git
cd dory

2️⃣ Install Dependencies

Install all required dependencies using pnpm:

pnpm install

Make sure you have pnpm installed. If not, you can install it via:

npm install -g pnpm

3️⃣ Copy Documentation Content

Copy your existing documentation into the ./docs directory:

rm -rf ./docs
cp ../wherever-the-docs-are/. ./docs

Replace ../wherever-the-docs-are/ with the actual path to your documentation source files.

4️⃣ Start Development Server

Start the development server to preview the documentation locally:

pnpm run dev

This will launch a local server (typically at http://localhost:3000) where you can preview and edit your documentation in real-time.

5️⃣ Build Static Site for Production

To generate a static version of the site for production deployment:

pnpm run build

This will create a dist directory containing the fully built static site, ready to be served.

🐳 Docker Deployment (Optional)

You can use our official Docker image clidey/dory to create a static server. Simply create a Dockerfile inside the project and build the following Dockerfile:

FROM clidey/dory
WORKDIR /app
COPY . .
RUN dory build
CMD ["dory", "preview"]

You can also build and run the static site inside a Docker container using Nginx:

Build Docker Image

docker build -f k8s/Dockerfile --tag docs:1.0.0 .

Run Docker Container

docker run -it -p 8080:80 docs:1.0.0

The site will be available at http://localhost:8080 inside your browser.

📂 Notes

• pnpm run build creates the static site inside the dist folder, which can be served using any static file server.
• The Docker image uses Nginx to serve the contents of the dist folder.

🔮 Roadmap

We’re actively improving Dory. Here’s what’s on deck:

• [ ] 📚 Full Documentation — comprehensive guides, API docs, and examples
• [ ] 🎨 Themes — full theming support with a flexible theme API
• [ ] 🌐 Multi-language Support — internationalization (i18n) & localization (l10n)
• [ ] 🚀 GraphQL Client — integrated GraphQL playground and client support