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

51–60 of 194 posts

Re: Markdown is holding you back

#51

Post by starkparker »

By suggesting DITA as a valid alternative to Markdown, for any use, this has so completely lost the plot that it blows up whatever credibility Brian might have on the subject. It's disappointing, because I know of Brian and otherwise respect his work.

Short of writing in raw Postscript, I can't think of a more completely different set of strengths, audiences, and applications. I had to get to a company with more than 5,000 employees, 20 product lines, and 5 required i18n locales to find one where the overhead, god-awful ergonomics, and half-broken tooling of DITA were appropriate for the scale of the work _and also_ resourced enough to paper over every miserable facet of its implementation.

If you're using Markdown today _at all_ for a task, DITA isn't appropriate for it. If DITA was appropriate for the task, you never would've picked Markdown to accomplish it to begin with. Don't waste your time with it either way.

Re: Markdown is holding you back

#52

Post by abathur »

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…

This is the kind of dismissive sneer the HN guidelines advise against.

You can write dev docs for humans and still want machine readability (without caring about whether some LLM can make sense of the docs).

Machine readability is how you repurpose your own documentation in different contexts. If your documentation it isn't machine readable it might as well be in a .doc(x) file.

Re: Markdown is holding you back

#53

Post by addaon »

TRiG_Ireland wrote: post #25
undeveloper wrote: post #15

Earlier quoted context omitted.

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.

I'm not aware of any limitations in the Tinymist plugin. And you can just write it in the plain text editor of your choice, and keep an eye on the PDF with typst watch.

> I'm not aware of any limitations in the Tinymist plugin.

I looked into this a while ago, and couldn't find a workflow I could live with. Have things improved? What's the workflow like for working on an image in, say, OmniGraffle to include in the document? Does text search in embedded PDFs work these days? LinkBack so I can edit the images easily inline?

Re: Markdown is holding you back

#54

Post by dardeaup »

ldng wrote: post #47
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?

How about markdown -> PDF (with Typst) -> epub/mobi ?

Thanks! I'll look into that as an option.

Re: Markdown is holding you back

#55

Post by dardeaup »

ifh-hn wrote: post #44
WA wrote: post #32

Earlier quoted context omitted.

You need: - table of contents - automatic chapter and section numbering - cross references and automatic tracking of figures, tables etc. - different styles besides blockquotes such as info sections, warnings, tips Imho, cross-referencing chapters, pages, figures, tables and the lack thereof in Markdown is the first and most important thing to check how you would like this to be solved.

Pandoc and pandoc-crossref. Or simply use quarto.

Thanks!

Re: Markdown is holding you back

#56

Post by dardeaup »

macintux wrote: post #28
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?

You might look at DocBook. I haven't used it in ~25 years, and then only for short documents, and it is XML hence quite verbose. But it's explicitly targeted at technical documentation. If nothing else, searching for DocBook alternatives might give you some ideas.

Thanks!

Re: Markdown is holding you back

#57

Post by tedggh »

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?

My stack is Markdown-Pandora-MiKTeX-PDF with Eisvogel for technical documentation and it works great for my use case. Eisvogel has a “book” typeset.

Re: Markdown is holding you back

#58

Post by tedggh »

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?

Re: Markdown is holding you back

#59

Post by vorpalhex »

throwaway150 wrote: post #49
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

> You can include arbitrary HTML tags in Markdown at any place you need them. That is well known and I am sure the author is aware of it. The problem they are describing is not whether HTML is technically allowed inside Markdown. It's that when you are writing Markdown, you are writing Markdown, not HTML, and that comes with some problems. > It is perfectly capable of what the author claims it isn't. In theory, yes.…

Most markdown engines allow short tags to stand in for html, so for frequent features you can just use a short tag.

Alternatively you can extend markdown. I wrote a simple text based game engine that was markdown based but I needed some arbitrary additions appropriate for a game.. so I just added a few elements.

Re: Markdown is holding you back

#60

Post by mycall »

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.

Markdown can be used where HTML is not available, like in AI chatbots for omnichannel mediums (e.g. WhatsApp).
Post reply on HN