{"id":27899477,"url":"https://github.com/roave/docbooktool","last_synced_at":"2025-07-23T04:03:43.228Z","repository":{"id":36970896,"uuid":"333405690","full_name":"Roave/DocbookTool","owner":"Roave","description":":books: Docbook Tool for static documentation generation from Markdown files","archived":false,"fork":false,"pushed_at":"2025-07-11T05:49:30.000Z","size":9769,"stargazers_count":56,"open_issues_count":20,"forks_count":5,"subscribers_count":5,"default_branch":"1.21.x","last_synced_at":"2025-07-14T06:35:55.727Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"PHP","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/Roave.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}},"created_at":"2021-01-27T11:59:37.000Z","updated_at":"2025-03-31T20:01:08.000Z","dependencies_parsed_at":"2024-01-10T10:54:53.383Z","dependency_job_id":"c8914888-494b-47a3-bce5-71277f79f393","html_url":"https://github.com/Roave/DocbookTool","commit_stats":null,"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"purl":"pkg:github/Roave/DocbookTool","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Roave%2FDocbookTool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Roave%2FDocbookTool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Roave%2FDocbookTool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Roave%2FDocbookTool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Roave","download_url":"https://codeload.github.com/Roave/DocbookTool/tar.gz/refs/heads/1.21.x","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Roave%2FDocbookTool/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266614306,"owners_count":23956341,"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-07-23T02:00:09.312Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"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":[],"created_at":"2025-05-05T19:33:23.326Z","updated_at":"2025-07-23T04:03:43.195Z","avatar_url":"https://github.com/Roave.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Roave Docbook Tool\n\nStatic HTML and PDF generator tool for generating documentation from Markdown files.\n\n * Generates a deployable HTML file from Markdown documentation\n * Generates PDF files of the same documentation that can be deployed alongside\n * Link pages to a Confluence instance so the content can be mirrored there\n\n## Running with Docker\n\nA Docker image is provided with all the pre-built tools. You will need to map several volumes into the container:\n\n - `/docs-package` - this will be where the tool writes the output\n - `/docs-src/book` - the path containing the Markdown files to be rendered\n - `/docs-src/templates` - the `online.twig` and `pdf.twig` templates to use for rendering HTML/PDF respectively\n - `/docs-src/features` - if you have features, this should contain your features\n\nAdditionally, you can provide environment variables to override the default paths used, or to enable the Confluence\nfunctionality.\n\n```bash\n# Will build the test fixtures and put in a folder called \"build\"\ndocker run \\\n  -v $(pwd)/test/fixture/docbook:/docs-src/book \\\n  -v $(pwd)/test/fixture/templates:/docs-src/templates \\\n  -v $(pwd)/test/fixture/feature:/docs-src/features \\\n  -v $(pwd)/build:/docs-package \\\n  --rm ghcr.io/roave/docbooktool:latest\n\n# Will build your stuff - replace host paths as appropriate\ndocker run \\\n  -v $(pwd)/docs/book:/docs-src/book \\\n  -v $(pwd)/docs/templates:/docs-src/templates \\\n  -v $(pwd)/features:/docs-src/features \\\n  -v $(pwd)/build:/docs-package \\\n  --rm ghcr.io/roave/docbooktool:latest\n\n# Will generate HTML, PDF, and update any configured Confluence pages\ndocker run \\\n  -v $(pwd)/docs/book:/docs-src/book \\\n  -v $(pwd)/docs/templates:/docs-src/templates \\\n  -v $(pwd)/features:/docs-src/features \\\n  -v $(pwd)/build:/docs-package \\\n  -e DOCBOOK_TOOL_CONFLUENCE_URL=https://confluence.mycompany.com \\\n  -e DOCBOOK_TOOL_CONFLUENCE_AUTH_TOKEN=\"\u003cauth token\u003e\" \\\n  --rm ghcr.io/roave/docbooktool:latest --html --pdf --confluence\n```\n\n## Usage\n\n```bash\nbin/docbook-tool [--html] [--pdf] [--confluence]\n```\n\nFor example, this command would generate only the HTML documentation:\n\n```bash\n$ DOCBOOK_TOOL_CONTENT_PATH=/path/to/myproject/docs/book \\\n\u003e DOCBOOK_TOOL_TEMPLATE_PATH=/path/to/myproject/docs/template \\\n\u003e DOCBOOK_TOOL_OUTPUT_HTML_FILE=/path/to/myproject/build/docs.html \\\n\u003e bin/docbook-tool --html\n[2021-01-28T12:28:41.000628+00:00] cli.INFO: Writing HTML output to /path/to/myproject/build/docs.html [] []\n$\n```\n\n## Formatting\n\nWe have limited support for YAML front matter:\n\n * `title: Your title here` - when specified, this will be used as the page title (`{{ title }}` in template)\n * `pdf: true` - when specified, a PDF will be generated for this\n * `confluencePageId: 1234` - when specified, Confluence page `1234` will be updated (numeric ID only)\n * `order: 100` - when specified, pages are ordered by this. Defaults to 100. Matching values are sorted alphabetically.\n\nAdditionally, we have a special Markdown syntax:\n\n * `{{feature:test.feature}}` will render `$(DOCBOOK_TOOL_FEATURES_PATH)/test.feature` as a code block\n * Code blocks (triple-backtick) with the `puml` syntax will be converted into a PlantUML diagram. Note your diagram\n   must start and end with `@startuml` and `@enduml` respectively.\n * `{{src-json:test.json}}` will render `$(DOCBOOK_TOOL_CONTENT_PATH)/test.json` as a code block. Only `json` is\n   supported at the moment.\n\nExample showing all syntax can be seen in `test/fixture/docbook/test.md`.\n\n## Environment variables\n\n * `DOCBOOK_TOOL_CONTENT_PATH` - the path where your Markdown documentation is kept (Required)\n   * Example: `/path/to/myproject/docs/book`\n * `DOCBOOK_TOOL_TEMPLATE_PATH` - the path to your Twig templates called `online.twig` and `pdf.twig` (Required)\n   * Example: `/path/to/myproject/docs/template`\n * `DOCBOOK_TOOL_FEATURES_PATH` - the base path from where features are stored (Optional)\n   * Example: `/path/to/myproject/features`\n * `DOCBOOK_TOOL_OUTPUT_HTML_FILE` - where to generate the HTML documentation (Required, if using `--html`)\n   * Example: `/path/to/myproject/build/docs/index.html`\n * `DOCBOOK_TOOL_OUTPUT_PDF_PATH` - where to generate the PDF files, if used (Required, if using `--pdf`)\n   * Example: `/path/to/myproject/build/docs/pdf`\n * `DOCBOOK_TOOL_CONFLUENCE_URL` - the base URL of confluence (`/rest/api/content` is appended to this, so don't\n   include that) (Required, if using `--confluence`)\n   * Example: `https://confluence.mycompany.com`\n * `DOCBOOK_TOOL_CONFLUENCE_AUTH_TOKEN` - the `Authorization` header value to use (Required, if using `--confluence` in\n   a non-interactive terminal).\n   * Example using a [personal access token (PAT)](https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html): `Bearer MTA4NjU3Njg2OTEyOt53L29niGxOkuIZJpKcgjItNMoI`\n   * Example using [basic auth](https://developer.atlassian.com/cloud/confluence/basic-auth-for-rest-apis/): `Basic bXktdXNlcm5hbWU6bXktcGFzc3dvcmQ=`\n * `DOCBOOK_TOOL_CONFLUENCE_SKIP_CONTENT_HASH_CHECKS` - Should the content hash check be skipped. Set to `yes` to skip\n   the hash check. Note that this means every time the tool runs, the content will create a version in Confluence, even\n   if nothing has changed. This is a workaround for some API issues with certain Confluence setups, so we don't\n   recommend enabling this unless you have a specific need to.\n   * Example: `no`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froave%2Fdocbooktool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Froave%2Fdocbooktool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froave%2Fdocbooktool/lists"}