4 ms·

Advice to the author: This is a subject I am interested in, so I began your article eagerly, but had to stop about halfway through out of frustration. Please c

Advice to the author: This is a subject I am interested in, so I began your article eagerly, but had to stop about halfway through out of frustration. Please consider these as the constructive suggestions that I intend them to be: Think about the story you want to tell. Maybe make an outline or diagram, marking at which points you will introduce which facts. Example: For some reason something called Commonmark is abruptly mentioned, with a link to spec documents that would seem to be of only technical interest. What is this, and how is it connected to anything else? Do enough research so that you know the highest peaks in the landscape. Why describe the foothills and take no notice of the prominent mountaintop right in front of us? Example: the bits about the comics were fascinating. But where is Pandoc? I don’t think I’m guilty, here, of demanding that you write the article I would have written. But Pandoc is the application of Markdown. It turns Markdown into a way to author HTML, TeX, PDF, Office formats, and a lot more. It‘s huge. Anyway, I like the look of your site (but agree with others that you should not hijack browser shortcuts).

gen220 6y ago
I feel like pandoc is kind of like a secret club. Once you know about pandoc, you orient all of your prose around it, because it's so powerful and useful. But before you use it, the common opinion is "oh that sounds nice", not "oh let me build all of my workflows around it". It is incredible how far markdown, sed and pandoc (with filters) can take you! I've made websites with breadcrumbs, validated inter-document links and images, on and on; mostly pipelines with sed and pandoc. All of my non-source-code homework in college went through pandoc, and was persisted as markdown source. It makes for clean diffs, and great version history. Anyway. Give pandoc a try if you haven't already.
- leephillips 6y ago
  I’m with you. And it’s true that’s it’s hard to take account of your own perspective. It’s possible to write a kind of story of Markdown and not make Pandoc a big part of it. But it seems like a glaring omission to not even mention it. It‘s what makes Markdown a real lingua franca, what gives it real power.
- kstrauser 6y ago
  One of the prouder moments in life was convincing a legal team to convert a folder of Word docs to Markdown, check them into GitHub, and set up a CI/CD pipeline to convert them to PDFs to sharing.
  - leephillips 6y ago
    That sounds like quite an accomplishment. At this point I don’t even think I would try.
    - kstrauser 6y ago
      Hard parts: - It's Markdown, not Word - Finding an editor that felt comfortable. (BTW, iA Writer is awesome for this.) Easy parts: - "You never have to care about formatting again!" - "Two people can edit stuff at the same time and we can work out the differences later, instead of playing the 'who has the most recent version?' game." - "Look, you just write text and a nice document with logos pops out the other side, and all of the documents look nearly identical without even trying!" - "Git shows you the full history of every line of this file." - "Hey, cryptographic signatures you can use to irrefutably prove the history of the document!" - "This 'pull request' thing in GitHub shows you exactly the changes you made, like 'track changes' except they're all in one place!"
      - TacticalTable 6y ago
        Seconding iA Writer. I especially enjoy the focus and editing modes.
      - gen220 6y ago
        The easy parts are what make it a selling product. I'd love to see "github for non-developers", that is little more than a markdown-app, with a thin wrapper around some git server and pandoc. Most CMSs implement all the hard stuff (version control, document generation) themselves, but exposing some of the "knobs" of pandoc/markdown/git and letting users run amok is kind of all you need to do, imo. Confluence is kind of like this, but limited to the production of web pages.
maguay 6y ago
Author here, appreciate the feedback! I got caught up a bit in the story of the inspiration behind Markdown (email for Markdown, typewriters for Textile), what I'd assumed was competition between Textile and Markdown (when it turned out they were more connected that you'd think just by seeing two "competing" standards on the market), and how this standard of sorts in Markdown both came from all these inputs but then was flexible enough that everyone can write how they prefer and also that others can take the Markdown idea and run with it and make their own thing. Pandoc would have absolutely been worth mentioning; that's definitely more on the modern look at how Markdown itself got remixed and taken further, but definitely relevant.
- leephillips 6y ago
  Thanks. I know that this kind of article, trying to untangle the threads of a complicated history, is not easy to write.

gen220 6y ago

I feel like pandoc is kind of like a secret club. Once you know about pandoc, you orient all of your prose around it, because it's so powerful and useful. But before you use it, the common opinion is "oh that sounds nice", not "oh let me build all of my workflows around it". It is incredible how far markdown, sed and pandoc (with filters) can take you! I've made websites with breadcrumbs, validated inter-document links and images, on and on; mostly pipelines with sed and pandoc. All of my non-source-code homework in college went through pandoc, and was persisted as markdown source. It makes for clean diffs, and great version history. Anyway. Give pandoc a try if you haven't already.

leephillips 6y ago
I’m with you. And it’s true that’s it’s hard to take account of your own perspective. It’s possible to write a kind of story of Markdown and not make Pandoc a big part of it. But it seems like a glaring omission to not even mention it. It‘s what makes Markdown a real lingua franca, what gives it real power.
kstrauser 6y ago
One of the prouder moments in life was convincing a legal team to convert a folder of Word docs to Markdown, check them into GitHub, and set up a CI/CD pipeline to convert them to PDFs to sharing.
- leephillips 6y ago
  That sounds like quite an accomplishment. At this point I don’t even think I would try.
  - kstrauser 6y ago
    Hard parts: - It's Markdown, not Word - Finding an editor that felt comfortable. (BTW, iA Writer is awesome for this.) Easy parts: - "You never have to care about formatting again!" - "Two people can edit stuff at the same time and we can work out the differences later, instead of playing the 'who has the most recent version?' game." - "Look, you just write text and a nice document with logos pops out the other side, and all of the documents look nearly identical without even trying!" - "Git shows you the full history of every line of this file." - "Hey, cryptographic signatures you can use to irrefutably prove the history of the document!" - "This 'pull request' thing in GitHub shows you exactly the changes you made, like 'track changes' except they're all in one place!"
    - TacticalTable 6y ago
      Seconding iA Writer. I especially enjoy the focus and editing modes.
    - gen220 6y ago
      The easy parts are what make it a selling product. I'd love to see "github for non-developers", that is little more than a markdown-app, with a thin wrapper around some git server and pandoc. Most CMSs implement all the hard stuff (version control, document generation) themselves, but exposing some of the "knobs" of pandoc/markdown/git and letting users run amok is kind of all you need to do, imo. Confluence is kind of like this, but limited to the production of web pages.

maguay 6y ago

Author here, appreciate the feedback! I got caught up a bit in the story of the inspiration behind Markdown (email for Markdown, typewriters for Textile), what I'd assumed was competition between Textile and Markdown (when it turned out they were more connected that you'd think just by seeing two "competing" standards on the market), and how this standard of sorts in Markdown both came from all these inputs but then was flexible enough that everyone can write how they prefer and also that others can take the Markdown idea and run with it and make their own thing. Pandoc would have absolutely been worth mentioning; that's definitely more on the modern look at how Markdown itself got remixed and taken further, but definitely relevant.

leephillips 6y ago
Thanks. I know that this kind of article, trying to untangle the threads of a complicated history, is not easy to write.