Hacker News Reader

Comment by dotdi | Hacker News Reader

When Gruber mentions that he never uses Markdown outside of his blog, and hinting at the fact that it was not intended for text editors (and other apps), there's one important point I want to make.

Yes, Markdown has disadvantages, and a few rough edges for uses as the format for editors et al, but there are two very big advantages and/or sideffects of it's widespread use: (1) it's cleartext and therefore very good as a measure against vendor lock-in and (2) it has, to some extent, dampened the rampant "not-invented-here"-esqe tendency to use proprietary formats. Even in open-source apps, proprietary formats make it hard for non-dev users to get their stuff out. If it's markdown (or at least supports markdown export) from the beginning, at least you know you can take your data with you.

View on HN

Agreed. For me, the popularity of Markdown on (pre-Microsoft) GitHub and GitLab was all I needed, to declare that the company wiki, code-embedded API docs, and anything else appropriate should just use Markdown.

Markdown is good enough for most of the documentation that software engineers do (other than diagrams), they already have to know it, and I don't want yet-another-markup-language to be a barrier to capturing and communicating institutional knowledge.

I also tell people that, if you're new to Markdown, even a plain text approximation that doesn't quite format correctly is strongly encouraged, so long as they capture the info somewhere accessible. I'll even offer to cheerfully fix the missing/bad Markdown, so that we have working docs and people can learn the very few parts of Markdown they missed; it's really not much.

(I personally have heavily used many much-much better technical documentation systems, and helped develop a WYSIWYG-ish SGML-based one professionally, but just using Markdown is a no-brainer right now. There are much more important things I want people learning and doing, than N different ways of minimally formatting documentation in N different places.)

> other than diagrams

Works fine with some help https://mermaid.live/ https://github.blog/developer-skills/github/include-diagrams...

No, mermaid is not fine. You don't have fine control over layout and composition, you can't place your own media and annotations where you like, you can't even use the correct icons for things like databases and cloud services. I usually go into Figma for anything more complex than about 7 entities or if I need to tell a story with composition.

A mix plantuml for constrained no-frills diffable standard diagrams and yEd for actual manual placement and boxes-and-arrows drawing - local editing, both can be scripted to export to an image format - is a good local optimum. I haven't found a much better combination for years.

I agree. I use markdown a lot and was trying to use Mermaid for diagrams in it and it was frustrating. Among the biggest issues I ran into was that text was constantly cut off or covered up.

Is there a reason you specify pre-Microsoft GitHub?

Markdown is like the new WordPerfect for some people, who want expressive written paths to format text.

Like with WordPerfect, there are people who get great utility (attorneys in WP, developers with Markdown), but 80-95% of people don’t get anything out of it.

It’s also one of those things where the constraints are an advantage. Markdown is great for internet facing text content, while many aspects of the mainstream wysiwyg editors are really descended from solutions for placing text on paper.

Former lawyer here. That most commercial contract work is done in Word is a source of major frustration and wasted time for many lawyers. Others are simply unaware that there are any authoring/editing paradigms that allow one to separate the drudgery of getting document formatting just-so, from the actual value-additive work.

Unfortunately there’s no realistic solution to the lock-in, so wrestling with broken paragraph formatting, mismatched text sizes, auto-numbering errors, etc at 2am before a client deadline remains the norm. One of the most frustrating parts of the job.

I never have those issues, but I'm the only one editing my stuff. I use styles religiously when I use Word for professional documents. It takes a little more time and effort but pays out over the long haul.

But very few people do that.

I was on a project and complained heavily that we were not using styles,. The complaints got my manager to state that another person would do all the formatting. Of course the other person left befor the end and I had to do all the formatting.

That’s why. If you use styles and embrace sanity in general, it’s fine. But word is like Perl, there’s more than one way to do it.

Paste additions to the middle of a numbered list from legacy documents that break the number sequence and use custom fonts altar create weird problems? Sure.

Allow sociopaths to format text using a series of invisible text boxes? Sure.

Decide to randomly lose the names of editors and contributors? Sure.

Do you use the comment and change tracking features of Word?

I write stories and everyone uses Word documents for editing.

What's the problem with Word documents if you open them in Word?

Those 80% sometimes DO get something out of it - when the resident nerd can fix their broken document because it’s Markdown or WordPerfect.

Just because I can’t fix my car doesn’t mean I want an unfixable car.

Agreed, but that’s the tension.

There’s no free lunch. On the flip, that user wants the complex features of the platform, and exposing them to a markup language takes elegant markdown and turns it into html or ooxml.

Attorneys and architects loved Word Perfect because it did line numbers better than any other software. I'm really surprised that MS didn't pick up on that and improve Word's line numbering: it's a vital feature for a number of professions.

> Attorneys and architects loved Word Perfect because it did line numbers better than any other software.

Lawyer here: I loved WordPerfect (for DOS) because of Reveal Codes and its easy keystroke macros, which let me write an Emacs keyboard emulator for it. (Yes, I eventually did one for Microsoft Word for Windows, which I use to this day.)

That sounds really cool. Have you ever shared it?

I posted the DOS version on CompuServe (!) probably 30 or 35 years ago. I don't think I ever posted the Word for Windows version. I switched to a MacBook a dozen years ago; I think I remapped some of its keys to emulate Emacs. (But in recent years I've used mostly Emacs itself and org-mode, because these days I'm mostly a law professor and use Word mainly in the occasional client contract-negotiation project.)

