7 ms·

My Contribution to Markdown

120 points by zdw 4y ago

brycewray 4y ago
> Anyway, it was during a digression—actually a digression within a digression— that Gruber talks about code blocks in Markdown and how one of his favorite features is that you don’t have to escape anything in a code block. You can paste source code directly into your Markdown document without any changes, and it will appear as expected in the rendered HTML. True enough as far as it goes but, if you use that Markdown in some static site generators (SSGs), you may still have to massage it a bit so the SSG output won’t be borked. For a couple of examples: - In Eleventy and Jekyll (and maybe others), you often have to wrap code blocks in `{% raw %}` and `{% endraw %}`. - In Hugo, if you're including anything that Go initially “thinks” is real code rather than just a reproduction thereof, you must put comment characters around it: `{{< this >}}` isn't OK, but `{{</* this */>}}` is (and will display in Hugo as the desired `{{< this >}}`).
- groby_b 4y ago
  If the SSGs are broken, that's hardly markdown's fault.
  - brycewray 4y ago
    Just sayin’. :-)
behnamoh 4y ago
> But I was there first, you're welcome. With these things, I always think "but if he hadn't done it, someone else would". Therefore, what matters is the thing that got done; the person doing it isn't special (nor should they feel so).
- abnry 4y ago
  You forgot these sentences right before it: > Undoubtedly, as Markdown became more popular, someone else would have pointed out this problem. Gruber himself would have been annoyed by it if he ever needed to write a code block with backslashes in it. People are overreacting to a tongue-in-cheek post. I doubt the author takes himself too seriously with all of this.
  - nescioquid 4y ago
    What was the purpose of the post? The author wrote a tedious story about listening to a podcast episode in which markdown codeblocks are mentioned and "That’s my doing". But the rest comes off like mock humility because there really wasn't any information of relevance to anyone but the author. Had the article been about the importance of user engagement in open source projects and then used his personal experience to underscore the point, then the article is really about raising awareness and might be something of utility to a reader. This article, however, just reads like me, me, me.
    - abnry 4y ago
      Yeah, it is self centered, but it is fun.
    - Veen 4y ago
      It wasn't a personal letter addressed to you so naturally it fails to account for your ignorance. He's writing for long-time readers of his blog who already understand the context, his style, his relationship with Gruber and Markdown, and so on. Perhaps, given that you haven't got a clue about any of that and don't seem to know what irony is, you should reconsider whether your rude comment is justified.
      - nescioquid 4y ago
        Well I did find the irony of your reply delicious; sure, I'll just leave it to you to decide what is justified and what is rude.
    - yen223 4y ago
      What is the purpose of this comment? Heck, what is the purpose of my comment?
ninepoints 4y ago
This is akin to filing a bug report, and then taking responsibility for the fix committed by someone else.
- dewey 4y ago
  > Undoubtedly, as Markdown became more popular, someone else would have pointed out this problem. Gruber himself would have been annoyed by it if he ever needed to write a code block with backslashes in it. But I was there first. And you’re welcome. I don't see how he's taking responsibility for fixing the bug. To me it just sounds like he's sharing an anecdote and this is not entirely serious.
- sophacles 4y ago
  Some credit as the motivator of the fix is deserved. The author very clearly states: Undoubtedly, as Markdown became more popular, someone else would have pointed out this problem. Gruber himself would have been annoyed by it if he ever needed to write a code block with backslashes in it. But I was there first. And you’re welcome. I don't think they are trying to take more credit than is due.
  - dathanb82 4y ago
    But also > You can paste source code directly into your Markdown document without any changes, and it will appear as expected in the rendered HTML. That’s my doing. In that sentence, it kinda does sound like they're trying to take credit for it.
    - water-your-self 4y ago
      Its upon the reader to ascribe malintent. Ill choose not to.
      - sophacles 4y ago
        Generally I don't like to point out typos, but in the context of malintent: Ill vs I'll is pretty amusing :D
isitmadeofglass 4y ago
A contribution typically implies actual work, not just having talked to the person who made the actual contribution.
- julianlam 4y ago
  Not according to GitHub, which — unless I'm mistaken — treats opened issues as contributions.
- soperj 4y ago
  Noticing a bug and filing a report on it is actual work.
  - isitmadeofglass 4y ago
    Noticing a broken window and telling the owner about it is not actual work towards fixing it.
    - soperj 4y ago
      If the owner has no idea that the window is broken, then it'll never get fixed until this step happens, so yes it is.
