|
| 1 | +Markdown |
| 2 | +======== |
| 3 | + |
| 4 | +Version 1.0.1 - Tue 14 Dec 2004 |
| 5 | + |
| 6 | +by John Gruber |
| 7 | +<http://daringfireball.net/> |
| 8 | + |
| 9 | + |
| 10 | +Introduction |
| 11 | +------------ |
| 12 | + |
| 13 | +Markdown is a text-to-HTML conversion tool for web writers. Markdown |
| 14 | +allows you to write using an easy-to-read, easy-to-write plain text |
| 15 | +format, then convert it to structurally valid XHTML (or HTML). |
| 16 | + |
| 17 | +Thus, "Markdown" is two things: a plain text markup syntax, and a |
| 18 | +software tool, written in Perl, that converts the plain text markup |
| 19 | +to HTML. |
| 20 | + |
| 21 | +Markdown works both as a Movable Type plug-in and as a standalone Perl |
| 22 | +script -- which means it can also be used as a text filter in BBEdit |
| 23 | +(or any other application that supporst filters written in Perl). |
| 24 | + |
| 25 | +Full documentation of Markdown's syntax and configuration options is |
| 26 | +available on the web: <http://daringfireball.net/projects/markdown/>. |
| 27 | +(Note: this readme file is formatted in Markdown.) |
| 28 | + |
| 29 | + |
| 30 | + |
| 31 | +Installation and Requirements |
| 32 | +----------------------------- |
| 33 | + |
| 34 | +Markdown requires Perl 5.6.0 or later. Welcome to the 21st Century. |
| 35 | +Markdown also requires the standard Perl library module `Digest::MD5`. |
| 36 | + |
| 37 | + |
| 38 | +### Movable Type ### |
| 39 | + |
| 40 | +Markdown works with Movable Type version 2.6 or later (including |
| 41 | +MT 3.0 or later). |
| 42 | + |
| 43 | +1. Copy the "Markdown.pl" file into your Movable Type "plugins" |
| 44 | + directory. The "plugins" directory should be in the same directory |
| 45 | + as "mt.cgi"; if the "plugins" directory doesn't already exist, use |
| 46 | + your FTP program to create it. Your installation should look like |
| 47 | + this: |
| 48 | + |
| 49 | + (mt home)/plugins/Markdown.pl |
| 50 | + |
| 51 | +2. Once installed, Markdown will appear as an option in Movable Type's |
| 52 | + Text Formatting pop-up menu. This is selectable on a per-post basis. |
| 53 | + Markdown translates your posts to HTML when you publish; the posts |
| 54 | + themselves are stored in your MT database in Markdown format. |
| 55 | + |
| 56 | +3. If you also install SmartyPants 1.5 (or later), Markdown will offer |
| 57 | + a second text formatting option: "Markdown with SmartyPants". This |
| 58 | + option is the same as the regular "Markdown" formatter, except that |
| 59 | + automatically uses SmartyPants to create typographically correct |
| 60 | + curly quotes, em-dashes, and ellipses. See the SmartyPants web page |
| 61 | + for more information: <http://daringfireball.net/projects/smartypants/> |
| 62 | + |
| 63 | +4. To make Markdown (or "Markdown with SmartyPants") your default |
| 64 | + text formatting option for new posts, go to Weblog Config -> |
| 65 | + Preferences. |
| 66 | + |
| 67 | +Note that by default, Markdown produces XHTML output. To configure |
| 68 | +Markdown to produce HTML 4 output, see "Configuration", below. |
| 69 | + |
| 70 | + |
| 71 | +### Blosxom ### |
| 72 | + |
| 73 | +Markdown works with Blosxom version 2.x. |
| 74 | + |
| 75 | +1. Rename the "Markdown.pl" plug-in to "Markdown" (case is |
| 76 | + important). Movable Type requires plug-ins to have a ".pl" |
| 77 | + extension; Blosxom forbids it. |
| 78 | + |
| 79 | +2. Copy the "Markdown" plug-in file to your Blosxom plug-ins folder. |
| 80 | + If you're not sure where your Blosxom plug-ins folder is, see the |
| 81 | + Blosxom documentation for information. |
| 82 | + |
| 83 | +3. That's it. The entries in your weblog will now automatically be |
| 84 | + processed by Markdown. |
| 85 | + |
| 86 | +4. If you'd like to apply Markdown formatting only to certain posts, |
| 87 | + rather than all of them, see Jason Clark's instructions for using |
| 88 | + Markdown in conjunction with Blosxom's Meta plugin: |
| 89 | + |
| 90 | + <http://jclark.org/weblog/WebDev/Blosxom/Markdown.html> |
| 91 | + |
| 92 | + |
| 93 | +### BBEdit ### |
| 94 | + |
| 95 | +Markdown works with BBEdit 6.1 or later on Mac OS X. (It also works |
| 96 | +with BBEdit 5.1 or later and MacPerl 5.6.1 on Mac OS 8.6 or later.) |
| 97 | + |
| 98 | +1. Copy the "Markdown.pl" file to appropriate filters folder in your |
| 99 | + "BBEdit Support" folder. On Mac OS X, this should be: |
| 100 | + |
| 101 | + BBEdit Support/Unix Support/Unix Filters/ |
| 102 | + |
| 103 | + See the BBEdit documentation for more details on the location of |
| 104 | + these folders. |
| 105 | + |
| 106 | + You can rename "Markdown.pl" to whatever you wish. |
| 107 | + |
| 108 | +2. That's it. To use Markdown, select some text in a BBEdit document, |
| 109 | + then choose Markdown from the Filters sub-menu in the "#!" menu, or |
| 110 | + the Filters floating palette |
| 111 | + |
| 112 | + |
| 113 | + |
| 114 | +Configuration |
| 115 | +------------- |
| 116 | + |
| 117 | +By default, Markdown produces XHTML output for tags with empty elements. |
| 118 | +E.g.: |
| 119 | + |
| 120 | + <br /> |
| 121 | + |
| 122 | +Markdown can be configured to produce HTML-style tags; e.g.: |
| 123 | + |
| 124 | + <br> |
| 125 | + |
| 126 | + |
| 127 | +### Movable Type ### |
| 128 | + |
| 129 | +You need to use a special `MTMarkdownOptions` container tag in each |
| 130 | +Movable Type template where you want HTML 4-style output: |
| 131 | + |
| 132 | + <MTMarkdownOptions output='html4'> |
| 133 | + ... put your entry content here ... |
| 134 | + </MTMarkdownOptions> |
| 135 | + |
| 136 | +The easiest way to use MTMarkdownOptions is probably to put the |
| 137 | +opening tag right after your `<body>` tag, and the closing tag right |
| 138 | +before `</body>`. |
| 139 | + |
| 140 | +To suppress Markdown processing in a particular template, i.e. to |
| 141 | +publish the raw Markdown-formatted text without translation into |
| 142 | +(X)HTML, set the `output` attribute to 'raw': |
| 143 | + |
| 144 | + <MTMarkdownOptions output='raw'> |
| 145 | + ... put your entry content here ... |
| 146 | + </MTMarkdownOptions> |
| 147 | + |
| 148 | + |
| 149 | +### Command-Line ### |
| 150 | + |
| 151 | +Use the `--html4tags` command-line switch to produce HTML output from a |
| 152 | +Unix-style command line. E.g.: |
| 153 | + |
| 154 | + % perl Markdown.pl --html4tags foo.text |
| 155 | + |
| 156 | +Type `perldoc Markdown.pl`, or read the POD documentation within the |
| 157 | +Markdown.pl source code for more information. |
| 158 | + |
| 159 | + |
| 160 | + |
| 161 | +Bugs |
| 162 | +---- |
| 163 | + |
| 164 | +To file bug reports or feature requests please send email to: |
| 165 | +<markdown@daringfireball.net>. |
| 166 | + |
| 167 | + |
| 168 | + |
| 169 | +Version History |
| 170 | +--------------- |
| 171 | + |
| 172 | +1.0.1 (14 Dec 2004): |
| 173 | + |
| 174 | ++ Changed the syntax rules for code blocks and spans. Previously, |
| 175 | + backslash escapes for special Markdown characters were processed |
| 176 | + everywhere other than within inline HTML tags. Now, the contents |
| 177 | + of code blocks and spans are no longer processed for backslash |
| 178 | + escapes. This means that code blocks and spans are now treated |
| 179 | + literally, with no special rules to worry about regarding |
| 180 | + backslashes. |
| 181 | + |
| 182 | + **NOTE**: This changes the syntax from all previous versions of |
| 183 | + Markdown. Code blocks and spans involving backslash characters |
| 184 | + will now generate different output than before. |
| 185 | + |
| 186 | ++ Tweaked the rules for link definitions so that they must occur |
| 187 | + within three spaces of the left margin. Thus if you indent a link |
| 188 | + definition by four spaces or a tab, it will now be a code block. |
| 189 | + |
| 190 | + [a]: /url/ "Indented 3 spaces, this is a link def" |
| 191 | + |
| 192 | + [b]: /url/ "Indented 4 spaces, this is a code block" |
| 193 | + |
| 194 | + **IMPORTANT**: This may affect existing Markdown content if it |
| 195 | + contains link definitions indented by 4 or more spaces. |
| 196 | + |
| 197 | ++ Added `>`, `+`, and `-` to the list of backslash-escapable |
| 198 | + characters. These should have been done when these characters |
| 199 | + were added as unordered list item markers. |
| 200 | + |
| 201 | ++ Trailing spaces and tabs following HTML comments and `<hr/>` tags |
| 202 | + are now ignored. |
| 203 | + |
| 204 | ++ Inline links using `<` and `>` URL delimiters weren't working: |
| 205 | + |
| 206 | + like [this](<http://example.com/>) |
| 207 | + |
| 208 | ++ Added a bit of tolerance for trailing spaces and tabs after |
| 209 | + Markdown hr's. |
| 210 | + |
| 211 | ++ Fixed bug where auto-links were being processed within code spans: |
| 212 | + |
| 213 | + like this: `<http://example.com/>` |
| 214 | + |
| 215 | ++ Sort-of fixed a bug where lines in the middle of hard-wrapped |
| 216 | + paragraphs, which lines look like the start of a list item, |
| 217 | + would accidentally trigger the creation of a list. E.g. a |
| 218 | + paragraph that looked like this: |
| 219 | + |
| 220 | + I recommend upgrading to version |
| 221 | + 8. Oops, now this line is treated |
| 222 | + as a sub-list. |
| 223 | + |
| 224 | + This is fixed for top-level lists, but it can still happen for |
| 225 | + sub-lists. E.g., the following list item will not be parsed |
| 226 | + properly: |
| 227 | + |
| 228 | + + I recommend upgrading to version |
| 229 | + 8. Oops, now this line is treated |
| 230 | + as a sub-list. |
| 231 | + |
| 232 | + Given Markdown's list-creation rules, I'm not sure this can |
| 233 | + be fixed. |
| 234 | + |
| 235 | ++ Standalone HTML comments are now handled; previously, they'd get |
| 236 | + wrapped in a spurious `<p>` tag. |
| 237 | + |
| 238 | ++ Fix for horizontal rules preceded by 2 or 3 spaces. |
| 239 | + |
| 240 | ++ `<hr>` HTML tags in must occur within three spaces of left |
| 241 | + margin. (With 4 spaces or a tab, they should be code blocks, but |
| 242 | + weren't before this fix.) |
| 243 | + |
| 244 | ++ Capitalized "With" in "Markdown With SmartyPants" for |
| 245 | + consistency with the same string label in SmartyPants.pl. |
| 246 | + (This fix is specific to the MT plug-in interface.) |
| 247 | + |
| 248 | ++ Auto-linked email address can now optionally contain |
| 249 | + a 'mailto:' protocol. I.e. these are equivalent: |
| 250 | + |
| 251 | + <mailto:user@example.com> |
| 252 | + <user@example.com> |
| 253 | + |
| 254 | ++ Fixed annoying bug where nested lists would wind up with |
| 255 | + spurious (and invalid) `<p>` tags. |
| 256 | + |
| 257 | ++ You can now write empty links: |
| 258 | + |
| 259 | + [like this]() |
| 260 | + |
| 261 | + and they'll be turned into anchor tags with empty href attributes. |
| 262 | + This should have worked before, but didn't. |
| 263 | + |
| 264 | ++ `***this***` and `___this___` are now turned into |
| 265 | + |
| 266 | + <strong><em>this</em></strong> |
| 267 | + |
| 268 | + Instead of |
| 269 | + |
| 270 | + <strong><em>this</strong></em> |
| 271 | + |
| 272 | + which isn't valid. (Thanks to Michel Fortin for the fix.) |
| 273 | + |
| 274 | ++ Added a new substitution in `_EncodeCode()`: s/\$/$/g; This |
| 275 | + is only for the benefit of Blosxom users, because Blosxom |
| 276 | + (sometimes?) interpolates Perl scalars in your article bodies. |
| 277 | + |
| 278 | ++ Fixed problem for links defined with urls that include parens, e.g.: |
| 279 | + |
| 280 | + [1]: http://sources.wikipedia.org/wiki/Middle_East_Policy_(Chomsky) |
| 281 | + |
| 282 | + "Chomsky" was being erroneously treated as the URL's title. |
| 283 | + |
| 284 | ++ At some point during 1.0's beta cycle, I changed every sub's |
| 285 | + argument fetching from this idiom: |
| 286 | + |
| 287 | + my $text = shift; |
| 288 | + |
| 289 | + to: |
| 290 | + |
| 291 | + my $text = shift || return ''; |
| 292 | + |
| 293 | + The idea was to keep Markdown from doing any work in a sub |
| 294 | + if the input was empty. This introduced a bug, though: |
| 295 | + if the input to any function was the single-character string |
| 296 | + "0", it would also evaluate as false and return immediately. |
| 297 | + How silly. Now fixed. |
| 298 | + |
| 299 | + |
| 300 | + |
| 301 | +Donations |
| 302 | +--------- |
| 303 | + |
| 304 | +Donations to support Markdown's development are happily accepted. See: |
| 305 | +<http://daringfireball.net/projects/markdown/> for details. |
| 306 | + |
| 307 | + |
| 308 | + |
| 309 | +Copyright and License |
| 310 | +--------------------- |
| 311 | + |
| 312 | +Copyright (c) 2003-2004 John Gruber |
| 313 | +<http://daringfireball.net/> |
| 314 | +All rights reserved. |
| 315 | + |
| 316 | +Redistribution and use in source and binary forms, with or without |
| 317 | +modification, are permitted provided that the following conditions are |
| 318 | +met: |
| 319 | + |
| 320 | +* Redistributions of source code must retain the above copyright notice, |
| 321 | + this list of conditions and the following disclaimer. |
| 322 | + |
| 323 | +* Redistributions in binary form must reproduce the above copyright |
| 324 | + notice, this list of conditions and the following disclaimer in the |
| 325 | + documentation and/or other materials provided with the distribution. |
| 326 | + |
| 327 | +* Neither the name "Markdown" nor the names of its contributors may |
| 328 | + be used to endorse or promote products derived from this software |
| 329 | + without specific prior written permission. |
| 330 | + |
| 331 | +This software is provided by the copyright holders and contributors "as |
| 332 | +is" and any express or implied warranties, including, but not limited |
| 333 | +to, the implied warranties of merchantability and fitness for a |
| 334 | +particular purpose are disclaimed. In no event shall the copyright owner |
| 335 | +or contributors be liable for any direct, indirect, incidental, special, |
| 336 | +exemplary, or consequential damages (including, but not limited to, |
| 337 | +procurement of substitute goods or services; loss of use, data, or |
| 338 | +profits; or business interruption) however caused and on any theory of |
| 339 | +liability, whether in contract, strict liability, or tort (including |
| 340 | +negligence or otherwise) arising in any way out of the use of this |
| 341 | +software, even if advised of the possibility of such damage. |
0 commit comments