Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Markdown is holding you back

newsletter.bphogan.com

Post reply on HN
Print view View original

81–90 of 194 posts

Re: Markdown is holding you back

#81

Post by eproxus »

jimmar wrote: post #5

Markdown is the minimum viable product. It’s easy to learn and still readable if not rendered in an alternate format. It’s great. For making PDFs, I’ve recently moved from AsciiDoc to Typst. I couldn’t find a good way to get AsciiDoc to make accessible PDFs, and I found myself struggling to control the output. Typst solves all of AsciiDoc’s problems for me. But in the end, no markup language will make you write bette…

Djot is another interesting alternative that tries to make Markdown more parsable and coherent: https://github.com/jgm/djot#rationale

Re: Markdown is holding you back

#82

Post by isodev »

I love this post. While I don't mind markdown for quick notes which require basic formatting (headlines, bold, maybe a link), time and time again, I've found myself having to build parsing libraries and scripts for specific use cases just so the content can be interpreted correctly.

Take for example my blog, which I've had since 2016. It has been rebuilt into various systems over time and every time I had to migrate, there was a manual step of going over all posts and making sure they're displayed and interpreted correctly. In my last and current iteration, I've designed the system so that content is also stored with some hierarchical information (from html) like , , etc, only applying styling to it when rendered.

I don't think we should stop using Markdown, but when something requires more than 200 lines of introductory text, more semantically enabled source feels necessary.

Re: Markdown is holding you back

#83

Post by locknitpicker »

nrhrjrjrjtntbt wrote: post #30
prmoustache wrote: post #14

The author seems to forget that markdown is just an extension of html. If markdown doesn't provide something that html does, you just write it in html and it will be rendered correctly. I'd also argue that the limitations of markdown allow me to focus on actual content and less on the presentation. I have little use of all the features of a markup language if I can't remember how to use them.

It is not features but structure and undetstanding that is missing. That said I am not sure what the solution is to that since your docs may need structure my docs dont need. Therefore you cant solve the "semantic" outside of a "namespace" of what you agree in your organization. E.g. you may decide architecture diagrams are in Mermaid but that is by no means a stanfard and my org uses embeded svg. So to go full circl…

> It is not features but structure and undetstanding that is missing.

I don't think this belief is valid. The whole purpose of markdown is to serve as a easy to read format that is publishable as plaintext and has minimalist standardized formatting and styling. It's something for humans to read and write without requiring specialized tooling.

For this purpose, "structure" is neither a requirement nor a valid concern.

> E.g. you may decide architecture diagrams are in Mermaid but that is by no means a stanfard and my org uses embeded svg.

That's a trait of your organization, not Markdown. Mermaid is ubiquitous, and used extensively in virtually everywhere in the internet. If you chose not use it that's a personal call you're making, and not related to Markdown at all.

Re: Markdown is holding you back

#84

Post by childintime »

I'm working on a HTML replacement right now. If I am to believe the author, it would solve her issue (I don't think so). But I don't know if I want to "share". Can I patent it? Good luck with that.

Going off-topic now, sort of.

The Open Source I see just isn't serious. We lose the right to have an opinion about a technology, to steer it, as that right is mediated by money, and it just evaporates, unless you can set the norm by being a major user, like a tech titan.

Markdown is special because we as developers are the users! Though tech titans dictate what we shall use. As developers we are seemingly in a concentration camp where others set the rules, and there is no escape, unless we surrender our work in the name of love, in the presence of those who absolutely don't, government included, and whose basic mode of operation is to make the profit on our work. It's just legalized demoralization, if not outright stealing.

If you're from a developing country you know what I'm talking about. There is no way to be creative and get paid. You are a beggar, no matter your talents. The end result is that human creativity remains untapped. That is the price we as a community pay every day. Heil the rise of AI, so we don't need each other any longer, and the abuse can stop ;-

There's crimes everyday, and we normalize them, if they are done by the trusted and verified, that talk about merit while they hire f*cks to do their bidding. As a community we are a harem, and they come to rape us, err, give us pleasure, whenever they feel like it, and expect us to love it. Well, don't you love your new toys? That is who we are. And we therefore tend to repeat the cycle in our homes, as "men".

In the end the framing as a technical issue is what marks us. It's is the safe zone, where we can deny the real issue, and cope. If you're a member of Nation Procrasti-me, you know what I'm talking about. Nation Procrasti-Me, Where Life Is Denied. And rent-seeking is the truth.

F*ck, how did we get so cooked? We shackled ourselves, duh. We are infants, or else outright dumb, dumb enough to give away our life force, for new toys to play. Worse, we dictate others do so too. That's when we stand on the side of the abuse, confidently like a toddler that just spread his shit all over the place and radiates "how good was that!".

Re: Markdown is holding you back

#85

Post by sallveburrpi »

josephg wrote: post #75
tedggh wrote: post #58