- redditor98654 4y ago
  A product manager that comes up with feature ideas is doing actual work, would you not agree? Even if they themselves do not implement anything.
  - just-ok 4y ago
    What? No. Writing a well-spec’d feature request with clear outcome and behavior expectations is work. Just asking, “Wouldn’t it be cool if ____?” is not actual work.
    - redditor98654 4y ago
swyx 4y ago
im too late to contribute anything to core markdown, but my claim to fame is making a list of "mistakes in markdown" that Gruber endorsed recently: - list: https://twitter.com/swyx/status/1240719259505963010 https://twitter.com/swyx/status/1240719259505963010 (previously on HN https://news.ycombinator.com/item?id=22776108 https://news.ycombinator.com/item?id=22776108 ) - gruber: https://twitter.com/gruber/status/1240888155307495426 https://twitter.com/gruber/status/1240888155307495426
- thangalin 4y ago
  Another item missing from Markdown is a standard syntax for cross-references and citations: https://talk.commonmark.org/t/cross-references-and-citations/4013 https://talk.commonmark.org/t/cross-references-and-citations... Is the tweeted list a little outdated now? > no id's in headers A natural ID is derived by changing the header to lowercase and replacing spaces with hyphens, such as: https://github.com/DaveJarvis/keenwrite/blob/master/docs/screenshots.md#pdf-themes https://github.com/DaveJarvis/keenwrite/blob/master/docs/scr... > no syntax for adding classes Pandoc introduced ::: annotation blocks that produce div tags with classes. I discuss this length: https://dave.autonoma.ca/blog/2020/04/28/typesetting-markdown-part-8/#annotations https://dave.autonoma.ca/blog/2020/04/28/typesetting-markdow... My editor, KeenWrite[0], also supports annotation syntax: https://user-images.githubusercontent.com/2131950/161400266-e84cff56-f05c-4e29-a81d-69b10f97907c.png https://user-images.githubusercontent.com/2131950/161400266-... > any number will do in ordered lists Isn't that either a presentation issue or a feature? I prefer numbering lists with a sequence of 1., 1., 1., 1., to let the computer automatically increment the number. Makes adding/removing items easier. Being able to arbitrarily change the numbering seems weird, though potentially useful. > code blocks (4 spaces) over code fences (```) Not sure why this is a design mistake. When reading technical documentation, indented stands out more. IMO, it improves readability for short snippets (where syntax highlighting doesn't matter). > can't nest Markdown in HTML in Markdown Depends on the Markdown flavour, doesn't it? [0]: https://github.com/DaveJarvis/keenwrite#download https://github.com/DaveJarvis/keenwrite#download
  - swyx 4y ago
    yes, i was commenting on the base markdown spec by Gruber (since that is the subset that all the supersets have to fit)
remram 4y ago
I do wish we could have both modes in Markdown, similar to how bash has <<END and <<'END' Sometimes I want to highlight a part of the code...
NelsonMinar 4y ago
That little asterix on "without any changes" is doing a lot of work. > The code block has to be indented, of course, or—in many implementations, but not Gruber’s—surrounded by fences. Indenting is always a nuisance and can present more complicated problems for Python or other whitespace-significant languages. CommonMark and most Markdown flavors support 3 backticks or 3 tildes as a fence. Then everything inside is literally unaltered code. Not sure what you do if your code sample itself has the fence in it.
throwthere 4y ago
I think you're meant to read this post as if the entire thing is surrounded by "sarcasm" tags.
trauco 4y ago
All the humming and hawing about how the author of the post is taking credit for someone else's work, etc, is a good example of the problem of reading one-off things on the internet and commenting on them here without understanding the context or the voice of the author. As a long-term reader of that blog, it is obvious to me this is a little historical anecdote, mostly tongue-in-cheek, from a particular mac-centric community to which both the author and Gruber belong to. He's not being grandiose or trying to take credit. Sometimes a story is just a story.
- capableweb 4y ago
  Sounds just like what the author could expect from a discussion in a community which is not the same community they usually find themselves in ("a particular mac-centric community", whichever that refers to). Strangers on the internet will come across your little random story if it's public, and rather than blaming first-time readers for not understanding the context nor the voice of the author, maybe the author could adjust the article to provide the context or make the voice stronger/more obvious? Honestly, I'm fine with not understanding everything from communities I don't generally hang-around, it's bound to happen at one point or another.
  - trauco 4y ago
    > Strangers on the internet will come across your little random story if it's public, and rather than blaming first-time readers for not understanding the context nor the voice of the author, maybe the author could adjust the article to provide the context or make the voice stronger/more obvious? I'm not "blaming" anyone. I'm just pointing out that the commenters here are missing the point of the story because they don't understand the context, and that this is a fairly common phenomenon. I think it's fine to tailor your writing to a community of like-minded readers rather than a first-time reader from here that is unlikely to come back. > Honestly, I'm fine with not understanding everything from communities I don't generally hang-around, it's bound to happen at one point or another. Me too, of course. It just makes a discussion without that context, i.e., what's happening here, detached from what the author meant with the post.
  - 4y ago
