{"slug": "asciidoctor", "name": "Asciidoctor", "category": "notes", "category_name": "Notes and knowledge", "description": "", "recommenders": 3, "commenters": 3, "warners": 0, "score": 2.433, "rising": -0.98, "first": "2025-11-04", "latest": "2026-01-13", "why": "it's quite old, it's battle-tested, and offers me many options to produce various forms of output", "why_is_quote": true, "has_verdict": false, "sentiment": {"recommend": 3, "neutral": 0, "compare": 0, "warn": 0}, "spark": [2, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0], "listed": true, "loved": [], "caveat": "", "short_quote": "it's quite old, it's battle-tested, and offers me many options to produce various forms of output", "icon": true, "domain": null, "github_repo": null, "official_url": "https://asciidoctor.org", "pricing": "", "aliases": ["Asciidoctor", "AsciiDoctor"], "verdict": null, "praise": [{"label": "", "summary": "", "quotes": [{"id": 745772305, "item_id": 46610769, "url": "https://news.ycombinator.com/item?id=46610769", "by": "dont__panic", "date": "2026-01-13", "stance": "recommend", "quote": "vanilla solutions out there like AsciiDoctor and Sphinx", "excerpt": "I love the linux philosophy at work here. Pandoc is an incredible tool that every documentarian knows. Markdown is a great tool that covers 80%+ of docs requirements (admonitions and tabs are not well-defined in vanilla markdown, for instance, but you don't strictly _need_ those). I've worked on docs at quite a few companies at this point. Almost every company I've ever seen has built a Rube Goldberg machine and tota", "context": "has worked on docs at many companies", "use_case": "documentation", "switched_from": "", "story": "You Don't Need Mintlify"}, {"id": 736388624, "item_id": 46024289, "url": "https://news.ycombinator.com/item?id=46024289", "by": "meonkeys", "date": "2025-11-23", "stance": "recommend", "quote": "Asciidoctor worked for this, although there were some compromises", "excerpt": "I wouldn't use Markdown for that. You're right to start with your requirements. Try to get detailed, like the list @WA wrote out, then match it up with appropriate tech. I wrote a technical book and I also wanted multiple decent-looking outputs. In my case: HTML, EPUB/mobi, screen and print PDFs. I was struggling with Markdown+pandoc+custom scripts/styles, so I switched to Asciidoc. I wrote about that process here: h", "context": "wrote a technical book", "use_case": "writing technical book, multiple outputs", "switched_from": "Pandoc", "story": "Markdown is holding you back"}, {"id": 733015761, "item_id": 45813485, "url": "https://news.ycombinator.com/item?id=45813485", "by": "stefanos82", "date": "2025-11-04", "stance": "recommend", "quote": "it's quite old, it's battle-tested, and offers me many options to produce various forms of output", "excerpt": "I have tried to follow Hugo's development but lost track with its constant evolution and addition of features I do not need...therefore for now I follow a simpler path: I keep my data in markdown files and I plan to switch to asciidoctor for good; it's quite old, it's battle-tested, and offers me many options to produce various forms of output; be it HTML, PDF, ePub, etc... If O'Reilly trusts it to produce its ebooks", "context": "", "use_case": "blogging and document output", "switched_from": "Hugo", "story": "Ask HN: What are you using for blogging?"}]}], "caveats": [], "who": [{"by": "dont__panic", "context": "has worked on docs at many companies", "url": "https://news.ycombinator.com/item?id=46610769", "date": "2026-01-13"}, {"by": "meonkeys", "context": "wrote a technical book", "url": "https://news.ycombinator.com/item?id=46024289", "date": "2025-11-23"}], "tags": [], "use_cases": ["documentation", "writing technical book, multiple outputs", "blogging and document output"], "compared": [{"slug": "pandoc", "name": "Pandoc", "co": 2, "switched_from": 1, "switched_to": 0}, {"slug": "hugo", "name": "Hugo", "co": 1, "switched_from": 1, "switched_to": 0}], "makers": [], "threads": [{"url": "https://news.ycombinator.com/item?id=46596823", "title": "You Don't Need Mintlify", "mentions": 1}, {"url": "https://news.ycombinator.com/item?id=46017782", "title": "Markdown is holding you back", "mentions": 1}, {"url": "https://news.ycombinator.com/item?id=45813221", "title": "Ask HN: What are you using for blogging?", "mentions": 1}], "sentiment_by_month": {"2025-11": {"recommend": 2}, "2025-12": {}, "2026-01": {"recommend": 1}, "2026-02": {}, "2026-03": {}, "2026-04": {}, "2026-05": {}, "2026-06": {}, "2026-07": {}, "2026-08": {}, "2026-09": {}, "2026-10": {}}, "quotes": [{"id": 745772305, "item_id": 46610769, "url": "https://news.ycombinator.com/item?id=46610769", "by": "dont__panic", "date": "2026-01-13", "stance": "recommend", "quote": "vanilla solutions out there like AsciiDoctor and Sphinx", "excerpt": "I love the linux philosophy at work here. Pandoc is an incredible tool that every documentarian knows. Markdown is a great tool that covers 80%+ of docs requirements (admonitions and tabs are not well-defined in vanilla markdown, for instance, but you don't strictly _need_ those). I've worked on docs at quite a few companies at this point. Almost every company I've ever seen has built a Rube Goldberg machine and tota", "context": "has worked on docs at many companies", "use_case": "documentation", "switched_from": "", "story": "You Don't Need Mintlify"}, {"id": 736388624, "item_id": 46024289, "url": "https://news.ycombinator.com/item?id=46024289", "by": "meonkeys", "date": "2025-11-23", "stance": "recommend", "quote": "Asciidoctor worked for this, although there were some compromises", "excerpt": "I wouldn't use Markdown for that. You're right to start with your requirements. Try to get detailed, like the list @WA wrote out, then match it up with appropriate tech. I wrote a technical book and I also wanted multiple decent-looking outputs. In my case: HTML, EPUB/mobi, screen and print PDFs. I was struggling with Markdown+pandoc+custom scripts/styles, so I switched to Asciidoc. I wrote about that process here: h", "context": "wrote a technical book", "use_case": "writing technical book, multiple outputs", "switched_from": "Pandoc", "story": "Markdown is holding you back"}, {"id": 733015761, "item_id": 45813485, "url": "https://news.ycombinator.com/item?id=45813485", "by": "stefanos82", "date": "2025-11-04", "stance": "recommend", "quote": "it's quite old, it's battle-tested, and offers me many options to produce various forms of output", "excerpt": "I have tried to follow Hugo's development but lost track with its constant evolution and addition of features I do not need...therefore for now I follow a simpler path: I keep my data in markdown files and I plan to switch to asciidoctor for good; it's quite old, it's battle-tested, and offers me many options to produce various forms of output; be it HTML, PDF, ePub, etc... If O'Reilly trusts it to produce its ebooks", "context": "", "use_case": "blogging and document output", "switched_from": "Hugo", "story": "Ask HN: What are you using for blogging?"}]}