README

   1 ========
   2 Markdown
   3 ========
   4
   5 Version 1.1.7
   6
   7 John Gruber
   8 Kyle J. McKay
   9
  10
  11 ------------
  12 Introduction
  13 ------------
  14
  15 Markdown is a text-to-HTML conversion tool for web writers. Markdown
  16 allows you to write using an easy-to-read, easy-to-write plain text
  17 format, then convert it to structurally valid XHTML (or HTML).
  18
  19 Thus, "Markdown" is two things: a plain text markup syntax, and a
  20 software tool, written in Perl, that converts the plain text markup
  21 to HTML.
  22
  23 Markdown works both as a Movable Type plug-in and as a standalone Perl
  24 script -- which means it can also be used as a text filter in BBEdit
  25 (or any other application that supporst filters written in Perl).
  26
  27 Full documentation of Markdown's syntax and configuration options is
  28 available in the `basics.md` and `syntax.md` files.
  29 (Note: this readme file and the basics and syntax files are formatted
  30 in Markdown.)
  31
  32
  33 -----------------------------
  34 Installation and Requirements
  35 -----------------------------
  36
  37 Markdown requires Perl 5.8.0 or later. Welcome to the 21st Century.
  38 Markdown also requires the standard Perl library module `Digest::MD5`.
  39
  40 As of version 1.1.1, Markdown auto-detects the character set of the
  41 input (US-ASCII, ISO-8859-1 and UTF-8 are supported) and always
  42 converts the input to UTF-8 when writing the output.
  43
  44
  45 Movable Type
  46 ~~~~~~~~~~~~
  47
  48 Markdown works with Movable Type version 2.6 or later (including
  49 MT 3.0 or later).
  50
  51 1.  Copy the "Markdown.pl" file into your Movable Type "plugins"
  52     directory. The "plugins" directory should be in the same directory
  53     as "mt.cgi"; if the "plugins" directory doesn't already exist, use
  54     your FTP program to create it. Your installation should look like
  55     this:
  56
  57         (mt home)/plugins/Markdown.pl
  58
  59 2.  Once installed, Markdown will appear as an option in Movable Type's
  60     Text Formatting pop-up menu. This is selectable on a per-post basis.
  61     Markdown translates your posts to HTML when you publish; the posts
  62     themselves are stored in your MT database in Markdown format.
  63
  64 3.  If you also install SmartyPants 1.5 (or later), Markdown will offer
  65     a second text formatting option: "Markdown with SmartyPants". This
  66     option is the same as the regular "Markdown" formatter, except that
  67     automatically uses SmartyPants to create typographically correct
  68     curly quotes, em-dashes, and ellipses. See the SmartyPants web page
  69     for more information: <http://daringfireball.net/projects/smartypants/>
  70
  71 4.  To make Markdown (or "Markdown with SmartyPants") your default
  72     text formatting option for new posts, go to Weblog Config ->
  73     Preferences.
  74
  75 Note that by default, Markdown produces XHTML output. To configure
  76 Markdown to produce HTML 4 output, see "Configuration", below.
  77
  78
  79 Blosxom
  80 ~~~~~~~
  81
  82 Markdown works with Blosxom version 2.x.
  83
  84 1.  Rename the "Markdown.pl" plug-in to "Markdown" (case is
  85     important). Movable Type requires plug-ins to have a ".pl"
  86     extension; Blosxom forbids it.
  87
  88 2.  Copy the "Markdown" plug-in file to your Blosxom plug-ins folder.
  89     If you're not sure where your Blosxom plug-ins folder is, see the
  90     Blosxom documentation for information.
  91
  92 3.  That's it. The entries in your weblog will now automatically be
  93     processed by Markdown.
  94
  95 4.  If you'd like to apply Markdown formatting only to certain posts,
  96     rather than all of them, see Jason Clark's instructions for using
  97     Markdown in conjunction with Blosxom's Meta plugin:
  98
  99     <http://jclark.org/weblog/WebDev/Blosxom/Markdown.html>
 100
 101
 102 BBEdit
 103 ~~~~~~
 104
 105 Markdown works with BBEdit 6.1 or later on Mac OS X. (It also works
 106 with BBEdit 5.1 or later and MacPerl 5.6.1 on Mac OS 8.6 or later.)
 107
 108 1.  Copy the "Markdown.pl" file to appropriate filters folder in your
 109     "BBEdit Support" folder. On Mac OS X, this should be:
 110
 111         BBEdit Support/Unix Support/Unix Filters/
 112
 113     See the BBEdit documentation for more details on the location of
 114     these folders.
 115
 116     You can rename "Markdown.pl" to whatever you wish.
 117
 118 2.  That's it. To use Markdown, select some text in a BBEdit document,
 119     then choose Markdown from the Filters sub-menu in the "#!" menu, or
 120     the Filters floating palette
 121
 122
 123 -------------
 124 Configuration
 125 -------------
 126
 127 By default, Markdown produces XHTML output for tags with empty elements.
 128 E.g.:
 129
 130       <br />
 131
 132 Markdown can be configured to produce HTML-style tags; e.g.:
 133
 134       <br>
 135
 136
 137 Movable Type
 138 ~~~~~~~~~~~~
 139
 140 You need to use a special `MTMarkdownOptions` container tag in each
 141 Movable Type template where you want HTML 4-style output:
 142
 143     <MTMarkdownOptions output='html4'>
 144         ... put your entry content here ...
 145     </MTMarkdownOptions>
 146
 147 The easiest way to use MTMarkdownOptions is probably to put the
 148 opening tag right after your `<body>` tag, and the closing tag right
 149 before `</body>`.
 150
 151 To suppress Markdown processing in a particular template, i.e. to
 152 publish the raw Markdown-formatted text without translation into
 153 (X)HTML, set the `output` attribute to 'raw':
 154
 155     <MTMarkdownOptions output='raw'>
 156         ... put your entry content here ...
 157     </MTMarkdownOptions>
 158
 159
 160 Command-Line
 161 ~~~~~~~~~~~~
 162
 163 Use the `--html4tags` command-line switch to produce HTML output from a
 164 Unix-style command line. E.g.:
 165
 166     % perl Markdown.pl --html4tags foo.txt
 167
 168 Type `perldoc Markdown.pl`, or read the POD documentation within the
 169 Markdown.pl source code for more information.
 170
 171
 172 ---------------
 173 Version History
 174 ---------------
 175
 176 1.1.7 (14 Feb 2018):
 177
 178 * Markdown.pl: _PrefixURL more intelligently
 179
 180
 181 1.1.6 (03 Jan 2018):
 182
 183 * Markdown.pl: be more flexible parsing backticks-delimited code blocks
 184
 185 * Markdown.pl: improve XML comment parsing
 186
 187 * Markdown.pl: correct .svg extension matching rule
 188
 189 * Markdown.pl: apply -i and -r options to a and img tags
 190
 191
 192 1.1.5 (07 Dec 2017):
 193
 194 * Markdown.pl: support tables
 195
 196 * Markdown.pl: make sure all alt= and title= text is escaped
 197
 198
 199 1.1.4 (24 Jun 2017):
 200
 201 + Markdown.pl: disallow <dir> and <menu> without --deprecated
 202
 203
 204 1.1.3 (13 Feb 2017):
 205
 206 + Markdown.pl: auto escape '<' of non-tags
 207
 208 + Markdown.pl: do not overlook sibling list items
 209
 210
 211 1.1.2 (19 Jan 2017):
 212
 213 + Markdown.pl: usually (i), (v) and (x) are roman
 214
 215 + Markdown.pl: retain square brackets around footnotes
 216
 217 + Markdown.pl: treat '*' in `<ol>` like last marker
 218
 219 + Markdown.pl: normalize link white space
 220
 221 + Markdown.pl: do not mishandle double list markers redux
 222
 223 + Markdown.pl: recognize two ```-delimited blocks in a row
 224
 225 + Markdown: allow trailing '[]' to be omitted
 226
 227 + Markdown.pl: tweak code block output again
 228
 229
 230 1.1.1 (12 Jan 2017):
 231
 232 + Markdown.pl: support lower-greek ol lists
 233
 234 + Markdown.pl: auto-detect latin-1/utf-8 input always output utf-8
 235   The minimum version of Perl required is now 5.8.0.
 236
 237
 238 1.1.0 (11 Jan 2017):
 239
 240 + Markdown.pl: handle some limited [[wiki style links]]
 241
 242 + Markdown.pl: add --stub, --stylesheet and --tabwidth options
 243
 244 + Markdown.pl: support more list markers
 245
 246 + Markdown.pl: format fancy checkboxes
 247
 248 + Markdown.pl: add anchors and definitions for headers
 249
 250 + Markdown.pl: do not mishandle double list markers
 251
 252 + Markdown.pl: handle non-backticks-delimited code blocks properly
 253
 254 + Markdown.pl: recognize top-level lists better
 255
 256 + Markdown.pl: output deterministic documents
 257
 258 + Markdown.pl: auto linkify without '<'...'>'
 259
 260
 261 1.0.4 (05 Jun 2016):
 262
 263 + Markdown.pl can now be require'd and the Markdown function called
 264   repeatedly by external code.
 265
 266 + Backticks (```) delimited code blocks are now handled better and are
 267   no longer subject to any further accidental processing.
 268
 269
 270 1.0.3 (06 Sep 2015):
 271
 272 + Added support for --htmlroot option to set a URL prefix.
 273
 274 + Relaxed matching rule for non-indented code blocks.
 275
 276 + Added support for --imageroot option to set an img URL prefix.
 277
 278
 279 1.0.2 (03 Sep 2015):
 280
 281 + Added support for -h and --help to display Markdown.pl help.
 282
 283 + Added support for third-level headers using setext-like
 284   underlining using tildes (`~`'s).
 285
 286 + Added support for an optional overline using the same character
 287   as the underline when using setext-style headers.
 288
 289 + Stopped recognizing `_` within words.  The `*` character is still
 290   recognized within words.
 291
 292 + Added support for strike through text using `~~` similarly to the
 293   way strong works using `**`.
 294
 295 + Added support for non-indended code blocks by preceding and following
 296   them with a line consisting of 3 backtick quotes (`` ` ``) or more.
 297
 298
 299 1.0.1 (14 Dec 2004):
 300
 301 + Changed the syntax rules for code blocks and spans. Previously,
 302   backslash escapes for special Markdown characters were processed
 303   everywhere other than within inline HTML tags. Now, the contents
 304   of code blocks and spans are no longer processed for backslash
 305   escapes. This means that code blocks and spans are now treated
 306   literally, with no special rules to worry about regarding
 307   backslashes.
 308
 309   **NOTE**: This changes the syntax from all previous versions of
 310   Markdown. Code blocks and spans involving backslash characters
 311   will now generate different output than before.
 312
 313 + Tweaked the rules for link definitions so that they must occur
 314   within three spaces of the left margin. Thus if you indent a link
 315   definition by four spaces or a tab, it will now be a code block.
 316
 317            [a]: /url/  "Indented 3 spaces, this is a link def"
 318
 319             [b]: /url/  "Indented 4 spaces, this is a code block"
 320
 321   **IMPORTANT**: This may affect existing Markdown content if it
 322   contains link definitions indented by 4 or more spaces.
 323
 324 + Added `>`, `+`, and `-` to the list of backslash-escapable
 325   characters. These should have been done when these characters
 326   were added as unordered list item markers.
 327
 328 + Trailing spaces and tabs following HTML comments and `<hr/>` tags
 329   are now ignored.
 330
 331 + Inline links using `<` and `>` URL delimiters weren't working:
 332
 333           like [this](<http://example.com/>)
 334
 335 + Added a bit of tolerance for trailing spaces and tabs after
 336   Markdown hr's.
 337
 338 + Fixed bug where auto-links were being processed within code spans:
 339
 340           like this: `<http://example.com/>`
 341
 342 + Sort-of fixed a bug where lines in the middle of hard-wrapped
 343   paragraphs, which lines look like the start of a list item,
 344   would accidentally trigger the creation of a list. E.g. a
 345   paragraph that looked like this:
 346
 347           I recommend upgrading to version
 348           8. Oops, now this line is treated
 349           as a sub-list.
 350
 351   This is fixed for top-level lists, but it can still happen for
 352   sub-lists. E.g., the following list item will not be parsed
 353   properly:
 354
 355           + I recommend upgrading to version
 356             8. Oops, now this line is treated
 357             as a sub-list.
 358
 359   Given Markdown's list-creation rules, I'm not sure this can
 360   be fixed.
 361
 362 + Standalone HTML comments are now handled; previously, they'd get
 363   wrapped in a spurious `<p>` tag.
 364
 365 + Fix for horizontal rules preceded by 2 or 3 spaces.
 366
 367 + `<hr>` HTML tags in must occur within three spaces of left
 368   margin. (With 4 spaces or a tab, they should be code blocks, but
 369   weren't before this fix.)
 370
 371 + Capitalized "With" in "Markdown With SmartyPants" for
 372   consistency with the same string label in SmartyPants.pl.
 373   (This fix is specific to the MT plug-in interface.)
 374
 375 + Auto-linked email address can now optionally contain
 376  a 'mailto:' protocol. I.e. these are equivalent:
 377
 378           <mailto:user@example.com>
 379           <user@example.com>
 380
 381 + Fixed annoying bug where nested lists would wind up with
 382   spurious (and invalid) `<p>` tags.
 383
 384 + You can now write empty links:
 385
 386           [like this]()
 387
 388   and they'll be turned into anchor tags with empty href attributes.
 389   This should have worked before, but didn't.
 390
 391 + `***this***` and `___this___` are now turned into
 392
 393           <strong><em>this</em></strong>
 394
 395   Instead of
 396
 397           <strong><em>this</strong></em>
 398
 399   which isn't valid. (Thanks to Michel Fortin for the fix.)
 400
 401 + Added a new substitution in `_EncodeCode()`: `s/\$/&#036;/g`;
 402   this is only for the benefit of Blosxom users, because Blosxom
 403   (sometimes?) interpolates Perl scalars in your article bodies.
 404
 405 + Fixed problem for links defined with urls that include parens, e.g.:
 406
 407           [1]: http://sources.wikipedia.org/wiki/Middle_East_Policy_(Chomsky)
 408
 409   "Chomsky" was being erroneously treated as the URL's title.
 410
 411 + At some point during 1.0's beta cycle, I changed every sub's
 412   argument fetching from this idiom:
 413
 414           my $text = shift;
 415
 416   to:
 417
 418           my $text = shift || return '';
 419
 420   The idea was to keep Markdown from doing any work in a sub
 421   if the input was empty. This introduced a bug, though:
 422   if the input to any function was the single-character string
 423   "0", it would also evaluate as false and return immediately.
 424   How silly. Now fixed.
 425
 426
 427 ---------------------
 428 Copyright and License
 429 ---------------------
 430
 431 Copyright (C) 2003-2004 John Gruber
 432 Copyright (C) 2015-2018 Kyle J. McKay
 433 All rights reserved.
 434
 435 Redistribution and use in source and binary forms, with or without
 436 modification, are permitted provided that the following conditions are
 437 met:
 438
 439 * Redistributions of source code must retain the above copyright notice,
 440   this list of conditions and the following disclaimer.
 441
 442 * Redistributions in binary form must reproduce the above copyright
 443   notice, this list of conditions and the following disclaimer in the
 444   documentation and/or other materials provided with the distribution.
 445
 446 * Neither the name "Markdown" nor the names of its contributors may
 447   be used to endorse or promote products derived from this software
 448   without specific prior written permission.
 449
 450 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
 451 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
 452 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
 453 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
 454 OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 455 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 456 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 457 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 458 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 459 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 460 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.