Kyle J. McKay
7fce1577a8
|
4 years ago | |
---|---|---|
LICENSE | 7 years ago | |
Markdown.pl | 4 years ago | |
Markdown.pm | 4 years ago | |
README | 4 years ago | |
README.md | 8 years ago | |
basics.md | 4 years ago | |
syntax.md | 4 years ago |
README.md
======== Markdown
Version 1.1.12
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.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
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