{"id":45374668,"url":"https://github.com/p-arndt/dorcs","last_synced_at":"2026-04-28T08:02:42.660Z","repository":{"id":228237508,"uuid":"773465518","full_name":"p-arndt/dorcs","owner":"p-arndt","description":"Serves your documentation easily with a single binary","archived":false,"fork":false,"pushed_at":"2025-12-15T02:23:00.000Z","size":715,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-16T22:17:20.644Z","etag":null,"topics":["docs","docs-generator","documentation","documentation-generator","documentation-tool","golang"],"latest_commit_sha":null,"homepage":"https://dorcs.allthing.eu","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/p-arndt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-03-17T18:26:59.000Z","updated_at":"2025-12-15T02:22:47.000Z","dependencies_parsed_at":"2024-06-19T09:24:01.296Z","dependency_job_id":null,"html_url":"https://github.com/p-arndt/dorcs","commit_stats":null,"previous_names":["padi2312/dorcs","p-arndt/dorcs"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/p-arndt/dorcs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/p-arndt%2Fdorcs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/p-arndt%2Fdorcs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/p-arndt%2Fdorcs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/p-arndt%2Fdorcs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/p-arndt","download_url":"https://codeload.github.com/p-arndt/dorcs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/p-arndt%2Fdorcs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29685018,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-21T15:51:39.154Z","status":"ssl_error","status_checked_at":"2026-02-21T15:49:03.425Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docs","docs-generator","documentation","documentation-generator","documentation-tool","golang"],"created_at":"2026-02-21T16:00:56.641Z","updated_at":"2026-04-28T08:02:42.645Z","avatar_url":"https://github.com/p-arndt.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./docs/logo.png\" alt=\"Dorcs Logo\" width=\"200\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eDorcs\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eStatic site generator in a single file 📄\u003c/strong\u003e\n\u003c/p\n\nDorcs is a single-binary static documentation server for Markdown files. It is a simple and easy to use documentation server that allows you to create and host your documentation site in minutes.\n\n## Documentation \n\nCheck out the [documentation](https://dorcs.allthing.eu) for more information and seeing it in action.\n\n## Features\n\n- **Single binary** – no runtime dependencies, statically linkable\n- **Extensionless URLs** – `/guide/getting-started` serves `docs/guide/getting-started.md`\n- **YAML front matter** – metadata support (title, description, date, tags, draft)\n- **Table of Contents** – auto-generated from headings with scrollspy\n- **Navigation sidebar** – built automatically from your folder structure\n- **Responsive design** – mobile-friendly with collapsible sidebar\n- **Dark mode** – automatic based on system preference\n- **Live reload** – watch mode for development with smart content updates\n- **Multiple themes** – choose from 20+ built-in themes\n- **Search** – built-in search functionality\n\n## Quick Start\n\n### Option 1: Use pre-built binary\n\n1. Download the latest release from the [releases page](https://github.com/p-arndt/dorcs/releases)\n2. Make it executable (Linux/macOS): `chmod +x dorcs`\n3. Run: `./dorcs --dir ./docs`\n\n### Option 2: Build from source\n\n```sh\n# Run from source\ngo run ./cmd/dorcs\n\n# Build and run\ngo build -o dorcs ./cmd/dorcs\n./dorcs\n\n# Run with auto-reload and live browser refresh (for development)\n./dorcs --watch\n```\n\nOpen http://localhost:8080 in your browser.\n\n## Building\n\n### Standard Build\n\n```sh\ngo build -o dorcs ./cmd/dorcs\n```\n\n### Static Linux Binary (for containers/deployment)\n\n```sh\nCGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build \\\n  -trimpath \\\n  -ldflags=\"-s -w\" \\\n  -o dorcs \\\n  ./cmd/dorcs\n```\n\n### Windows\n\n```sh\nGOOS=windows GOARCH=amd64 go build -o dorcs.exe ./cmd/dorcs\n```\n\n## Command Line Options\n\n| Flag          | Default  | Description                                                                          |\n| ------------- | -------- | ------------------------------------------------------------------------------------ |\n| `-dir`        | `./docs` | Directory containing markdown documents                                              |\n| `-addr`       | `:8080`  | Listen address (e.g., `:8080`, `127.0.0.1:8080`)                                     |\n| `-base-url`   | `\"\"`     | URL path prefix (e.g., `/docs`)                                                      |\n| `-title`      | `\"\"`     | Site title shown in header (overrides config file)                                   |\n| `-cache`      | `true`   | Cache rendered documents in memory                                                   |\n| `-no-drafts`  | `true`   | Hide documents with `draft: true` front matter                                       |\n| `-config`     | `\"\"`     | Path to config file (default: current directory first, then docs directory)          |\n| `-repo`       | `\"\"`     | GitHub repository to bootstrap docs and config from                                  |\n| `-theme`      | `\"\"`     | Theme preset: `default`, `ocean`, `forest`, `sunset`, `midnight`, `lavender`, `rose` |\n| `-theme-mode` | `\"\"`     | Theme mode: `light`, `dark`, `auto`                                                  |\n| `-watch`      | `false`  | Watch for file changes and automatically reload                                      |\n\n## Folder Structure\n\n```\ndocs/\n├── index.md              # Home page (served at /)\n├── getting-started.md    # Served at /getting-started\n├── guide/\n│   ├── index.md          # Served at /guide\n│   ├── installation.md   # Served at /guide/installation\n│   └── configuration.md  # Served at /guide/configuration\n└── api/\n    ├── index.md          # Served at /api\n    └── endpoints.md      # Served at /api/endpoints\n```\n\n### URL Routing Rules\n\n- `docs/index.md` → `/`\n- `docs/foo.md` → `/foo`\n- `docs/guide/index.md` → `/guide`\n- `docs/guide/intro.md` → `/guide/intro`\n\n## Front Matter\n\nEach markdown file can include YAML front matter:\n\n```yaml\n---\ntitle: Getting Started\ndescription: Learn how to set up and configure dorcs\ndate: 2024-01-15\ntags:\n  - tutorial\n  - beginner\ndraft: false\n---\n# Your content starts here...\n```\n\n| Field         | Type   | Description                              |\n| ------------- | ------ | ---------------------------------------- |\n| `title`       | string | Page title (used in nav, browser tab)    |\n| `description` | string | Meta description                         |\n| `date`        | string | Publication date (YYYY-MM-DD)            |\n| `tags`        | list   | Tags for categorization                  |\n| `draft`       | bool   | If true, hidden when `-no-drafts` is set |\n\n## Configuration File\n\ndorcs supports a configuration file for advanced customization. By default it looks for `dorcs.yaml`, `dorcs.yml`, or `dorcs.json` in the current directory first, then in the docs directory.\n\nYou can also bootstrap both docs and config directly from GitHub:\n\n```sh\ndorcs --repo https://github.com/owner/repo/tree/main/docs\n```\n\nWhen `-repo` is used, dorcs looks for config files at the repo root first and then at the repo path. `-config` still takes precedence over `-repo`.\n\n\n### Theme Presets\n\n| Preset     | Description                            |\n| ---------- | -------------------------------------- |\n| `default`  | GitHub-inspired light/dark theme       |\n| `ocean`    | Cool blue tones                        |\n| `forest`   | Natural green palette                  |\n| `sunset`   | Warm orange/brown tones                |\n| `midnight` | Deep purple/blue (Catppuccin-inspired) |\n| `lavender` | Soft purple aesthetic                  |\n| `rose`     | Pink/rose accent colors                |\n\n### Custom Colors\n\nOverride any preset color by specifying custom values:\n\n```yaml\ntheme:\n  preset: default\n  colors:\n    light:\n      background: \"#ffffff\"\n      foreground: \"#1f2328\"\n      muted: \"#57606a\"\n      border: \"#d0d7de\"\n      accent: \"#0969da\"\n      code_background: \"#f6f8fa\"\n    dark:\n      background: \"#0d1117\"\n      foreground: \"#e6edf3\"\n      accent: \"#2f81f7\"\n```\n\n## Development\n\n```sh\n# Run with auto-reload for markdown changes\ngo run ./cmd/dorcs --dir ./docs --watch\n```\n\nThe server will automatically detect changes to:\n- .md and .markdown files\n- New files and directories\n- File deletions and renames\n\n# Run tests\n```sh\ngo test ./...\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fp-arndt%2Fdorcs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fp-arndt%2Fdorcs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fp-arndt%2Fdorcs/lists"}