n4jm4 4y ago
I supported an effort to standardize Markdown into an actual common syntax, instead of the nasty variation we see between GitHub, Reddit, Stack Overflow, Atlassian, etc. etc. This became CommonMark, which everyone ignores.
- polygamous_bat 4y ago
  I am sorry. However, XKCD did warn us about this: https://xkcd.com/927/ https://xkcd.com/927/
  - deleted 4y ago
    [deleted]
  - avgcorrection 4y ago
    > 14 competing standards MarkDown didn’t have any standards to begin with, just different implementations for different platforms. Tired 927 refuted.
- bosswipe 4y ago
  If Gruber had gotten behind that initiative it probably would've worked but he was weirdly antagonistic to it.
BrainVirus 4y ago
Did you know you can embed code blocks in HTML without escaping anything? You put them inside <script> tag with type="text/html". Then you style such tags to be visible and preserve whitespace. E.g.: <script type="text/plain"> > hello world <- this is legal </script>
- klysm 4y ago
  I didnt know this but the semantics do seem odd as we have <pre> and <code> right?
  - BrainVirus 4y ago
    <pre> and <code> still require you to escape all HTML special symbols. <script> and <style> do not.
    - krapp 4y ago
      what about <xmp>?
      - BrainVirus 4y ago
        I don't know what it does in practice, since it's obsolete. Heck, I've never even heard about it until right now. https://developer.mozilla.org/en-US/docs/Web/HTML/Element/xmp https://developer.mozilla.org/en-US/docs/Web/HTML/Element/xm... I think HTML should have a dedicated tag for this, but sadly <script> is the closest thing that I know of.
michele_f 4y ago
zdw, I’m curious about what made you think this deserved to be shared with the world.

120 points by zdw 4y ago

> Anyway, it was during a digression—actually a digression within a digression— that Gruber talks about code blocks in Markdown and how one of his favorite features is that you don’t have to escape anything in a code block. You can paste source code directly into your Markdown document without any changes, and it will appear as expected in the rendered HTML. True enough as far as it goes but, if you use that Markdown in some static site generators (SSGs), you may still have to massage it a bit so the SSG output won’t be borked. For a couple of examples: - In Eleventy and Jekyll (and maybe others), you often have to wrap code blocks in `{% raw %}` and `{% endraw %}`. - In Hugo, if you're including anything that Go initially “thinks” is real code rather than just a reproduction thereof, you must put comment characters around it: `{{< this >}}` isn't OK, but `{{</* this */>}}` is (and will display in Hugo as the desired `{{< this >}}`).

groby_b 4y ago
If the SSGs are broken, that's hardly markdown's fault.
- brycewray 4y ago
  Just sayin’. :-)

behnamoh 4y ago

> But I was there first, you're welcome. With these things, I always think "but if he hadn't done it, someone else would". Therefore, what matters is the thing that got done; the person doing it isn't special (nor should they feel so).

abnry 4y ago
You forgot these sentences right before it: > Undoubtedly, as Markdown became more popular, someone else would have pointed out this problem. Gruber himself would have been annoyed by it if he ever needed to write a code block with backslashes in it. People are overreacting to a tongue-in-cheek post. I doubt the author takes himself too seriously with all of this.
- nescioquid 4y ago
  What was the purpose of the post? The author wrote a tedious story about listening to a podcast episode in which markdown codeblocks are mentioned and "That’s my doing". But the rest comes off like mock humility because there really wasn't any information of relevance to anyone but the author. Had the article been about the importance of user engagement in open source projects and then used his personal experience to underscore the point, then the article is really about raising awareness and might be something of utility to a reader. This article, however, just reads like me, me, me.
  - abnry 4y ago
    Yeah, it is self centered, but it is fun.
  - Veen 4y ago
    It wasn't a personal letter addressed to you so naturally it fails to account for your ignorance. He's writing for long-time readers of his blog who already understand the context, his style, his relationship with Gruber and Markdown, and so on. Perhaps, given that you haven't got a clue about any of that and don't seem to know what irony is, you should reconsider whether your rude comment is justified.
    - nescioquid 4y ago
      Well I did find the irony of your reply delicious; sure, I'll just leave it to you to decide what is justified and what is rude.
  - yen223 4y ago
    What is the purpose of this comment? Heck, what is the purpose of my comment?

