Live data from Hacker News

Thoughts on Markdown

smashingmagazine.com

11–20 of 167 posts

Re: Thoughts on Markdown

#11
post #2

Those who do not understand history are doomed to repeat it. In the beginning, there was HTML, and it was good. Then "modern content creators" did not "want to learn syntax", created "tools that edited and rendered HTML differently and inconsistently", added hundreds of unnecessary tags in it, then started to get smart about "semantic information" and introduced HTML-5-style tags like , which too few people use... Te…

The ideas behind Markdown are much older than HTML5 and all those tags you talk about.

Wikipedia with its MediaWiki syntax is from 2001, ReStructuredText is from 2002, Markdown from 2004, HTML5 from 2008. And I am sure you can find way older formats which Wikipedia and ReST used as inspiration.

Re: Thoughts on Markdown

#12
post #2

Those who do not understand history are doomed to repeat it. In the beginning, there was HTML, and it was good. Then "modern content creators" did not "want to learn syntax", created "tools that edited and rendered HTML differently and inconsistently", added hundreds of unnecessary tags in it, then started to get smart about "semantic information" and introduced HTML-5-style tags like , which too few people use... Te…

As someone who regularily writes HTML manually, there are distinct advantages of markdown over html:

* The most common use case (paragraphs of text) needs no boilerplate or magical syntax

* A typical Readme can still be easily read and understood without markdown rendering (e.g. a # Heading is still understood as a Heading, and a _emphasized_ text is still understood as being emphasized, even by the uninitiated.

* Writing markdown can be faster than both HTML or a WYSIWYG-editor, because the syntax is minimal

HTML is certainly more powerful, but sometimes you just want to chug out some text quickly and this is where markdown (IMO) shines

Re: Thoughts on Markdown

#13
As a developer that really likes to document stuff I don't like markdown. It's limited and as the article states too fragmented. I started using AsciiDoc a while back. It's like markdown but with more advanced options for true documentation stuff like charts, tables (formatted!), diagrams and more.

Re: Thoughts on Markdown

#14
post #2

Those who do not understand history are doomed to repeat it. In the beginning, there was HTML, and it was good. Then "modern content creators" did not "want to learn syntax", created "tools that edited and rendered HTML differently and inconsistently", added hundreds of unnecessary tags in it, then started to get smart about "semantic information" and introduced HTML-5-style tags like , which too few people use... Te…

Those who do not understand history are doomed to repeat it ;)

In the beginning, there were tens of text processors with rich text encoding syntaxes (troff, TeX, IBM pre-GML, DEC stuff, WordPerfect, etc.) Then came SGML with customizable meta syntax and vocabulary to unify those. A large part of HTML is actually contained in ISO 8879, as "folklore" elements

, -, and so on. Then came HTML as an SGML application, and later XML as an SGML subset. Then people forgot the aspects of SGML not in XML, and invented ad-hoc syntax such as Markdown and MediaWiki syntax (both of which can be partly represented as SGML SHORTREF syntax), and Ian Hickson (WHATWG) started to specify HTML parsing rules in an informal ad-hoc way, based on the tag omission/inference rules of W3C's HTML4, and what was called "real-world" HTML (nevertheless also inventing new elements , , ). Then, due to presentation as prose and mere enumeration of element names, the basic construction of HTML as a formal DTD grammar was lost, and WHATWG added elements and rules nilly-willy, without being informed by a DTD grammar or other formal mechanism to ensure parse-ability.

Re: Thoughts on Markdown

#16
post #8

I've said it so many times my throat is sore but here goes again... As with literally everything, it depends. Markdown is lovely for tech documentation, notes and journaling. It's simple and beautiful and mostly independent of layout. Want to author something rich and expressive which has a modern web audience in front of it (either end user or editor) and it's probably not the right tool. I work with large numbers o…

Yes, and:

For personal notes, I find Gemtext even better than Markdown, because it's even simpler.

=> https://web.archive.org/web/20220124235538/https://gemini.ci... Gemtext

I spend less time trying to remember syntax or decide on which syntax option to use, because there is so little syntax. It feels like writing plain text with just a handful of conventions.

