{"id":31578338,"url":"https://github.com/tkowalski29/doc-builder","last_synced_at":"2025-10-05T19:56:56.518Z","repository":{"id":318112674,"uuid":"1070031449","full_name":"tkowalski29/doc-builder","owner":"tkowalski29","description":"CLI tool for automated documentation building with VitePress integration A self-contained Go CLI that replaces bash scripts for building documentation. Automatically discovers prefixed markdown files, assembles VitePress workspaces, and generates ready-to-deploy documentation sites with structured error handling and extensible engine support.","archived":false,"fork":false,"pushed_at":"2025-10-05T07:24:05.000Z","size":43,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-05T07:41:29.972Z","etag":null,"topics":["build-automation","cli","documentation","documentation-builder","go-tools","markdown","static-site-generator","vitepress"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tkowalski29.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2025-10-05T05:48:01.000Z","updated_at":"2025-10-05T07:29:41.000Z","dependencies_parsed_at":"2025-10-05T07:41:32.876Z","dependency_job_id":"f63b3448-ea02-41ca-a5e5-c8344b1fffe5","html_url":"https://github.com/tkowalski29/doc-builder","commit_stats":null,"previous_names":["tkowalski29/doc-builder"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/tkowalski29/doc-builder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tkowalski29%2Fdoc-builder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tkowalski29%2Fdoc-builder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tkowalski29%2Fdoc-builder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tkowalski29%2Fdoc-builder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tkowalski29","download_url":"https://codeload.github.com/tkowalski29/doc-builder/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tkowalski29%2Fdoc-builder/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278510917,"owners_count":25998997,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-05T02:00:06.059Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["build-automation","cli","documentation","documentation-builder","go-tools","markdown","static-site-generator","vitepress"],"created_at":"2025-10-05T19:56:55.197Z","updated_at":"2025-10-05T19:56:56.510Z","avatar_url":"https://github.com/tkowalski29.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# doc-builder\n\n`doc-builder` rewrites the former `build-docs.sh` workflow into a self-contained Go\nCLI. It scans a project for prefixed markdown files, assembles a temporary VitePress\nworkspace, and produces a ready-to-ship `dist` directory without requiring any\nmanual steps.\n\n## Features\n\n- Discover markdown files whose names start with a configurable prefix (default `DOC_`).\n- Merge additional markdown content that already lives inside the documentation\n  directory, preserving hand-crafted guides.\n- Generate a VitePress sidebar by replacing the `// SIDEBAR_ITEMS - will be replaced by build script`\n  placeholder in `.vitepress/base.config.js`.\n- Run `npm install` (only when needed) inside the temporary workspace and execute\n  `npm run docs:build` for the chosen engine (currently VitePress).\n- Copy the produced `.vitepress/dist` output back into the documentation workspace.\n- Provide a `helper` subcommand that explains the complete workflow and expected\n  repository layout.\n\n## Requirements\n\n- Go 1.22 or newer (for building the CLI).\n- Node.js toolchain available on the system (`npm` must be on `PATH`).\n- A documentation workspace that contains:\n  - `.vitepress/base.config.js` with the sidebar placeholder comment.\n  - `package.json` defining `npm run docs:build`.\n\nThe command stops with a clear error message whenever a required file is missing.\n\n## Building the CLI\n\n```bash\ngo build -o bin/doc-builder ./cmd/docbuilder\n```\n\n## Testing\n\nRun the unit test suite—covering front-matter parsing, sidebar generation, and\nfilesystem helpers—with:\n\n```bash\ngo test ./...\n```\n\n## Usage\n\nRun the tool from your documentation directory (the directory that contains\n`.vitepress` and `package.json`). Point `--search` to the project location you\nwant to scan for prefixed markdown files.\n\n```bash\n./bin/doc-builder \\\n  --search ../ \\\n  --doc-dir . \\\n  --prefix DOC_ \\\n  --engine vitepress\n```\n\n### Flags\n\n- `--search` *(required)*: root folder where prefixed markdown files are\n  discovered.\n- `--doc-dir` *(default: current directory)*: documentation workspace that holds\n  `.vitepress` and `package.json`.\n- `--prefix` *(default: `DOC_`)*: filename prefix used to select markdown sources.\n- `--engine` *(default: `vitepress`)*: documentation engine. Only `vitepress`\n  is implemented today; the flag keeps the interface forward compatible.\n- `--temp-dir` *(default: `temp`)*: name of the temporary build directory inside\n  the documentation workspace.\n- `--verbose`: prints detailed progress information.\n\n### Helper\n\nTo see a high-level overview of the pipeline, run:\n\n```bash\n./bin/doc-builder helper\n```\n\n### Example Document\n\nGenerate a sample markdown file (default `DOC_this_is_example.md`) to use as a\nstarting point:\n\n```bash\n./bin/doc-builder example-doc --doc-dir .\n```\n\nUse `--prefix` if your project relies on a different filename prefix.\n\n### Typical Workflow\n\n1. The CLI deletes and recreates `./temp` (or the configured temporary directory).\n2. Markdown files that match the prefix are copied into the temp workspace with\n   slugs derived from their filenames and categories read from YAML front matter.\n3. Existing markdown content inside the documentation workspace is merged so that\n   curated guides remain available.\n4. The sidebar is regenerated based on the collected metadata and written both to\n   `temp/.vitepress/config.js` and `.vitepress/config.js`.\n5. Node dependencies are installed into the temp directory (unless `node_modules`\n   already exists there) and `npm run docs:build` is executed.\n6. The freshly generated `temp/.vitepress/dist` directory replaces\n   `.vitepress/dist` in the documentation workspace.\n\nIf any of the steps fail (for example when `package.json` or the base config\ncannot be found), the command stops immediately and reports the offending path in\nEnglish.\n\n## Migrating from the Bash Script\n\nThe original `build-docs.sh` script is no longer required. The new CLI provides the\nsame behaviour, adds structured error handling, and keeps the door open for\nadditional engines beyond VitePress.\n\n## License\n\nThis project is released under the [Apache 2.0 License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftkowalski29%2Fdoc-builder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftkowalski29%2Fdoc-builder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftkowalski29%2Fdoc-builder/lists"}