mirror of
https://github.com/KnpLabs/KnpMarkdownBundle.git
synced 2024-05-19 05:46:33 +02:00
192 lines
8.5 KiB
HTML
192 lines
8.5 KiB
HTML
<h2>Download</h2>
|
|
|
|
<p><a href="http://daringfireball.net/projects/downloads/Markdown_1.0.1.zip">Markdown 1.0.1</a> (18 KB) -- 17 Dec 2004</p>
|
|
|
|
<h2>Introduction</h2>
|
|
|
|
<p>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).</p>
|
|
|
|
<p>Thus, "Markdown" is two things: (1) a plain text formatting syntax;
|
|
and (2) a software tool, written in Perl, that converts the plain text
|
|
formatting to HTML. See the <a href="/projects/markdown/syntax">Syntax</a> page for details pertaining to
|
|
Markdown's formatting syntax. You can try it out, right now, using the
|
|
online <a href="/projects/markdown/dingus">Dingus</a>.</p>
|
|
|
|
<p>The overriding design goal for Markdown's formatting syntax is to make
|
|
it as readable as possible. The idea is that a Markdown-formatted
|
|
document should be publishable as-is, as plain text, without looking
|
|
like it's been marked up with tags or formatting instructions. While
|
|
Markdown's syntax has been influenced by several existing text-to-HTML
|
|
filters, the single biggest source of inspiration for Markdown's
|
|
syntax is the format of plain text email.</p>
|
|
|
|
<p>The best way to get a feel for Markdown's formatting syntax is simply
|
|
to look at a Markdown-formatted document. For example, you can view
|
|
the Markdown source for the article text on this page here:
|
|
<a href="http://daringfireball.net/projects/markdown/index.text">http://daringfireball.net/projects/markdown/index.text</a></p>
|
|
|
|
<p>(You can use this '.text' suffix trick to view the Markdown source for
|
|
the content of each of the pages in this section, e.g. the
|
|
<a href="/projects/markdown/syntax.text">Syntax</a> and <a href="/projects/markdown/license.text">License</a> pages.)</p>
|
|
|
|
<p>Markdown is free software, available under a BSD-style open source
|
|
license. See the <a href="/projects/markdown/license">License</a> page for more information.</p>
|
|
|
|
<h2>Discussion List <a id="discussion-list" /></h2>
|
|
|
|
<p>I've set up a public <a href="http://six.pairlist.net/mailman/listinfo/markdown-discuss">mailing list for discussion about Markdown</a>.
|
|
Any topic related to Markdown -- both its formatting syntax and
|
|
its software -- is fair game for discussion. Anyone who is interested
|
|
is welcome to join.</p>
|
|
|
|
<p>It's my hope that the mailing list will lead to good ideas for future
|
|
improvements to Markdown.</p>
|
|
|
|
<h2>Installation and Requirements <a id="install" /></h2>
|
|
|
|
<p>Markdown requires Perl 5.6.0 or later. Welcome to the 21st Century.
|
|
Markdown also requires the standard Perl library module <a href="http://search.cpan.org/dist/Digest-MD5/MD5.pm">Digest::MD5</a>, which is probably already installed on your server.</p>
|
|
|
|
<h3>Movable Type</h3>
|
|
|
|
<p>Markdown works with Movable Type version 2.6 or later (including
|
|
Movable Type 3.0).</p>
|
|
|
|
<ol>
|
|
<li><p>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:</p>
|
|
|
|
<pre><code>(mt home)/plugins/Markdown.pl
|
|
</code></pre></li>
|
|
<li><p>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:</p>
|
|
|
|
<p><img src="/graphics/markdown/mt_textformat_menu.png" alt="Screenshot of Movable Type 'Text Formatting' Menu" /></p>
|
|
|
|
<p>Markdown translates your posts to HTML when you publish; the posts
|
|
themselves are stored in your MT database in Markdown format.</p></li>
|
|
<li><p>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 it automatically uses SmartyPants to create
|
|
typographically correct curly quotes, em-dashes, and ellipses. See
|
|
the <a href="http://daringfireball.net/projects/smartypants/">SmartyPants web page</a> for more information.</p></li>
|
|
<li><p>To make Markdown (or "Markdown With SmartyPants") your default
|
|
text formatting option for new posts, go to Weblog Config:
|
|
Preferences.</p></li>
|
|
</ol>
|
|
|
|
<p>Note that by default, Markdown produces XHTML output. To configure
|
|
Markdown to produce HTML 4 output, see "Configuration", below.</p>
|
|
|
|
<h3>Blosxom</h3>
|
|
|
|
<p>Markdown works with Blosxom version 2.0 or later.</p>
|
|
|
|
<ol>
|
|
<li><p>Rename the "Markdown.pl" plug-in to "Markdown" (case is
|
|
important). Movable Type requires plug-ins to have a ".pl"
|
|
extension; Blosxom forbids it.</p></li>
|
|
<li><p>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.</p></li>
|
|
<li><p>That's it. The entries in your weblog will now automatically be
|
|
processed by Markdown.</p></li>
|
|
<li><p>If you'd like to apply Markdown formatting only to certain
|
|
posts, rather than all of them, Markdown can optionally be used in
|
|
conjunction with Blosxom's <a href="http://www.blosxom.com/plugins/meta/meta.htm">Meta</a> plug-in. First, install the
|
|
Meta plug-in. Next, open the Markdown plug-in file in a text
|
|
editor, and set the configuration variable <code>$g_blosxom_use_meta</code>
|
|
to 1. Then, simply include a "<code>meta-markup: Markdown</code>" header line
|
|
at the top of each post you compose using Markdown.</p></li>
|
|
</ol>
|
|
|
|
<h3>BBEdit</h3>
|
|
|
|
<p>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. If
|
|
you're running Mac OS X 10.2 (Jaguar), you may need to install the
|
|
Perl module <a href="http://search.cpan.org/dist/Digest-MD5/MD5.pm">Digest::MD5</a> from CPAN; Digest::MD5 comes
|
|
pre-installed on Mac OS X 10.3 (Panther).</p>
|
|
|
|
<ol>
|
|
<li><p>Copy the "Markdown.pl" file to appropriate filters folder in your
|
|
"BBEdit Support" folder. On Mac OS X, this should be:</p>
|
|
|
|
<pre><code>BBEdit Support/Unix Support/Unix Filters/
|
|
</code></pre>
|
|
|
|
<p>See the BBEdit documentation for more details on the location of
|
|
these folders.</p>
|
|
|
|
<p>You can rename "Markdown.pl" to whatever you wish.</p></li>
|
|
<li><p>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</p></li>
|
|
</ol>
|
|
|
|
<h2>Configuration <a id="configuration"></a></h2>
|
|
|
|
<p>By default, Markdown produces XHTML output for tags with empty elements.
|
|
E.g.:</p>
|
|
|
|
<pre><code><br />
|
|
</code></pre>
|
|
|
|
<p>Markdown can be configured to produce HTML-style tags; e.g.:</p>
|
|
|
|
<pre><code><br>
|
|
</code></pre>
|
|
|
|
<h3>Movable Type</h3>
|
|
|
|
<p>You need to use a special <code>MTMarkdownOptions</code> container tag in each
|
|
Movable Type template where you want HTML 4-style output:</p>
|
|
|
|
<pre><code><MTMarkdownOptions output='html4'>
|
|
... put your entry content here ...
|
|
</MTMarkdownOptions>
|
|
</code></pre>
|
|
|
|
<p>The easiest way to use MTMarkdownOptions is probably to put the
|
|
opening tag right after your <code><body></code> tag, and the closing tag right
|
|
before <code></body></code>.</p>
|
|
|
|
<p>To suppress Markdown processing in a particular template, i.e. to
|
|
publish the raw Markdown-formatted text without translation into
|
|
(X)HTML, set the <code>output</code> attribute to 'raw':</p>
|
|
|
|
<pre><code><MTMarkdownOptions output='raw'>
|
|
... put your entry content here ...
|
|
</MTMarkdownOptions>
|
|
</code></pre>
|
|
|
|
<h3>Command-Line</h3>
|
|
|
|
<p>Use the <code>--html4tags</code> command-line switch to produce HTML output from a
|
|
Unix-style command line. E.g.:</p>
|
|
|
|
<pre><code>% perl Markdown.pl --html4tags foo.text
|
|
</code></pre>
|
|
|
|
<p>Type <code>perldoc Markdown.pl</code>, or read the POD documentation within the
|
|
Markdown.pl source code for more information.</p>
|
|
|
|
<h2>Acknowledgements <a id="acknowledgements" /></h2>
|
|
|
|
<p><a href="http://www.aaronsw.com/">Aaron Swartz</a> deserves a tremendous amount of credit for helping to
|
|
design Markdown's formatting syntax. Markdown is <em>much</em> better thanks
|
|
to Aaron's ideas, feedback, and testing. Also, Aaron's <a href="http://www.aaronsw.com/2002/html2text/">html2text</a>
|
|
is a very handy (and free) utility for turning HTML into
|
|
Markdown-formatted plain text.</p>
|
|
|
|
<p><a href="http://bumppo.net/">Nathaniel Irons</a>, <a href="http://hivelogic.com/">Dan Benjamin</a>, <a href="http://waferbaby.com/">Daniel Bogan</a>, and <a href="http://pressedpants.com/">Jason Perkins</a>
|
|
also deserve thanks for their feedback.</p>
|
|
|
|
<p><a href="http://www.michelf.com/projects/php-markdown/">Michel Fortin</a> has ported Markdown to PHP; it's a splendid port, and highly recommended for anyone looking for a PHP implementation of Markdown.</p>
|