1. 17
  1. 17

    On the one hand, I totally get the value of a lack of a build step. Build steps are annoying. On the other hand, authoring directly in HTML is something I am perfectly happy to do as little of as possible. It’s just not a pleasant language to write in for any extended amount of time!

    1. 20

      I’m pretty convinced that Markdown is the local maxima for the “low effort, nice looking content” market.

      1. 10

        Agreed. ASCIIDoc, reStructuredText, LaTeX, and other more-robust-than-Markdown syntaxes all have significantly more power but also require a great deal more from you as a result. For just put words out, Markdown is impressively “good enough”.

        1. 4

          I can never remember Markdown syntax (or any other wiki syntax for that matter), while I’m fairly fluent in HTML, and I’m not even a frontend dev. HTML also has the advantage that if some sort of exotic markup is necessary, you know it’s expressble, given time and effort.

          1. 7

            That’s fine, because Markdown allows embedded HTML [1]

            About the only thing that’s a bit obtuse is the link syntax, and I’ve gladly learned that to not have to manually enclose every damn list with or tags.

            [1] at least Gruber’s OG Markdown allowed it by default, and I recently learned CommonMark has an “unsafe” mode to allow it too.

            1. 11

              The trick to remember how to do links in Markdown is to remember that there are brackets and parentheses involved, then think what syntax would make sense, then do the opposite.

              1. 4

                For reference: a Markdown [link](https://example.com)

                Elaboration on the mnemonic you describe

                I thought like you when I first started learning Markdown:

                • Parentheses () are normal English punctuation, so you would intuitively expect them to surround the text, but they don’t.
                • Square brackets [] are technical symbols, so you would intuitively expect them to surround the URL, but they don’t.

                However, I find “don’t do this” mnemonics easy to accidentally negate, so I don’t recommend trying to remember the order that way.

                Another mnemonic

                I think Markdown’s order of brackets and parentheses is easier to remember once one recognizes the following benefit:

                When you read the first character in […](…), it’s clear that you’re reading a link. ‘[’ is a technical symbol, so you know you’re not reading a parenthetical, which would start with ‘(’. Demonstration:

                In this Markdown, parentheticals (which are everywhere) and
                [links like these](https://example.com) can quickly be told
                apart when reading from left to right.
                Why not URL first?

                Since you wrote that Markdown does “the opposite”, I wonder if you also intuitively expect the syntax to put the URL before the text, like in [https://www.mediawiki.org/wiki/Help:Links MediaWiki’s syntax] (actual link: MediaWiki’s syntax). I never found that order intuitive, but I can explain why I prefer text first:

                When trying to read only the text and skip over the URLs, it’s easier to skip URLs if they come between grammatical phrases of the text (here), rather than interrupting a (here) phrase. And links are usually written at the end of phrases, rather than at the beginning.

                1. 2

                  Well I’ll be dammed. That completely makes sense.

                  I do, however, wonder whether this is a post-hoc rationalization and the real reason for the syntax is much dumber.

                2. 3

                  Hah. The mnemonic I use is everyone gets the ) on the end of their wiki URLs fucked up by markdown… because the () goes around the URL. therefore it is s []().

                  1. 2

                    This is exactly what I do. Parens are for humans, square brackets are for computers, so obviously it’s the other way around in markdown.

                  2. 3

                    A wiki also implies a social contract about editability. If my fellow editors have expressed that they’re uncomfortable with HTML, it’s not very polite of me to use it whenever I find Markdown inconvenient.

                    1. 1

                      Of course. I was replying in context of someone writing for themselves.

                  3. 3

                    This is interesting: I’ve heard that same experience report from a number of people over the years so I believe it’s a real phenomenon (the sibling comment about links especially being the most common) but Markdown clicked instantly for me so I always find it a little surprising!

                    I have hypothesized that it’s a case of (a) not doing it in a sustained way, which of course is the baseline, and (b) something like syntactical cross-talk from having multiple markup languages floating around; I took longer to learn Confluence’s wiki markup both because it’s worse than Markdown but also because I already had Markdown, rST, and Textile floating around in my head.

                    I’m curious if either or both of those ring true, or if you think there are other reasons those kinds of markup languages don’t stick for you while HTML has?

                    1. 2

                      I’m not Michiel, but for me, it’s because HTML is consistent (even if it’s tedious). In my opinion, Gruber developed Markdown to make it easier for him to write HTML, and to use conventions that made sense to him for some shortcuts (the fact that you could include HTML in his Markdown says to me that he wasn’t looking to replace HTML). Markdown was to avoid having to type common tags like <P> or <EM>.

                      For years I hand wrote the HTML for my blog (and for the record, I still have to click the “Markdown formatting available” link to see how to make links here). A few years ago I implemented my own markup language [1] that suits me. [2] My entries are still stored as HTML. That is a deliberate decision so I don’t get stuck with a subpar markup syntax I late come to hate. I can change the markup language (I’ve done it a few times already) and if I need to edit past entries, I can deal with the HTML.

                      [1] Sample input file

                      [2] For instance, a section for quoting email, which I do quite often. Or to include pictures in my own particular way. Or tabular data with a very light syntax and some smarts to generate the right class on <TD> elements consisting of numeric data (so they’re flush right). Stuff like that.

                      1. 2

                        Yeah, with markdown, I often accidentally trigger some of its weird syntax. It needs a bunch of arbitrary escapes, whereas HTML you can get away with just using &lt;. Otherwise, it is primarily just those <p> tags that get you; the rest are simple or infrequent enough to not worry about.

                        whereas again, with the markdown, it is too easy to accidentally write something it thinks is syntax and break your whole thing.

                        1. 1

                          Yes, I’ve found that with mine as well.

                        2. 1

                          I don’t mean this as an offense, but I did a quick look at your custom markup sample and I hated pretty much everything about it.

                          Since we’re all commenting under a post from someone that is handwriting HTML, I think it goes without saying that personal preferences can vary enormously.

                          Updated: I don’t hate the tables syntax, and, although I don’t particularly like que quote syntax, having a specific syntax for it is cool and a good idea.

                          1. 1

                            Don’t worry about hating it—even I hate parts of it. It started out as a mash up of Markdown or Org mode. The current version I’m using replaces the #+BEGIN_blah #+END_blah with #+blah #-blah. I’m still working on the quote syntax. But that’s the thing—I can change the syntax of the markup, because I don’t store the posts in said markup format.

                        3. 2

                          You’re absolutely right, and so is spc476; HTML has a regular syntax. Even if I’ve never seen the <aside> tag, I can reason about what it does. Escaping rules are known and well-defined. If you want to read the text, you know you can just ignore anything inside the angular brackets.

                          Quick: in Markdown, if I want to use a backtick in a fixed-width span, do I have to escape it? How about an italic block?

                          This would all be excusable if Markdown was a WYSIWYG plain-text format (as per Gruber’s later rationalisation in the CommonMark debate). Then I could mix Markdown, Mediawiki, rST and email syntax freely, because it’s intended for humans to read, and humans tend to be very flexible.

                          But people do expect to render it to HTML, and then the ambiguities and flexibility become weaknesses, rather than strengths.

                      2. 2


                        While I agree about the others, I fairly strongly disagree about AsciiDoc (in asciidoctor dialect). When I converted my blog from md to adoc, the only frequent change was the syntax of links (in adoc, URL goes first). Otherwise, markdown is pretty much valid asciidoc.

                        Going in the opposite direction would be hard though — adoc has a bunch of stuff inexpressible in markdown.

                        I am fairly certain in my opinion that, purely as a language, adoc is far superior for authoring html-shaped documents. But it does have some quality of implementation issues. I am hopeful that, after it gets a standard, things in that front would improve.

                        1. 1

                          That’s helpful feedback! It’s limped with the others in my head because I had such an unhappy time trying to use it when working with a publisher[1] a few years back; it’s possible the problem was the clumsiness of the tools more than the syntax. I’ll have to give it another look at some point!

                          [1] on a contract they ultimately dropped after an editor change, alas

                      3. 4

                        Agree, I’ve been using it a ton since 2016 and it has served me well. I think it’s very “Huffman coded” by people who have written a lot. In other words, the common constructs are short, and the rare constructs are possible with embedded HTML.

                        However I have to add that I started with the original markdown.pl (written ~2004) and it had some serious bugs.

                        Now I’m using the CommonMark reference implementation and it is a lot better.

                        CommonMark is a Useful, High-Quality Project (2018)

                        It has additionally standardized markdown with HTML within markdown, which is useful, e.g.

                        <div class="">
                        this is *markdown*

                        I’ve used both ASCIIDoc and reStructuredText and prefer markdown + embedded HTML.

                        1. 3

                          I tend to agree, but there’s a very sharp usability cliff in Markdown if you go beyond the core syntax. With GitHub-flavoured Markdown, I can specify the language for a code block, but if I write virtual then there’s no consistent syntax to specify that it’s a C++ code snippet and not something else where the word ‘virtual’ is an identifier and not a keyword. I end up falling back to things like liquid or plain HTML. In contrast, in LaTeX I’d write \cxx{virtual} and define a macro elsewhere.

                          I wish Markdown had some kind of generic macro definition syntax like this, which I could use to provide inline domain-specific semantic markup that was easier to type (and use) than <cxx>virtual</cxx> and an XSLT to convert it into <code style="cxx">virtual</code> or whatever.

                          1. 3

                            I agree. What sometimes makes me a bit sad is that markdown had a feature compared to others that you can write it to make a nice looking text document as well that you might just output on the terminal for example.

                            It kind of has that nicely formated plain text email style. Also with the alternative syntax for headings.

                            Yet when looking at READMEs in many projects it is really ugly and hard to read for various reasons.

                            1. 4

                              The biggest contributor there in my experience (and I’m certainly “guilty” here!) is unwrapped lines. That has other upsides in that editing it doesn’t produce horrible diffs when rewrapping, but that in turn highlights how poor most of our code-oriented tools are at working with text. Some people work around the poor diff experience by doing a hard break after every sentence so that diffs are constrained and that makes reading as plain text even worse.

                              A place I do wrap carefully while using Markdown is git commit messages, which are basically a perfect use case for the plain text syntax of Markdown.

                              1. 1

                                I honestly don’t care that much about the diffs? I always wrap at around 88/90 (Python’s black’s default max line length), and diffs be dammed.

                                I also pretty much NEVER have auto wrap enabled, specially for code. I’d rather suffer the horizontal scroll than have the editor lie about where the new lines are

                          2. 4

                            It’s not just that they’re annoying, computing has largely been about coping with annoyances ever since the Amiga became a vintage computer :-). But in the context of maintaining a support site, which is what the article is about, you also have to deal with keeping up with whatever’s building the static websites, the kind of website that easily sits around for like 10-15 years. The technology that powers many popular static site generators today is… remarkably fluid. Unless you want to write your own static site generator using tools you trust to stay sane, there’s a good chance that you’re signing up for a bunch of tech churn that you really don’t want to deal with for a support site.

                            Support sites tend to be built by migrating a bunch of old pages in the first two weeks, writing a bunch of new ones for the first two months, and then infrequently editing existing pages and writing maybe two new pages each year for another fifteen years. With most tools today, after those first two or three honeymoon years, you end up spending more time just keeping the stupid thing buildable than actually writing the support pages.

                            Not that writing HTML is fun, mind you :(.

                            (Please don’t take this as a “back in my day” lament. A static site generator that lasts 10 years is doable today and really not bad at all – how many tools written in 1992 could you still use in 2002, with good results, not as an exercise in retrocomputing? It’s not really a case of “kids these days ruined it” – it’s just time scales are like that ¯\(ツ)/¯ )

                            1. 1

                              Heh. I was using an editor written in 1981 in 2002! [1] But more seriously, I wrote a static site generator in 2002 that I’m still using (I had to update it once in 2009 due to a language change). On the down side, the 22 year old codebase requires the site to be stored in XML, and uses XSLT (via xsltproc) to convert it to HTML. On the plus side, it generates all the cross-site links automatically.

                              [1] Okay, it was to edit text files on MS-DOS/Windows.

                            2. 2

                              I find that writing and edititing XML or HTML isn’t so much of a pain if you use some kind of structural editor. I use tagedit in Emacs along with a few snippets / templates and imo it’s pretty nice once you get used to it.

                            3. 8

                              Dare I say that a little sprinkle of PHP may be the happy middle ground that avoids both a build step and too much duplicated boilerplate.

                              Equally a different piece of middleware, like Caddy’s templates, would do the job.

                              1. 8

                                One big upside to either writing plain HTML or a build step is they dramatically simplify what kind of server needs you have. Deploying static content is something I personally find much, much easier to do in ways that leave me not worried about opening security holes that will let a server get botnetified etc., even leaving aside the ease of deploying to GitHub, Vercel, Netlify, or even just S3 or similar. I would be really happy never to deal with the security considerations of a PHP or Node server ever again. 😂

                                1. 3

                                  Server Side Includes then? :P

                                  1. 2

                                    If all you’re using PHP for is includes on an otherwise-static site, I can’t think of any security concern.

                                    But… I did end up going with a static site generator (wrote my own, as is traditional) because that gives me the freedom to deploy anywhere. My site is also archive-ready. If I ever want to switch up my blogging software entirely, I can just… keep the generated HTML in place for older posts.

                                2. 4

                                  So what do you do when editing the header? Update all pages? A sed I assume.

                                  1. 4

                                    The post mentions that it’s filled in with a bit of JavaScript. RIP you if the JavaScript fails to load, I guess?

                                    1. 2

                                      yikes. that’s not plain HTML at all. Horrible solution.

                                  2. 3

                                    I’d personally throw a local git repo or something in there if we’re just editing html files on some server. One bad file glob or “sed” command can delete the only copy of some critical documentation. Plus the git log itself serves as additional documentation.

                                    1. 1

                                      The editing on the server made me wince. Build steps can be annoying, but a separate step between development and production is ABSOLUTELY necessary. And NONE of the benefits would be lost.