The Markdown Mindset(hiltmon.com)
hiltmon.com
The Markdown Mindset
http://www.hiltmon.com/blog/2012/02/20/the-markdown-mindset/
16 comments
My favorite thing about Pandoc is its LaTeX transparency. You can just throw some TeX in there and it will pass it through.
Of course doing this bypasses the possibility of easily converting to HTML, but I've started many research papers writing in Markdown, which has less, let's say, "markup overhead" than LaTeX, previewing the results using pandoc's markdown2pdf utility. Then later when I'm ready to use the proper article template it's an easy step to convert to tex and insert it in the template. It's a nice way to initially not worry about formatting while writing the draft, but pandoc's TeX transparency allows to you insert figures and math-mode markup and still keep the rest of the document in markdown, so it's brilliant.
Also with a little regex script to change "section" into "slide" it's trivial to use markdown and pandoc for generating Beamer presentations, which is way nicer than writing them directly in tex, because of all the enumeration/itemize sections.
Of course doing this bypasses the possibility of easily converting to HTML, but I've started many research papers writing in Markdown, which has less, let's say, "markup overhead" than LaTeX, previewing the results using pandoc's markdown2pdf utility. Then later when I'm ready to use the proper article template it's an easy step to convert to tex and insert it in the template. It's a nice way to initially not worry about formatting while writing the draft, but pandoc's TeX transparency allows to you insert figures and math-mode markup and still keep the rest of the document in markdown, so it's brilliant.
Also with a little regex script to change "section" into "slide" it's trivial to use markdown and pandoc for generating Beamer presentations, which is way nicer than writing them directly in tex, because of all the enumeration/itemize sections.
With a little script? Have you seen the recent pandoc+beamer integration?
To elaborate: in pandoc 1.9 you can just do:
pandoc -t beamer -o presentation.pdfHadn't seen that, thanks!
I love pandoc too, and there are three things that would make me absolutely giddy if they were added:
1) Proper reference support. In LaTeX you can use things like \ref{fig:foo} to insert autonumbers for things like Figure X and Table Y. (Which is awesome, because if you move a figure, you don't have to change all of your numbers around.) There's no Pandoc markdown equivalent, so this gets lost if I convert to e.g. HTML. I have to work around this with a script that looks for this LaTeX snippet and does the counters before passing to Pandoc.
2) Better footnote output for LaTeX. Right now, if you use a [^foo] footnote mark twice, you will get two \footnote{}'s in your LaTeX (and therefore a repeated footnote message in your output) instead of a \footnotemark for the second one.
3) Better metadata. Both Jekyll and MMD are so much more flexible about the metadata you add at the top of a document; Pandoc seems to think the only items I'll ever need are author, title, and date. If I could only add things like addresses, enclosures, salutation lines, and extra variables my templates could adjust to, I could produce more sensible templates for formats like business letters.
1) Proper reference support. In LaTeX you can use things like \ref{fig:foo} to insert autonumbers for things like Figure X and Table Y. (Which is awesome, because if you move a figure, you don't have to change all of your numbers around.) There's no Pandoc markdown equivalent, so this gets lost if I convert to e.g. HTML. I have to work around this with a script that looks for this LaTeX snippet and does the counters before passing to Pandoc.
2) Better footnote output for LaTeX. Right now, if you use a [^foo] footnote mark twice, you will get two \footnote{}'s in your LaTeX (and therefore a repeated footnote message in your output) instead of a \footnotemark for the second one.
3) Better metadata. Both Jekyll and MMD are so much more flexible about the metadata you add at the top of a document; Pandoc seems to think the only items I'll ever need are author, title, and date. If I could only add things like addresses, enclosures, salutation lines, and extra variables my templates could adjust to, I could produce more sensible templates for formats like business letters.
All my notes, like this one:
http://notes.ceondo.com/mongrel2-zmq-paas/
are both available as HTML and PDF thanks to Pandoc. I really really recommend it. It is robust and extremely fast.
Many thanks for the link to pandoc. This is incredibly helpful.
I'd feel a lot better about Markdown if it had an actual spec apart from a pile of perl regexes and a maintainer that hadn't abandoned it. I still use it because it's the lowest-common-denominator, but I have a hard time feeling good about it.
I disagree. I was one of the “six active users” of Infogami before it was shuttered, so perhaps I have a unique perspective…
If Markdown were just a single language, then sure, it’d be nice to have a more precise specification, and a cleaner Word-of-God implementation. But with all the slightly different implementations that now exist, Markdown has become less a language and more a language family. It’s just not useful to talk about standardisation, because it isn’t possible now, and we can’t go back to 2005 when it might’ve been.
Besides, the Daring Fireball implementation is hairy only because it’s designed to “just work”. The handling of “special” cases is the very thing that made the original Markdown so user-friendly and tolerant to variation. That is what Markdown is all about, and why it has become so popular in the first place.
More than a language, it’s a culture—a culture of getting things done without worrying about all the details of formatting. And that, I think, is the point of the article.
If Markdown were just a single language, then sure, it’d be nice to have a more precise specification, and a cleaner Word-of-God implementation. But with all the slightly different implementations that now exist, Markdown has become less a language and more a language family. It’s just not useful to talk about standardisation, because it isn’t possible now, and we can’t go back to 2005 when it might’ve been.
Besides, the Daring Fireball implementation is hairy only because it’s designed to “just work”. The handling of “special” cases is the very thing that made the original Markdown so user-friendly and tolerant to variation. That is what Markdown is all about, and why it has become so popular in the first place.
More than a language, it’s a culture—a culture of getting things done without worrying about all the details of formatting. And that, I think, is the point of the article.
I agree with you. Markdown is meant to be very straightforward and simple, especially since it can be augmented with HTML. MultiMarkdown[1] and GFM[2] exist as variants of Markdown that can do much more, for those who want more... and I'm sure there are other flavors.
[1]http://fletcherpenney.net/multimarkdown/ [2]http://github.github.com/github-flavored-markdown/
[1]http://fletcherpenney.net/multimarkdown/ [2]http://github.github.com/github-flavored-markdown/
The only quibble I have with Markdown is that it shows its web-oriented origins by making it difficult to insert page breaks. That's largely the reason I still use LaTeX for a lot of things. Other than that, though, I fully agree with the author. Plain text is great because 1) it'll always be readable and 2) it forces you to focus on the writing first and the formatting second.
In pandoc you can just use `\newpage`. This will create a page break in LaTeX/PDF output but be ignored in other formats, such as HTML.
> The only quibble I have with Markdown is that it shows its web-oriented origins by making it difficult to insert page breaks.
I'm not sure it's got to do with web-orientation, reStructuredText has targetted a number of builders from the start, yet does not have a native pagebreak directive (you either need to use an extension, or use raw passthrough to the latex builder)
I'm not sure it's got to do with web-orientation, reStructuredText has targetted a number of builders from the start, yet does not have a native pagebreak directive (you either need to use an extension, or use raw passthrough to the latex builder)
I use Markdown everywhere. Including places that don't even support it. My goal is to use it so much that it just makes sense for web-developers to implement it everywhere. Ideally replacing BBCode and such for forums.
Thanks for the article: useful. Until recently almost all of my writing has been plain text (really plain text, and plain text with bits of Latex for documentation and writing books).
I have reverted recently to using RTF a lot for writing work notes, not feeling great about it, but there is a real convenience factor because OS X plays nicely with RTF for Finder instant view and using TextEdit. The bulk of my day to day (non-programming) writing is simply writing out copious daily work notes documenting everything that I do for my customers. I have found that being able to lightly style especially important notes is a large enough advantage to forgo the simplicity of plain text. Also, RTF pastes well into GMail if I want to send a styled text email (which I seldom do).
Based on reading this article, I may try the experiment of keeping my work notes for a single customer in plain text + markdown. The Marked OS X app looks pretty nice, but I am concerned that having two windows open (for editing and for viewing) might slow down what is now a very low ceremony activity.
I have reverted recently to using RTF a lot for writing work notes, not feeling great about it, but there is a real convenience factor because OS X plays nicely with RTF for Finder instant view and using TextEdit. The bulk of my day to day (non-programming) writing is simply writing out copious daily work notes documenting everything that I do for my customers. I have found that being able to lightly style especially important notes is a large enough advantage to forgo the simplicity of plain text. Also, RTF pastes well into GMail if I want to send a styled text email (which I seldom do).
Based on reading this article, I may try the experiment of keeping my work notes for a single customer in plain text + markdown. The Marked OS X app looks pretty nice, but I am concerned that having two windows open (for editing and for viewing) might slow down what is now a very low ceremony activity.
I have also moved to markdown for nearly everything, using pandoc much of the time for output to HTML or PDF. It handles a few things (like citations) a bit better than multi-markdown, although I find multi-markdown tables to be more convenient.
[deleted]
My only problem is that I have no way to do easy footnoting. I had to add my own special HTML code at the bottom of the page, manually verify the link, and so on. Too much work.
There's always reStructuredText/sphinx as a bigger markdown, it has extensive support for linkage including footnotes: http://docutils.sourceforge.net/docs/user/rst/quickref.html#...
Without even delving into Sphinx's extensions.
Without even delving into Sphinx's extensions.
Pandoc extension for footnotes in markdown:
Here is a footnote reference,[^1] and another.[^longnote]
[^1]: Here is the footnote.
[^longnote]: Here's one with multiple blocks.
Here is a footnote reference,[^1] and another.[^longnote]
[^1]: Here is the footnote.
[^longnote]: Here's one with multiple blocks.
FYI MultiMarkdown by Fletcher Penney adds footnotes to standard Markdown, see http://fletcherpenney.net/multimarkdown/
[deleted]
i'm going to do a shameless plug for my github project here because it's quite related but not large enough to dedicate an entire thread to it. it converts DOM > markdown on the client.
https://github.com/leeoniya/reMarked.js
the stated goal is to integrate into existing WYSIWYG html editors to produce markdown output. kind of like Markdownify, but on the client.
yay markdown! :D
https://github.com/leeoniya/reMarked.js
the stated goal is to integrate into existing WYSIWYG html editors to produce markdown output. kind of like Markdownify, but on the client.
yay markdown! :D
I ended up writing a Markdown plugin to a client-side WYSIWYG editor. I needed the ability to store formatted text in MS SQL without either uploaded a binary blob (.doc/.pdf) or using a WYSIWYG with HTML output.
Markdown is exactly what we needed but there weren't any good JS WYSIWYG editors available, so I hacked one together.
Markdown is exactly what we needed but there weren't any good JS WYSIWYG editors available, so I hacked one together.
yep, same requirement here...
We've also installed markdown into Hackful (the HN for Europe) - it's a bit hit and miss though, especially with line breaks http://Hackful.com
yes, line breaks are oddballs. it was especially fun in my testing since every markdown > html converter treats whitespace differently and it's possible to have many extra text nodes as well as leading trailing whitespace, etc. makes testing a faithful round trip very difficult indeed. and then there are different flavors to account for...
These are the benefits of LaTex - logical rather than physical structure. But LaYeX, strikingly beautiful though its output is, has not taken off outside computer science journal articles.
Two opposing points: (1) on reddit, I'll often check the markup result, going back and forth (esp checking URLs - probably less important for other writing), and that seems inefficient. I did the same with LaTeX; (2) when I read the text in the rendered format, I'll pick up different typos, perhaps because the line-spacing and font are different and so my eyes parse it differently (like that trick with "of" doubled at end and start of a line).
For a year, I used a homegrown markup language for uni notes. It was fun to use, seemed helpful, but I think was primarily self-indulgent. Maybe I should try it again - I'm currently using either plaintext for documentation (which isn't really clear enough); or open office Word (which takes forever to startup, doesn't feel accessible (can't just cat or head or tail or more or less or grep it), has non-vi keybindings and generally is a pain (though I complement their job of copying MS Word).
Finally - I'm kinda surprised at markdown's success (and it really is successful). I would expect WYSIWYG to be more user-friendly. I think one factor is that markup is optional in the context where it's been successful (like reddit). In other words, it may be "successful" because (1) it's not actually needed or used much (I mean, typos/grammos are endemic online, right?) (2) it has the gentlest possible learning curve if you do want to use it. Does this mean it would be terrible at more serious uses? Or that it is ideal to disrupt incumbent formatting methods? (disrupt defined: "initially worse at key features, but has features appealing to different users such as convenience/price/accessibility").
It would be interesting to measure the percentage of reddit comments that actually use any markdown at all. I think it would be very low, something like 1-2%
BTW: You had my vote at ZX81 is that wrong?
Two opposing points: (1) on reddit, I'll often check the markup result, going back and forth (esp checking URLs - probably less important for other writing), and that seems inefficient. I did the same with LaTeX; (2) when I read the text in the rendered format, I'll pick up different typos, perhaps because the line-spacing and font are different and so my eyes parse it differently (like that trick with "of" doubled at end and start of a line).
For a year, I used a homegrown markup language for uni notes. It was fun to use, seemed helpful, but I think was primarily self-indulgent. Maybe I should try it again - I'm currently using either plaintext for documentation (which isn't really clear enough); or open office Word (which takes forever to startup, doesn't feel accessible (can't just cat or head or tail or more or less or grep it), has non-vi keybindings and generally is a pain (though I complement their job of copying MS Word).
Finally - I'm kinda surprised at markdown's success (and it really is successful). I would expect WYSIWYG to be more user-friendly. I think one factor is that markup is optional in the context where it's been successful (like reddit). In other words, it may be "successful" because (1) it's not actually needed or used much (I mean, typos/grammos are endemic online, right?) (2) it has the gentlest possible learning curve if you do want to use it. Does this mean it would be terrible at more serious uses? Or that it is ideal to disrupt incumbent formatting methods? (disrupt defined: "initially worse at key features, but has features appealing to different users such as convenience/price/accessibility").
It would be interesting to measure the percentage of reddit comments that actually use any markdown at all. I think it would be very low, something like 1-2%
BTW: You had my vote at ZX81 is that wrong?
For Reddit, you should check out the Reddit Enhancement Suite[1]. It shows you a realtime preview of the post as it'll show up.
[1]: http://redditenhancementsuite.com/
[1]: http://redditenhancementsuite.com/
I like markdown. I dislike the use of brackets () to delimit links. I would have preferred angle brackets <> for links.
Brackets are reserved delimiters in RFC3986 (etc) whereas angle brackets are recommended for delimiting URIs.
Brackets are reserved delimiters in RFC3986 (etc) whereas angle brackets are recommended for delimiting URIs.
I think Markdown avoids angle brackets because angle brackets are frequently used for inline HTML. Sure, Markdown could look at the content of each pair of brackets and try to figure out whether it's a link or a valid HTML tag, but that would introduce a lot of complexity and it won't always work given the diversity of tags and URL schemes.
Since angle brackets are used for "automatic links" in markdown (http://daringfireball.net/projects/markdown/syntax#autolink), a markdown processor already has to look at the contents.
Markdown will let you mention a bare link, e.g. <http://google.com>, and will turn that in a hyperlink with the URL as the linking text.
There is a detailed comparison of pandoc and multimarkdown here: https://github.com/jgm/pandoc/wiki/Pandoc-vs-Multimarkdown.
I really dig Markdown. But this nasty voice inside my head is saying "5 years from now, you're gonna wish you just did this in troff." Or for better and worse, it will evolve into troff.
Well, apparently pandoc can convert Markdown into groff. I don't know if it's troff compatible or if it has diverged, though.
Actually, I'm more concerned with the Markdown syntax and not about how pandoc (nice tool btw) converts it. The issue I see is unchecked feature creep, especially with the variants of markdown we're starting to see.
Reluctantly, I agree that plain text documents are the way to go. I used to be a FrameMaker user.
Reluctantly, I agree that plain text documents are the way to go. I used to be a FrameMaker user.
I totally agree. I just converted my blog to Markdown and Jekyll to be published on GitHub pages. It's awesome to be able to edit blogs in a programmers' editor with all its power and features, integrate code snippets and just push my changes when done.
While much of this was possible before, Markdown is so much easier for writing a programming/tech blog.
While much of this was possible before, Markdown is so much easier for writing a programming/tech blog.
Markdown and Restructured Text are pretty nice. One Markdown annoyance is having to use two spaces at the end of a line to indicate a line break. In some text editors, you can't see the spaces at the end of the line so when you visually scan your Markdown you don't see the line breaks.
One of the nice things about Markdown and reStructuredText is that there is actually a substantial overlap in their markup formatting - it is not too difficult to write documents in the common subset, e.g. this brief guide that I wrote up documenting the common subset: http://gist.github.com/1855764 (you can see the same file interpreted as Markdown and reStructuredText there).
My biggest complaint with the various lightweight/plaintext markup formats is the sheer variety and incompatibility of their markup syntax. Pandoc goes a long way to being able to convert the more popular ones easily, but it would have been nice if there had not been so much gratuitous re-invention of the wheel. It's kind of sad that the MultiMarkdown table format is incompatible with the tables in reStructuredText.
My biggest complaint with the various lightweight/plaintext markup formats is the sheer variety and incompatibility of their markup syntax. Pandoc goes a long way to being able to convert the more popular ones easily, but it would have been nice if there had not been so much gratuitous re-invention of the wheel. It's kind of sad that the MultiMarkdown table format is incompatible with the tables in reStructuredText.
There are "extra" versions of Markdown that can be configured to respect literal line breaks. But if you rely on that, your text would not be compatible with other Markdown parsers.
Markdown's default behavior of disregarding line breaks has two benefits: (1) you can keep your lines short without breaking paragraphs apart, and (2) putting each sentence (or long clause) in its own line plays very nicely with version control systems.
Markdown's default behavior of disregarding line breaks has two benefits: (1) you can keep your lines short without breaking paragraphs apart, and (2) putting each sentence (or long clause) in its own line plays very nicely with version control systems.
Yeah, respecting literal line breaks would break some things, but simply replacing the two spaces at the end of a line with something visible (maybe two underscores if that doesn't break something else) should work.
Pandoc's extended markdown allows you to use a backslash at the end of the line to indicate a line break. (Think of this as a backslash-escaped newline, if you want.)
Shameless plug: we go through HTML + CSS with WeasyPrint to make PDF from Markdown: http://weasyprint.org/
CSS is so much more designer-friendly than LaTeX stylesheets...
CSS is so much more designer-friendly than LaTeX stylesheets...
Anybody use textile here?
I used it before I discovered Markdown. The syntax for code was very annoying: <pre><code></code></pre>. But I still miss the easy distinction between emphasis (underscores) and strong emphasis (asterisks). Markdown makes both symbols behave identically, which I think is wasteful.
We use TextPattern as a lightweight CMS from time to time, and it's Textile. Code just requires "pre." at the start of the first line of code, like so:
I find Markdown best for generating documents/documentation, and Textile best for generating styled web copy.
A *simple* example.
pre. 10 print "hello"
20 goto 10
And that's that, except for @inline@ code.
I find Markdown best for generating documents/documentation, and Textile best for generating styled web copy.
> Code just requires "pre." at the start of the first line of code,
The last time I tried Textile, the "pre." prefix didn't produce the desired effect. But maybe that was a problem with that particular website's CSS. Thanks for correcting me there.
> Markdown can feel limited in its access to readable HTML style indicators.
Fair point. Textile seems to be optimized for producing styled HTML, whereas Markdown tries very hard to make the user forget about the fact that they're using a markup language at all. Even its name suggests that it's meant to be an anti-markup-language markup language.
For example, if you use "pre." in Textile, you're saying that the text should appear exactly as entered (because HTML ignores whitespace by default). Similarly, class attributes are only meaningful in HTML+CSS. On the other hand, when you indent a code block in Markdown, you're not saying anything about presentation, you're just making the code block look nice in plain text while also making a semantic point that the indented block is computer code. Gruber has consistently vetoed any feature that would make Markdown look less like plain text and more like HTML. You would think it odd if a plain text document contained things like "pre." and "(class)".
This makes it easy to compile Markdown to non-HTML formats like LaTeX and even ODF, which MultiMarkdown does. But I can see how Markdown's obsession with plain-text purity can be a limitation if you're trying to add style to a document that you know will be compiled to HTML.
The last time I tried Textile, the "pre." prefix didn't produce the desired effect. But maybe that was a problem with that particular website's CSS. Thanks for correcting me there.
> Markdown can feel limited in its access to readable HTML style indicators.
Fair point. Textile seems to be optimized for producing styled HTML, whereas Markdown tries very hard to make the user forget about the fact that they're using a markup language at all. Even its name suggests that it's meant to be an anti-markup-language markup language.
For example, if you use "pre." in Textile, you're saying that the text should appear exactly as entered (because HTML ignores whitespace by default). Similarly, class attributes are only meaningful in HTML+CSS. On the other hand, when you indent a code block in Markdown, you're not saying anything about presentation, you're just making the code block look nice in plain text while also making a semantic point that the indented block is computer code. Gruber has consistently vetoed any feature that would make Markdown look less like plain text and more like HTML. You would think it odd if a plain text document contained things like "pre." and "(class)".
This makes it easy to compile Markdown to non-HTML formats like LaTeX and even ODF, which MultiMarkdown does. But I can see how Markdown's obsession with plain-text purity can be a limitation if you're trying to add style to a document that you know will be compiled to HTML.
I did the same, used textile before markdown and i use it on textpattern. yes, the code's syntax is was annoying so i prefer to use html instead of textile for code's. I still more familiar with the textile compared with markdowns.
Only in Basecamp, where I wish I could use Markdown.
http://johnmacfarlane.net/pandoc/