
The Markdown Mindset - hiltmon
http://www.hiltmon.com/blog/2012/02/20/the-markdown-mindset/
======
dfc
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/>

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

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

~~~
fiddlosopher
To elaborate: in pandoc 1.9 you can just do:

    
    
        pandoc -t beamer -o presentation.pdf

------
technomancy
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
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
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/>

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

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

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

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

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

~~~
masklinn
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#...](http://docutils.sourceforge.net/docs/user/rst/quickref.html#footnotes)

Without even delving into Sphinx's extensions.

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

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

~~~
leeoniya
yep, same requirement here...

------
6ren
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?

~~~
icebraining
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/>

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

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

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

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

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

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

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

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

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

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

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

~~~
fiddlosopher
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.)

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

------
wildtype
Anybody use textile here?

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

~~~
kijin
> _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.

