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

11–20 of 194 posts

Re: Markdown is holding you back

#11

Post by zihotki »

dragonwriter wrote: post #9
philipwhiuk wrote: post #3

> If you're writing a quick README or a short-lived doc, Markdown is fine. It's fast, approachable, and does the job. If you're building a developer documentation site that needs some structure, reStructuredText or AsciiDoc are better choices. This is dumb. If I'm writing developer documentation I'm not writing it for a machine. And if the aim here is to expose it to a LLM, then the LLM needs to get smarter about sem…

> If I'm writing developer documentation I'm not writing it for a machine. And if the aim here is to expose it to a LLM, then the LLM needs to get smarter about semantics, not force us back to formats that are more technically complex to write and maintain AsciiDoc is much better than Markdown for docs intended for humans that are more than short, README type of documents. Any advantage it has for documents intended…

Many consider AsciiDoc being too complex.

Re: Markdown is holding you back

#12

Post by johnathandos »

It’s good to spread awareness (or just remind folks) that alternatives to Markdown exist. The right tool for the job depends on your circumstances. If I were scaling a docset for a team of contributors primarily consisting of technical writers, .adoc or .rst would be my preference. If I were scaling internal docs-as-code infra for software engineers, I’d use Markdown.

Re: Markdown is holding you back

#14

Post by prmoustache »

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.

Re: Markdown is holding you back

#15

Post by undeveloper »

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…

typst looks interesting -- but how are you writing it? from what I looked at, it looks like theres an official web editor and a vscode plugin with limited support. this feels pretty limited, as someone who came in expecting something like obsidian.

Re: Markdown is holding you back

#16

Post by dardeaup »

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.

Wow! TIL!

Re: Markdown is holding you back

#17

Post by undeveloper »

perlgeek wrote: post #13
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've used typst for generating PDFs before, how good is its HTML output?

it looks like typst's html output is under construction [1].

1: https://typst.app/docs/reference/html/

Re: Markdown is holding you back

#18

Post by dardeaup »

This is a timely topic for me. I'm just beginning the writing of a technical book. I plan to target epub/mobi. My research thus far has pointed to markdown -> html -> epub/mobi. If you were going to write a technical ebook would you use markdown or an alternative?

Re: Markdown is holding you back

#20

Post by codybontecou »

dardeaup wrote: post #18

This is a timely topic for me. I'm just beginning the writing of a technical book. I plan to target epub/mobi. My research thus far has pointed to markdown -> html -> epub/mobi. If you were going to write a technical ebook would you use markdown or an alternative?

What about markdown do you feel limits you in your writing process?

The beauty of markdown is that it’s standardized. If you find your self midway through the book and feel a need to change formats, it’s easy enough to parse and reformat.

Post reply on HN