Re: Thoughts on Markdown

#17
The discussion reminds me a little of the one around LaTeX in the scientific community. Latex is extremely powerful but reading the raw source of a text is a pain. WISYWIG is just so much more comfortable when writing, but MS Word sucks in its own specific and manifold ways (as does LibreOffice).

HTML is still not nice to read, too much boilerplate tags required. Markdown source however is mostly well-readable in a plain-text editor, and offers the basic formatting that serves 95% of the needs.

But the truth is: the ideal text layout platform for scientific writing does not exist.

Markdown+HTML+CSS could be getting close, but it currently still lacks LaTeX's tooling for citations, support for pagination.

MS Word's "track changes" is extremely useful when collaboratively editing (and no, Overleaf's version doesn't come close, unfortunately). But references and citations in Word still are no match for the flexibility of bibtex, even with Papers/Zotero/Mendeley. Figure placing can be a nightmare, although LaTeX is not infallible, either. And you need a Mac or Windows to use Word, and on a Mac it feels like it's running in an emulator.

I have given up on the belief that one tool could solve all this. There are a few good attempts like overleaf and the less-known authorea (which I liked more), but these are cloud apps which complicates writing offline.

The only solution is to choose whatever tool works for the specific use case, learn to live with its shortcomings, and never forget that in the end only the finished manuscript counts.

Re: Thoughts on Markdown

#18

As a developer that really likes to document stuff I don't like markdown. It's limited and as the article states too fragmented. I started using AsciiDoc a while back. It's like markdown but with more advanced options for true documentation stuff like charts, tables (formatted!), diagrams and more.

I share the same opinion. Its limit make it useful only for a very small set of use cases.

It's being used a lot for code documentation, but MD is bad fit for documentation. Good documentation requires a lot more formatting and cross-referencing than you'd think. Every language I'm using that has been using MD (for embedded and online docs) added extensions, resulting in more fragmentation.

So in general I switch between 3-4 differently-flavoured markdowns constantly. The extended syntax used by various projects sucks. Where did the simplicity of MD go? It reads poorly when unformatted, which is how I read it 99.9% of the time.

I gravitate more towards RST as it's a bit more widely used, but also agree about AsciiDoc.

Re: Thoughts on Markdown

#19
If this is just a container format for storage / transformation - as I understand the author promote front-end editing tools hiding the storage format, then they just try to reinvent structured text… sgml, xml and all their tools, schema description…

Re: Thoughts on Markdown

#20
KeenWrite[1] is my text editor that takes a slightly different approach than MDX. Rather than include variable definitions within documents, variables are defined in an external file[2]. I find that when variables are embedded into documents, those variables often include controls for presentation logic. To me, any presentation logic meant to affect a plain text document's presentation does not belong in the document itself. Part 8 of my Typesetting Markdown series shows the power of separating content from presentation by leveraging pandoc's annotation syntax[3].

Annotated Markdown is sufficiently powerful to produce a wide variety of different styles. Here are a few such documents typeset using ConTeXt[5]:

* https://dave.autonoma.ca/blog/2020/04/28/typesetting-markdow...

* https://dave.autonoma.ca/blog/2020/04/28/typesetting-markdow...

* https://impacts.to/downloads/lowres/impacts.pdf

* https://github.com/DaveJarvis/keenwrite/blob/master/docs/scr...

What's bothersome is how some companies are setting de facto Markdown standards without considering the greater ecosystem. GitHub has done this by introducing the "``` mermaid" syntax, which creates some problems[6].

[1]: https://github.com/DaveJarvis/keenwrite

[2]: https://www.youtube.com/watch?v=u_dFd6UhdV8&t=18s (renamed afterwards)

[3]: https://dave.autonoma.ca/blog/2020/04/28/typesetting-markdow...

[4]: https://dave.autonoma.ca/blog/2020/04/28/typesetting-markdow...

[5]: https://wiki.contextgarden.net/Installation

[6]: https://news.ycombinator.com/item?id=30337894

Post reply on HN