Hacker News Reader

Comment by julienb_sea | Hacker News Reader

To be fair, I'm not sure "offline readability" is an actual problem anymore. VS Code and (presumably) other IDEs offer a very simple live-preview window for viewing and editing markdown files.

View on HN

While it is true, these features seem to me to be added because Markdown is (ab)used the way it is. The issue is if you are working in an environment where it isn't possible, e.g. on a server where you only have vi/nano, and not even a TUI browser (or if you don't want to use an editor based on electron).

My issue is that you can still have a nice readme (often even giving a better, brief overview) by sticking to HTML-free Markdown.

Gitlab seems to be slightly better than Github, by allowing things like badges to be listed outside of the README, in the header of the repository page.

> badges to be listed outside of the README

This always irked me as I can't read the image when trying to look at raw text and the, say build status, isn't actually relevant to understanding the project. Sourcehut has an interesting approach where you can POST any HTML to an endpoint at it becomes the homepage. You can tag on extra markup if you want in the build step and that markup doesn't have to live in the README (say badges, other images, abbreviation tags, summary/details, etc.)

My vanilla vim on ssh begs to differ. Offline readability matters

To you it does but manifestly your use case doesn’t matter to the people writing these pieces of software and these readme files. They care about their audience which want different things than you. At some point you can’t expect the world to cater for you. You have to deal with the annoyances which come with doing things differently or move on with your time.

the world runs on ssh terminals so I'd argue it does matter

Assuming that those tools also implement the same set of MD functionality (like Mermaid)

Yes. The main use case I have for markdown is:

* reading documents in the terminal (like man pages)

* note taking

In both those instances the less auto-formatting that the editor does the easier it is for me to use the use the file format.

I’m sure you can say that editor auto-formatting isn’t an issue because people manage fine on MS Word. But the point is I want as little distractions as possible when not taking but I also want to be able to add headings and code snippets. So wrestling with an editor when it gets its formatting rules in a mess is the exact opposite of productively. Eg take a look at the number of authors that still use DOS editors for similar reasons.

We need to go back to something like Word documents. We’ve come full circle

README.docx

At least do LibreOffice format.

README.pdf with interactive JS and 3D elements

Now we're talking! Why read the documentation, when you can play the documentation?

If I ever see that in the wild, I'm going to escalate the arms race with a README.xml file.

How so? Word Documents are not made to be edited by hand. They are meant to be edited in Word. Markdown even with Mermaid is still readable and editable by hand. While I can agree Mermaid isn't my ideal markup, there are alternatives and you can even propose your own.

Mermaid is as readable as C++.

The examples shown in the fine article are Hello, world. The information contained within would be just as clear in vulgar prose. However the Mermaid code to create complex flowcharts that are not easily described in words, would be just as opaque as the Netscape 5 codebase.

I agree that it is no ideal, at least for my tastes, but I think what you are stating is an exaggeration. If you are using reference points like someone that knows little to nothing about technology, then just about anything different that what they are used is probably as readable as C++. For example, trying to read HTML would be the same to my grandma as trying to read C++.

The whole point of Markdown is "readable by humans" in unrendered form. Mermaid breaks that.

Readable by humans is relative. Mermaid does not make it unreadable to some humans. Again, you are free to create an alternative that makes it more readable. Some could say that adding tables to markdown makes it unreadable. There are lot of extensions for markdown that adds features, but you have to know what they are to read them and use them. Grandma doesn't have to use Mermaid if she doesn't want to.

Not everyone uses vscode

Reply on news.ycombinator.com