Echox turns a folder of Markdown files into a polished documentation site. Add a config.json, run echox dev, and you get tabs, sidebar navigation, search, optional OpenAPI docs, and file-based task boards—without touching the framework source. Perfect for product docs, API references, and internal wikis.

Features

| | | |---|---| | Folder-based routing | Your tab/group/page.md structure becomes the site. No routing config. | | Static by default | HTML + CSS. No runtime JS unless you add it. | | OpenAPI | Drop .json specs into apis/; each file becomes a tab with generated endpoint docs. | | Tasks | Add tasks.yml per tab for Todo / In progress / Done views. | | Search | Pagefind index built at build time. Cmd+K / Ctrl+K in the UI. | | Theming | One color in config; 22 Tailwind palettes. Dark mode with system detection. | | Callouts, cards, accordions | GitHub-style alerts and custom directives in Markdown. | | Syntax highlighting | Shiki, copy button, line highlight, diff view, Mermaid diagrams. |

Quick start

1. Scaffold a new project

npx echox init
# or: echox init --name "My Docs"

This creates guides/, assets/, config.json, a sample OpenAPI spec in apis/, and a tasks.yml example.

2. Run the dev server

echox dev

3. Build for production

echox build

Output goes to dist/. Use echox preview to serve it locally.

Install

From npm (npmjs.com)

npm install -g @sonmezerekrem/echox

After install, run echox from any directory that has a docs project (see Project structure).

From GitHub (clone and link)

git clone https://github.com/sonmezerekrem/echox.git
cd echox
npm install
npm link

From GitHub Packages (scoped): set @sonmezerekrem:registry=https://npm.pkg.github.com in ~/.npmrc and npm login --registry=https://npm.pkg.github.com with a token that has read:packages. Then npm install -g @sonmezerekrem/echox.

Project structure

Your docs repo stays minimal:

my-docs/
├── guides/               # Tab folder (Markdown)
│   └── getting_started/
│       └── introduction.md
├── apis/                 # Optional OpenAPI 3.x JSON (one file = one tab)
│   └── sample_api.json
├── assets/               # Images, favicon, logo (served at /)
└── config.json          # Site name, theme color, logo, links, footer

• Tabs = top-level folders (e.g. guides, features).
• Groups = subfolders (e.g. getting_started).
• Pages = .md files. Use frontmatter for title, order, icon, status badge.

Add _meta.json in any tab or group folder to set display name and sort order. Add tasks.yml in a tab folder to get Todo / In progress / Done pages for that tab.

Configuration

Minimal config.json:

{
  "name": "My Docs",
  "color": "blue"
}

Optional: description, logo, favicon, github, links, footer. Valid color values: any Tailwind-style name (e.g. slate, emerald, violet, rose). Use echox logo <color> to generate a logo and favicon from your project name.

CLI commands

| Command | Description | |--------|--------------| | echox init | Scaffold guides/, config.json, apis/, assets/, and sample tasks | | echox dev | Start dev server with hot reload | | echox build | Build static site to dist/ (runs link check + Pagefind) | | echox build --no-link-check | Build without broken-link check | | echox preview | Serve the built dist/ locally | | echox logo <color> | Generate logo.svg and favicon.svg in assets/ and set paths in config |

Documentation

• Full docs — The docs/ folder in this repo is a complete Echox site; use it as reference.
• npm package — Install from npm.

Contributing

Contributions are welcome. Open an issue or a pull request. If you change behavior or add options, consider updating the docs/ content so it stays in sync.

License

GNU GPL v3. You may use, modify, and distribute this software under the terms of the GNU General Public License version 3. If you distribute it, you must provide the source and preserve the same license. See LICENSE for the full text.