general/Markdown.README

   1 Markdown
   2 ========
   3
   4 Version 1.0.1 - Tue 14 Dec 2004
   5
   6 by John Gruber
   7 <http://daringfireball.net/>
   8
   9
  10 Introduction
  11 ------------
  12
  13 Markdown is a text-to-HTML conversion tool for web writers. Markdown
  14 allows you to write using an easy-to-read, easy-to-write plain text
  15 format, then convert it to structurally valid XHTML (or HTML).
  16
  17 Thus, "Markdown" is two things: a plain text markup syntax, and a
  18 software tool, written in Perl, that converts the plain text markup
  19 to HTML.
  20
  21 Markdown works both as a Movable Type plug-in and as a standalone Perl
  22 script -- which means it can also be used as a text filter in BBEdit
  23 (or any other application that supporst filters written in Perl).
  24
  25 Full documentation of Markdown's syntax and configuration options is
  26 available on the web: <http://daringfireball.net/projects/markdown/>.
  27 (Note: this readme file is formatted in Markdown.)
  28
  29
  30
  31 Installation and Requirements
  32 -----------------------------
  33
  34 Markdown requires Perl 5.6.0 or later. Welcome to the 21st Century.
  35 Markdown also requires the standard Perl library module `Digest::MD5`.
  36
  37
  38 ### Movable Type ###
  39
  40 Markdown works with Movable Type version 2.6 or later (including
  41 MT 3.0 or later).
  42
  43 1.  Copy the "Markdown.pl" file into your Movable Type "plugins"
  44     directory. The "plugins" directory should be in the same directory
  45     as "mt.cgi"; if the "plugins" directory doesn't already exist, use
  46     your FTP program to create it. Your installation should look like
  47     this:
  48
  49         (mt home)/plugins/Markdown.pl
  50
  51 2.  Once installed, Markdown will appear as an option in Movable Type's
  52     Text Formatting pop-up menu. This is selectable on a per-post basis.
  53     Markdown translates your posts to HTML when you publish; the posts
  54     themselves are stored in your MT database in Markdown format.
  55
  56 3.  If you also install SmartyPants 1.5 (or later), Markdown will offer
  57     a second text formatting option: "Markdown with SmartyPants". This
  58     option is the same as the regular "Markdown" formatter, except that
  59     automatically uses SmartyPants to create typographically correct
  60     curly quotes, em-dashes, and ellipses. See the SmartyPants web page
  61     for more information: <http://daringfireball.net/projects/smartypants/>
  62
  63 4.  To make Markdown (or "Markdown with SmartyPants") your default
  64     text formatting option for new posts, go to Weblog Config ->
  65     Preferences.
  66
  67 Note that by default, Markdown produces XHTML output. To configure
  68 Markdown to produce HTML 4 output, see "Configuration", below.
  69
  70
  71 ### Blosxom ###
  72
  73 Markdown works with Blosxom version 2.x.
  74
  75 1.  Rename the "Markdown.pl" plug-in to "Markdown" (case is
  76     important). Movable Type requires plug-ins to have a ".pl"
  77     extension; Blosxom forbids it.
  78
  79 2.  Copy the "Markdown" plug-in file to your Blosxom plug-ins folder.
  80     If you're not sure where your Blosxom plug-ins folder is, see the
  81     Blosxom documentation for information.
  82
  83 3.  That's it. The entries in your weblog will now automatically be
  84     processed by Markdown.
  85
  86 4.  If you'd like to apply Markdown formatting only to certain posts,
  87     rather than all of them, see Jason Clark's instructions for using
  88     Markdown in conjunction with Blosxom's Meta plugin:
  89
  90     <http://jclark.org/weblog/WebDev/Blosxom/Markdown.html>
  91
  92
  93 ### BBEdit ###
  94
  95 Markdown works with BBEdit 6.1 or later on Mac OS X. (It also works
  96 with BBEdit 5.1 or later and MacPerl 5.6.1 on Mac OS 8.6 or later.)
  97
  98 1.  Copy the "Markdown.pl" file to appropriate filters folder in your
  99     "BBEdit Support" folder. On Mac OS X, this should be:
 100
 101         BBEdit Support/Unix Support/Unix Filters/
 102
 103     See the BBEdit documentation for more details on the location of
 104     these folders.
 105
 106     You can rename "Markdown.pl" to whatever you wish.
 107
 108 2.  That's it. To use Markdown, select some text in a BBEdit document,
 109     then choose Markdown from the Filters sub-menu in the "#!" menu, or
 110     the Filters floating palette
 111
 112
 113
 114 Configuration
 115 -------------
 116
 117 By default, Markdown produces XHTML output for tags with empty elements.
 118 E.g.:
 119
 120     <br />
 121
 122 Markdown can be configured to produce HTML-style tags; e.g.:
 123
 124     <br>
 125
 126
 127 ### Movable Type ###
 128
 129 You need to use a special `MTMarkdownOptions` container tag in each
 130 Movable Type template where you want HTML 4-style output:
 131
 132     <MTMarkdownOptions output='html4'>
 133         ... put your entry content here ...
 134     </MTMarkdownOptions>
 135
 136 The easiest way to use MTMarkdownOptions is probably to put the
 137 opening tag right after your `<body>` tag, and the closing tag right
 138 before `</body>`.
 139
 140 To suppress Markdown processing in a particular template, i.e. to
 141 publish the raw Markdown-formatted text without translation into
 142 (X)HTML, set the `output` attribute to 'raw':
 143
 144     <MTMarkdownOptions output='raw'>
 145         ... put your entry content here ...
 146     </MTMarkdownOptions>
 147
 148
 149 ### Command-Line ###
 150
 151 Use the `--html4tags` command-line switch to produce HTML output from a
 152 Unix-style command line. E.g.:
 153
 154     % perl Markdown.pl --html4tags foo.text
 155
 156 Type `perldoc Markdown.pl`, or read the POD documentation within the
 157 Markdown.pl source code for more information.
 158
 159
 160
 161 Bugs
 162 ----
 163
 164 To file bug reports or feature requests please send email to:
 165 <markdown@daringfireball.net>.
 166
 167
 168
 169 Version History
 170 ---------------
 171
 172 1.0.1 (14 Dec 2004):
 173
 174 +       Changed the syntax rules for code blocks and spans. Previously,
 175         backslash escapes for special Markdown characters were processed
 176         everywhere other than within inline HTML tags. Now, the contents
 177         of code blocks and spans are no longer processed for backslash
 178         escapes. This means that code blocks and spans are now treated
 179         literally, with no special rules to worry about regarding
 180         backslashes.
 181
 182         **NOTE**: This changes the syntax from all previous versions of
 183         Markdown. Code blocks and spans involving backslash characters
 184         will now generate different output than before.
 185
 186 +       Tweaked the rules for link definitions so that they must occur
 187         within three spaces of the left margin. Thus if you indent a link
 188         definition by four spaces or a tab, it will now be a code block.
 189
 190                    [a]: /url/  "Indented 3 spaces, this is a link def"
 191
 192                     [b]: /url/  "Indented 4 spaces, this is a code block"
 193
 194         **IMPORTANT**: This may affect existing Markdown content if it
 195         contains link definitions indented by 4 or more spaces.
 196
 197 +       Added `>`, `+`, and `-` to the list of backslash-escapable
 198         characters. These should have been done when these characters
 199         were added as unordered list item markers.
 200
 201 +       Trailing spaces and tabs following HTML comments and `<hr/>` tags
 202         are now ignored.
 203
 204 +       Inline links using `<` and `>` URL delimiters weren't working:
 205
 206                 like [this](<http://example.com/>)
 207
 208 +       Added a bit of tolerance for trailing spaces and tabs after
 209         Markdown hr's.
 210
 211 +       Fixed bug where auto-links were being processed within code spans:
 212
 213                 like this: `<http://example.com/>`
 214
 215 +       Sort-of fixed a bug where lines in the middle of hard-wrapped
 216         paragraphs, which lines look like the start of a list item,
 217         would accidentally trigger the creation of a list. E.g. a
 218         paragraph that looked like this:
 219
 220                 I recommend upgrading to version
 221                 8. Oops, now this line is treated
 222                 as a sub-list.
 223
 224         This is fixed for top-level lists, but it can still happen for
 225         sub-lists. E.g., the following list item will not be parsed
 226         properly:
 227
 228                 +       I recommend upgrading to version
 229                         8. Oops, now this line is treated
 230                         as a sub-list.
 231
 232         Given Markdown's list-creation rules, I'm not sure this can
 233         be fixed.
 234
 235 +       Standalone HTML comments are now handled; previously, they'd get
 236         wrapped in a spurious `<p>` tag.
 237
 238 +       Fix for horizontal rules preceded by 2 or 3 spaces.
 239
 240 +       `<hr>` HTML tags in must occur within three spaces of left
 241         margin. (With 4 spaces or a tab, they should be code blocks, but
 242         weren't before this fix.)
 243
 244 +       Capitalized "With" in "Markdown With SmartyPants" for
 245         consistency with the same string label in SmartyPants.pl.
 246         (This fix is specific to the MT plug-in interface.)
 247
 248 +       Auto-linked email address can now optionally contain
 249         a 'mailto:' protocol. I.e. these are equivalent:
 250
 251                 <mailto:user@example.com>
 252                 <user@example.com>
 253
 254 +       Fixed annoying bug where nested lists would wind up with
 255         spurious (and invalid) `<p>` tags.
 256
 257 +       You can now write empty links:
 258
 259                 [like this]()
 260
 261         and they'll be turned into anchor tags with empty href attributes.
 262         This should have worked before, but didn't.
 263
 264 +       `***this***` and `___this___` are now turned into
 265
 266                 <strong><em>this</em></strong>
 267
 268         Instead of
 269
 270                 <strong><em>this</strong></em>
 271
 272         which isn't valid. (Thanks to Michel Fortin for the fix.)
 273
 274 +       Added a new substitution in `_EncodeCode()`: s/\$/&#036;/g; This
 275         is only for the benefit of Blosxom users, because Blosxom
 276         (sometimes?) interpolates Perl scalars in your article bodies.
 277
 278 +       Fixed problem for links defined with urls that include parens, e.g.:
 279
 280                 [1]: http://sources.wikipedia.org/wiki/Middle_East_Policy_(Chomsky)
 281
 282         "Chomsky" was being erroneously treated as the URL's title.
 283
 284 +       At some point during 1.0's beta cycle, I changed every sub's
 285         argument fetching from this idiom:
 286
 287                 my $text = shift;
 288
 289         to:
 290
 291                 my $text = shift || return '';
 292
 293         The idea was to keep Markdown from doing any work in a sub
 294         if the input was empty. This introduced a bug, though:
 295         if the input to any function was the single-character string
 296         "0", it would also evaluate as false and return immediately.
 297         How silly. Now fixed.
 298
 299
 300
 301 Donations
 302 ---------
 303
 304 Donations to support Markdown's development are happily accepted. See:
 305 <http://daringfireball.net/projects/markdown/> for details.
 306
 307
 308
 309 Copyright and License
 310 ---------------------
 311
 312 Copyright (c) 2003-2004 John Gruber
 313 <http://daringfireball.net/>
 314 All rights reserved.
 315
 316 Redistribution and use in source and binary forms, with or without
 317 modification, are permitted provided that the following conditions are
 318 met:
 319
 320 * Redistributions of source code must retain the above copyright notice,
 321   this list of conditions and the following disclaimer.
 322
 323 * Redistributions in binary form must reproduce the above copyright
 324   notice, this list of conditions and the following disclaimer in the
 325   documentation and/or other materials provided with the distribution.
 326
 327 * Neither the name "Markdown" nor the names of its contributors may
 328   be used to endorse or promote products derived from this software
 329   without specific prior written permission.
 330
 331 This software is provided by the copyright holders and contributors "as
 332 is" and any express or implied warranties, including, but not limited
 333 to, the implied warranties of merchantability and fitness for a
 334 particular purpose are disclaimed. In no event shall the copyright owner
 335 or contributors be liable for any direct, indirect, incidental, special,
 336 exemplary, or consequential damages (including, but not limited to,
 337 procurement of substitute goods or services; loss of use, data, or
 338 profits; or business interruption) however caused and on any theory of
 339 liability, whether in contract, strict liability, or tort (including
 340 negligence or otherwise) arising in any way out of the use of this
 341 software, even if advised of the possibility of such damage.