The Markdown Mindset

http://www.hiltmon.com/blog/2012/02/20/the-markdown-mindset/

by hiltmon • 14 years ago

111 49 14 years ago

phren0logy• 14 years ago

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.

kiba• 14 years ago

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.

dfc3• 14 years ago

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.

hiltmon• 14 years ago

FYI MultiMarkdown by Fletcher Penney adds footnotes to standard Markdown, see http://fletcherpenney.net/multimarkdown/

masklinn2• 14 years ago

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.

_rs• 14 years ago

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.

quanticle• 14 years ago

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.

fiddlosopher5• 14 years ago

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.

masklinn2• 14 years ago

> 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)

dfc3• 14 years ago

If you like markdown you will LOVE using pandoc. I can't stress how wonderful things have been since I moved to pandoc.

http://johnmacfarlane.net/pandoc/

radarsat12• 14 years ago

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.

dfc3• 14 years ago

With a little script? Have you seen the recent pandoc+beamer integration?

pak• 14 years ago

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.

Craiggybear• 14 years ago

Many thanks for the link to pandoc. This is incredibly helpful.

Loic• 14 years ago

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.

DanBC• 14 years ago

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.

kijin4• 14 years ago

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.

fiddlosopher5• 14 years ago

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.

unwiredben• 14 years ago

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.

fiddlosopher5• 14 years ago

There is a detailed comparison of pandoc and multimarkdown here: https://github.com/jgm/pandoc/wiki/Pandoc-vs-Multimarkdown.

wildtype2• 14 years ago

Anybody use textile here?

kijin4• 14 years ago

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.

Terretta• 14 years ago

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:

    A *simple* example.
    
    pre. 10 print "hello"
    20 goto 10
    
    And that's that, except for @inline@ code.

Paste that into http://textile.thresholdstate.com/ with no leading spaces. If one is fluent in Textile, Markdown can feel limited in its access to readable HTML style indicators. For example, I appreciate the %(class)this is a styled span% feature.

I find Markdown best for generating documents/documentation, and Textile best for generating styled web copy.

rachelbaker• 14 years ago

Only in Basecamp, where I wish I could use Markdown.

mcantelon2• 14 years ago

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.

kijin4• 14 years ago

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.

mcantelon2• 14 years ago

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.

sashametro• 14 years ago

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.

kickingvegas2• 14 years ago

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.

icebraining2• 14 years ago

Well, apparently pandoc can convert Markdown into groff. I don't know if it's troff compatible or if it has diverged, though.

kickingvegas2• 14 years ago

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.

leeoniya3• 14 years ago

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

rayhano• 14 years ago

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

leeoniya3• 14 years ago

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...

saryant• 14 years ago

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.

leeoniya3• 14 years ago

yep, same requirement here...

SimonSapin• 14 years ago

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...

6ren• 14 years ago

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?

icebraining2• 14 years ago

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/

technomancy• 14 years ago

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.

evincarofautumn• 14 years ago

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.

avree• 14 years ago

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/

antonyme• 14 years ago

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.

mark_l_watson• 14 years ago

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.

The Markdown Mindset

Related Stories