idk, a lot of non-devs use chat programs that use (a subset of) Markdown for rich text even if they don't know what that is.

Its the new BBCode.

It's a lot better than BBCode tbh

You can underline in BBCode.

You can have colors in BBCode.

You can embed html inside markdown

But at what price?

very high, usually, equivalent of dagnerouslySetInnerHtml on react if not handled/escaped/sanitized and taking user inputs

Everyone gets something out of markdown, even the 80-95% of document writers that don't get what they want out of it for writing don't have to read as much slop from the others in their group.

It's also great for writing documentation in a plaintext IDE, which I think is what _really_ drove a lot of the adoption.

> which I think is what _really_ drove a lot of the adoption

That GitHub used it as a "native" format everywhere from the beginning (as far as I remember), probably helped Markdown become at least as popular (or maybe even more) as GitHub itself.

Then everyone and their mother started doing static blogs, and since people already wrote their READMEs and issue comments with Markdown, I guess it was natural to want to write your blogposts with Markdown too, just like Gruber.

Don't overlook Reddit as a major reason for many otherwise-non-technical people to learn Markdown.

And Discord as well. Every young person is on Discord, they're all learning some Markdown

Teams and Slack as well, though they use an odd variant markdown (where single asterisk indicates bold instead of italics).

What things like Slack and WhatsApp use are not variants of Markdown, but entirely unrelated lightweight markup languages <https://en.m.wikipedia.org/wiki/Lightweight_markup_language>.

As for Teams, it looks like it’s much closer to Markdown (uses the same idiosyncratic/stupid link syntax), but still significantly incompatible even if they call it that. And my guess (as a non-user) is that it’s just an input method immediately converted to HTML or similar, not retained as text. So in that way it’s not Markdown either.

My least favorite Teams markdown idiosyncrasy is using (foobar) for emoji search instead of :foobar:

Technically speaking, Slack's markup language is mrkdwn.

That’s not technically, that’s marketingly (sure, it was presumably developers that named it, but it’s still marketing). mrkdwn is a horribly misleading name and they should feel guilty. https://hn.algolia.com/?query=chrismorgan+mrkdwn&type=commen...

I get bold and italic confused because Google Chat is almost-Markdown except for * being bold and _ being italic (whereas it's double vs singular in classic Markdown).

Teams does not use Markdown AFAIK. I wish it did.

See https://support.microsoft.com/en-us/office/use-markdown-form...

My company is on Teams and I regularly use Markdown in my messages, though I still struggle to remember that I have to use underscores not asterisks for italics.

It is funny to occasionally see it explained like 'on Reddit you can use ...' and think '..dude, markdown, just tell them you can use markdown' (and then realise oh right yeah ok, your way is probably clearer to them and you probably don't know it as 'markdown' either).

Reddit's Markdown flavor is a bit weird though. It got closer to CommonMark with New Reddit, but the rest of the UI got worse, and people using Old Reddit don't get the formatting the new version supports, so things like code blocks are often broken.

Original Markdown didn’t have fenced code blocks either.

Yes, Old Reddit Markdown is much closer to original Markdown than to CommonMark. New Reddit Markdown is closer to CommonMark.

> Then everyone and their mother started doing static blogs

It helps that Jekyll, one such static blog, was also pushed by GitHub back in the day.

Was Jekyll ever that popular though?

I can’t provide usage numbers, but it used to be the happy path for using GitHub Pages. I suppose static site generation was fairly niche so “popular” may not be the right word. I think Jekyll was a big fish in a little pond, however.

It certainly populated the "Mark Town to static HTML" blogging approach and created the room for its successors.

It's simple but has good enough capabilities and it's available in a universal format (plain text) that will never expire or get sold or become inaccessible

Another nice thing about markdown is that you can pick up the formatting even if reading the markdown in plaintext.

So lists look exactly how you would expect lists to look like if you were writing it on a piece of paper.

Italic/Bolds are surrounded by /* which convey emphasis even in plaintext.

Headings prefixed by # is a reasonable way to depict headings in plaintext and convey the intention immediately even if you don't know Markdown.

Many formats these days are cleartext. Microsoft Office documents and LibreOffice documents, to name two collections of formats, are both xml based. Not to mention HTML, Latex - the list is long. Markdown is fine but overused, to the point where even the creator is now warning it’s not for everything.

Markdown was here before the other (currently) big formats and will be here after them. It's not perfect, but at least I don't need to worry about it disappearing on me like every other piece of tech and software I own.

> (1) it's cleartext and therefore very good as a measure against vendor lock-in and (2) it has, to some extent, dampened the rampant "not-invented-here"-esqe tendency to use proprietary formats.

Also covered by AsciiDoc.

"Compare AsciiDoc and Markdown": https://news.ycombinator.com/item?id=27744509

I love the relative simplicity of core markdown with if I need to get fancy to add some html (which is rare) and it works so well in programs like Joplin, rather than fighting weird formatting in programs like OneNote and EverNote

1. That's solved via readily available exports, so no need to pay the markup price 2. Same thing + other open formats exist

Reply on news.ycombinator.com