1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348
|
# WARNING
This Readme is from the original version of Markdown; not all of the
information contained herein is applicable to Test::Markdown the CPAN
module that includes this file. See the module's POD and the README file for
more information.
Markdown
========
Version 1.0.1 - Tue 14 Dec 2004
by John Gruber
<http://daringfireball.net/>
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: <http://daringfireball.net/projects/markdown/>.
(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: <http://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:
<http://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.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:
<markdown@daringfireball.net>.
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 `<hr/>` tags
are now ignored.
+ Inline links using `<` and `>` URL delimiters weren't working:
like [this](<http://example.com/>)
+ 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: `<http://example.com/>`
+ 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 `<p>` tag.
+ Fix for horizontal rules preceded by 2 or 3 spaces.
+ `<hr>` 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:
<mailto:user@example.com>
<user@example.com>
+ Fixed annoying bug where nested lists would wind up with
spurious (and invalid) `<p>` 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
<strong><em>this</em></strong>
Instead of
<strong><em>this</strong></em>
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:
<http://daringfireball.net/projects/markdown/> for details.
Copyright and License
---------------------
Copyright (c) 2003-2004 John Gruber
<http://daringfireball.net/>
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.
|