ninepoints 4y ago

This is akin to filing a bug report, and then taking responsibility for the fix committed by someone else.

dewey 4y ago
> Undoubtedly, as Markdown became more popular, someone else would have pointed out this problem. Gruber himself would have been annoyed by it if he ever needed to write a code block with backslashes in it. But I was there first. And you’re welcome. I don't see how he's taking responsibility for fixing the bug. To me it just sounds like he's sharing an anecdote and this is not entirely serious.
sophacles 4y ago
Some credit as the motivator of the fix is deserved. The author very clearly states: Undoubtedly, as Markdown became more popular, someone else would have pointed out this problem. Gruber himself would have been annoyed by it if he ever needed to write a code block with backslashes in it. But I was there first. And you’re welcome. I don't think they are trying to take more credit than is due.
- dathanb82 4y ago
  But also > You can paste source code directly into your Markdown document without any changes, and it will appear as expected in the rendered HTML. That’s my doing. In that sentence, it kinda does sound like they're trying to take credit for it.
  - water-your-self 4y ago
    Its upon the reader to ascribe malintent. Ill choose not to.
    - sophacles 4y ago
      Generally I don't like to point out typos, but in the context of malintent: Ill vs I'll is pretty amusing :D

isitmadeofglass 4y ago

A contribution typically implies actual work, not just having talked to the person who made the actual contribution.

julianlam 4y ago
Not according to GitHub, which — unless I'm mistaken — treats opened issues as contributions.
soperj 4y ago
Noticing a bug and filing a report on it is actual work.
- isitmadeofglass 4y ago
  Noticing a broken window and telling the owner about it is not actual work towards fixing it.
  - soperj 4y ago
    If the owner has no idea that the window is broken, then it'll never get fixed until this step happens, so yes it is.
redditor98654 4y ago
A product manager that comes up with feature ideas is doing actual work, would you not agree? Even if they themselves do not implement anything.
- just-ok 4y ago
  What? No. Writing a well-spec’d feature request with clear outcome and behavior expectations is work. Just asking, “Wouldn’t it be cool if ____?” is not actual work.
  - redditor98654 4y ago

swyx 4y ago

im too late to contribute anything to core markdown, but my claim to fame is making a list of "mistakes in markdown" that Gruber endorsed recently: - list: https://twitter.com/swyx/status/1240719259505963010 https://twitter.com/swyx/status/1240719259505963010 (previously on HN https://news.ycombinator.com/item?id=22776108 https://news.ycombinator.com/item?id=22776108 ) - gruber: https://twitter.com/gruber/status/1240888155307495426 https://twitter.com/gruber/status/1240888155307495426

thangalin 4y ago
Another item missing from Markdown is a standard syntax for cross-references and citations: https://talk.commonmark.org/t/cross-references-and-citations/4013 https://talk.commonmark.org/t/cross-references-and-citations... Is the tweeted list a little outdated now? > no id's in headers A natural ID is derived by changing the header to lowercase and replacing spaces with hyphens, such as: https://github.com/DaveJarvis/keenwrite/blob/master/docs/screenshots.md#pdf-themes https://github.com/DaveJarvis/keenwrite/blob/master/docs/scr... > no syntax for adding classes Pandoc introduced ::: annotation blocks that produce div tags with classes. I discuss this length: https://dave.autonoma.ca/blog/2020/04/28/typesetting-markdown-part-8/#annotations https://dave.autonoma.ca/blog/2020/04/28/typesetting-markdow... My editor, KeenWrite[0], also supports annotation syntax: https://user-images.githubusercontent.com/2131950/161400266-e84cff56-f05c-4e29-a81d-69b10f97907c.png https://user-images.githubusercontent.com/2131950/161400266-... > any number will do in ordered lists Isn't that either a presentation issue or a feature? I prefer numbering lists with a sequence of 1., 1., 1., 1., to let the computer automatically increment the number. Makes adding/removing items easier. Being able to arbitrarily change the numbering seems weird, though potentially useful. > code blocks (4 spaces) over code fences (```) Not sure why this is a design mistake. When reading technical documentation, indented stands out more. IMO, it improves readability for short snippets (where syntax highlighting doesn't matter). > can't nest Markdown in HTML in Markdown Depends on the Markdown flavour, doesn't it? [0]: https://github.com/DaveJarvis/keenwrite#download https://github.com/DaveJarvis/keenwrite#download
- swyx 4y ago
  yes, i was commenting on the base markdown spec by Gruber (since that is the subset that all the supersets have to fit)

