======== Markdown

Version 1.1.15

John Gruber
Kyle J. McKay

---

Introduction

Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).

Thus, "Markdown" is two things: a plain text markup syntax, and a software tool, written in Perl, that converts the plain text markup to HTML.

Markdown works both as a Movable Type plug-in and as a standalone Perl script -- which means it can also be used as a text filter in BBEdit (or any other application that supporst filters written in Perl).

Full documentation of Markdown's syntax and configuration options is available in the basics.md and syntax.md files. (Note: this readme file and the basics and syntax files are formatted in Markdown.)

---

Installation and Requirements

Markdown requires Perl 5.8.0 or later. Welcome to the 21st Century. Markdown also requires the standard Perl library module Digest::MD5.

As of version 1.1.1, Markdown auto-detects the character set of the input (US-ASCII, ISO-8859-1 and UTF-8 are supported) and always converts the input to UTF-8 when writing the output.

Movable Type

Markdown works with Movable Type version 2.6 or later (including
MT 3.0 or later).

1.  Copy the "Markdown.pl" file into your Movable Type "plugins"
    directory. The "plugins" directory should be in the same directory
    as "mt.cgi"; if the "plugins" directory doesn't already exist, use
    your FTP program to create it. Your installation should look like
    this:

        (mt home)/plugins/Markdown.pl

2.  Once installed, Markdown will appear as an option in Movable Type's
    Text Formatting pop-up menu. This is selectable on a per-post basis.
    Markdown translates your posts to HTML when you publish; the posts
    themselves are stored in your MT database in Markdown format.

3.  If you also install SmartyPants 1.5 (or later), Markdown will offer
    a second text formatting option: "Markdown with SmartyPants". This
    option is the same as the regular "Markdown" formatter, except that
    automatically uses SmartyPants to create typographically correct
    curly quotes, em-dashes, and ellipses. See the SmartyPants web page
    for more information: <https://daringfireball.net/projects/smartypants/>

4.  To make Markdown (or "Markdown with SmartyPants") your default
    text formatting option for new posts, go to Weblog Config ->
    Preferences.

Note that by default, Markdown produces XHTML output. To configure
Markdown to produce HTML 4 output, see "Configuration", below.


Blosxom
~~~~~~~

Markdown works with Blosxom version 2.x.

1.  Rename the "Markdown.pl" plug-in to "Markdown" (case is
    important). Movable Type requires plug-ins to have a ".pl"
    extension; Blosxom forbids it.

2.  Copy the "Markdown" plug-in file to your Blosxom plug-ins folder.
    If you're not sure where your Blosxom plug-ins folder is, see the
    Blosxom documentation for information.

3.  That's it. The entries in your weblog will now automatically be
    processed by Markdown.

4.  If you'd like to apply Markdown formatting only to certain posts,
    rather than all of them, see Jason Clark's instructions for using
    Markdown in conjunction with Blosxom's Meta plugin:

    <https://jclark.org/weblog/WebDev/Blosxom/Markdown.html>


BBEdit
~~~~~~

Markdown works with BBEdit 6.1 or later on Mac OS X. (It also works
with BBEdit 5.1 or later and MacPerl 5.6.1 on Mac OS 8.6 or later.)

1.  Copy the "Markdown.pl" file to appropriate filters folder in your
    "BBEdit Support" folder. On Mac OS X, this should be:

        BBEdit Support/Unix Support/Unix Filters/

    See the BBEdit documentation for more details on the location of
    these folders.

    You can rename "Markdown.pl" to whatever you wish.

2.  That's it. To use Markdown, select some text in a BBEdit document,
    then choose Markdown from the Filters sub-menu in the "#!" menu, or
    the Filters floating palette


-------------
Configuration
-------------

By default, Markdown produces XHTML output for tags with empty elements.
E.g.:

      <br />

Markdown can be configured to produce HTML-style tags; e.g.:

      <br>


Movable Type

You need to use a special MTMarkdownOptions container tag in each Movable Type template where you want HTML 4-style output:

<MTMarkdownOptions output='html4'>
    ... put your entry content here ...
</MTMarkdownOptions>

The easiest way to use MTMarkdownOptions is probably to put the opening tag right after your <body> tag, and the closing tag right before </body>.

To suppress Markdown processing in a particular template, i.e. to publish the raw Markdown-formatted text without translation into (X)HTML, set the output attribute to 'raw':

<MTMarkdownOptions output='raw'>
    ... put your entry content here ...
</MTMarkdownOptions>

Command-Line

Use the `--html4tags` command-line switch to produce HTML output from a
Unix-style command line. E.g.:

    $ perl Markdown.pl --html4tags foo.txt

Type `perldoc Markdown.pl`, or read the POD documentation within the
Markdown.pl source code for more information.


Viewing with w3m

If w3m is available, a Markdown-formatted text file can be viewed like so (change README to the actual name of the Markdown-formatted file to view):

$ perl Markdown.pl --stub README | w3m -T text/html

---

Version History

1.1.15 (15 Aug 2021):

• allow '/' in auto-quoted attribute values

• add new --us-ascii option for 7-bit output

1.1.14 (14 Jun 2021):

• do not start sublist in list marker line

1.1.13 (13 Jun 2021):

• adjust strip-comments options and defaults

• allow backticks-delimited code blocks in lists

• support \ EOL to generate a <br />

• do not mistake table for code block

1.1.12 (17 Mar 2021):

• allow some overlooked table attributes

• do not choke on \n inside attribute values

• better sanitization of href and src attributes

• add more comment stripping options

• clean up closing tag whitespace

• do not choke on <br></br> etc.

• add limited tilde-delimited code block support

• allow target="_blank" rel="nofollow"

• add missing space to implied attributes

1.1.11 (05 Mar 2021):

• new --strip-comments option

• new --keep-abs option

• new --raw-xml and --raw-html options

• new --auto-number option for headers

• new --div option to wrap output in <div>...</div>

• convert named character entities to numeric by default

• add XML comments section to syntax.md

• detail API and ability to "use" Markdown module

• support floating images and <br clear=all>

• recognize wiki style image links

• YAML front matter support

• make -i/-r work on top-level raw html blocks

• avoid accidentally creating nested <a> elements

• ignore junk on end of backticks-delimited code block start line

• strip markup out of implicit anchors

1.1.10 (08 Jul 2020):

• enhance --wiki "s" option operation

• support new --absroot=prefix option

• document ability to split link references

• hook up fragment only link definitions

• remove markup from