10 ms·
Thoughts on Markdown
- DocTomoe 5y agoThose 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 <article>, which too few people use... Techies felt that all to be unworkable and did a new thing. They remembered text files being good, and started to call a very minimal syntax "Markdown", with a common core large enough to be almost universally understood. And now we have this article again, which reads a lot like it was about HTML, ca. 1995.
- smugglerFlynn 5y agoI, for one, welcome our new semantic overlords
- WalterBright 5y agoIn the beginning, was runoff. At least runoff was around on DEC machines in 1975. I wrote a couple term papers with it, Markdown is hardly different.
- unfocussed_mike 5y agoI once typeset an Occam assignment paper in groff, for kicks.
- red_trumpet 5y ago> Those who do not understand history are doomed to repeat it. HTML5 was introduced in 2008, whereas Markdown was published in 2004.
- deleted 5y ago[deleted]
- jeltz 5y agoThe 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.
- webmaven 5y agoYou missed ASCIIDoc[0] (2002) from your chosen timeframe, but also some much older Lightweight Markup Languages[1] like setext[2] from 1992. [0] https://en.m.wikipedia.org/wiki/AsciiDoc https://en.m.wikipedia.org/wiki/AsciiDoc [1] https://en.m.wikipedia.org/wiki/Lightweight_markup_language https://en.m.wikipedia.org/wiki/Lightweight_markup_language [2] https://en.m.wikipedia.org/wiki/Setext https://en.m.wikipedia.org/wiki/Setext
- atoav 5y agoAs 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
- tannhaeuser 5y agoThose 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 <p>, <h1>-<h2>, 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 <main>, <article>, <aside>). 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.
- eadmund 5y ago> In the beginning, there was HTML, and it was good. No, it's really not. It is excessively verbose for human usage, and too loose for computer usage. It's a hack. For human usage, Markdown is pretty decent. For computer usage, an S-expression–based HTML would have been preferable: (html (head (title "Hello world!") (meta ((http-equiv content-type) (content text/html) (charset utf-8)))) (body ((bgcolor white)) (h1 "Hello world!") (p "This is my first webpage.")))
- open-source-ux 5y agoI agree with a lot in this article. I too have seen 'non-technical' users struggle with Markdown. The popularity of Markdown among developers also reminds me about SSGs (Static Site Generators). Two technologies loved by developers - and no-one else. "For limited use cases, like blog posts of simple rich text with images and links, markdown will get the job done." I'd argue it's even less suitable than that. Developers never look beyond Markdown when writing documentation or articles and are thus blissly unaware of the much richer writing possibilties of using HTML (which is simple to learn, unlike CSS). Full HTML also gives readers a much better reading experience. In Markdown, even a simple image caption is not possible.
- ihateolives 5y ago> Developers never look beyond Markdown when writing documentation or articles and are thus blissly unaware of the much richer writing possibilties of using HTML (which is simple to learn, unlike CSS). HTML is wolf in sheep's clothing though. It's deceptively simple to learn the basics, but the nested nature of it is something that will allow one to shoot their semantical or representational foot off, even before trying to apply CSS. Take, for example, humble P tag. The thing that trips up most people, for example, is that ideally you'd need to contain text blocks in paragraphs, not just have it free floating in the document. In theory. P tag is simple. Except that end tag is optional. When writing HTML, that is. But not always, as per standard: "A P element's end tag can be omitted if the p element is immediately followed by an address, article, aside, blockquote, details, div, dl, fieldset, figcaption, figure, footer, form, h1, h2, h3, h4, h5, h6, header, hgroup, hr, main, menu, nav, ol, p, pre, section, table, or ul element, or if there is no more content in the parent element and the parent element is an HTML element that is not an a, audio, del, ins, map, noscript, or video element, or an autonomous custom element." But in XHTML end tag is always required. And you shouldn't have block level elements like images within P. And you can't nest them. When outputting DIV with a block of text that DIV should contain a P, not just text. DIV's are cool, you can nest DIVs. And they need end tag. Simple? Well: "Authors are strongly encouraged to view the div element as an element of last resort, for when no other element is suitable. Use of more appropriate elements instead of the div element leads to better accessibility for readers and easier maintainability for authors." But who does that nowadays? It's DIVs all the way down usually. So no, HTML is not simple. https://html.spec.whatwg.org/ https://html.spec.whatwg.org/
- dmje 5y agoI'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 of - let me call them "creative editors and authors". They want to embed video, pullquotes, tables, interactives. They want to float images, include audio and much more. Markdown is not for them. Something block based and visual, namely Gutenberg or similar - is. As ever (voice grows increasingly hoarse...) it's dependent on needs.
- deleted 5y ago[deleted]
- grey_earthling 5y agoYes, and: For personal notes, I find Gemtext even better than Markdown, because it's even simpler. => https://web.archive.org/web/20220124235538/https://gemini.circumlunar.space/docs/gemtext.gmi 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.
- masklinn 5y ago> Markdown is lovely for tech documentation That’s one of the weakest points of Markdown, because it has no support for any sort of cross-referencing so they have to be maintained by hand or through bespoke extension (often conflicting).
- BiteCode_dev 5y agoMySt and sphinx are getting attentions these days. As a ascii doc lurker, and fed up of rst, I'm very hopeful.
- rk06 5y ago
- taubek 5y agoI like markdown. At the moment it is somewhat like HTML without CSS. Great for structuring documents. Not so good when it comes to formatting. There are extensions to it, but I like clean flavor.
- ivolimmen 5y agoAs 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.
- wakeupcall 5y agoI 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.
- fjorde 5y agoI agree with both these points. Inter-document references are bad in markdown and wiki style formats. Wikipedia is replete with overlapping and contradictory information that should be pulled from a single source. Do you have any ideas re link-rot, or underlying assets changing and semantic links becoming invalid? How do you reference a code asset whose name could change, what will not only replace all references in the code but also in the documentation?
- wakeupcall 5y agoCross-reference checking is a huge problem on it's own, almost unrelated to the formatting being used. Some language tooling do provide cross-ref checking, generally as an extra step part of the documentation generation process. I don't have anything to add to the table compared to what we do already...
- 5y ago
- jokoon 5y agoI wish libreoffice would have some sort of editor to edit a document using markdown.
- periheli0n 5y agoThe 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.
- deleted 5y ago[deleted]
- cprecioso 5y agoUsing Markdown with pandoc and pandoc-crossref is basically perfect as a substitute of LaTeX. It allows in-line and standalone LaTeX, and citations with crossref.
- jonathanstrange 5y agoIn my experience this has zero advantage over LaTeX since converting your markdown to formats other than LaTeX will be just as hard as converting from a LaTeX source. It's even harder because you have to deal with an eclectic mix of LaTeX and markdown, and various errors and restrictions in pandoc.
- lpointal 5y agoIf 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…
- thangalin 5y agoKeenWrite[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-markdown-part-8/images/fire-and-ice.png https://dave.autonoma.ca/blog/2020/04/28/typesetting-markdow... * https://dave.autonoma.ca/blog/2020/04/28/typesetting-markdown-part-8/jekyll-hyde.pdf https://dave.autonoma.ca/blog/2020/04/28/typesetting-markdow... * https://impacts.to/downloads/lowres/impacts.pdf https://impacts.to/downloads/lowres/impacts.pdf * https://github.com/DaveJarvis/keenwrite/blob/master/docs/screenshots.md 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 https://github.com/DaveJarvis/keenwrite [2]: https://www.youtube.com/watch?v=u_dFd6UhdV8&t=18s https://www.youtube.com/watch?v=u_dFd6UhdV8&t=18s (renamed afterwards) [3]: https://dave.autonoma.ca/blog/2020/04/28/typesetting-markdown-part-8/#annotations https://dave.autonoma.ca/blog/2020/04/28/typesetting-markdow... [4]: https://dave.autonoma.ca/blog/2020/04/28/typesetting-markdown-part-8/jekyll-hyde.pdf https://dave.autonoma.ca/blog/2020/04/28/typesetting-markdow... [5]: https://wiki.contextgarden.net/Installation https://wiki.contextgarden.net/Installation [6]: https://news.ycombinator.com/item?id=30337894 https://news.ycombinator.com/item?id=30337894
- tonetheman 5y agoWhat you have done is really interesting. You might need to do more smaller chunks of how to use it though. I watched part of the video and I understood the substitution but the next part just went over my head. Maybe it is like a double pointer. Anyway your editor and your idea is super interesting. Just needs some explanation. Maybe you have already done that somewhere?
- fjorde 5y agoFirst, many thanks to the author for a reasoned and researched post. The editing/mass-adoption sides of the text formatting story vis-a-vis markdown were well told. I think the story of text is important and misunderstood and evaluation brings better understanding. So please take the rest of this as a supplement more than an argument, even if a lot of it is a disagreement about the value and future of markdown and where its utility does and could exist. I'm not partial to markdown or any flavor of markdown or any other plaintext schema. I appreciate org mode and almost every variety of "readable semantic text". These are all reasonable efforts that provide actual value to practitioners and neophytes alike. There are reasons why a tiny fractional percentage of the world uses org-mode. There are reasons why orders of magnitudes more people have come across markdown, to the point where today the overlap with HTML developers is almost, but obviously not fully, complete. On top of the HTML aware writer population, cms's have propagated a lot of incompatible and often poorly implemented "wysiwyg-md" textareas that have often leave a lot of room for improvement, but still introduce the idea of semantic text, or even store that as html/markdown. In all these ways, markdown has been a bridge between the .txt and the .html for many people. It was always a simplification and an added complexity in that regard, and its sole points of reference were txt and HTML, so digital/web-oriented. That said, HTML semantics differ from .doc(x) semantics primarily in philosophy and ergonomics. In HTML there is <h1>, which has rules and specifications about it. In a .docx document there is no such "understood hierarchy" philosophically speaking. This represents a major structural advantage from a user and machine standpoint that I believe is the single most important advancement represented by markdown. The ability to render an automatic table of contents based on hash-tags or gather/conform citations and references programatically, has _never_ been a selling point of word or any other editor until recently when markdown starting making this type of feature obvious. People will point out word-based variations on "auto-table-of-contents" but please find me one single school in America or anywhere that teaches students to write the "html/md" way by default, in terms of organization or structure. I believe the primary reason they don't is because MSword is a free-form typesetting machine, and not an editor's tool and not a research tool. I was in academic research and talked to dozens of professors publishing in every domain. None of them had a one-click answer to "this journal rejected me; I need to reformat for another journal". That was always done by hand, by every single academic I've ever met, including in maths and sciences and cs disciplines. At best they're using a latex document, but those are way too heavy for non-maths disciplines, and often people aren't or can't make full use of the features it has to offer and end up reformatting latex for various publications. > If you think about it, do you own your content less if it’s hosted in a database? ... And is it fair to say that proprietary database technology impinges on the portability of your content? ... > But anyone who has tried to move out of a mature WordPress install knows how little this helps if you’re trying to get away from WordPress. The author addresses a critical aspect of the markdown document but avoids discussing the implications. Text in MSword is hard to get back out.[^1] Data recovery and searchability is critical. But even "pure html" is locked in a lot of un-indexable un-searchable code. markdown, on the other hand, makes grep, or any indexer-search tool trivial to implement and use. Imagine any company on earth having five-thousand blog posts worth of content. At the end of the day what is the only format that can be guaranteed "readable" in 5-10-20 years time, when some internal analyst wants to find out what people have been posting? Is it easier for the analyst to spin up a wordpress install from 20?? or read through plaintext files that can be searched any number of ways instantly from a kindle reader? Content lock-in is only one side of the equation. What are you doing with all that content? What is its value? Are you deriving real value from all the content you are creating? Is that value-creation easier or harder because its in txt or sql? These answers depend on who you hire and what you're trying to do. Mostly txt people have questions and sql people help them find answers, but sql people don't always know what questions to ask. So anyways, txt people need text to formulate questions for sql people to run. But neither of them can do anything with docx. Which is why markdown is loose lingua-franca for the developer world, and it always had to start this way and be this way and pretending like markdown could ever exist for a txt market without a million developer tools and programs is a joke, but nvm. So anyways, markdown required fundamentally a huge buy-in from the dev community and it was well positioned to do so given its html inheritance, regardless of what latecomers to this domain say in public. Now that there are tools that do a reasonable job translating markdown to pdf, docx, etc, the reality is that for most academics, markdown should represent a huge shift in writing, from a mostly formatting based experience, to a type-and-print model. The same exact .md file should be able to be used to generate the properly formatted and annotated text for any journal publication. This is still a dream mostly, but it could save researchers thousands of hours over the course of their careers. When considered together with enhanced searchability and citability, something like markdown or a "correctly" structured txt document would provide a lot of cognitive "unload". Anyways, the market is ripe for replacing word, there are hundreds of great text editing products in all the markets and people are piecing together writing systems that make sense for them. It never made sense for academics and students and business people to be typesetters, because that's a professional's job and requires mostly a designer's eye. People want to put important information in a retrievable format and get it back when they need it. pretty-printing for the teacher was always a dumb exercise in scholastic obeisance, but markdown makes a readable document almost by default. [^1] A <title> tag is easy to use for a title of a document when searching, indexing, scanning, aggregating, etc. But Word defaults you to the filename.docx, which usually ends in DRAFT-FIANL(2001-232-23-).docx What is the title of word document? HTML has <title> and <h1> but each has a specification, and websites are free to conform to those.e
- silvestrov 5y agoOne feature request from business that caught me by surprise when recently implementing an editing page was that it should discard all font styling when pasting from Word. That is the #1 feature missing from all rich text editors: ability to restrict allowed formatting. No user specified fonts, no user specified font-size (all headings must be paragraph style), all lists must use standard style, etc... This is where Markdown/CommonMark shines: no hidden formatting that is difficult to get rid of. The real problem with Markdown is it lackluster support for tables and support for site-specific macros.
- coffeeling 5y agoIt also doesn't respect single line breaks and is rather limited/opinionated about lists and indentation in general.
- jillesvangurp 5y agoMarkdown is merely the lowest common denominator of what is essentially a jungle of weird and wonderful wiki languages. The reason it is so under-specified is that it emerged out of the Ruby community in a time where the whole point of Ruby was that it was a scripting language without a lot of appreciation for things like types or specifications. The first serious attempts to unit test and specify ruby itself actually came out of the JRuby community. Which had an obvious need to cover all the complicated stuff that Ruby did so they could handle all the edge cases in the same way. You see the same with other scripting languages where the obsession with specifying what things like Javascript or Python actually do came later in the life of the languages. I think the main reason for the popularity of Markdown is that is minimal, forgiving, and uses things that are kind of intuitive for basic formatting. * for bold, - for bullets, etc. Similar compatibility issues between various implementations exist for things like Json, Yaml, HTML, etc. Some of these things even have IETF or W3C specifications nowadays. The specifications usually come after things get popular; rarely before. Whatever the ruby markdown library did was the specified behavior of Markdown for some time. And then of course it caught on and several alternate implementations emerged for different languages; each with their own features added or interpretations of features. Then Github adopted it, added a few features they needed and then it went mainstream in a big way by virtue of world+dog using Github. At this point Markdown is collection of features that may or may not work depending on which library and language you use; or even where you use it. The simple stuff works everywhere. But your mileage may vary with some of the more advanced stuff like tables for example. Mostly, the Github dialect seems dominant for the simple reason that that is a popular place to find a lot of markdown content. The problem with alternatives is that they are comparatively less widely used and therefore a bit more obscure. You need good library support across multiple language ecosystems and a lot of the alternatives simply don't have that or enough of a community of users that care enough to fix that. People have their favorites but they can't seem to agree on a single one. So, Markdown it is for most of us. I'm not even sure that is a bad thing. I kind of like it, actually. It's good enough for my needs. I use pandoc to convert markdown files to html for my website. It supports enough of the Github dialect that I don't have to obsess over what it supports or doesn't support too much. I'm unlikely to convert my content to another format at this point. I use it without thinking in Github issues, in readme's, etc.
- Falkon1313 5y ago>That’s almost 20 years ago — yikes! What started as a more writer- and reader-friendly syntax for HTML The author appears to have some recency bias that misses the point of Markdown. It didn't start when it was named and mapped to HTML. It was in use on usenet and in emails before HTML even existed. And most of its conventions came from typewriters before that. You could print out a Markdown document today and jump in a time machine to 1970 and hand it to someone and they'd understand it. Chances are they still will in 2070. In the meantime we've had countless proprietary binary word processor formats that couldn't be read before their program was released and most of which can't be read today. We've had bad attempts to replicate print publishing designs and unusable Flash websites. We've had a variety of markup formats including HTML, XML, etc. which are relatively a pain to read or write. We've had lousy WYSIWYG editors that never work correctly. And we've stored the documents split into chunks in databases. And now the suggestion is to write text as JSON data structures? All that stuff has its place, but none of it has the timelessness and clarity of plain text and markdown when it comes to documents. It's not particularly good for structured data. Nor multimedia (though you can reference it with links). But it's still quite good at what it is good at. Has been since before HTML and will be long into the future.
- unfocussed_mike 5y ago> We've had a variety of markup formats including HTML, XML, etc. which are relatively a pain to read or write. Right, but Markdown relies on HTML (or whatever other markup it is pre-procesing) for anything difficult. I like Markdown[0] but surely our job as technologists is to find better solutions than a system that requires you to escape asterisks in certain situations, or rely on a preview pane to work out what it will do. [0] but YAML front matter should burn in the fire
- simias 5y agoI would argue that it may be a case of "less is more". Yes Markdown is limited, but the limits make the language trivial to learn, modify and understand. It also means that the format can be trivially displayed almost anywhere and converted to all sorts of other formats. There will always be a tradeoff between simplicity and the feature set, I find that for the vast majority of my use cases Markdown is simply good enough. When I read markdown docs on github I usually get a pleasant sense of familiarity, everybody tends to gravitate towards the same basic layout because that's what Markdown does. That's a feature IMO, it means that you can focus on the content, not waste time parsing the quirky layout. Monthly reminder that Gopher should've won btw.
- fjorde 5y agoappreciate a lot of the points made in the post but ``` distinct( *["code" in body[]._type] .body[_type == "code"] .language ) ``` is "trivial" for no human being
- andrewingram 5y agoYour content editors would never write that. But if they asked for a feature where you can filter content by programming languages, GROQ would allow your engineers to build it very quickly. I think it was probably a mistake for the article to go into GROQ, but the essence of the point is that content as structured data means content is queryable.
- fjorde 5y agogrep -rE '```\w+' |uniq seems like the same query across text files to me. it's not "trivial" but at least grep has a man page and people have used it reliably for decades now. Spinning up whatever it takes to get groq going is not the same thing as having widely available tools that just work. Somehow structuring content in json is a new idea? There are a lot of html to json parsers out there already. jq and grep can do everything his post suggests and require no less or more investment from a dev perspective.
- atombender 5y agoCorrect me if I'm wrong — my use of Jq is limited to basic shell stuff — but I believe Jq does not have joins at all. You can do joining by writing your own functions, but it's not built into the syntax. GROQ was designed to query and join multiple sources of data, and to make it easy to plan for efficient execution (e.g. on top of a relational database or search engine). For example: *[_type == "author"] { _id, name, "books": *[_type == "book" && author == ^._id] { title, year, publisher-> // Join referenced publisher genres[]-> // and all the genres ] } This gives you all the authors with each author's books. You can do a lot of the same transformations that Jq does, but you can also do it across multiple collections of data; it's not a pipeline with an implicit input. (Disclosure: I work at Sanity.)
- filmgirlcw 5y agoI find this article to be sort of ridiculous. Sure, some of the critiques about the various flavors of Markdown might be valid (but I would posit that for the non-technical users the author claims to be so concerned about, the chances of them regularly having to interact with more than one flavor (and no, Slack and Reddit don’t count), is extremely low), but the whole piece seems to be an advertisement for the author's company's JSON-based rich text specification, which couldn’t be further away from the point of Markdown if it tried. Markdown is for writers. The fact that it has been adapted and forked and flavored into something that many developers like is wonderful. But it is fundamentally for writers. And I’ve taught dozens, if not hundredS, of “normies” to use Markdown when writing for the web over the last 15 years. Some of them have hated it — which is totally fine - but many more have appreciated being able to write readable content for the web without having to do it in the CMS, which is always, always, always, a flat-out terrible idea. Or the other alternative, which is write in Google Docs or Word or Notion or whatever and then paste it into the CMS for the hell that will ensue. There is a certain irony in the author claiming to want to make a better authoring system for users, but only in a way that adds complexity, requires developers to build UIs around its spec, and has benefits that really only appeal to the people building the CMS or trying to sell people on why their version of TinyMCE is best (oh, but you have to build the TinyMCE UI yourself…this is just another overly-complicated JSON spec that really is provably only suited by whatever it is Sanity is trying to hawk). Markdown isn’t perfect. And it doesn’t claim to be. But in terms of being a readable and easily usable way to write content for the web, it’s pretty damn great.
- kmelve 5y agoThe author here! I'm kinda bummbed out that the post read as an ad. I was super nervous to publish this because it I knew I was poking at something that's near and dear to a lot of devs (myself included). But I have experienced enough friction with Markdown in the real world and wanted to explore poking what I see as the status quo. And it seems to have sparked some conversation, which was what I wanted. I'm truly not trying to “hawk” something, but I believe the thinking that went into Portable Text can provide value and I'm sort of putting it out there for people to make up their own minds. To your point: I agree, Markdown is for writers, but only for some writers. Maybe I didn't get that across, but it is kinda amazing that it has become so ubiquotos in all its shapes and colors. But it comes with these actual constrains and challenges that I feel a lot of developers aren't really being upfront or honest about. The simplicity comes with trade-offs that just adds complexity elsewhere. Either for people who don't desire to learn specialized syntax or developers who have to spend a lot of time figuring out how to parse it in a sensible manner to get their job done.
- john-doe 5y ago> If Not Markdown, Then What? Textile!
- mukundesh 5y agoGitHub is doubling down on Markdown https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/ https://github.blog/2022-02-14-include-diagrams-markdown-fil... https://github.blog/changelog/2022-01-21-allow-to-upload-svg-files-to-markdown/ https://github.blog/changelog/2022-01-21-allow-to-upload-svg... Long live Markdown !!
- jdvh 5y agoWe have a binary and universal format for plain text (utf8) that is extended all the time with additional emojis. But it seems almost unimaginable that we ever get a binary text format that also allows simple semantic markup, like emphasis, tables, hyperlinks, amounts, dates, and phone numbers. It's 2022, and really, we should be able to copy a paragraph from an email with a table in it into a chat app and have it just work. HTML is way too complex to use as data communication format between apps (vulnerabilities; every app allows a different subset). Markdown is made for humans to read/write, when what we need is a simple unambiguous binary format that is easy to parse. We can have compound emojis where a polar bear is a bear + a snowflake joined by a zero-width joiner. But a datetime or number in text is too much to ask?
- seletz 5y agoWell, that really seems to be a very hard problem to me. Tables for instance get quite complex pretty fast -- joined cells, text alignment, etc. As for a format which -- not plain text, though -- that handles this is rich text. It's been around for quite some time. IMHO the problem is in the difference between presentation and data. One group of consumers want the "data" and parse it, the other group of consumers want to basically have it "look the same in this app as in the other app, and don't make my think."
- jdvh 5y agoTables can be arbitrarily complex, just like html, so yes a line has to be drawn somewhere. Spreadsheets and slide presentations can be copy-pasted as file attachments. That's fine. You can't have a table look the same in every app, nor is that desirable (you'd have to embed fonts and re-create postscript). What you can have is the ability to copy-paste a table (or a bulleted list) back and forth between apps without mangling the state in the process. Rich Text intertwines semantics and style and it's not a good solution. Most of the time you don't need the layout precision of postscript. There is a huge difference between not having any kind of tables or semantic context for text and having some that cover the 95% of daily use.
- deleted 5y ago[deleted]
- cromulent 5y agoDiscussion from the launch of Standard Markdown / CommonMark: https://news.ycombinator.com/item?id=8264733 https://news.ycombinator.com/item?id=8264733
- cryptos 5y agoI'm wondering that the article doesn't mention AsciiDoc with a single word. AsciiDoc is a perfect tool for complex text documents with tables, references, side notes etc. It is almost as easy as Markdown (if you compare only the features included in both), but offers way more possibilities. There are also good tools to convert it to different output formats like HTML and PDF. A good starting point is: https://asciidoctor.org/ https://asciidoctor.org/
- llimllib 5y agoOne minor note: jekyll definitely was not first to introduce front matter (though they may have introduced yaml front matter?). I am sure that at least pyblosxom had it earlier: https://pyblosxom.github.io/Documentation/1.5/writing_entries.html#metadata https://pyblosxom.github.io/Documentation/1.5/writing_entrie... Here's the earliest surviving commit showing blog entry front matter in 2002: https://github.com/pyblosxom/pyblosxom/blob/f80cdb42eb37ee0e7d4e7776f206e519b7452d99/libs/pyblosxom.py#L178 https://github.com/pyblosxom/pyblosxom/blob/f80cdb42eb37ee0e... My recollection is that blosxom (a perl blogging engine) had front matter as well, but I can't find any evidence of it.
- kmelve 5y agoThe author here! Thanks for these links! I tried to track the origin down, but there's only so much digging one could do. But I think it safe to say that Jekyll _popularlized_ the YAML-style frontmatter.
- xlii 5y agoI think author misses the point completely. Markdown is for writing not for editing. If you want to focus on writing, text, and content instead of on bells and whistles with formatting and typesetting it's really hard to go easier than Markdown. Sure, Markdown is overused. Probably one shouldn't use it for heavily linked content, where one has to show examples, cross-link, check references, verify the sources etc. and on top of it follow very strict line/page breaking and paragraph rules. But it's not a huge issue, because if the end result is plain text itself one can easily work with pipeline. Text can be easily split, mixed and matched. One can figure out their own content and script it easily assuming they are wanting and tech savvy enough. Working with text first and then transforming it to LaTeX once the writing process is done is easy. Then you can make semantic adjustments and decide to either output as PDF, process in complex pipeline or plug-in one of the hundreds of solutions that exist today. It might hold back "editorial" experience but it definitely enables "authoring" experience.
- kmelve 5y agoThe author here! Markdown is for writing not for editing. If you want to focus on writing, text, and content instead of on bells and whistles with formatting and typesetting it's really hard to go easier than Markdown. That's exactly my argument. I literally quote Gruber on it.
- acmdas 5y agoWhile I've been a "geek" since I joined IBM in 1967, I've been primarily a writer for at least 35 years. In that time, I've used Wordstar, WordPerfect, literally every flavour of MS Word up to 2011, vi, iTerm and emacs. I've converted files of one format to another to another to another, and finally to ASCII text and that is that. No more orphaning as one or another company goes out of business or decides to update their file format. My editor now is Emacs and, depending on who/what I'm writing for I use plain text, or org or md if I need to include basic formatting. I've published enough to know that I'm a wordsmith, not an artist and going beyond basic formatting is a job for a typographic artist, which I'm not. I know that makes me a grumpy old fart, as does my refusal to rely on The Cloud (i.e., Somebody Else's Computer) for backups, and so be it. Fool me once, shame on you, fool me twice (or more), shame on me.
- prepend 5y agoI don’t want an “authoring experience.” I want a simple, durable text format that will still be around and useful in 10 years. I like that markdown is cheap, free, and independent of any platform or language or tool. When coupled with git, the editorial experience is fantastic through diff and merges. It’s not for everyone and author can use what ve likes. But the author proposes something that in no way is as useful as markdown.
- vlark 5y agoAnybody remember setext, which was used in the original TidBITS newsletters back in the early 1990s? When Gruber introduced Markdown back '04, it struck me as an enhancement on setext more than anything else.
- seadan83 5y agoReferring to slack turning on markdown: "shows how deep the love for markdown is in the developer community." I think I need to call BS here. Typing out a phrase, taking your hands off the keyboard to then fight with wysiwyg is a step back and unusable. What is a max typing speed doing this? I'm curious if anyone can break 20wpm doing that. The mouse controls for formatting are simply not usable for anyone wanting to effectively type above 30wpm So that aside. I thought markdown was a unification of the absurd number of wiki languages that were coming out. There is tracwiki, wikipedia's, mediawiki, countless more with different variations of markdown. They all have HTML knock-offs because html is overly verbose for quickly typing out a simple wiki page that us mostly lists and headers.
- irrational 5y ago> the appeal of plain text files is understandable. But that era is pretty much gone with the emergence of backends as a service. Services and tools like Fauna, Firestore, Hasura, Prisma, PlanetScale, and Sanity’s Content Lake, invest heavily in developer experience. Am I the only one who has never heard of any of these?
- irrational 5y ago> Portable Text isn’t design to be written or be easily readable in its raw form; it’s designed to be produced by an user interface, manipulated by code, and to be serialized and rendered where ever it needs to go. Oh hell no. The most important aspect of markdown to me is that it is human readable in text file format. I can be quite certain that in 500 years (assuming humanity lasts that long and still has computers) that my notes in markdown will still be completely legible.