# euv-docs
A **VuePress-style documentation site generator** built with
[euv](https://github.com/euv-dev/euv) + `euv-ui`, compiled to WebAssembly.
Write markdown in `docs/` — get a full docs site with a home hero, navbar,
multi-level collapsible sidebar, right anchor TOC, prev/next links, footer,
dark mode, and i18n.
## Quick start
```bash
cargo install euv-cli
# dev server with hot reload
euv run --dev --port 8080 --index-html template.html -- --target web --out-dir www/pkg --out-name euv_docs --no-typescript --no-pack
# production build → www/
euv build --release --index-html template.html -- --target web --out-dir www/pkg --out-name euv_docs --no-typescript --no-pack
```
Open <http://localhost:8080> after `euv run`.
## Writing docs
| `docs/README.md` | `/` (home, with frontmatter hero) |
| `docs/guide/README.md` | `/guide/` (sidebar group index) |
| `docs/guide/getting-started.md` | `/guide/getting-started.html` |
| `docs/zh/README.md` | `/zh/` (locale home) |
- **Navbar, locales, footer, UI labels** — `docs/config.toml`
- **Sidebar** — auto-generated from the file tree; order with frontmatter `order: <int>`
- **Home page** — frontmatter `home: true` + `heroText` / `tagline` / `actions` / `features` / `footer`
- **Static assets** — put them in `docs/public/`, reference as `/logo.png`
## Building a site from any markdown directory
The `euv-docs` binary builds any directory containing `config.toml` and
`*.md` files into a static site. Use this to ship documentation for a
project without modifying euv-docs itself.
```bash
cargo install --path . --bin euv-docs --locked
euv-docs <SRC_DIR> [--out <OUT_DIR>] [--name <NAME>] [--index-html <FILE>] [--debug]
```
| `<SRC_DIR>` | (required) | Directory containing `config.toml` and `*.md` files |
| `--out <DIR>` | `./dist` | Output directory; produces `<DIR>/index.html` and `<DIR>/pkg/` |
| `--name <NAME>` | `euv_docs` | Wasm package name (sets the `<pkg>_bg.wasm` filename) |
| `--index-html <FILE>` | CLI-bundled | Path to a custom `index.html` template (forwarded to `euv build --index-html`); replaces the bundled one |
| `--release` | enabled | Release wasm profile (default) |
| `--debug` | | Dev wasm profile (faster build, slower runtime) |
| `-h`, `--help` | | Print help |
| `-v`, `--version` | | Print version |
Example:
```bash
euv-docs ./my-docs --out ./public
```
The CLI sets `EUV_DOCS_SRC_DIR` and `EUV_DOCS_OUT_DIR` for the embedded
build script, then shells out to `euv build` (the `euv-cli` package). See
`src/bin/euv_docs/main.rs` and `src/bin/euv_docs/fn.rs` for the exact
argument wiring.
## Markdown features
- Frontmatter (YAML)
- GFM tables, task lists, strikethrough, footnotes
- Fenced code blocks
- Heading permalinks + right anchor TOC (h2/h3)
- Custom containers: `::: tip` / `::: warning` / `::: danger` / `::: note [title]`
- Internal `.md` links rewritten to routes; external links open in a new tab
- Same-page anchors: `[text](#heading-slug)`
## Internationalization
Add a `[[locales]]` entry in `docs/config.toml` (`prefix = "/zh/"`) and a
matching directory `docs/zh/`. The navbar language dropdown switches locale,
keeping the current page when a translation exists.
## License
MIT