{"id":18494815,"url":"https://github.com/qaware/clean-documentation-template","last_synced_at":"2025-06-10T10:38:53.648Z","repository":{"id":258118104,"uuid":"834005485","full_name":"qaware/clean-documentation-template","owner":"qaware","description":"A documentation suggestion based on Antora","archived":false,"fork":false,"pushed_at":"2024-11-28T18:42:01.000Z","size":691,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-05-14T03:14:28.016Z","etag":null,"topics":["antora","asciidoc","documentation"],"latest_commit_sha":null,"homepage":"http://blog.qaware.de/clean-documentation-template/","language":"Handlebars","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/qaware.png","metadata":{"files":{"readme":"README.adoc","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}},"created_at":"2024-07-26T08:18:05.000Z","updated_at":"2024-11-25T15:07:37.000Z","dependencies_parsed_at":"2025-02-16T23:26:38.391Z","dependency_job_id":"6292ac2c-7377-48db-83e4-2918f8368047","html_url":"https://github.com/qaware/clean-documentation-template","commit_stats":null,"previous_names":["qaware/clean-documentation-template"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qaware%2Fclean-documentation-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qaware%2Fclean-documentation-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qaware%2Fclean-documentation-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qaware%2Fclean-documentation-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qaware","download_url":"https://codeload.github.com/qaware/clean-documentation-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qaware%2Fclean-documentation-template/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259057094,"owners_count":22799081,"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","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":["antora","asciidoc","documentation"],"created_at":"2024-11-06T13:22:16.413Z","updated_at":"2025-06-10T10:38:53.612Z","avatar_url":"https://github.com/qaware.png","language":"Handlebars","funding_links":[],"categories":[],"sub_categories":[],"readme":"= Clean Documentation Template\n\n////\nTODOs:\n* nav.adoc's are missing\n* Add repo descriptions\n* Use dockerized build =\u003e CI and local use for antora build\n  https://github.com/qaware/clean-documentation-template/pull/1#discussion_r1736311093\n* Add jekyll startpage just like https://github.com/ahus1/intellij-asciidoc-plugin.ahus1.de/tree/main/startpage\n* Build own ui-bundle with wider nav bar\n////\n\nThis repo shows how\nhttps://github.com/alex0ptr[Alex Krause (@alex0ptr)]\nand\nhttps://github.com/aeimer[Alexander Eimer (@aeimer)]\nthink how AsciiDoc, Antora and vale can be used to document your software and product better.\n\n[.text-center]\n****\nYou can find the rendered Antora docs\nhttps://qaware.github.io/clean-documentation-template[here]\n****\n\n== Structure\n\nThis repo has two main parts, the first can be found under\nxref:templates/[templates]\nand provide standalone files which can be used within the next part.\n\nThe second part shows how to set up a working Antora and all the by us suggested  tooling.\nAlmost any other files not under the `templates` directory belongs to this part.\nThe templates provided are our suggestion to use within the documentation structure.\n\n== Content\n\nFrom a technical perspective the following components are used.\n\nAntora::\n#TODO#\n\nAntora Lunr::\n#TODO#\n\nAntora Collector::\n#TODO#\n\nAntora Assembler::\n#TODO#\n\nAntora Kroki::\n#TODO#\n\nVale::\n#TODO#\n\nPre-Commit::\n#TODO#\n\n== Differences to the real world\n\nAs this is a template which is contained within one repo, there are some differences to a real world setup.\n\n* As\nhttps://docs.antora.org/antora/latest/playbook/#where-is-a-playbook-stored[suggested by Antora]\nthe playbook and the configuration files are stored in a separate repository.\nHaving a \"docs\" repo with the playbook, config and some documentation content together works for some setups well, always look at your use-case.\nIf in doubt start small and adapt if you grow.\n\n* You probably want to have different repos as source defined in the `antora-playbook.yml` with branches or tags as references which state to use.\n\n== Using the Taskfile\n\nhttps://taskfile.dev[`Taskfile`]\nis a `Makefile` on steroids.\nYou need to install Taskfile globally to use it.\n\n[source,bash]\n----\n# Install required dependencies via Brewfile\nbrew bundle\n\n# Alternatively, install at least Taskfile (manually)\nbrew install go-task\n\n# Show all tasks available\ntask\n\n# Render documentation\ntask generate\n\n# Render documentation and open in browser\ntask generate open\n# or\ntask g o\n\n# Open rendered documentation with http server\ntask serve\n----\n\n== Useful links\n\n* https://diataxis.fr[Diátaxis]\n* https://antora.org[Antora]\n** https://gitlab.com/antora/antora-collector-extension[Antora collector] +\nA hook plugin to run custom code while generating the docs.\nIt can be used to auto-generate `nav.adoc` files for dynamic content.\n** https://gitlab.com/antora/antora-assembler[Antora assembler] +\nA plugin which has pure AsciiDoc as output and has all the Antora magic removed.\nIt can be used to generate PDFs with the whole content.\n* https://vale.sh[Vale]\n* https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[AsciiDoctor Quick Reference]\n* https://nick.groenen.me/notes/one-sentence-per-line/[One sentence per line rule]\n* https://github.com/joelparkerhenderson/architecture-decision-record[Joels ADR]\n* https://www.blameless.com/blog/what-are-blameless-postmortems-do-they-work-how[blameless.com]\n* https://github.com/dastergon/postmortem-templates/blob/master/templates/postmortem-template-srebook.md?plain=1[dastergon/postmortem-templates^]\n* https://ahus1.de[Alexander Schwartz]\n** https://www.ahus1.de/post/content-pipeline-antora[Talk about Antora] +\n=\u003e https://github.com/ahus1/antora-extensions-demo[Demo repo to the talk]\n** https://www.ahus1.de/post/documentation-site-antora[Another talk about Antora] +\n=\u003e https://github.com/ahus1/intellij-asciidoc-plugin.ahus1.de[IntelliJ AsciiDoc Plugin documentation]\n\n== Support\n\nThis project is made possible with the support of\n\n[link=\"https://qaware.de\"]\nimage::https://blog.qaware.de/images/icons/logo_qaware.svg[QAware GmbH logo,200]\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqaware%2Fclean-documentation-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqaware%2Fclean-documentation-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqaware%2Fclean-documentation-template/lists"}