X-Git-Url: https://git.stderr.nl/gitweb?p=matthijs%2Fupstream%2Fblosxom-plugins.git;a=blobdiff_plain;f=general%2FMarkdown.README;fp=general%2FMarkdown.README;h=6fbb95fd2167782d41b0024c8933d58cd1e5fe48;hp=0000000000000000000000000000000000000000;hb=67e5bf3facd593833bd47045602cf016192a9065;hpb=f0e04e40d8c0d902eab73fe3feede1607379ed35 diff --git a/general/Markdown.README b/general/Markdown.README new file mode 100644 index 0000000..6fbb95f --- /dev/null +++ b/general/Markdown.README @@ -0,0 +1,341 @@ +Markdown +======== + +Version 1.0.1 - Tue 14 Dec 2004 + +by John Gruber + + + +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 on the web: . +(Note: this readme file is formatted in Markdown.) + + + +Installation and Requirements +----------------------------- + +Markdown requires Perl 5.6.0 or later. Welcome to the 21st Century. +Markdown also requires the standard Perl library module `Digest::MD5`. + + +### 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: + +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: + + + + +### 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.: + +
+ +Markdown can be configured to produce HTML-style tags; e.g.: + +
+ + +### Movable Type ### + +You need to use a special `MTMarkdownOptions` container tag in each +Movable Type template where you want HTML 4-style output: + + + ... put your entry content here ... + + +The easiest way to use MTMarkdownOptions is probably to put the +opening tag right after your `` tag, and the closing tag right +before ``. + +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': + + + ... put your entry content here ... + + + +### 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.text + +Type `perldoc Markdown.pl`, or read the POD documentation within the +Markdown.pl source code for more information. + + + +Bugs +---- + +To file bug reports or feature requests please send email to: +. + + + +Version History +--------------- + +1.0.1 (14 Dec 2004): + ++ Changed the syntax rules for code blocks and spans. Previously, + backslash escapes for special Markdown characters were processed + everywhere other than within inline HTML tags. Now, the contents + of code blocks and spans are no longer processed for backslash + escapes. This means that code blocks and spans are now treated + literally, with no special rules to worry about regarding + backslashes. + + **NOTE**: This changes the syntax from all previous versions of + Markdown. Code blocks and spans involving backslash characters + will now generate different output than before. + ++ Tweaked the rules for link definitions so that they must occur + within three spaces of the left margin. Thus if you indent a link + definition by four spaces or a tab, it will now be a code block. + + [a]: /url/ "Indented 3 spaces, this is a link def" + + [b]: /url/ "Indented 4 spaces, this is a code block" + + **IMPORTANT**: This may affect existing Markdown content if it + contains link definitions indented by 4 or more spaces. + ++ Added `>`, `+`, and `-` to the list of backslash-escapable + characters. These should have been done when these characters + were added as unordered list item markers. + ++ Trailing spaces and tabs following HTML comments and `
` tags + are now ignored. + ++ Inline links using `<` and `>` URL delimiters weren't working: + + like [this]() + ++ Added a bit of tolerance for trailing spaces and tabs after + Markdown hr's. + ++ Fixed bug where auto-links were being processed within code spans: + + like this: `` + ++ Sort-of fixed a bug where lines in the middle of hard-wrapped + paragraphs, which lines look like the start of a list item, + would accidentally trigger the creation of a list. E.g. a + paragraph that looked like this: + + I recommend upgrading to version + 8. Oops, now this line is treated + as a sub-list. + + This is fixed for top-level lists, but it can still happen for + sub-lists. E.g., the following list item will not be parsed + properly: + + + I recommend upgrading to version + 8. Oops, now this line is treated + as a sub-list. + + Given Markdown's list-creation rules, I'm not sure this can + be fixed. + ++ Standalone HTML comments are now handled; previously, they'd get + wrapped in a spurious `

` tag. + ++ Fix for horizontal rules preceded by 2 or 3 spaces. + ++ `

` HTML tags in must occur within three spaces of left + margin. (With 4 spaces or a tab, they should be code blocks, but + weren't before this fix.) + ++ Capitalized "With" in "Markdown With SmartyPants" for + consistency with the same string label in SmartyPants.pl. + (This fix is specific to the MT plug-in interface.) + ++ Auto-linked email address can now optionally contain + a 'mailto:' protocol. I.e. these are equivalent: + + + + ++ Fixed annoying bug where nested lists would wind up with + spurious (and invalid) `

` tags. + ++ You can now write empty links: + + [like this]() + + and they'll be turned into anchor tags with empty href attributes. + This should have worked before, but didn't. + ++ `***this***` and `___this___` are now turned into + + this + + Instead of + + this + + which isn't valid. (Thanks to Michel Fortin for the fix.) + ++ Added a new substitution in `_EncodeCode()`: s/\$/$/g; This + is only for the benefit of Blosxom users, because Blosxom + (sometimes?) interpolates Perl scalars in your article bodies. + ++ Fixed problem for links defined with urls that include parens, e.g.: + + [1]: http://sources.wikipedia.org/wiki/Middle_East_Policy_(Chomsky) + + "Chomsky" was being erroneously treated as the URL's title. + ++ At some point during 1.0's beta cycle, I changed every sub's + argument fetching from this idiom: + + my $text = shift; + + to: + + my $text = shift || return ''; + + The idea was to keep Markdown from doing any work in a sub + if the input was empty. This introduced a bug, though: + if the input to any function was the single-character string + "0", it would also evaluate as false and return immediately. + How silly. Now fixed. + + + +Donations +--------- + +Donations to support Markdown's development are happily accepted. See: + for details. + + + +Copyright and License +--------------------- + +Copyright (c) 2003-2004 John Gruber + +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + +* Redistributions of source code must retain the above copyright notice, + this list of conditions and the following disclaimer. + +* Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + +* Neither the name "Markdown" nor the names of its contributors may + be used to endorse or promote products derived from this software + without specific prior written permission. + +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.