descriptionMarkdown text-to-HTML conversion tool
ownermackyle@fastmail.com
last changeSun, 15 Aug 2021 20:24:31 +0000 (15 13:24 -0700)
content tags
add:
README.md

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):

1.1.14 (14 Jun 2021):

1.1.13 (13 Jun 2021):

1.1.12 (17 Mar 2021):

1.1.11 (05 Mar 2021):

1.1.10 (08 Jul 2020):

1.1.9 (15 Dec 2019):

1.1.8 (22 Nov 2019):

1.1.7 (14 Feb 2018):

1.1.6 (03 Jan 2018):

1.1.5 (07 Dec 2017):

1.1.4 (24 Jun 2017):

1.1.3 (13 Feb 2017):

1.1.2 (19 Jan 2017):

1.1.1 (12 Jan 2017):

1.1.0 (11 Jan 2017):

1.0.4 (05 Jun 2016):

1.0.3 (06 Sep 2015):

1.0.2 (03 Sep 2015):

1.0.1 (14 Dec 2004):

Copyright (C) 2003-2004 John Gruber
Copyright (C) 2015-2021 Kyle J. McKay
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

shortlog
2021-08-15 Kyle J. McKayMarkdown version 1.1.15mastermarkdown_1.1.15
2021-08-14 Kyle J. McKayREADME: clean up old version history entries
2021-08-14 Kyle J. McKayMarkdown.pl: clarify help text for --no-validate-xml...
2021-08-12 Kyle J. McKayMarkdown.pl: add new --us-ascii option for 7-bit output
2021-08-03 Kyle J. McKayMarkdown.pl: allow '/' in auto-quoted attribute values
2021-08-03 Kyle J. McKayMarkdown.pl: improve readability of a few regexs
2021-08-03 Kyle J. McKayMarkdown.pl: next version is 1.1.15
2021-06-14 Kyle J. McKayMarkdown version 1.1.14markdown_1.1.14
2021-06-14 Kyle J. McKayMarkdown.pl: do not start sublist in list marker line
2021-06-14 Kyle J. McKayMarkdown.pl: tidy up some regex options
2021-06-14 Kyle J. McKayMarkdown.pl: next version is 1.1.14
2021-06-13 Kyle J. McKayMarkdown version 1.1.13markdown_1.1.13
2021-06-13 Kyle J. McKayMarkdown.pl: adjust strip-comments options and defaults
2021-06-13 Kyle J. McKayMarkdown: allow backticks-delimited code blocks in...
2021-06-12 Kyle J. McKayMarkdown: support `\` EOL to generate a `<br />`
2021-06-06 Kyle J. McKaysyntax.md: mention headers supersede horizontal rules
...
tags
2 years ago markdown_1.1.15 Markdown 1.1.15
2 years ago markdown_1.1.14 Markdown 1.1.14
2 years ago markdown_1.1.13 Markdown 1.1.13
3 years ago markdown_1.1.12 Markdown 1.1.12
3 years ago markdown_1.1.11 Markdown 1.1.11
3 years ago mackyle-gpg-pub GPG key used to sign markdown stuff
3 years ago markdown_1.1.10 Markdown 1.1.10
4 years ago markdown_1.1.9 Markdown 1.1.9
4 years ago markdown_1.1.8 Markdown 1.1.8
6 years ago markdown_1.1.7 Markdown 1.1.7
6 years ago markdown_1.1.6 Markdown 1.1.6
6 years ago markdown_1.1.5 Markdown 1.1.5
6 years ago markdown_1.1.4 Markdown 1.1.4
7 years ago markdown_1.1.3 Markdown 1.1.3
7 years ago markdown_1.1.2 Markdown 1.1.2
7 years ago markdown_1.1.1 Markdown 1.1.1
...
heads
2 years ago master