README

   1 ========
   2 Markdown
   3 ========
   4
   5 Version 1.1.10
   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: <https://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     <https://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.10 (08 Jul 2020):
 177
 178 * enhance --wiki "s" option operation
 179
 180 * support new --absroot=prefix option
 181
 182 * document ability to split link references
 183
 184 * hook up fragment only link definitions
 185
 186 * remove markup from <title> value
 187
 188 * update links to https where possible
 189
 190
 191 1.1.9 (15 Dec 2019):
 192
 193 * improve bare fragment URL link handling and add fragment `--base` option
 194
 195 * match block tags case-insensitively and relax `<hr>` matching rules
 196
 197
 198 1.1.8 (22 Nov 2019):
 199
 200 * correct a number of issues with improperly nested markup involving
 201   links, blockquotes, strong and emphasis etc.
 202
 203 * parse nested `[`...`]` and `(`...`)` properly when inside links
 204
 205 * avoid getting confused by nested lists
 206
 207 * allow first blockquote line to be empty
 208
 209 * as-documented single-quote titles in link definitions now work
 210
 211 * when escaping a single-quote use `&#39;` instead of `&apos;`
 212
 213 * ignore control characters in input (other than whitespace)
 214
 215 * wiki links can be processed by providing a new `--wiki` option
 216
 217 * an empty table header row is omitted from the output
 218
 219 * table rows can be joined with a trailing `\` (see syntax.md)
 220
 221 * add several new XML validation options
 222
 223 * perform XML validation and tag sanitation by default (see help)
 224
 225 * tab expansion in shifted backticks-delimited code blocks has
 226   been adjusted to better match expected behavior
 227
 228 * all atx-style header levels now get anchors not just levels 1-3
 229
 230 * internal document "fragment" links `[...](#section)` hook up to
 231   the target section much more reliably now
 232
 233 * backticks-delimited code blocks can now specify a syntax language
 234   name that ends with a `#` character
 235
 236 * more lists that were not being recognized before because they did
 237   not have a preceding blank line are now recognized
 238
 239
 240 1.1.7 (14 Feb 2018):
 241
 242 * Markdown.pl: _PrefixURL more intelligently
 243
 244
 245 1.1.6 (03 Jan 2018):
 246
 247 * Markdown.pl: be more flexible parsing backticks-delimited code blocks
 248
 249 * Markdown.pl: improve XML comment parsing
 250
 251 * Markdown.pl: correct .svg extension matching rule
 252
 253 * Markdown.pl: apply -i and -r options to a and img tags
 254
 255
 256 1.1.5 (07 Dec 2017):
 257
 258 * Markdown.pl: support tables
 259
 260 * Markdown.pl: make sure all alt= and title= text is escaped
 261
 262
 263 1.1.4 (24 Jun 2017):
 264
 265 + Markdown.pl: disallow <dir> and <menu> without --deprecated
 266
 267
 268 1.1.3 (13 Feb 2017):
 269
 270 + Markdown.pl: auto escape '<' of non-tags
 271
 272 + Markdown.pl: do not overlook sibling list items
 273
 274
 275 1.1.2 (19 Jan 2017):
 276
 277 + Markdown.pl: usually (i), (v) and (x) are roman
 278
 279 + Markdown.pl: retain square brackets around footnotes
 280
 281 + Markdown.pl: treat '*' in `<ol>` like last marker
 282
 283 + Markdown.pl: normalize link white space
 284
 285 + Markdown.pl: do not mishandle double list markers redux
 286
 287 + Markdown.pl: recognize two ```-delimited blocks in a row
 288
 289 + Markdown: allow trailing '[]' to be omitted
 290
 291 + Markdown.pl: tweak code block output again
 292
 293
 294 1.1.1 (12 Jan 2017):
 295
 296 + Markdown.pl: support lower-greek ol lists
 297
 298 + Markdown.pl: auto-detect latin-1/utf-8 input always output utf-8
 299   The minimum version of Perl required is now 5.8.0.
 300
 301
 302 1.1.0 (11 Jan 2017):
 303
 304 + Markdown.pl: handle some limited [[wiki style links]]
 305
 306 + Markdown.pl: add --stub, --stylesheet and --tabwidth options
 307
 308 + Markdown.pl: support more list markers
 309
 310 + Markdown.pl: format fancy checkboxes
 311
 312 + Markdown.pl: add anchors and definitions for headers
 313
 314 + Markdown.pl: do not mishandle double list markers
 315
 316 + Markdown.pl: handle non-backticks-delimited code blocks properly
 317
 318 + Markdown.pl: recognize top-level lists better
 319
 320 + Markdown.pl: output deterministic documents
 321
 322 + Markdown.pl: auto linkify without '<'...'>'
 323
 324
 325 1.0.4 (05 Jun 2016):
 326
 327 + Markdown.pl can now be require'd and the Markdown function called
 328   repeatedly by external code.
 329
 330 + Backticks (```) delimited code blocks are now handled better and are
 331   no longer subject to any further accidental processing.
 332
 333
 334 1.0.3 (06 Sep 2015):
 335
 336 + Added support for --htmlroot option to set a URL prefix.
 337
 338 + Relaxed matching rule for non-indented code blocks.
 339
 340 + Added support for --imageroot option to set an img URL prefix.
 341
 342
 343 1.0.2 (03 Sep 2015):
 344
 345 + Added support for -h and --help to display Markdown.pl help.
 346
 347 + Added support for third-level headers using setext-like
 348   underlining using tildes (`~`'s).
 349
 350 + Added support for an optional overline using the same character
 351   as the underline when using setext-style headers.
 352
 353 + Stopped recognizing `_` within words.  The `*` character is still
 354   recognized within words.
 355
 356 + Added support for strike through text using `~~` similarly to the
 357   way strong works using `**`.
 358
 359 + Added support for non-indended code blocks by preceding and following
 360   them with a line consisting of 3 backtick quotes (`` ` ``) or more.
 361
 362
 363 1.0.1 (14 Dec 2004):
 364
 365 + Changed the syntax rules for code blocks and spans. Previously,
 366   backslash escapes for special Markdown characters were processed
 367   everywhere other than within inline HTML tags. Now, the contents
 368   of code blocks and spans are no longer processed for backslash
 369   escapes. This means that code blocks and spans are now treated
 370   literally, with no special rules to worry about regarding
 371   backslashes.
 372
 373   **NOTE**: This changes the syntax from all previous versions of
 374   Markdown. Code blocks and spans involving backslash characters
 375   will now generate different output than before.
 376
 377 + Tweaked the rules for link definitions so that they must occur
 378   within three spaces of the left margin. Thus if you indent a link
 379   definition by four spaces or a tab, it will now be a code block.
 380
 381            [a]: /url/  "Indented 3 spaces, this is a link def"
 382
 383             [b]: /url/  "Indented 4 spaces, this is a code block"
 384
 385   **IMPORTANT**: This may affect existing Markdown content if it
 386   contains link definitions indented by 4 or more spaces.
 387
 388 + Added `>`, `+`, and `-` to the list of backslash-escapable
 389   characters. These should have been done when these characters
 390   were added as unordered list item markers.
 391
 392 + Trailing spaces and tabs following HTML comments and `<hr/>` tags
 393   are now ignored.
 394
 395 + Inline links using `<` and `>` URL delimiters weren't working:
 396
 397           like [this](<http://example.com/>)
 398
 399 + Added a bit of tolerance for trailing spaces and tabs after
 400   Markdown hr's.
 401
 402 + Fixed bug where auto-links were being processed within code spans:
 403
 404           like this: `<http://example.com/>`
 405
 406 + Sort-of fixed a bug where lines in the middle of hard-wrapped
 407   paragraphs, which lines look like the start of a list item,
 408   would accidentally trigger the creation of a list. E.g. a
 409   paragraph that looked like this:
 410
 411           I recommend upgrading to version
 412           8. Oops, now this line is treated
 413           as a sub-list.
 414
 415   This is fixed for top-level lists, but it can still happen for
 416   sub-lists. E.g., the following list item will not be parsed
 417   properly:
 418
 419           + I recommend upgrading to version
 420             8. Oops, now this line is treated
 421             as a sub-list.
 422
 423   Given Markdown's list-creation rules, I'm not sure this can
 424   be fixed.
 425
 426 + Standalone HTML comments are now handled; previously, they'd get
 427   wrapped in a spurious `<p>` tag.
 428
 429 + Fix for horizontal rules preceded by 2 or 3 spaces.
 430
 431 + `<hr>` HTML tags in must occur within three spaces of left
 432   margin. (With 4 spaces or a tab, they should be code blocks, but
 433   weren't before this fix.)
 434
 435 + Capitalized "With" in "Markdown With SmartyPants" for
 436   consistency with the same string label in SmartyPants.pl.
 437   (This fix is specific to the MT plug-in interface.)
 438
 439 + Auto-linked email address can now optionally contain
 440  a 'mailto:' protocol. I.e. these are equivalent:
 441
 442           <mailto:user@example.com>
 443           <user@example.com>
 444
 445 + Fixed annoying bug where nested lists would wind up with
 446   spurious (and invalid) `<p>` tags.
 447
 448 + You can now write empty links:
 449
 450           [like this]()
 451
 452   and they'll be turned into anchor tags with empty href attributes.
 453   This should have worked before, but didn't.
 454
 455 + `***this***` and `___this___` are now turned into
 456
 457           <strong><em>this</em></strong>
 458
 459   Instead of
 460
 461           <strong><em>this</strong></em>
 462
 463   which isn't valid. (Thanks to Michel Fortin for the fix.)
 464
 465 + Added a new substitution in `_EncodeCode()`: `s/\$/&#036;/g`;
 466   this is only for the benefit of Blosxom users, because Blosxom
 467   (sometimes?) interpolates Perl scalars in your article bodies.
 468
 469 + Fixed problem for links defined with urls that include parens, e.g.:
 470
 471           [1]: https://sources.wikipedia.org/wiki/Middle_East_Policy_(Chomsky)
 472
 473   "Chomsky" was being erroneously treated as the URL's title.
 474
 475 + At some point during 1.0's beta cycle, I changed every sub's
 476   argument fetching from this idiom:
 477
 478           my $text = shift;
 479
 480   to:
 481
 482           my $text = shift || return '';
 483
 484   The idea was to keep Markdown from doing any work in a sub
 485   if the input was empty. This introduced a bug, though:
 486   if the input to any function was the single-character string
 487   "0", it would also evaluate as false and return immediately.
 488   How silly. Now fixed.
 489
 490
 491 ---------------------
 492 Copyright and License
 493 ---------------------
 494
 495 Copyright (C) 2003-2004 John Gruber
 496 Copyright (C) 2015-2020 Kyle J. McKay
 497 All rights reserved.
 498
 499 Redistribution and use in source and binary forms, with or without
 500 modification, are permitted provided that the following conditions are
 501 met:
 502
 503 * Redistributions of source code must retain the above copyright notice,
 504   this list of conditions and the following disclaimer.
 505
 506 * Redistributions in binary form must reproduce the above copyright
 507   notice, this list of conditions and the following disclaimer in the
 508   documentation and/or other materials provided with the distribution.
 509
 510 * Neither the name "Markdown" nor the names of its contributors may
 511   be used to endorse or promote products derived from this software
 512   without specific prior written permission.
 513
 514 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
 515 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
 516 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
 517 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
 518 OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 519 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 520 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 521 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 522 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 523 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 524 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.