https://github.com/aredoff/veldoc
Veldoc is a lightweight self-hosted web viewer for browsing and rendering Markdown documentation from a local directory, with optional auth and Docker support.
https://github.com/aredoff/veldoc
developer-tools docker docs documentation file-browser golang knowledge-base markdown markdown-viewer self-hosted
Last synced: about 15 hours ago
JSON representation
Veldoc is a lightweight self-hosted web viewer for browsing and rendering Markdown documentation from a local directory, with optional auth and Docker support.
- Host: GitHub
- URL: https://github.com/aredoff/veldoc
- Owner: aredoff
- License: mit
- Created: 2026-06-15T09:13:29.000Z (22 days ago)
- Default Branch: main
- Last Pushed: 2026-06-22T12:42:14.000Z (14 days ago)
- Last Synced: 2026-06-22T14:23:18.212Z (14 days ago)
- Topics: developer-tools, docker, docs, documentation, file-browser, golang, knowledge-base, markdown, markdown-viewer, self-hosted
- Language: Go
- Homepage:
- Size: 10.1 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Veldoc
[](https://hub.docker.com/r/aredoff/veldoc/)
[](https://goreportcard.com/report/github.com/aredoff/veldoc)
[](./LICENSE)
Minimal file browser for viewing a mounted directory in the browser. Designed for Docker: mount a folder, open the UI, read files and rendered Markdown.
## Quick start
```bash
docker run -p 8080:8080 -v ./your-folder:/data ghcr.io/aredoff/veldoc
```
Open http://localhost:8080
## Docker Compose
```bash
mkdir -p data
echo "# Hello" > data/readme.md
docker compose up --build
```
## Configuration
| Flag / Env | Default | Description |
|---|---|---|
| `--root` / `VELDOC_ROOT` | `/data` | Directory to serve |
| `--addr` / `VELDOC_ADDR` | `:8080` | Listen address |
| `--auth` / `VELDOC_AUTH` | `none` | `none`, `basic`, `form`, `token` |
| `VELDOC_BASIC_USER` | | Basic auth username |
| `VELDOC_BASIC_PASSWORD` | | Basic auth password |
| `VELDOC_FORM_USER` | | Form auth username |
| `VELDOC_FORM_PASSWORD` | | Form auth password |
| `VELDOC_SESSION_SECRET` | | Form auth session secret |
| `VELDOC_TOKEN` | | Bearer token |
| `--poll-interval` / `VELDOC_POLL_INTERVAL` | `3s` | UI poll interval |
| `--max-preview-size` / `VELDOC_MAX_PREVIEW_SIZE` | `52428800` | Max file size for preview in bytes (download is unlimited) |
## Excluding files (`.docignore`)
Place a `.docignore` file in the served root or any subdirectory. Syntax matches `.gitignore`: wildcards (`*`, `?`, `**`), negation (`!`), directory patterns (trailing `/`), and comments (`#`).
Ignored paths are hidden from the file tree and cannot be read via the API. `.docignore` files themselves are always hidden.
**Root example** (`data/.docignore`):
```gitignore
# secrets
.env
private/
# build artifacts
*.log
dist/
# except this one
!important.log
```
**Nested example** (`data/docs/.docignore`):
```gitignore
drafts/
*.tmp
```
Patterns in a nested `.docignore` apply only to files under that directory, like Git.
## Auth examples
**Basic auth:**
```bash
docker run -p 8080:8080 -v ./data:/data \
-e VELDOC_AUTH=basic \
-e VELDOC_BASIC_USER=admin \
-e VELDOC_BASIC_PASSWORD=secret \
veldoc
```
**Form auth:**
```bash
docker run -p 8080:8080 -v ./data:/data \
-e VELDOC_AUTH=form \
-e VELDOC_FORM_USER=admin \
-e VELDOC_FORM_PASSWORD=secret \
-e VELDOC_SESSION_SECRET=change-me \
veldoc
```
**Token auth:**
```bash
curl -H "Authorization: Bearer my-token" http://localhost:8080/api/tree
```
## Development
```bash
go run ./cmd/veldoc --root ./data
go test ./...
```
## License
MIT