README
1NAME
2 Text::MultiMarkdown - Convert MultiMarkdown syntax to (X)HTML
3
4SYNOPSIS
5 use Text::MultiMarkdown 'markdown';
6 my $html = markdown($text);
7
8 use Text::MultiMarkdown 'markdown';
9 my $html = markdown( $text, {
10 empty_element_suffix => '>',
11 tab_width => 2,
12 use_wikilinks => 1,
13 } );
14
15 use Text::MultiMarkdown;
16 my $m = Text::MultiMarkdown->new;
17 my $html = $m->markdown($text);
18
19 use Text::MultiMarkdown;
20 my $m = Text::MultiMarkdown->new(
21 empty_element_suffix => '>',
22 tab_width => 2,
23 use_wikilinks => 1,
24 );
25 my $html = $m->markdown( $text );
26
27DESCRIPTION
28 Markdown is a text-to-HTML filter; it translates an easy-to-read /
29 easy-to-write structured text format into HTML. Markdown's text format
30 is most similar to that of plain text email, and supports features such
31 as headers, *emphasis*, code blocks, blockquotes, and links.
32
33 Markdown's syntax is designed not as a generic markup language, but
34 specifically to serve as a front-end to (X)HTML. You can use span-level
35 HTML tags anywhere in a Markdown document, and you can use block level
36 HTML tags ("<div>", "<table>" etc.). Note that by default Markdown isn't
37 interpreted in HTML block-level elements, unless you add a "markdown=1""
38 attribute to the element. See Text::Markdown for details.
39
40 This module implements the MultiMarkdown markdown syntax extensions
41 from:
42
43 http://fletcherpenney.net/multimarkdown/
44
45SYNTAX
46 For more information about (original) Markdown's syntax, see:
47
48 http://daringfireball.net/projects/markdown/
49
50 This module implements MultiMarkdown, which is an extension to
51 Markdown..
52
53 The extension is documented at:
54
55 http://fletcherpenney.net/multimarkdown/
56
57 and borrows from php-markdown, which lives at:
58
59 http://michelf.com/projects/php-markdown/extra/
60
61 This documentation is going to be moved/copied into this module for
62 clearer reading in a future release..
63
64OPTIONS
65 MultiMarkdown supports a number of options to it's processor which
66 control the behaviour of the output document.
67
68 These options can be supplied to the constructor, on in a hash with the
69 individual calls to the markdown method. See the synopsis for examples
70 of both of the above styles.
71
72 The options for the processor are:
73
74 use_metadata
75 Controls the metadata options below.
76
77 strip_metadata
78 If true, any metadata in the input document is removed from the
79 output document (note - does not take effect in complete document
80 format).
81
82 empty element suffix
83 This option can be used to generate normal HTML output. By default,
84 it is ' />', which is xHTML, change to '>' for normal HTML.
85
86 img_ids
87 Controls if <img> tags generated have an id attribute. Defaults to
88 true. Turn off for compatibility with the original markdown.
89
90 heading_ids
91 Controls if <hX> tags generated have an id attribute. Defaults to
92 true. Turn off for compatibility with the original markdown.
93
94 bibliography_title
95 The title of the generated bibliography, defaults to 'Bibliography'.
96
97 tab_width
98 Controls indent width in the generated markup, defaults to 4
99
100 disable_tables
101 If true, this disables the MultiMarkdown table handling.
102
103 disable_footnotes
104 If true, this disables the MultiMarkdown footnotes handling.
105
106 disable_bibliography
107 If true, this disables the MultiMarkdown bibliography/citation
108 handling.
109
110 disable_definition_lists
111 If true, this disables the MultiMarkdown definition list handling.
112
113 A number of possible items of metadata can also be supplied as options.
114 Note that if the use_metadata is true then the metadata in the document
115 will overwrite the settings on command line.
116
117 Metadata options supported are:
118
119 document_format
120 use_wikilinks
121 base_url
122 self_url - The document url is prepended to the "#" anchor of footnotes.
123
124METADATA
125 MultiMarkdown supports the concept of 'metadata', which allows you to
126 specify a number of formatting options within the document itself.
127 Metadata should be placed in the top few lines of a file, on value per
128 line as colon separated key/value pairs. The metadata should be
129 separated from the document with a blank line.
130
131 Most metadata keys are also supported as options to the constructor, or
132 options to the markdown method itself. (Note, as metadata, keys contain
133 space, whereas options the keys are underscore separated.)
134
135 You can attach arbitrary metadata to a document, which is output in HTML
136 <META> tags if unknown, see t/11document_format.t for more info.
137
138 A list of 'known' metadata keys, and their effects are listed below:
139
140 document format
141 If set to 'complete', MultiMarkdown will render an entire xHTML
142 page, otherwise it will render a document fragment
143
144 css Sets a CSS file for the file, if in 'complete' document format.
145
146 title
147 Sets the page title, if in 'complete' document format.
148
149 use wikilinks
150 If set to '1' or 'on', causes links that are WikiWords to
151 automatically be processed into links.
152
153 base url
154 This is the base URL for referencing wiki pages. In this is not
155 supplied, all wiki links are relative.
156
157METHODS
158 new
159 A simple constructor, see the SYNTAX and OPTIONS sections for more
160 information.
161
162 markdown
163 The main function as far as the outside world is concerned. See the
164 SYNOPSIS for details on use.
165
166BUGS
167 To file bug reports or feature requests please send email to:
168
169 bug-Text-Markdown@rt.cpan.org
170
171 Please include with your report: (1) the example input; (2) the output
172 you expected; (3) the output Markdown actually produced.
173
174VERSION HISTORY
175 See the Changes file for detailed release notes for this version.
176
177AUTHOR
178 John Gruber
179 http://daringfireball.net/
180
181 PHP port and other contributions by Michel Fortin
182 http://michelf.com/
183
184 MultiMarkdown changes by Fletcher Penney
185 http://fletcher.freeshell.org/
186
187 CPAN Module Text::MultiMarkdown (based on Text::Markdown by Sebastian
188 Riedel) originally by Darren Kulp (http://kulp.ch/)
189
190 This module is maintained by: Tomas Doran http://www.bobtfish.net/
191
192THIS DISTRIBUTION
193 Please note that this distribution is a fork of Fletcher Penny's
194 MultiMarkdown project, and it *is not* in any way blessed by him.
195
196 Whilst this code aims to be compatible with the original MultiMarkdown
197 (and incorporates and passes the MultiMarkdown test suite) whilst fixing
198 a number of bugs in the original - there may be differences between the
199 behaviour of this module and MultiMarkdown. If you find any differences
200 where you believe Text::MultiMarkdown behaves contrary to the
201 MultiMarkdown spec, please report them as bugs.
202
203SOURCE CODE
204 You can find the source code repository for Text::Markdown and
205 Text::MultiMarkdown on GitHub at
206 <http://github.com/bobtfish/text-markdown>.
207
208COPYRIGHT AND LICENSE
209 Original Code Copyright (c) 2003-2004 John Gruber
210 <http://daringfireball.net/> All rights reserved.
211
212 MultiMarkdown changes Copyright (c) 2005-2006 Fletcher T. Penney
213 <http://fletcher.freeshell.org/> All rights reserved.
214
215 Text::MultiMarkdown changes Copyright (c) 2006-2009 Darren Kulp
216 <http://kulp.ch> and Tomas Doran <http://www.bobtfish.net>
217
218 Redistribution and use in source and binary forms, with or without
219 modification, are permitted provided that the following conditions are
220 met:
221
222 * Redistributions of source code must retain the above copyright notice,
223 this list of conditions and the following disclaimer.
224
225 * Redistributions in binary form must reproduce the above copyright
226 notice, this list of conditions and the following disclaimer in the
227 documentation and/or other materials provided with the distribution.
228
229 * Neither the name "Markdown" nor the names of its contributors may be
230 used to endorse or promote products derived from this software without
231 specific prior written permission.
232
233 This software is provided by the copyright holders and contributors "as
234 is" and any express or implied warranties, including, but not limited
235 to, the implied warranties of merchantability and fitness for a
236 particular purpose are disclaimed. In no event shall the copyright owner
237 or contributors be liable for any direct, indirect, incidental, special,
238 exemplary, or consequential damages (including, but not limited to,
239 procurement of substitute goods or services; loss of use, data, or
240 profits; or business interruption) however caused and on any theory of
241 liability, whether in contract, strict liability, or tort (including
242 negligence or otherwise) arising in any way out of the use of this
243 software, even if advised of the possibility of such damage.
244
245
Readme.text
1# WARNING
2
3This Readme is from the original version of Markdown; not all of the
4information contained herein is applicable to Test::Markdown the CPAN
5module that includes this file. See the module's POD and the README file for
6more information.
7
8Markdown
9========
10
11Version 1.0.1 - Tue 14 Dec 2004
12
13by John Gruber
14<http://daringfireball.net/>
15
16
17Introduction
18------------
19
20Markdown is a text-to-HTML conversion tool for web writers. Markdown
21allows you to write using an easy-to-read, easy-to-write plain text
22format, then convert it to structurally valid XHTML (or HTML).
23
24Thus, "Markdown" is two things: a plain text markup syntax, and a
25software tool, written in Perl, that converts the plain text markup
26to HTML.
27
28Markdown works both as a Movable Type plug-in and as a standalone Perl
29script -- which means it can also be used as a text filter in BBEdit
30(or any other application that supporst filters written in Perl).
31
32Full documentation of Markdown's syntax and configuration options is
33available on the web: <http://daringfireball.net/projects/markdown/>.
34(Note: this readme file is formatted in Markdown.)
35
36
37
38Installation and Requirements
39-----------------------------
40
41Markdown requires Perl 5.6.0 or later. Welcome to the 21st Century.
42Markdown also requires the standard Perl library module `Digest::MD5`.
43
44
45### Movable Type ###
46
47Markdown works with Movable Type version 2.6 or later (including
48MT 3.0 or later).
49
501. Copy the "Markdown.pl" file into your Movable Type "plugins"
51 directory. The "plugins" directory should be in the same directory
52 as "mt.cgi"; if the "plugins" directory doesn't already exist, use
53 your FTP program to create it. Your installation should look like
54 this:
55
56 (mt home)/plugins/Markdown.pl
57
582. Once installed, Markdown will appear as an option in Movable Type's
59 Text Formatting pop-up menu. This is selectable on a per-post basis.
60 Markdown translates your posts to HTML when you publish; the posts
61 themselves are stored in your MT database in Markdown format.
62
633. If you also install SmartyPants 1.5 (or later), Markdown will offer
64 a second text formatting option: "Markdown with SmartyPants". This
65 option is the same as the regular "Markdown" formatter, except that
66 automatically uses SmartyPants to create typographically correct
67 curly quotes, em-dashes, and ellipses. See the SmartyPants web page
68 for more information: <http://daringfireball.net/projects/smartypants/>
69
704. To make Markdown (or "Markdown with SmartyPants") your default
71 text formatting option for new posts, go to Weblog Config ->
72 Preferences.
73
74Note that by default, Markdown produces XHTML output. To configure
75Markdown to produce HTML 4 output, see "Configuration", below.
76
77
78### Blosxom ###
79
80Markdown works with Blosxom version 2.x.
81
821. Rename the "Markdown.pl" plug-in to "Markdown" (case is
83 important). Movable Type requires plug-ins to have a ".pl"
84 extension; Blosxom forbids it.
85
862. Copy the "Markdown" plug-in file to your Blosxom plug-ins folder.
87 If you're not sure where your Blosxom plug-ins folder is, see the
88 Blosxom documentation for information.
89
903. That's it. The entries in your weblog will now automatically be
91 processed by Markdown.
92
934. If you'd like to apply Markdown formatting only to certain posts,
94 rather than all of them, see Jason Clark's instructions for using
95 Markdown in conjunction with Blosxom's Meta plugin:
96
97 <http://jclark.org/weblog/WebDev/Blosxom/Markdown.html>
98
99
100### BBEdit ###
101
102Markdown works with BBEdit 6.1 or later on Mac OS X. (It also works
103with BBEdit 5.1 or later and MacPerl 5.6.1 on Mac OS 8.6 or later.)
104
1051. Copy the "Markdown.pl" file to appropriate filters folder in your
106 "BBEdit Support" folder. On Mac OS X, this should be:
107
108 BBEdit Support/Unix Support/Unix Filters/
109
110 See the BBEdit documentation for more details on the location of
111 these folders.
112
113 You can rename "Markdown.pl" to whatever you wish.
114
1152. That's it. To use Markdown, select some text in a BBEdit document,
116 then choose Markdown from the Filters sub-menu in the "#!" menu, or
117 the Filters floating palette
118
119
120
121Configuration
122-------------
123
124By default, Markdown produces XHTML output for tags with empty elements.
125E.g.:
126
127 <br />
128
129Markdown can be configured to produce HTML-style tags; e.g.:
130
131 <br>
132
133
134### Movable Type ###
135
136You need to use a special `MTMarkdownOptions` container tag in each
137Movable Type template where you want HTML 4-style output:
138
139 <MTMarkdownOptions output='html4'>
140 ... put your entry content here ...
141 </MTMarkdownOptions>
142
143The easiest way to use MTMarkdownOptions is probably to put the
144opening tag right after your `<body>` tag, and the closing tag right
145before `</body>`.
146
147To suppress Markdown processing in a particular template, i.e. to
148publish the raw Markdown-formatted text without translation into
149(X)HTML, set the `output` attribute to 'raw':
150
151 <MTMarkdownOptions output='raw'>
152 ... put your entry content here ...
153 </MTMarkdownOptions>
154
155
156### Command-Line ###
157
158Use the `--html4tags` command-line switch to produce HTML output from a
159Unix-style command line. E.g.:
160
161 % perl Markdown.pl --html4tags foo.text
162
163Type `perldoc Markdown.pl`, or read the POD documentation within the
164Markdown.pl source code for more information.
165
166
167
168Bugs
169----
170
171To file bug reports or feature requests please send email to:
172<markdown@daringfireball.net>.
173
174
175
176Version History
177---------------
178
1791.0.1 (14 Dec 2004):
180
181+ Changed the syntax rules for code blocks and spans. Previously,
182 backslash escapes for special Markdown characters were processed
183 everywhere other than within inline HTML tags. Now, the contents
184 of code blocks and spans are no longer processed for backslash
185 escapes. This means that code blocks and spans are now treated
186 literally, with no special rules to worry about regarding
187 backslashes.
188
189 **NOTE**: This changes the syntax from all previous versions of
190 Markdown. Code blocks and spans involving backslash characters
191 will now generate different output than before.
192
193+ Tweaked the rules for link definitions so that they must occur
194 within three spaces of the left margin. Thus if you indent a link
195 definition by four spaces or a tab, it will now be a code block.
196
197 [a]: /url/ "Indented 3 spaces, this is a link def"
198
199 [b]: /url/ "Indented 4 spaces, this is a code block"
200
201 **IMPORTANT**: This may affect existing Markdown content if it
202 contains link definitions indented by 4 or more spaces.
203
204+ Added `>`, `+`, and `-` to the list of backslash-escapable
205 characters. These should have been done when these characters
206 were added as unordered list item markers.
207
208+ Trailing spaces and tabs following HTML comments and `<hr/>` tags
209 are now ignored.
210
211+ Inline links using `<` and `>` URL delimiters weren't working:
212
213 like [this](<http://example.com/>)
214
215+ Added a bit of tolerance for trailing spaces and tabs after
216 Markdown hr's.
217
218+ Fixed bug where auto-links were being processed within code spans:
219
220 like this: `<http://example.com/>`
221
222+ Sort-of fixed a bug where lines in the middle of hard-wrapped
223 paragraphs, which lines look like the start of a list item,
224 would accidentally trigger the creation of a list. E.g. a
225 paragraph that looked like this:
226
227 I recommend upgrading to version
228 8. Oops, now this line is treated
229 as a sub-list.
230
231 This is fixed for top-level lists, but it can still happen for
232 sub-lists. E.g., the following list item will not be parsed
233 properly:
234
235 + I recommend upgrading to version
236 8. Oops, now this line is treated
237 as a sub-list.
238
239 Given Markdown's list-creation rules, I'm not sure this can
240 be fixed.
241
242+ Standalone HTML comments are now handled; previously, they'd get
243 wrapped in a spurious `<p>` tag.
244
245+ Fix for horizontal rules preceded by 2 or 3 spaces.
246
247+ `<hr>` HTML tags in must occur within three spaces of left
248 margin. (With 4 spaces or a tab, they should be code blocks, but
249 weren't before this fix.)
250
251+ Capitalized "With" in "Markdown With SmartyPants" for
252 consistency with the same string label in SmartyPants.pl.
253 (This fix is specific to the MT plug-in interface.)
254
255+ Auto-linked email address can now optionally contain
256 a 'mailto:' protocol. I.e. these are equivalent:
257
258 <mailto:user@example.com>
259 <user@example.com>
260
261+ Fixed annoying bug where nested lists would wind up with
262 spurious (and invalid) `<p>` tags.
263
264+ You can now write empty links:
265
266 [like this]()
267
268 and they'll be turned into anchor tags with empty href attributes.
269 This should have worked before, but didn't.
270
271+ `***this***` and `___this___` are now turned into
272
273 <strong><em>this</em></strong>
274
275 Instead of
276
277 <strong><em>this</strong></em>
278
279 which isn't valid. (Thanks to Michel Fortin for the fix.)
280
281+ Added a new substitution in `_EncodeCode()`: s/\$/$/g; This
282 is only for the benefit of Blosxom users, because Blosxom
283 (sometimes?) interpolates Perl scalars in your article bodies.
284
285+ Fixed problem for links defined with urls that include parens, e.g.:
286
287 [1]: http://sources.wikipedia.org/wiki/Middle_East_Policy_(Chomsky)
288
289 "Chomsky" was being erroneously treated as the URL's title.
290
291+ At some point during 1.0's beta cycle, I changed every sub's
292 argument fetching from this idiom:
293
294 my $text = shift;
295
296 to:
297
298 my $text = shift || return '';
299
300 The idea was to keep Markdown from doing any work in a sub
301 if the input was empty. This introduced a bug, though:
302 if the input to any function was the single-character string
303 "0", it would also evaluate as false and return immediately.
304 How silly. Now fixed.
305
306
307
308Donations
309---------
310
311Donations to support Markdown's development are happily accepted. See:
312<http://daringfireball.net/projects/markdown/> for details.
313
314
315
316Copyright and License
317---------------------
318
319Copyright (c) 2003-2004 John Gruber
320<http://daringfireball.net/>
321All rights reserved.
322
323Redistribution and use in source and binary forms, with or without
324modification, are permitted provided that the following conditions are
325met:
326
327* Redistributions of source code must retain the above copyright notice,
328 this list of conditions and the following disclaimer.
329
330* Redistributions in binary form must reproduce the above copyright
331 notice, this list of conditions and the following disclaimer in the
332 documentation and/or other materials provided with the distribution.
333
334* Neither the name "Markdown" nor the names of its contributors may
335 be used to endorse or promote products derived from this software
336 without specific prior written permission.
337
338This software is provided by the copyright holders and contributors "as
339is" and any express or implied warranties, including, but not limited
340to, the implied warranties of merchantability and fitness for a
341particular purpose are disclaimed. In no event shall the copyright owner
342or contributors be liable for any direct, indirect, incidental, special,
343exemplary, or consequential damages (including, but not limited to,
344procurement of substitute goods or services; loss of use, data, or
345profits; or business interruption) however caused and on any theory of
346liability, whether in contract, strict liability, or tort (including
347negligence or otherwise) arising in any way out of the use of this
348software, even if advised of the possibility of such damage.
349