Certainly not holding me back. I can go from crappy notes on a notepad to a polished and branded PDF release including TOC, tables, images and formulas, info/warning boxes, lists, code snippets with syntax highlighting, header/footer, etc in literally minutes. What else do you need?

What else? I want figures. I want linked references. I want custom styling for images, and for blocks of text (eg warnings, notes, etc). I want a TOC and numbered chapters and sections. Sometimes I want a bibliography. Or a table generated from data within a JSON file. You don't need this stuff for a readme file. But IMO markdown isn't powerful enough for blog posts, documentation or longer form content.

I use docusaurus as markdown renderer which adds most of what you need. Mermaid.js for figures. Never needed a data table from JSON but would be easy to add a custom component for this.

So yes for me markdown is definitely powerful enough for blogging and complex technical writing - has been for the last 6 years- with a few small extensions and I’ll eat my hat before I use anything xml based or reinvent html…

Re: Markdown is holding you back

#86

Post by youngtaff »

henrebotha wrote: post #29
dschuessler wrote: post #10

You can include arbitrary HTML tags in Markdown at any place you need them.[0] I am not aware of any Markdown tooling that does not support this. So, no, Markdown is not holding me back. It is perfectly capable of what the author claims it isn't. [0]: https://daringfireball.net/projects/markdown/syntax#html

There are real limitations to this: You can't arbitrarily mix and match HTML and Markdown. As soon as you introduce an HTML block, you're locked out of Markdown syntax. AsciiDoc lets you mix and match however you want. Or, put differently: AsciiDoc's superiority over Markdown extends even to being better at shelling out to HTML.

O’Reilly’s authoring system used to use AsciiDoc (may still do), made me hate AsciiDoc

Re: Markdown is holding you back

#87

Post by swiftcoder »

hobofan wrote: post #72
jimmar wrote: post #5

Markdown is the minimum viable product. It’s easy to learn and still readable if not rendered in an alternate format. It’s great. For making PDFs, I’ve recently moved from AsciiDoc to Typst. I couldn’t find a good way to get AsciiDoc to make accessible PDFs, and I found myself struggling to control the output. Typst solves all of AsciiDoc’s problems for me. But in the end, no markup language will make you write bette…

Yes, the author conflates two different use-cases. Markdown is the answer for "how do we enable people that don't want to invest a lot of time into producing content that's somewhat better than plain text?". It's not trying to solve the problem of "how do we enable people that are willing to invest time into learning to produce the best possible and most structured content possible?" and I doubt that there will be la…

One downside here is that as more and more tools focus on the first use-case, people start using those tools by default when they actually fall into the second use-case. And there's often a pretty high barrier to switching once you've produced a lot of content, so a bunch of projects are using the wrong one long-term.

Re: Markdown is holding you back

#88

Post by WhyNotHugo »

nicoburns wrote: post #6

This article doesnt consider Typst, which IMO ought to be the first port of call if Markdown isnt sufficient for your needs.

I think Typst looks really interesting for some scenarios, but inadequate for others.

I like RST a lot for Python documentation, because of all the directives for types, admonitions, and lots of domain-specific stuff. I wouldn't use RST if I'm writing a book, or a research paper.

In the same way, Typst looks like a great candidate for those last examples, but is likely unsuitable for documenting a library written in Python.

Re: Markdown is holding you back

#89

Post by mettamage »

jimmar wrote: post #5

Markdown is the minimum viable product. It’s easy to learn and still readable if not rendered in an alternate format. It’s great. For making PDFs, I’ve recently moved from AsciiDoc to Typst. I couldn’t find a good way to get AsciiDoc to make accessible PDFs, and I found myself struggling to control the output. Typst solves all of AsciiDoc’s problems for me. But in the end, no markup language will make you write bette…

LaTeX made me write better because of commenting above every paragraph.

Re: Markdown is holding you back

#90

Post by pas »

swiftcoder wrote: post #87
hobofan wrote: post #72

Earlier quoted context omitted.

Yes, the author conflates two different use-cases. Markdown is the answer for "how do we enable people that don't want to invest a lot of time into producing content that's somewhat better than plain text?". It's not trying to solve the problem of "how do we enable people that are willing to invest time into learning to produce the best possible and most structured content possible?" and I doubt that there will be la…

One downside here is that as more and more tools focus on the first use-case, people start using those tools by default when they actually fall into the second use-case. And there's often a pretty high barrier to switching once you've produced a lot of content, so a bunch of projects are using the wrong one long-term.

Arguably having a ton of hard to write, hard to maintain docs is waaay worse than Markdown that gets attention in PRs (MRs).

Especially that the things in the article seem irrelevant compared to actually adding and handling non-text content IMHO. (Mermaid diagrams for example.)

Sure a validator would be nice, but that's why a simple preview is available in most collaboration platforms.

Post reply on HN