Hacker News Reader

Comment by papascrubs | Hacker News Reader

Fellow AsciiDoc supporter. I want an AsciiDoc note taking app so badly too. So many awesome features in AsciiDoc that blow markdown out of the water. I use asciidoc-pdf for doc/report generation and the workflow is so smooth.

- Includes/embeds (reference your source code by line range(s)

- Complex table support + the ability to embed CSV (automatic headers)

- Frontmatter as a first class citizen

- Macros (Variables) that can be referenced across documents

- Numerous Diagram parsing libraries (embed pretty much any diagram-as-code language)

I've had the same thoughts on building a Dendron type extension for AsciiDoc (AsciiDoc vscode plugin is fairly robust). Really would just need to hammer out some front matter parsing to get basic functionality.

View on HN

Thanks for the reminder to check out asciidoctor-pdf! I forgot about it because I was using macOS's default, out-of-date Ruby version for the longest time and the gem required a newer version. I've since figured out how to install and change the default Ruby installation though, so I need to check it out. It's certainly a pain getting my current workflow set up on a new machine (e.g. installing TexLive takes forever for the latex-pdf support in pandoc).

ReStructuredText seems like it would be a better contender because it's the standard markup language for the most popular programming language.

It's also natively supported in VSCode (unlike AsciiDoc).

I honestly haven't played with ReStructuredText. I'll take a peek.

AsciiDoc includes are very powerful though, being able to populate your tables/code blocks from external data sources (filtering for certain lines/ranges). Also Tables can have complex structures (merged cells etc).

I feel like AsciiDoc was designed around writing technical papers than code documentation. It's essentially an opinionated wrapper around LaTex but less complexity. reST looks like it can produce great code documentation. AsciiDoc lets me cover both code documentation and customer facing documentation/reports with one code base. But I'll definitely continue to take a peek at reST. Although I think it's use case is more for embedding documentation directly in code. It's probably just my "I know the AsciiDoc toolchain well" bias though.

Reply on news.ycombinator.com