Hacker News Reader

Comment by bluGill | Hacker News Reader

Another doc site that uses .md. Unfortunately md doesn't do a few things you want from a complex documentation (good and easy for small documents, but not powerful enough for complex projects). Things like deep linking into a different document rarely work.

View on HN

Yeah. A lot of the new .md build systems are sprouting up to address the gaps between .md and complex pubs, a space occupied by the more complex LMLs (lightweight markup) like .adoc and .rst. This - for the Nth million time - beautifully illustrates conservation of complexity: you liked Markdown because low complexity, then you got complex requirements, now you have to shovel the complexity into a bespoke build system.

I understand there's a couple of .md forks dedicated to solving some of the problems with complex docs, but the trap phrase there is "a couple of forks". One writer goes with MDX, another writer uses a Jekyll script, another writer uses MultiMarkdown . . whoops! Broken pubs system.

I understand Markdown, and I like it. I like it a LOT[1]. But it's not for every use case.

[1] It led the charge against the XML Publications Fortress, which had[a] locked down documents inside of an ivory fortress for decades. Curious what the doc looks like? Want to contribute? TOO BAD. But then came Adam Schwartz on his White Horse, and the world was changed.

[1.a] And continues to lock, in many industries.

In the past, I've either dropped into just straight-up HTML for more complicated bits, or done two-pass rendering. (E.g., have input → tool A → documentation generator → docs. We do this to render a few tables in our docs from YAML data files that just contain the actual data in the table. Our doc system includes an "include this file" directive, so the result can be pasted into other prose still written normally.)

It's not completely optimal. I do wish M↓ supported things like admonitions (callouts for warnings, notes, todos) better, in particular, since our docs are rife with those.

Doks supports authoring content in Markdown and HTML with no configuration required. You can add support for Emacs Org-Mode, AsciiDoc, RST, and Pandoc by installing additional parsers.

What is deep linking into a different document? You mean to a header or something else?

From one document to the middle of a different one. I use restructured text which lets me link that way. It is a little tricky, but not difficult and makes it much easier to have documents reference others. I have separate user documentation from design documentation, but the design documentation often needs to reference the user documentation for the thing it just talked about to get into details that otherwise would have to be repeated.

Unfortunately restructure text is not nearly as popular as markdown and so lots of other tools I want either don't exist, or are out of date.

The lack of non-docutils implementations is easily explained by rst being essentially impossible to parse; it's also somewhat annoying to write, in particular with the distinct lack of nested markup and the very baroque indentation rules - try writing nested lists without accidentally putting half of them in blockquotes. That being said sphinx-doc works very well even for complex projects and most documentation tools are rather inferior, much like static site generators it's a straightforward project to get to a "works for me" point.

rst (and sphinx) are also one of the few (open source) options which have some support for multiple modalities.

> deep linking into a different document

This is difficult in every docu system.

ReStructuredText (.rst, what Sphinx uses) handles it quite well. I understand why Markdown became so popular (super easy/intuitive) but what I don't understand is why so many documentation systems use it. It's quite limited... On purpose!

You want to support simple text features in a forum or comments on a website? Markdown is perfect. You want to support basically every documentation feature imaginable while still retaining reasonable ease-of-use? ReStructuredText is the way to go.

As I understand it, rST and Asciidoc are roughly equivalent in that they provide significant document-oriented upgrades to Markdown - upgrades that are on the order of Docbook. This makes them attractive. But you won't convince me that cross-document deep linking is a solved problem unless you accept that the use case is a static document base. Anything to do with products under continuing development is going to bring headaches. Is there any CMS that "solves" this in a robust way ? I wonder.

It's fairly easy in rST. I just can never remember the syntax :P

We switched the iommi docs from markdown to rST for this and many other similar issues of rST being more powerful.

nah we use asciidoc for this. worked next to the guy who invented it back in the day. another team at our company used to to make topic-based authoring the CMS standard. been doing this fine for years now and even the writers seem happy (super rare for tech writers innit)

Not hard with RST/Sphinx, but that comes with other usability nits.

Reply on news.ycombinator.com