https://github.com/skvggor/mugdoc
Generate a documentation site from your project's README using Astro and Starlight.
https://github.com/skvggor/mugdoc
astro-build developer-experience developer-tools docs documentation documentation-generator dx ssr starlight starlight-astro static-site-generator
Last synced: about 14 hours ago
JSON representation
Generate a documentation site from your project's README using Astro and Starlight.
- Host: GitHub
- URL: https://github.com/skvggor/mugdoc
- Owner: skvggor
- License: other
- Created: 2026-03-14T16:05:12.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-03-25T21:11:31.000Z (3 months ago)
- Last Synced: 2026-03-26T20:11:53.118Z (3 months ago)
- Topics: astro-build, developer-experience, developer-tools, docs, documentation, documentation-generator, dx, ssr, starlight, starlight-astro, static-site-generator
- Language: Shell
- Homepage: https://mugdoc.reposito.rio.br
- Size: 142 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# mugdoc
Generate a documentation site from your project's README using Astro and Starlight.
---
---
## How it works
Clone this repo into your project, run `setup.sh`, and get a static documentation site. The setup script detects your project name and description, converts your README into the site content, copies referenced images, installs dependencies, and removes itself.
The generated site is a single page with your README content, no sidebar, and a table of contents on the right. If you provide `--repo`, a floating "Star on GitHub" button will appear in the bottom-right corner.
## Usage
```bash
git clone --depth 1 git@github.com:skvggor/mugdoc.git docs && rm -rf docs/.git && ./docs/setup.sh
```
### Options
| Flag | Description | Required |
|---|---|---|
| `--domain` | Base domain for the site URL | Yes |
| `--deploy` | Absolute path on the server to deploy via SSH | No |
| `--port` | Container port for the docs site (requires --deploy) | No |
| `--repo` | URL to your GitHub repository (shows floating star button) | No |
### Examples
With a custom domain:
```bash
./docs/setup.sh --domain example.com
```
With original repository link:
```bash
./docs/setup.sh --domain example.com --repo https://github.com/user/my-project
```
Deploy to a VPS:
```bash
./docs/setup.sh --domain example.com --deploy /root/projects/my-project
```
Deploy with custom port:
```bash
./docs/setup.sh --domain example.com --deploy /root/projects/my-project --port 3001
```
After setup:
```bash
cd docs && npm run dev # development server
cd docs && npm run build # build static site
cd docs && npm run preview # preview build
```
## Project detection
The setup script detects your project name from (in order):
| File | Field |
|---|---|
| `package.json` | `name` |
| `Cargo.toml` | `[package] name` |
| `go.mod` | `module` |
| `pyproject.toml` | `[project] name` |
Falls back to the parent directory name.
Description is extracted from the first text line in the README (skipping headings, HTML tags, links, and code blocks), then from `package.json` description, then a generic fallback.
## Images
Local images referenced in the README (both markdown and HTML `![]()
` syntax) are automatically copied to the site's public directory and their paths are rewritten. External URLs are left unchanged.
If the project has an `assets/` directory at the root, its contents are also copied.
## Videos
Bare video URLs in the README are automatically converted to `` tags in the generated site. This covers:
- GitHub user-attachment URLs (e.g. `https://github.com/user-attachments/assets/...`)
- Direct links to `.mp4`, `.webm`, and `.mov` files
On GitHub, pasting a video URL on its own line auto-embeds a player. Since Astro/Starlight doesn't do this, mugdoc handles the conversion during setup.
## Deploy
The `--deploy` flag generates everything needed to deploy the docs site to a VPS using Docker, Caddy, and GitHub Actions.
This creates:
- `docs/Dockerfile` -- multi-stage build: Node builds the Astro site, Caddy serves the static files
- `docs/compose.yml` -- Docker Compose service with [caddy-docker-proxy](https://github.com/lucaslorentz/caddy-docker-proxy) labels for automatic HTTPS
- `.github/workflows/deploy-docs.yml` -- GitHub Actions workflow that deploys via SSH on push to `main`
The site URL is `https://{project-name}.{domain}`.
The workflow uses [appleboy/ssh-action](https://github.com/appleboy/ssh-action) and requires these repository secrets:
| Secret | Description |
|---|---|
| `HOST` | Server IP or hostname |
| `USERNAME` | SSH user |
| `SSH_PRIVATE_KEY` | Private key for authentication |
| `PORT` | SSH port (optional, defaults to 22) |
Without `--deploy`, the deploy files are removed and only the local development setup is kept.
## Requirements
- Node.js
- npm, pnpm, or yarn
## Stack
- [Astro](https://astro.build) + [Starlight](https://starlight.astro.build)
- [Tailwind CSS](https://tailwindcss.com) via `@astrojs/starlight-tailwind`
## License
[GNU General Public License v3.0](LICENSE)