remram 4y ago

I do wish we could have both modes in Markdown, similar to how bash has <<END and <<'END' Sometimes I want to highlight a part of the code...

NelsonMinar 4y ago

That little asterix on "without any changes" is doing a lot of work. > The code block has to be indented, of course, or—in many implementations, but not Gruber’s—surrounded by fences. Indenting is always a nuisance and can present more complicated problems for Python or other whitespace-significant languages. CommonMark and most Markdown flavors support 3 backticks or 3 tildes as a fence. Then everything inside is literally unaltered code. Not sure what you do if your code sample itself has the fence in it.

throwthere 4y ago

I think you're meant to read this post as if the entire thing is surrounded by "sarcasm" tags.

trauco 4y ago

All the humming and hawing about how the author of the post is taking credit for someone else's work, etc, is a good example of the problem of reading one-off things on the internet and commenting on them here without understanding the context or the voice of the author. As a long-term reader of that blog, it is obvious to me this is a little historical anecdote, mostly tongue-in-cheek, from a particular mac-centric community to which both the author and Gruber belong to. He's not being grandiose or trying to take credit. Sometimes a story is just a story.

capableweb 4y ago
Sounds just like what the author could expect from a discussion in a community which is not the same community they usually find themselves in ("a particular mac-centric community", whichever that refers to). Strangers on the internet will come across your little random story if it's public, and rather than blaming first-time readers for not understanding the context nor the voice of the author, maybe the author could adjust the article to provide the context or make the voice stronger/more obvious? Honestly, I'm fine with not understanding everything from communities I don't generally hang-around, it's bound to happen at one point or another.
- trauco 4y ago
  > Strangers on the internet will come across your little random story if it's public, and rather than blaming first-time readers for not understanding the context nor the voice of the author, maybe the author could adjust the article to provide the context or make the voice stronger/more obvious? I'm not "blaming" anyone. I'm just pointing out that the commenters here are missing the point of the story because they don't understand the context, and that this is a fairly common phenomenon. I think it's fine to tailor your writing to a community of like-minded readers rather than a first-time reader from here that is unlikely to come back. > Honestly, I'm fine with not understanding everything from communities I don't generally hang-around, it's bound to happen at one point or another. Me too, of course. It just makes a discussion without that context, i.e., what's happening here, detached from what the author meant with the post.
- 4y ago

n4jm4 4y ago

I supported an effort to standardize Markdown into an actual common syntax, instead of the nasty variation we see between GitHub, Reddit, Stack Overflow, Atlassian, etc. etc. This became CommonMark, which everyone ignores.

polygamous_bat 4y ago
I am sorry. However, XKCD did warn us about this: https://xkcd.com/927/ https://xkcd.com/927/
- deleted 4y ago
  [deleted]
- avgcorrection 4y ago
  > 14 competing standards MarkDown didn’t have any standards to begin with, just different implementations for different platforms. Tired 927 refuted.
bosswipe 4y ago
If Gruber had gotten behind that initiative it probably would've worked but he was weirdly antagonistic to it.

BrainVirus 4y ago

Did you know you can embed code blocks in HTML without escaping anything? You put them inside <script> tag with type="text/html". Then you style such tags to be visible and preserve whitespace. E.g.: <script type="text/plain"> > hello world <- this is legal </script>

klysm 4y ago
I didnt know this but the semantics do seem odd as we have <pre> and <code> right?
- BrainVirus 4y ago
  <pre> and <code> still require you to escape all HTML special symbols. <script> and <style> do not.
  - krapp 4y ago
    what about <xmp>?
    - BrainVirus 4y ago
      I don't know what it does in practice, since it's obsolete. Heck, I've never even heard about it until right now. https://developer.mozilla.org/en-US/docs/Web/HTML/Element/xmp https://developer.mozilla.org/en-US/docs/Web/HTML/Element/xm... I think HTML should have a dedicated tag for this, but sadly <script> is the closest thing that I know of.

michele_f 4y ago

zdw, I’m curious about what made you think this deserved to be shared with the world.