Asciidoctor: because writing docs does not have to suck
summary
Asciidoctor turns documentation into docs as code: the include macro pulls live production files into pages (select by line ranges, negative end -1, or named tags) so code examples never drift, and indentation and captioning adjust output. The JVM toolset uses JRuby plus Maven or the asciidoctor-gradle-plugin with -T for continuous rebuilds; extensions add screenshots (Geb/Selenium), diagrams (asciidoctor-diagram → Ditaa/PlantUML), and custom transforms, all rendering to HTML/PDF/ePub.
AI-written summary · about
chapters (11)
- 0:00Asciidoctor introduction
- 1:06Asciidoc vs Markdown
- 8:12Include macro & source code
- 17:23Refactoring docs snippets
- 20:18Attributes & conditional rendering
- 24:58Custom syntax extensions
- 29:43Automating translations
- 33:57Dynamic screenshots & diagrams
- 37:14Ecosystem & tools
- 40:20Open source contributions
- 41:42Q&A
related talks
51mGetting started with Asciidoctor
47mSpice Up Asciidoctor Documentation With Java
41mStop making fool of yourself about documentation
29mAsciidoctor: New, Noteworthy, and Beyond
25mDocumentation as Code, Where to Start?
50mContinuous and Automated Documentation Docs As Code in Practice
01h 00mLevels of Docs as Code
51mDocumentation as Code (Explained to My Father)