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

171–180 of 194 posts

Re: Markdown is holding you back

#171

Post by vidarh »

judahmeek wrote: post #91
vidarh wrote: post #34

Earlier quoted context omitted.

While that's true, I'd take Markdown + extensions to allow inline HTML or custom tags over AsciiDoc any day, even at the cost of losing some compatibility - converting that to plain Markdown is usually easy enough.

What are the trade-offs with AsciiDoc that would make you choose Markdown instead?

It has sufficient differences to what is already accepted "everywhere" that I would have think about syntax more often than I'd like. That is enough. The minor inconveniences of Markdown incompatibilities are smaller than the inconveniece of AsciiDoc. It simply doesn't offer nearly enough potential advantages to be worth the hassle.

Re: Markdown is holding you back

#172

Post by josephg »

sallveburrpi wrote: post #85
josephg wrote: post #75

Earlier quoted context omitted.

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…

I hear you, but to be clear - you're not using markdown any more. A quick look at the docusaurus website suggests it uses MDX, which explicitly does not support commonmark. MDX documents cannot be rendered with other markdown renderers. And normal markdown text can also be incompatible with mdx.

If markdown were actually good enough, you wouldn't be reaching for bespoke extensions to markdown to make it more capable.

Re: Markdown is holding you back

#173

Post by josephg »

MrWB wrote: post #106
josephg wrote: post #75

Earlier quoted context omitted.

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.

Have you looked at Quarto?

No. Should I? It looks like a markdown renderer with a huge pile of custom extensions.

It looks like they've added support for some of the things I need (eg references). But not other stuff. It has hardcoded block support for Note and Warning. But it looks like I can't program my own?

It supports front matter, but only in a few predefined styles? And it looks like I can't define my own rendering / styling for image blocks? Like, if I want to make images clickable and be shown full screen, I can't do it using quarto?

Like I said in another comment, if you're writing a markdown-like document that can only be rendered properly in one bespoke tool, you're not writing in actual markdown any more. Like if I had my own C compiler with a bunch of custom extensions, code written which uses all of those extensions isn't really C code. With actual markdown, you can send people the markdown content itself and they can render it locally using whatever tool they like.

Use a tool like quarto if you want. But the need for something like this proves the point that markdown on its own isn't sufficient. If you're reaching for a markdown-incompatible document format, why stick with markdown at all, and not React, or ascii doctor, or typst?

Re: Markdown is holding you back

#174

Post by bryanhogan »

I prefer writing Markdown for notes, e.g. in Obsidian, I think it fits very there. Because now you can easily take your notes to most other note-taking programs, and letting AI interact with these files also works great.

If I needed more context / am writing a paper I'd choose something like Typst, but usually I don't need the additional overhead.

(Btw: The author has a great name!)

Re: Markdown is holding you back

#175

Post by dwaltrip »

> Why semantic markup matters

> ...

> Web developers already went through all this with HTML. Prior to HTML5, you had as a logical container. But HTML5 introduced , , , and many other elements that described the content.

Isn't the semantic web super dead? As in dead, buried, and decorated with countless generations of moss and lichen growing on its gravestone?

---

Edit: Huh, I guess it isn't as dead as I thought!

https://claude.ai/share/b4622d93-2724-4310-9cdd-95c99693a007

Re: Markdown is holding you back

#176

Post by [deleted] »

dwaltrip wrote: post #175

> Why semantic markup matters > ... > Web developers already went through all this with HTML. Prior to HTML5, you had as a logical container. But HTML5 introduced , , , and many other elements that described the content. Isn't the semantic web super dead? As in dead, buried, and decorated with countless generations of moss and lichen growing on its gravestone? --- Edit: Huh, I guess it isn't as dead as I thought! htt…

[deleted]

Re: Markdown is holding you back

#177

Post by adamwong246 »

ctenb wrote: post #147

I'm surprised Pandoc markdown is not mentioned. You can make that semi structured quite easily, and write your own transformations using lua. It's powerful enough to write math papers and export into both pdf and html.

Pandoc is great for resumes too. My static website turns my pandoc resume into pdf and html and they look great

Re: Markdown is holding you back

#178

Post by QQ00 »

zdc1 wrote: post #108
jillesvangurp wrote: post #93

The main point of Markdown is that it has a very important feature that other languages don't have: it's supported in a lot of places. Most of the alternatives mentioned in this thread or in the article are things that require custom tools, that can't be used in most of the places that currently do support markdown. It's common in a lot of places. Even Google Docs has a well hidden feature that allows you to paste ma…

Yeah, I don't see the point of this article: Markdown has already won. I have some clients where I will send docs in MS Word/PDF format, but that kind of proves the point: the recipient sets the format. They may not explicitly say anything, but I'm not going to send something if there's a risk of receiving a "how do I open this?" Also, code blocks are the worst example of it's limitations: just use backticks. Sometim…

What sorts of limitations you have with Obsidian? for diagrams I use Mermaid and it's work flawlessly within Obsidian. For anything fancy, advanced and customized, I use Obsidian Canvas, it's a new feature they released recently. So far, I don't need anything outside Obsidian to do any kind of note taking/writing.

Re: Markdown is holding you back

#179

Post by bccdee »

hysan wrote: post #164
bccdee wrote: post #148

Earlier quoted context omitted.

> I read portable as meaning the format’s semantics are consistent across platforms. By that definition, a format which is only implemented on one platform is 100% consistent. I agree Markdown is uniquely fragmented, but it's also uniquely widespread. Markdown is an extensible core for writing platform-specific languages. I think comparing markdown in general to something like DocBook is comparing apples to oranges.…

> I think comparing markdown in general to something like DocBook is comparing apples to oranges. Hmm let me rephrase the issue I have with the comments in this thread. If your position is that markdown doesn’t belong in the same category as the others, then yeah, I agree. But I also think that’s basically rejecting the premise of the article and there isn’t a discussion to be had. If you disagree with the core premi…

I think you can have the discussion, but you also have to be careful about how you have it. Markdown is a family of languages; if you want to evaluate markdown against something like asciidoc for a particular use case, you have to pick the members of the markdown family which are best-suited for that use case and evaluate those flavours individually.

Take the comparison between markdown and asciidoc. You can't say, "asciidoc has semantic structure and markdown doesn't," because pandoc markdown does have semantic structure. If you need semantics, you can use pandoc markdown, which is a very fully-featured language that suffers from none of the issues the author points out. Yes, other flavours of markdown exist too, but so what? This one has great tooling and suits your needs.

Of course, you can't use pandoc in (e.g.) Reddit comments. But you also don't really need semantic markup in Reddit comments. It's a different flavour of markdown in a different application that is solving a different problem. Or consider MDX: Yes, `Command` is a react component, but maybe it needs to be a react component. Maybe it has a "run this command" button, or it generates an interactive graph of some sort. If you mark that up in asciidoc, you need a whole separate system to attach your components to your markup. That's just using the wrong tool for the job.

Re: Markdown is holding you back

#180

Post by Aaron2222 »

euroderf wrote: post #100
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.

Typst really does look good. Can one get an editor with live PDF preview ? It would be useful mainly for immediate feedback on markup correctness; then an HTML output ought to be "close enough".

Tinymist in VS Code does this out of the box (and looks like it can be set up in other editors). That or you can configure it to save out a new PDF automatically on save or as you edit the document and just open it in a PDF viewer that'll reload when the file changes.
Post reply on HN