diff --git a/LICENSE b/LICENSE index 9513f08..cede7b8 100644 --- a/LICENSE +++ b/LICENSE @@ -1,5 +1,5 @@ -Copyright (C) 2004, John Gruber -Copyright (C) 2015, Kyle J. McKay +Copyright (C) 2004 John Gruber +Copyright (C) 2015,2016,2017 Kyle J. McKay All rights reserved. Redistribution and use in source and binary forms, with or without diff --git a/Markdown.pl b/Markdown.pl index 685b87b..a31ce17 100755 --- a/Markdown.pl +++ b/Markdown.pl @@ -4,27 +4,37 @@ # Markdown -- A text-to-HTML conversion tool for web writers # # Copyright (C) 2004 John Gruber -# Copyright (C) 2015,2016 Kyle J. McKay +# Copyright (C) 2015,2016,2017 Kyle J. McKay +# All rights reserved. +# License is Modified BSD (aka 3-clause BSD) License\n"; +# See LICENSE file (or ) # - package Markdown; + require 5.006_000; use strict; use warnings; + +use vars qw($COPYRIGHT $VERSION @ISA @EXPORT_OK); + +BEGIN {*COPYRIGHT = +\"Copyright (C) 2004 John Gruber +Copyright (C) 2015,2016,2017 Kyle J. McKay +All rights reserved. +"; +*VERSION = \"1.0.4+" # Sun 05 Jun 2016+ +} + close(DATA) if fileno(DATA); require Exporter; use Digest::MD5 qw(md5_hex); use File::Basename qw(basename); -use vars qw($VERSION @ISA @EXPORT_OK); @ISA = qw(Exporter); @EXPORT_OK = qw(Markdown); $INC{__PACKAGE__.'.pm'} = $INC{basename(__FILE__)} unless exists $INC{__PACKAGE__.'.pm'}; -$VERSION = '1.0.4'; -# Sun 05 Jun 2016 - ## Disabled; causes problems under Perl 5.6.1: # use utf8; @@ -46,19 +56,19 @@ my $g_tab_width = 4; # Legacy even though it's wrong # "Mastering Regular Expressions", 2nd Ed., pp. 328-331. my $g_nested_brackets; $g_nested_brackets = qr{ - (?> # Atomic matching - [^\[\]]+ # Anything other than brackets + (?> # Atomic matching + [^\[\]]+ # Anything other than brackets | - \[ - (??{ $g_nested_brackets }) # Recursive set of nested brackets - \] + \[ + (??{ $g_nested_brackets }) # Recursive set of nested brackets + \] )* }x; # Table of hash values for escaped characters: my %g_escape_table; -foreach my $char (split //, "\\\`*_{}[]()>#+-.!~") { +foreach my $char (split //, "\\\`*_~{}[]()>#+-.!") { $g_escape_table{$char} = md5_hex($char); } @@ -86,12 +96,12 @@ sub start { 1; } sub story { my($pkg, $path, $filename, $story_ref, $title_ref, $body_ref) = @_; - if ( (! $g_blosxom_use_meta) or - (defined($meta::markup) and ($meta::markup =~ /^\s*markdown\s*$/i)) - ){ - $$body_ref = Markdown($$body_ref); - } - 1; + if ((! $g_blosxom_use_meta) or + (defined($meta::markup) and ($meta::markup =~ /^\s*markdown\s*$/i)) + ) { + $$body_ref = Markdown($$body_ref); + } + 1; } @@ -103,10 +113,10 @@ unless ($@) { require MT::Template::Context; import MT::Template::Context; - eval {require MT::Plugin}; # Test to see if we're running >= MT 3.0. + eval {require MT::Plugin}; # Test to see if we're running >= MT 3.0. unless ($@) { require MT::Plugin; - import MT::Plugin; + import MT::Plugin; my $plugin = new MT::Plugin({ name => "Markdown", description => "A plain-text-to-HTML formatting plugin. (Version: $VERSION)", @@ -116,7 +126,7 @@ unless ($@) { } MT::Template::Context->add_container_tag(MarkdownOptions => sub { - my $ctx = shift; + my $ctx = shift; my $args = shift; my $builder = $ctx->stash('builder'); my $tokens = $ctx->stash('tokens'); @@ -127,23 +137,23 @@ unless ($@) { defined (my $str = $builder->build($ctx, $tokens) ) or return $ctx->error($builder->errstr); - $str; # return value + $str; # return value }); MT->add_text_filter('markdown' => { - label => 'Markdown', - docs => 'http://daringfireball.net/projects/markdown/', + label => 'Markdown', + docs => 'http://daringfireball.net/projects/markdown/', on_format => sub { my $text = shift; my $ctx = shift; my $raw = 0; if (defined $ctx) { my $output = $ctx->stash('markdown_output'); - if (defined $output && $output =~ m/^html/i) { + if (defined $output && $output =~ m/^html/i) { $g_empty_element_suffix = ">"; $ctx->stash('markdown_output', ''); } - elsif (defined $output && $output eq 'raw') { + elsif (defined $output && $output eq 'raw') { $raw = 1; $ctx->stash('markdown_output', ''); } @@ -171,10 +181,10 @@ unless ($@) { docs => 'http://daringfireball.net/projects/markdown/', on_format => sub { my $text = shift; - my $ctx = shift; + my $ctx = shift; if (defined $ctx) { my $output = $ctx->stash('markdown_output'); - if (defined $output && $output eq 'html') { + if (defined $output && $output eq 'html') { $g_empty_element_suffix = ">"; } else { @@ -212,23 +222,23 @@ elsif (!caller) { if ($cli_opts{'help'}) { exec 'perldoc', $0; } - if ($cli_opts{'version'}) { # Version info - print "\nThis is Markdown, version $VERSION.\n"; - print "Copyright (C) 2004 John Gruber\n"; - print "Copyright (C) 2015 Kyle J. McKay\n"; + if ($cli_opts{'version'}) { # Version info + print "\nThis is Markdown, version $VERSION.\n", $COPYRIGHT; + print "License is Modified BSD (aka 3-clause BSD) License\n"; + print "\n"; exit 0; } - if ($cli_opts{'shortversion'}) { # Just the version number string. + if ($cli_opts{'shortversion'}) { # Just the version number string. print $VERSION; exit 0; } - if ($cli_opts{'html4tags'}) { # Use HTML tag style instead of XHTML + if ($cli_opts{'html4tags'}) { # Use HTML tag style instead of XHTML $options{empty_element_suffix} = ">"; } - if ($cli_opts{'htmlroot'}) { # Use URL prefix + if ($cli_opts{'htmlroot'}) { # Use URL prefix $options{url_prefix} = $cli_opts{'htmlroot'}; } - if ($cli_opts{'imageroot'}) { # Use image URL prefix + if ($cli_opts{'imageroot'}) { # Use image URL prefix $options{img_prefix} = $cli_opts{'imageroot'}; } @@ -236,7 +246,7 @@ elsif (!caller) { #### Process incoming text: ########################### my $text; { - local $/; # Slurp the whole file + local $/; # Slurp the whole file $text = <>; } print Markdown($text, \%options); @@ -261,8 +271,8 @@ sub Markdown { # set initial defaults empty_element_suffix => $g_empty_element_suffix, tab_width => $g_tab_width, - url_prefix => "", # Prefixed to non-absolute URLs - img_prefix => "", # Prefixed to non-absolute image URLs + url_prefix => "", # Prefixed to non-absolute URLs + img_prefix => "", # Prefixed to non-absolute image URLs ); my %args = (); if (ref($_[0]) eq "HASH") { @@ -325,11 +335,11 @@ sub _HashBTCodeBlocks { $text =~ s{ (?:\n|\A) ``(`+)[ \t]*(?:([\w.+-]+)[ \t]*)?\n - ( # $3 = the code block -- one or more lines, starting with ``` + ( # $3 = the code block -- one or more lines, starting with ``` (?: .*\n+ )+? - ) + ) (?:(?:``\1[ \t]*(?:\n|\Z))|\Z) # and ending with ``` or end of document }{ # $2 contains syntax highlighting to use if defined @@ -378,7 +388,7 @@ sub _StripLinkDefinitions { (?:\n+|\Z) } {}mx) { - $g_urls{lc $1} = _EncodeAmpsAndAngles( $2 ); # Link IDs are case-insensitive + $g_urls{lc $1} = _EncodeAmpsAndAngles( $2 ); # Link IDs are case-insensitive if ($3) { $g_titles{lc $1} = $3; $g_titles{lc $1} =~ s/\042/"/g; @@ -403,11 +413,11 @@ sub _HashHTMLBlocks { my $block_tags_b = qr/p|div|h[1-6]|blockquote|pre|table|dl|ol|ul|script|noscript|form|fieldset|iframe|math/; # First, look for nested blocks, e.g.: - #
- #
- # tags for inner block must be indented. - #
- #
+ #
+ #
+ # tags for inner block must be indented. + #
+ #
# # The outermost tags must start at the left margin for this to match, and # the inner nested divs must be indented. @@ -415,13 +425,13 @@ sub _HashHTMLBlocks { # match will start at the first `
` and stop at the first `
`. $text =~ s{ ( # save in $1 - ^ # start of line (with /m) + ^ # start of line (with /m) <($block_tags_a) # start tag = $2 \b # word break (.*\n)*? # any number of lines, minimally matching # the matching end tag [ \t]* # trailing spaces/tabs - (?=\n+|\Z) # followed by a newline or end of document + (?=\n+|\Z) # followed by a newline or end of document ) }{ my $key = md5_hex($1); @@ -435,13 +445,13 @@ sub _HashHTMLBlocks { # $text =~ s{ ( # save in $1 - ^ # start of line (with /m) + ^ # start of line (with /m) <($block_tags_b) # start tag = $2 \b # word break (.*\n)*? # any number of lines, minimally matching .* # the matching end tag [ \t]* # trailing spaces/tabs - (?=\n+|\Z) # followed by a newline or end of document + (?=\n+|\Z) # followed by a newline or end of document ) }{ my $key = md5_hex($1); @@ -478,7 +488,7 @@ sub _HashHTMLBlocks { | # or \A\n? # the beginning of the doc ) - ( # save in $1 + ( # save in $1 [ ]{0,$less_than_tab} (?s: ) [ \t]* - (?=\n{2,}|\Z) # followed by a blank line or end of document + (?=\n{2,}|\Z) # followed by a blank line or end of document ) }{ my $key = md5_hex($1); @@ -557,7 +567,7 @@ sub _RunSpanGamut { $text = _DoItalicsAndBoldAndStrike($text); # Do hard breaks: - $text =~ s/ {2,}\n/ or tags. # my $tags_to_skip = qr!<(/?)(?:pre|code|kbd|script|math)[\s>]!; @@ -579,9 +589,9 @@ sub _EscapeSpecialChars { # corresponding MD5 checksum value; this is likely # overkill, but it should prevent us from colliding # with the escape values by accident. - $cur_token->[1] =~ s! \* !$g_escape_table{'*'}!gx; - $cur_token->[1] =~ s! _ !$g_escape_table{'_'}!gx; - $cur_token->[1] =~ s! ~ !$g_escape_table{'~'}!gx; + $cur_token->[1] =~ s! \* !$g_escape_table{'*'}!gx; + $cur_token->[1] =~ s! _ !$g_escape_table{'_'}!gx; + $cur_token->[1] =~ s! ~ !$g_escape_table{'~'}!gx; $text .= $cur_token->[1]; } else { my $t = $cur_token->[1]; @@ -605,14 +615,14 @@ sub _DoAnchors { $text =~ s{ ( # wrap whole match in $1 \[ - ($g_nested_brackets) # link text = $2 + ($g_nested_brackets) # link text = $2 \] [ ]? # one optional space (?:\n[ ]*)? # one optional newline followed by spaces \[ - (.*?) # id = $3 + (.*?) # id = $3 \] ) }{ @@ -627,9 +637,9 @@ sub _DoAnchors { if (defined $g_urls{$link_id}) { my $url = _PrefixURL($g_urls{$link_id}); - $url =~ s! \* !$g_escape_table{'*'}!gx; # We've got to encode these to avoid - $url =~ s! _ !$g_escape_table{'_'}!gx; # conflicting with italics, bold - $url =~ s! ~ !$g_escape_table{'~'}!gx; # and strike through. + $url =~ s! \* !$g_escape_table{'*'}!gx; # We've got to encode these to avoid + $url =~ s! _ !$g_escape_table{'_'}!gx; # conflicting with italics, bold + $url =~ s! ~ !$g_escape_table{'~'}!gx; # and strike through. $result = "? # href = $3 [ \t]* ( # $4 - (['\042]) # quote char = $5 + (['\042]) # quote char = $5 (.*?) # Title = $6 \5 # matching quote )? # title is optional @@ -669,13 +679,13 @@ sub _DoAnchors { my $result; my $whole_match = $1; my $link_text = $2; - my $url = $3; - my $title = $6; + my $url = $3; + my $title = $6; $url = _PrefixURL($url); - $url =~ s! \* !$g_escape_table{'*'}!gx; # We've got to encode these to avoid - $url =~ s! _ !$g_escape_table{'_'}!gx; # conflicting with italics, bold - $url =~ s! ~ !$g_escape_table{'~'}!gx; # and strike through. + $url =~ s! \* !$g_escape_table{'*'}!gx; # We've got to encode these to avoid + $url =~ s! _ !$g_escape_table{'_'}!gx; # conflicting with italics, bold + $url =~ s! ~ !$g_escape_table{'~'}!gx; # and strike through. $result = "? # src url = $3 [ \t]* ( # $4 - (['\042]) # quote char = $5 + (['\042]) # quote char = $5 (.*?) # title = $6 \5 # matching quote [ \t]* @@ -777,24 +787,24 @@ sub _DoImages { my $result; my $whole_match = $1; my $alt_text = $2; - my $url = $3; - my $title = ''; + my $url = $3; + my $title = ''; if (defined($6)) { - $title = $6; + $title = $6; } $url = _PrefixURL($url); $alt_text =~ s/"/"/g; $title =~ s/"/"/g; - $url =~ s! \* !$g_escape_table{'*'}!gx; # We've got to encode these to avoid - $url =~ s! _ !$g_escape_table{'_'}!gx; # conflicting with italics, bold - $url =~ s! ~ !$g_escape_table{'~'}!gx; # and strike through. + $url =~ s! \* !$g_escape_table{'*'}!gx; # We've got to encode these to avoid + $url =~ s! _ !$g_escape_table{'_'}!gx; # conflicting with italics, bold + $url =~ s! ~ !$g_escape_table{'~'}!gx; # and strike through. $result = "\"$alt_text\"";" . _RunSpanGamut($1) . "\n\n"; + "

" . _RunSpanGamut($1) . "

\n\n"; }egmx; $text =~ s{ ^(?:-+[ \t]*\n)?(.+)[ \t]*\n-+[ \t]*\n+ }{ - "

" . _RunSpanGamut($1) . "

\n\n"; + "

" . _RunSpanGamut($1) . "

\n\n"; }egmx; $text =~ s{ ^(?:~+[ \t]*\n)?(.+)[ \t]*\n~+[ \t]*\n+ }{ - "

" . _RunSpanGamut($1) . "

\n\n"; + "

" . _RunSpanGamut($1) . "

\n\n"; }egmx; # atx-style headers: - # # Header 1 - # ## Header 2 - # ## Header 2 with closing hashes ## - # ... - # ###### Header 6 + # # Header 1 + # ## Header 2 + # ## Header 2 with closing hashes ## + # ... + # ###### Header 6 # $text =~ s{ ^(\#{1,6}) # $1 = string of #'s @@ -847,7 +857,7 @@ sub _DoHeaders { \n+ }{ my $h_level = length($1); - "" . _RunSpanGamut($2) . "\n\n"; + "" . _RunSpanGamut($2) . "\n\n"; }egmx; return $text; @@ -868,19 +878,19 @@ sub _DoLists { # Re-usable pattern to match any entirel ul or ol list: my $whole_list = qr{ - ( # $1 = whole list - ( # $2 + ( # $1 = whole list + ( # $2 [ ]{0,$less_than_tab} - (${marker_any}) # $3 = first list item marker + (${marker_any}) # $3 = first list item marker [ \t]+ ) (?s:.+?) - ( # $4 + ( # $4 \z | \n{2,} (?=\S) - (?! # Negative lookahead for another list item marker + (?! # Negative lookahead for another list item marker [ \t]* ${marker_any}[ \t]+ ) @@ -891,7 +901,7 @@ sub _DoLists { # We use a different prefix before nested lists than top-level lists. # See extended comment in _ProcessListItems(). # - # Note: There's a bit of duplication here. My original implementation + # Note: (jg) There's a bit of duplication here. My original implementation # created a scalar regex pattern as the conditional result of the test on # $g_list_level, and then only ran the $text =~ s{...}{...}egmx # substitution once, using the scalar as the pattern. This worked, @@ -959,9 +969,9 @@ sub _ProcessListItems { # We do this because when we're not inside a list, we want to treat # something like this: # - # I recommend upgrading to version - # 8. Oops, now this line is treated - # as a sub-list. + # I recommend upgrading to version + # 8. Oops, now this line is treated + # as a sub-list. # # As a single paragraph, despite the fact that the second line starts # with a digit-period-space sequence. @@ -1019,7 +1029,7 @@ sub _DoCodeBlocks { $text =~ s{ (?:\n\n|\A) - ( # $1 = the code block -- one or more lines, starting with a space/tab + ( # $1 = the code block -- one or more lines, starting with a space/tab (?: (?:[ ]{$opt{tab_width}} | \t) # Lines must start with a tab or a tab-width of spaces .*\n+ @@ -1046,28 +1056,28 @@ sub _DoCodeBlocks { sub _DoCodeSpans { # -# * Backtick quotes are used for spans. +# * Backtick quotes are used for spans. # -# * You can use multiple backticks as the delimiters if you want to -# include literal backticks in the code span. So, this input: +# * You can use multiple backticks as the delimiters if you want to +# include literal backticks in the code span. So, this input: # -# Just type ``foo `bar` baz`` at the prompt. +# Just type ``foo `bar` baz`` at the prompt. # # Will translate to: # -#

Just type foo `bar` baz at the prompt.

+#

Just type foo `bar` baz at the prompt.

# -# There's no arbitrary limit to the number of backticks you -# can use as delimters. If you need three consecutive backticks -# in your code, use four for delimiters, etc. +# There's no arbitrary limit to the number of backticks you +# can use as delimters. If you need three consecutive backticks +# in your code, use four for delimiters, etc. # -# * You can use spaces to get literal backticks at the edges: +# * You can use spaces to get literal backticks at the edges: # -# ... type `` `bar` `` ... +# ... type `` `bar` `` ... # # Turns to: # -# ... type `bar` ... +# ... type `bar` ... # my $text = shift; @@ -1155,28 +1165,28 @@ sub _DoBlockQuotes { my $text = shift; $text =~ s{ - ( # Wrap whole match in $1 + ( # Wrap whole match in $1 ( - ^[ \t]*>[ \t]? # '>' at the start of a line - .+\n # rest of the first line - (.+\n)* # subsequent consecutive lines - \n* # blanks + ^[ \t]*>[ \t]? # '>' at the start of a line + .+\n # rest of the first line + (.+\n)* # subsequent consecutive lines + \n* # blanks )+ ) }{ my $bq = $1; - $bq =~ s/^[ \t]*>[ \t]?//gm; # trim one level of quoting - $bq =~ s/^[ \t]+$//mg; # trim whitespace-only lines - $bq = _RunBlockGamut($bq); # recurse + $bq =~ s/^[ \t]*>[ \t]?//gm; # trim one level of quoting + $bq =~ s/^[ \t]+$//mg; # trim whitespace-only lines + $bq = _RunBlockGamut($bq); # recurse - $bq =~ s/^/ /g; + $bq =~ s/^/ /mg; # These leading spaces screw with
 content, so we need to fix that:
 	    $bq =~ s{
-		    (\s*
.+?
) + (\s*)(
.+?
) }{ - my $pre = $1; - $pre =~ s/^ //mg; - $pre; + my ($indent, $pre) = ($1, $2); + $pre =~ s/^ //mg; + $indent.$pre; }egsx; "
\n$bq\n
\n\n"; @@ -1189,8 +1199,8 @@ sub _DoBlockQuotes { sub _FormParagraphs { # -# Params: -# $text - string to process with html

tags +# Params: +# $text - string to process with html

tags # my $text = shift; @@ -1230,7 +1240,7 @@ sub _EncodeAmpsAndAngles { my $text = shift; # Ampersand-encoding based entirely on Nat Irons's Amputator MT plugin: - # http://bumppo.net/projects/amputator/ + # http://bumppo.net/projects/amputator/ $text =~ s/&(?!#?[xX]?(?:[0-9a-fA-F]+|\w+);)/&/g; # Encode naked <'s @@ -1242,13 +1252,12 @@ sub _EncodeAmpsAndAngles { sub _EncodeBackslashEscapes { # -# Parameter: String. -# Returns: The string, with after processing the following backslash -# escape sequences. +# Parameter: String. +# Returns: String after processing the following backslash escape sequences. # local $_ = shift; - s! \\\\ !$g_escape_table{'\\'}!gx; # Must process escaped backslashes first. + s! \\\\ !$g_escape_table{'\\'}!gx; # Must process escaped backslashes first. s! \\` !$g_escape_table{'`'}!gx; s! \\\* !$g_escape_table{'*'}!gx; s! \\_ !$g_escape_table{'_'}!gx; @@ -1273,7 +1282,7 @@ sub _EncodeBackslashEscapes { sub _DoAutoLinks { my $text = shift; - $text =~ s{<((https?|ftp):[^'\042>\s]+)>}{$1}gi; + $text =~ s{<((https?|ftp):[^'\042>\s]+)>}{<$1>}gi; # Email addresses: $text =~ s{ @@ -1286,7 +1295,7 @@ sub _DoAutoLinks { ) > }{ - _EncodeEmailAddress( _UnescapeSpecialChars($1) ); + "<"._EncodeEmailAddress( _UnescapeSpecialChars($1) ).">"; }egix; return $text; @@ -1295,18 +1304,18 @@ sub _DoAutoLinks { sub _EncodeEmailAddress { # -# Input: an email address, e.g. "foo@example.com" +# Input: an email address, e.g. "foo@example.com" # -# Output: the email address as a mailto link, with each character -# of the address encoded as either a decimal or hex entity, in -# the hopes of foiling most address harvesting spam bots. E.g.: +# Output: the email address as a mailto link, with each character +# of the address encoded as either a decimal or hex entity, in +# the hopes of foiling most address harvesting spam bots. E.g.: # -# foo -# @example.com +# foo +# @example.com # -# Based on a filter by Matthew Wickline, posted to the BBEdit-Talk -# mailing list: +# Based on a filter by Matthew Wickline, posted to the BBEdit-Talk +# mailing list: # my $addr = shift; @@ -1360,17 +1369,17 @@ sub _UnescapeSpecialChars { sub _TokenizeHTML { # -# Parameter: String containing HTML markup. -# Returns: Reference to an array of the tokens comprising the input -# string. Each token is either a tag (possibly with nested, -# tags contained therein, such as , or a -# run of text between tags. Each element of the array is a -# two-element array; the first is either 'tag' or 'text'; -# the second is the actual value. +# Parameter: String containing HTML markup. +# Returns: Reference to an array of the tokens comprising the input +# string. Each token is either a tag (possibly with nested, +# tags contained therein, such as , or a +# run of text between tags. Each element of the array is a +# two-element array; the first is either 'tag' or 'text'; +# the second is the actual value. # # -# Derived from the _tokenize() subroutine from Brad Choate's MTRegex plugin. -# +# Derived from the _tokenize() subroutine from Brad Choate's MTRegex plugin. +# # my $str = shift; @@ -1379,10 +1388,10 @@ sub _TokenizeHTML { my @tokens; my $depth = 6; - my $nested_tags = join('|', ('(?:<[a-z/!$](?:[^<>]') x $depth) . (')*>)' x $depth); - my $match = qr/(?s: ) | # comment - (?s: <\? .*? \?> ) | # processing instruction - $nested_tags/ix; # nested tags + my $nested_tags = join('|', ('(?:<[a-z/!$](?:[^<>]') x $depth) . (')*>)' x $depth); + my $match = qr/(?s: ) | # comment + (?s: <\? .*? \?> ) | # processing instruction + $nested_tags/ix; # nested tags while ($str =~ m/($match)/g) { my $whole_tag = $1; @@ -1449,8 +1458,7 @@ __DATA__ =head1 NAME -B - +Markdown.pl - convert Markdown format text files to HTML =head1 SYNOPSIS @@ -1471,8 +1479,8 @@ specifically to serve as a front-end to (X)HTML. You can use span-level HTML tags anywhere in a Markdown document, and you can use block level HTML tags (like

and as well). -For more information about Markdown's syntax, see the `basics.text` -and `syntax.text` files included with `Markdown.pl`. +For more information about Markdown's syntax, see the F +and F files included with F. =head1 OPTIONS @@ -1481,7 +1489,7 @@ Use "--" to end switch parsing. For example, to open a file named "-z", use: Markdown.pl -- -z -=over 4 +=over =item B<--html4tags> @@ -1526,52 +1534,90 @@ Display Markdown's help. =head1 VERSION HISTORY -See the readme file for detailed release notes for this version. +Z<> See the F file for detailed release notes for this version. + +=over -1.0.4 - 05 Jun 2016 +=item Z<> 1.0.4 - 05 Jun 2016 -1.0.3 - 06 Sep 2015 +=item Z<> 1.0.3 - 06 Sep 2015 -1.0.2 - 03 Sep 2015 +=item Z<> 1.0.2 - 03 Sep 2015 -1.0.1 - 14 Dec 2004 +=item Z<> 1.0.1 - 14 Dec 2004 -1.0 - 28 Aug 2004 +=item Z<> 1.0.0 - 28 Aug 2004 +=back =head1 AUTHORS - John Gruber - http://daringfireball.net - http://daringfireball.net/projects/markdown/ +=over + +=item John Gruber + +=item L + +=item L + +=item E<160> - PHP port and other contributions by Michel Fortin - http://michelf.com +=back + +=over + +=item PHP port and other contributions by Michel Fortin - Additional enhancements and tweaks by Kyle J. McKay - mackylegmail.com +=item L + +=item E<160> + +=back +=over + +=item Additional enhancements and tweaks by Kyle J. McKay + +=item mackylegmail.com + +=back =head1 COPYRIGHT AND LICENSE - Copyright (C) 2003-2004 John Gruber - Copyright (C) 2015,2016 Kyle J. McKay - All rights reserved. +=over + +=item Copyright (C) 2003-2004 John Gruber + +=item Copyright (C) 2015,2016 Kyle J. McKay + +=item All rights reserved. + +=back 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. +=over + +=item * -* 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. +Redistributions of source code must retain the above copyright +notice, this list of conditions and the following disclaimer. -* 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. +=item * + +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. + +=item * + +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. + +=back This software is provided by the copyright holders and contributors "as is" and any express or implied warranties, including, but not limited diff --git a/README b/README index 7a0a5ff..7958486 100644 --- a/README +++ b/README @@ -4,7 +4,7 @@ Markdown Version 1.0.4 - Sun 05 Jun 2016 John Gruber -Kyle J. McKay +Kyle J. McKay Introduction @@ -15,7 +15,7 @@ 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 +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 @@ -23,7 +23,7 @@ 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 in the basics.text and syntax.text files. +available in the `basics.md` and `syntax.md` files. (Note: this readme file and the basics and syntax files are formatted in Markdown.) @@ -33,12 +33,12 @@ 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`. +Markdown also requires the standard Perl library module `Digest::MD5`. ### Movable Type ### -Markdown works with Movable Type version 2.6 or later (including +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" @@ -87,7 +87,7 @@ Markdown works with Blosxom version 2.x. 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: - + @@ -118,11 +118,11 @@ 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 ### @@ -152,7 +152,7 @@ publish the raw Markdown-formatted text without translation into Use the `--html4tags` command-line switch to produce HTML output from a Unix-style command line. E.g.: - % perl Markdown.pl --html4tags foo.text + % perl Markdown.pl --html4tags foo.txt Type `perldoc Markdown.pl`, or read the POD documentation within the Markdown.pl source code for more information. @@ -164,168 +164,168 @@ Version History 1.0.4 (05 Jun 2016): -+ Markdown.pl can now be require'd and the Markdown function called - repeatedly by external code. ++ Markdown.pl can now be require'd and the Markdown function called + repeatedly by external code. -+ Backticks (```) delimited code blocks are now handled better and are - no longer subject to any further accidental processing. ++ Backticks (```) delimited code blocks are now handled better and are + no longer subject to any further accidental processing. 1.0.3 (06 Sep 2015): -+ Added support for --htmlroot option to set a URL prefix. ++ Added support for --htmlroot option to set a URL prefix. -+ Relaxed matching rule for non-indented code blocks. ++ Relaxed matching rule for non-indented code blocks. -+ Added support for --imageroot option to set an img URL prefix. ++ Added support for --imageroot option to set an img URL prefix. 1.0.2 (03 Sep 2015): -+ Added support for -h and --help to display Markdown.pl help. ++ Added support for -h and --help to display Markdown.pl help. -+ Added support for third-level headers using setext-like - underlining using tildes (`~`'s). ++ Added support for third-level headers using setext-like + underlining using tildes (`~`'s). -+ Added support for an optional overline using the same character - as the underline when using setext-style headers. ++ Added support for an optional overline using the same character + as the underline when using setext-style headers. -+ Stopped recognizing `_` within words. The `*` character is still - recognized within words. ++ Stopped recognizing `_` within words. The `*` character is still + recognized within words. -+ Added support for strike through text using `~~` similarly to the - way strong works using `**`. ++ Added support for strike through text using `~~` similarly to the + way strong works using `**`. -+ Added support for non-indended code blocks by preceding and following - them with a line consisting of 3 backtick quotes (`` ` ``) or more. ++ Added support for non-indended code blocks by preceding and following + them with a line consisting of 3 backtick quotes (`` ` ``) or more. 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. ++ 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. - **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. + [a]: /url/ "Indented 3 spaces, this is a link def" -+ 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" - [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. + **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. ++ 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. ++ Trailing spaces and tabs following HTML comments and `
` tags + are now ignored. -+ Inline links using `<` and `>` URL delimiters weren't working: ++ Inline links using `<` and `>` URL delimiters weren't working: - like [this]() + like [this]() -+ Added a bit of tolerance for trailing spaces and tabs after - Markdown hr's. ++ 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: ++ Fixed bug where auto-links were being processed within code spans: - like this: `` + 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: ++ 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. + 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: + 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. + + 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. + 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. ++ 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. ++ 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.) ++ `
` 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.) ++ 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: ++ 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. ++ Fixed annoying bug where nested lists would wind up with + spurious (and invalid) `

` tags. -+ You can now write empty links: ++ You can now write empty links: - [like this]() + [like this]() - and they'll be turned into anchor tags with empty href attributes. - This should have worked before, but didn't. + 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***` and `___this___` are now turned into - this + this - Instead of + Instead of - this + this - which isn't valid. (Thanks to Michel Fortin for the fix.) + 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. ++ 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.: ++ Fixed problem for links defined with urls that include parens, e.g.: - [1]: http://sources.wikipedia.org/wiki/Middle_East_Policy_(Chomsky) + [1]: http://sources.wikipedia.org/wiki/Middle_East_Policy_(Chomsky) - "Chomsky" was being erroneously treated as the URL's title. + "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: ++ At some point during 1.0's beta cycle, I changed every sub's + argument fetching from this idiom: - my $text = shift; + my $text = shift; - to: + to: - my $text = shift || return ''; + 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. + 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. @@ -333,7 +333,7 @@ Copyright and License --------------------- Copyright (C) 2003-2004 John Gruber -Copyright (C) 2015 Kyle J. McKay +Copyright (C) 2015-2017 Kyle J. McKay All rights reserved. Redistribution and use in source and binary forms, with or without diff --git a/basics.md b/basics.md index d5373ef..39c4c68 100644 --- a/basics.md +++ b/basics.md @@ -4,7 +4,7 @@ Markdown: Basics

@@ -23,10 +23,10 @@ web application that allows you type your own Markdown-formatted text and translate it to XHTML. **Note:** This document is itself written using Markdown; you -can [see the source for it by adding '.text' to the URL] [src]. +can [see the source for it by adding `.md` to the URL] [src]. [s]: syntax.html "Markdown Syntax" - [src]: basics.text + [src]: basics.md ## Paragraphs, Headers, Blockquotes ## @@ -51,56 +51,56 @@ Blockquotes are indicated using email-style '`>`' angle brackets. Markdown: - ==================== - A First Level Header - ==================== - - A Second Level Header - --------------------- + ==================== + A First Level Header + ==================== - A Third Level Header - ~~~~~~~~~~~~~~~~~~~~ + A Second Level Header + --------------------- - Now is the time for all good men to come to - the aid of their country. This is just a - regular paragraph. + A Third Level Header + ~~~~~~~~~~~~~~~~~~~~ - The quick brown fox jumped over the lazy - dog's back. - - ### Header 4 + Now is the time for all good men to come to + the aid of their country. This is just a + regular paragraph. - > This is a blockquote. - > - > This is the second paragraph in the blockquote. - > - > ## This is an H2 in a blockquote + The quick brown fox jumped over the lazy + dog's back. + + ### Header 4 + + > This is a blockquote. + > + > This is the second paragraph in the blockquote. + > + > ## This is an H2 in a blockquote Output: -

A First Level Header

- -

A Second Level Header

- -

A Third Level Header

- -

Now is the time for all good men to come to - the aid of their country. This is just a - regular paragraph.

- -

The quick brown fox jumped over the lazy - dog's back.

- -

Header 3

- -
-

This is a blockquote.

- -

This is the second paragraph in the blockquote.

- -

This is an H2 in a blockquote

-
+

A First Level Header

+ +

A Second Level Header

+ +

A Third Level Header

+ +

Now is the time for all good men to come to + the aid of their country. This is just a + regular paragraph.

+ +

The quick brown fox jumped over the lazy + dog's back.

+ +

Header 3

+ +
+

This is a blockquote.

+ +

This is the second paragraph in the blockquote.

+ +

This is an H2 in a blockquote

+
@@ -110,22 +110,22 @@ Markdown uses asterisks and underscores to indicate spans of emphasis. Markdown: - Some of these words *are emphasized*. - Some of these words _are emphasized also_. - - Use two asterisks for **strong emphasis**. - Or, if you prefer, __use two underscores instead__. - Or, even, ~~strike through instead~~. + Some of these words *are emphasized*. + Some of these words _are emphasized also_. + + Use two asterisks for **strong emphasis**. + Or, if you prefer, __use two underscores instead__. + Or, even, ~~strike through instead~~. Output: -

Some of these words are emphasized. - Some of these words are emphasized also.

- -

Use two asterisks for strong emphasis. - Or, if you prefer, use two underscores instead. - Or, even, strike through instead.

- +

Some of these words are emphasized. + Some of these words are emphasized also.

+ +

Use two asterisks for strong emphasis. + Or, if you prefer, use two underscores instead. + Or, even, strike through instead.

+ ## Lists ## @@ -134,63 +134,63 @@ Unordered (bulleted) lists use asterisks, pluses, and hyphens (`*`, `+`, and `-`) as list markers. These three markers are interchangable; this: - * Candy. - * Gum. - * Booze. + * Candy. + * Gum. + * Booze. this: - + Candy. - + Gum. - + Booze. + + Candy. + + Gum. + + Booze. and this: - - Candy. - - Gum. - - Booze. + - Candy. + - Gum. + - Booze. all produce the same output: -
    -
  • Candy.
  • -
  • Gum.
  • -
  • Booze.
  • -
+
    +
  • Candy.
  • +
  • Gum.
  • +
  • Booze.
  • +
Ordered (numbered) lists use regular numbers, followed by periods, as list markers: - 1. Red - 2. Green - 3. Blue + 1. Red + 2. Green + 3. Blue Output: -
    -
  1. Red
  2. -
  3. Green
  4. -
  5. Blue
  6. -
+
    +
  1. Red
  2. +
  3. Green
  4. +
  5. Blue
  6. +
If you put blank lines between items, you'll get `

` tags for the list item text. You can create multi-paragraph list items by indenting the paragraphs by 4 spaces or 1 tab: - * A list item. - - With multiple paragraphs. + * A list item. - * Another item in the list. + With multiple paragraphs. + + * Another item in the list. Output: -

    -
  • A list item.

    -

    With multiple paragraphs.

  • -
  • Another item in the list.

  • -
- +
    +
  • A list item.

    +

    With multiple paragraphs.

  • +
  • Another item in the list.

  • +
+ ### Links ### @@ -202,51 +202,51 @@ text you want to turn into a link. Inline-style links use parentheses immediately after the link text. For example: - This is an [example link](http://example.com/). + This is an [example link](http://example.com/). Output: -

This is an - example link.

+

This is an + example link.

Optionally, you may include a title attribute in the parentheses: - This is an [example link](http://example.com/ "With a Title"). + This is an [example link](http://example.com/ "With a Title"). Output: -

This is an - example link.

+

This is an + example link.

Reference-style links allow you to refer to your links by names, which you define elsewhere in your document: - I get 10 times more traffic from [Google][1] than from - [Yahoo][2] or [MSN][3]. + I get 10 times more traffic from [Google][1] than from + [Yahoo][2] or [MSN][3]. - [1]: http://google.com/ "Google" - [2]: http://search.yahoo.com/ "Yahoo Search" - [3]: http://search.msn.com/ "MSN Search" + [1]: http://google.com/ "Google" + [2]: http://search.yahoo.com/ "Yahoo Search" + [3]: http://search.msn.com/ "MSN Search" Output: -

I get 10 times more traffic from Google than from Yahoo or MSN.

+

I get 10 times more traffic from Google than from Yahoo or MSN.

The title attribute is optional. Link names may contain letters, numbers and spaces, but are *not* case sensitive: - I start my morning with a cup of coffee and - [The New York Times][NY Times]. + I start my morning with a cup of coffee and + [The New York Times][NY Times]. - [ny times]: http://www.nytimes.com/ + [ny times]: http://www.nytimes.com/ Output: -

I start my morning with a cup of coffee and - The New York Times.

+

I start my morning with a cup of coffee and + The New York Times.

### Images ### @@ -255,17 +255,17 @@ Image syntax is very much like link syntax. Inline (titles are optional): - ![alt text](/path/to/img.jpg "Title") + ![alt text](/path/to/img.jpg "Title") Reference-style: - ![alt text][id] + ![alt text][id] - [id]: /path/to/img.jpg "Title" + [id]: /path/to/img.jpg "Title" Both of the above examples produce the same output: - alt text + alt text @@ -276,19 +276,19 @@ backtick quotes. Any ampersands (`&`) and angle brackets (`<` or `>`) will automatically be translated into HTML entities. This makes it easy to use Markdown to write about HTML example code: - I strongly recommend against using any `` tags. + I strongly recommend against using any `` tags. - I wish SmartyPants used named entities like `—` - instead of decimal-encoded entites like `—`. + I wish SmartyPants used named entities like `—` + instead of decimal-encoded entites like `—`. Output: -

I strongly recommend against using any - <blink> tags.

- -

I wish SmartyPants used named entities like - &mdash; instead of decimal-encoded - entites like &#8212;.

+

I strongly recommend against using any + <blink> tags.

+ +

I wish SmartyPants used named entities like + &mdash; instead of decimal-encoded + entites like &#8212;.

To specify an entire block of pre-formatted code, indent every line of @@ -308,41 +308,41 @@ snippets. Markdown: - ``` - # This is a simple code block with unspecified syntax - ``` + ``` + # This is a simple code block with unspecified syntax + ``` Output: -
# This is a simple code block with unspecified syntax
-    
+
# This is a simple code block with unspecified syntax
+      
Markdown: - ``` perl - my $var = "value"; # this should be highlighted as Perl code - ``` + ``` perl + my $var = "value"; # this should be highlighted as Perl code + ``` Output: -
my $var = "value"; # this should be highlighted as Perl code
-    
+
my $var = "value"; # this should be highlighted as Perl code
+      
Markdown: - If you want your page to validate under XHTML 1.0 Strict, - you've got to put paragraph tags in your blockquotes: + If you want your page to validate under XHTML 1.0 Strict, + you've got to put paragraph tags in your blockquotes: -
-

For example.

-
+
+

For example.

+
Output: -

If you want your page to validate under XHTML 1.0 Strict, - you've got to put paragraph tags in your blockquotes:

- -
<blockquote>
-        <p>For example.</p>
-    </blockquote>
-    
+

If you want your page to validate under XHTML 1.0 Strict, + you've got to put paragraph tags in your blockquotes:

+ +
<blockquote>
+          <p>For example.</p>
+      </blockquote>
+      
diff --git a/syntax.md b/syntax.md index 78d4bc7..932a28b 100644 --- a/syntax.md +++ b/syntax.md @@ -30,12 +30,12 @@ Markdown: Syntax **Note:** This document is itself written using Markdown; you -can [see the source for it by adding '.text' to the URL][src]. +can [see the source for it by adding `.md` to the URL][src]. [b]: basics.html "Markdown Basics" - [src]: syntax.text + [src]: syntax.md -* * * +- - - - -

Overview

@@ -94,15 +94,15 @@ to add extra (unwanted) `

` tags around HTML block-level tags. For example, to add an HTML table to a Markdown article: - This is a regular paragraph. + This is a regular paragraph. -

- - - -
Foo
+ + + + +
Foo
- This is another regular paragraph. + This is another regular paragraph. Note that Markdown formatting syntax is not processed within block-level HTML tags. E.g., you can't use Markdown-style `*emphasis*` inside an @@ -130,11 +130,11 @@ Ampersands in particular are bedeviling for web writers. If you want to write about 'AT&T', you need to write '`AT&T`'. You even need to escape ampersands within URLs. Thus, if you want to link to: - http://images.google.com/images?num=30&q=larry+bird + http://images.google.com/images?num=30&q=larry+bird you need to encode the URL as: - http://images.google.com/images?num=30&q=larry+bird + http://images.google.com/images?num=30&q=larry+bird in your anchor tag `href` attribute. Needless to say, this is easy to forget, and is probably the single most common source of HTML validation @@ -147,25 +147,25 @@ into `&`. So, if you want to include a copyright symbol in your article, you can write: - © + © and Markdown will leave it alone. But if you write: - AT&T + AT&T Markdown will translate it to: - AT&T + AT&T Similarly, because Markdown supports [inline HTML](#html), if you use angle brackets as delimiters for HTML tags, Markdown will treat them as such. But if you write: - 4 < 5 + 4 < 5 Markdown will translate it to: - 4 < 5 + 4 < 5 However, inside Markdown code spans and blocks, angle brackets and ampersands are *always* encoded automatically. This makes it easy to use @@ -174,7 +174,7 @@ terrible format for writing about HTML syntax, because every single `<` and `&` in your example code needs to be escaped.) -* * * +- - - - -

Block Elements

@@ -216,38 +216,38 @@ Setext-style headers are "underlined" using equal signs (for first-level headers), dashes (for second-level headers) and tildes (for third-level headers). For example: - This is an H1 - ============= + This is an H1 + ============= - This is an H2 - ------------- + This is an H2 + ------------- - This is an H3 - ~~~~~~~~~~~~~ + This is an H3 + ~~~~~~~~~~~~~ Any number of underlining `=`'s, `-`'s or `~`'s will work. An optional matching "overline" may precede the header like so: - ============= - This is an H1 - ============= + ============= + This is an H1 + ============= - ------------- - This is an H2 - ------------- + ------------- + This is an H2 + ------------- - ~~~~~~~~~~~~~ - This is an H3 - ~~~~~~~~~~~~~ + ~~~~~~~~~~~~~ + This is an H3 + ~~~~~~~~~~~~~ Atx-style headers use 1-6 hash characters at the start of the line, corresponding to header levels 1-6. For example: - # This is an H1 + # This is an H1 - ## This is an H2 + ## This is an H2 - ###### This is an H6 + ###### This is an H6 Optionally, you may "close" atx-style headers. This is purely cosmetic -- you can use this if you think it looks better. The @@ -255,11 +255,11 @@ closing hashes don't even need to match the number of hashes used to open the header. (The number of opening hashes determines the header level.) : - # This is an H1 # + # This is an H1 # - ## This is an H2 ## + ## This is an H2 ## - ### This is an H3 ###### + ### This is an H3 ######

Blockquotes

@@ -269,43 +269,43 @@ familiar with quoting passages of text in an email message, then you know how to create a blockquote in Markdown. It looks best if you hard wrap the text and put a `>` before every line: - > This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, - > consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. - > Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus. - > - > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse - > id sem consectetuer libero luctus adipiscing. + > This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, + > consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. + > Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus. + > + > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse + > id sem consectetuer libero luctus adipiscing. Markdown allows you to be lazy and only put the `>` before the first line of a hard-wrapped paragraph: - > This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, - consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. - Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus. + > This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, + consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. + Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus. - > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse - id sem consectetuer libero luctus adipiscing. + > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse + id sem consectetuer libero luctus adipiscing. Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by adding additional levels of `>`: - > This is the first level of quoting. - > - > > This is nested blockquote. - > - > Back to the first level. + > This is the first level of quoting. + > + > > This is nested blockquote. + > + > Back to the first level. Blockquotes can contain other Markdown elements, including headers, lists, and code blocks: - > ## This is a header. - > - > 1. This is the first list item. - > 2. This is the second list item. - > - > Here's some example code: - > - > return shell_exec("echo $input | $markdown_script"); + > ## This is a header. + > + > 1. This is the first list item. + > 2. This is the second list item. + > + > Here's some example code: + > + > return shell_exec("echo $input | $markdown_script"); Any decent text editor should make email-style quoting easy. For example, with BBEdit, you can make a selection and choose Increase @@ -319,49 +319,49 @@ Markdown supports ordered (numbered) and unordered (bulleted) lists. Unordered lists use asterisks, pluses, and hyphens -- interchangably -- as list markers: - * Red - * Green - * Blue + * Red + * Green + * Blue is equivalent to: - + Red - + Green - + Blue + + Red + + Green + + Blue and: - - Red - - Green - - Blue + - Red + - Green + - Blue Ordered lists use numbers followed by periods: - 1. Bird - 2. McHale - 3. Parish + 1. Bird + 2. McHale + 3. Parish It's important to note that the actual numbers you use to mark the list have no effect on the HTML output Markdown produces. The HTML Markdown produces from the above list is: -
    -
  1. Bird
  2. -
  3. McHale
  4. -
  5. Parish
  6. -
+
    +
  1. Bird
  2. +
  3. McHale
  4. +
  5. Parish
  6. +
If you instead wrote the list in Markdown like this: - 1. Bird - 1. McHale - 1. Parish + 1. Bird + 1. McHale + 1. Parish or even: - 3. Bird - 1. McHale - 8. Parish + 3. Bird + 1. McHale + 8. Parish you'd get the exact same HTML output. The point is, if you want to, you can use ordinal numbers in your ordered Markdown lists, so that @@ -378,97 +378,97 @@ or a tab. To make lists look nice, you can wrap items with hanging indents: - * Lorem ipsum dolor sit amet, consectetuer adipiscing elit. - Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, - viverra nec, fringilla in, laoreet vitae, risus. - * Donec sit amet nisl. Aliquam semper ipsum sit amet velit. - Suspendisse id sem consectetuer libero luctus adipiscing. + * Lorem ipsum dolor sit amet, consectetuer adipiscing elit. + Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, + viverra nec, fringilla in, laoreet vitae, risus. + * Donec sit amet nisl. Aliquam semper ipsum sit amet velit. + Suspendisse id sem consectetuer libero luctus adipiscing. But if you want to be lazy, you don't have to: - * Lorem ipsum dolor sit amet, consectetuer adipiscing elit. - Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, - viverra nec, fringilla in, laoreet vitae, risus. - * Donec sit amet nisl. Aliquam semper ipsum sit amet velit. - Suspendisse id sem consectetuer libero luctus adipiscing. + * Lorem ipsum dolor sit amet, consectetuer adipiscing elit. + Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, + viverra nec, fringilla in, laoreet vitae, risus. + * Donec sit amet nisl. Aliquam semper ipsum sit amet velit. + Suspendisse id sem consectetuer libero luctus adipiscing. If list items are separated by blank lines, Markdown will wrap the items in `

` tags in the HTML output. For example, this input: - * Bird - * Magic + * Bird + * Magic will turn into: -

    -
  • Bird
  • -
  • Magic
  • -
+
    +
  • Bird
  • +
  • Magic
  • +
But this: - * Bird + * Bird - * Magic + * Magic will turn into: -
    -
  • Bird

  • -
  • Magic

  • -
+
    +
  • Bird

  • +
  • Magic

  • +
List items may consist of multiple paragraphs. Each subsequent paragraph in a list item must be indented by either 4 spaces or one tab: - 1. This is a list item with two paragraphs. Lorem ipsum dolor - sit amet, consectetuer adipiscing elit. Aliquam hendrerit - mi posuere lectus. + 1. This is a list item with two paragraphs. Lorem ipsum dolor + sit amet, consectetuer adipiscing elit. Aliquam hendrerit + mi posuere lectus. - Vestibulum enim wisi, viverra nec, fringilla in, laoreet - vitae, risus. Donec sit amet nisl. Aliquam semper ipsum - sit amet velit. + Vestibulum enim wisi, viverra nec, fringilla in, laoreet + vitae, risus. Donec sit amet nisl. Aliquam semper ipsum + sit amet velit. - 2. Suspendisse id sem consectetuer libero luctus adipiscing. + 2. Suspendisse id sem consectetuer libero luctus adipiscing. It looks nice if you indent every line of the subsequent paragraphs, but here again, Markdown will allow you to be lazy: - * This is a list item with two paragraphs. + * This is a list item with two paragraphs. - This is the second paragraph in the list item. You're - only required to indent the first line. Lorem ipsum dolor - sit amet, consectetuer adipiscing elit. + This is the second paragraph in the list item. You're + only required to indent the first line. Lorem ipsum dolor + sit amet, consectetuer adipiscing elit. - * Another item in the same list. + * Another item in the same list. To put a blockquote within a list item, the blockquote's `>` delimiters need to be indented: - * A list item with a blockquote: + * A list item with a blockquote: - > This is a blockquote - > inside a list item. + > This is a blockquote + > inside a list item. To put a code block within a list item, the code block needs to be indented *twice* -- 8 spaces or two tabs: - * A list item with a code block: + * A list item with a code block: - + It's worth noting that it's possible to trigger an ordered list by accident, by writing something like this: - 1986. What a great season. + 1986. What a great season. In other words, a *number-period-space* sequence at the beginning of a line. To avoid this, you can backslash-escape the period: - 1986\. What a great season. + 1986\. What a great season. @@ -486,24 +486,24 @@ line consisting of the same number of backtick quotes -- in this case the code lines themselves do not require any additional indentation. For example, given this input: - This is a normal paragraph: + This is a normal paragraph: - This is a code block. + This is a code block. Or this equivalent input: - This is a normal paragraph. + This is a normal paragraph. - ``` - This is a code block. - ``` + ``` + This is a code block. + ``` Markdown will generate: -

This is a normal paragraph:

+

This is a normal paragraph:

-
This is a code block.
-    
+
This is a code block.
+      
Note that when using the 3 backtick quotes technique, the blank line before the start of the code block is optional. One level of @@ -511,20 +511,20 @@ indentation -- 4 spaces or 1 tab -- is removed from each line of the code block unless the 3 backtick quotes are used. For example, this: - Here is an example of AppleScript: + Here is an example of AppleScript: - tell application "Foo" - beep - end tell + tell application "Foo" + beep + end tell will turn into: -

Here is an example of AppleScript:

+

Here is an example of AppleScript:

-
tell application "Foo"
-        beep
-    end tell
-    
+
tell application "Foo"
+          beep
+      end tell
+      
A code block continues until it reaches a line that is not indented (or the end of the article) when using the indentation technique or @@ -544,16 +544,16 @@ easy to include example HTML source code using Markdown -- just paste it and indent it, and Markdown will handle the hassle of encoding the ampersands and angle brackets. For example, this: - + will turn into: -
<div class="footer">
-        &copy; 2004 Foo Corporation
-    </div>
-    
+
<div class="footer">
+          &copy; 2004 Foo Corporation
+      </div>
+      
Regular Markdown syntax is not processed within code blocks. E.g., asterisks are just literal asterisks within a code block. This means @@ -568,18 +568,18 @@ more hyphens, asterisks, or underscores on a line by themselves. If you wish, you may use spaces between the hyphens or asterisks. Each of the following lines will produce a horizontal rule: - * * * + * * * - *** + *** - ***** + ***** - - - - + - - - - --------------------------------------- + --------------------------------------- -* * * +- - - - -

Span Elements

@@ -594,36 +594,36 @@ after the link text's closing square bracket. Inside the parentheses, put the URL where you want the link to point, along with an *optional* title for the link, surrounded in quotes. For example: - This is [an example](http://example.com/ "Title") inline link. + This is [an example](http://example.com/ "Title") inline link. - [This link](http://example.net/) has no title attribute. + [This link](http://example.net/) has no title attribute. Will produce: -

This is - an example inline link.

+

This is + an example inline link.

-

This link has no - title attribute.

+

This link has no + title attribute.

If you're referring to a local resource on the same server, you can use relative paths: - See my [About](/about/) page for details. + See my [About](/about/) page for details. Reference-style links use a second set of square brackets, inside which you place a label of your choosing to identify the link: - This is [an example][id] reference-style link. + This is [an example][id] reference-style link. You can optionally use a space to separate the sets of brackets: - This is [an example] [id] reference-style link. + This is [an example] [id] reference-style link. Then, anywhere in the document, you define your link label like this, on a line by itself: - [id]: http://example.com/ "Optional Title Here" + [id]: http://example.com/ "Optional Title Here" That is: @@ -637,22 +637,22 @@ That is: The following three link definitions are equivalent: - [foo]: http://example.com/ "Optional Title Here" - [foo]: http://example.com/ 'Optional Title Here' - [foo]: http://example.com/ (Optional Title Here) + [foo]: http://example.com/ "Optional Title Here" + [foo]: http://example.com/ 'Optional Title Here' + [foo]: http://example.com/ (Optional Title Here) **Note:** There is a known bug in Markdown.pl 1.0.3 which prevents single quotes from being used to delimit link titles. The link URL may, optionally, be surrounded by angle brackets: - [id]: "Optional Title Here" + [id]: "Optional Title Here" You can put the title attribute on the next line and use extra spaces or tabs for padding, which tends to look better with longer URLs: - [id]: http://example.com/longish/path/to/resource/here - "Optional Title Here" + [id]: http://example.com/longish/path/to/resource/here + "Optional Title Here" Link definitions are only used for creating links during Markdown processing, and are stripped from your document in the HTML output. @@ -661,8 +661,8 @@ Link definition names may consist of letters, numbers, spaces, and punctuation -- but they are *not* case sensitive. E.g. these two links: - [link text][a] - [link text][A] + [link text][a] + [link text][A] are equivalent. @@ -671,20 +671,20 @@ link, in which case the link text itself is used as the name. Just use an empty set of square brackets -- e.g., to link the word "Google" to the google.com web site, you could simply write: - [Google][] + [Google][] And then define the link: - [Google]: http://google.com/ + [Google]: http://google.com/ Because link names may contain spaces, this shortcut even works for multiple words in the link text: - Visit [Daring Fireball][] for more information. + Visit [Daring Fireball][] for more information. And then define the link: - - [Daring Fireball]: http://daringfireball.net/ + + [Daring Fireball]: http://daringfireball.net/ Link definitions can be placed anywhere in your Markdown document. I tend to put them immediately after each paragraph in which they're @@ -693,8 +693,8 @@ document, sort of like footnotes. Here's an example of reference links in action: - I get 10 times more traffic from [Google] [1] than from - [Yahoo] [2] or [MSN] [3]. + I get 10 times more traffic from [Google] [1] than from + [Yahoo] [2] or [MSN] [3]. [1]: http://google.com/ "Google" [2]: http://search.yahoo.com/ "Yahoo Search" @@ -702,8 +702,8 @@ Here's an example of reference links in action: Using the implicit link name shortcut, you could instead write: - I get 10 times more traffic from [Google][] than from - [Yahoo][] or [MSN][]. + I get 10 times more traffic from [Google][] than from + [Yahoo][] or [MSN][]. [google]: http://google.com/ "Google" [yahoo]: http://search.yahoo.com/ "Yahoo Search" @@ -711,17 +711,17 @@ Using the implicit link name shortcut, you could instead write: Both of the above examples will produce the following HTML output: -

I get 10 times more traffic from Google than from - Yahoo - or MSN.

+

I get 10 times more traffic from Google than from + Yahoo + or MSN.

For comparison, here is the same paragraph written using Markdown's inline link style: - I get 10 times more traffic from [Google](http://google.com/ "Google") - than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or - [MSN](http://search.msn.com/ "MSN Search"). + I get 10 times more traffic from [Google](http://google.com/ "Google") + than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or + [MSN](http://search.msn.com/ "MSN Search"). The point of reference-style links is not that they're easier to write. The point is that with reference-style links, your document @@ -746,27 +746,27 @@ HTML `` tag; double `*`'s or `_`'s will be wrapped with an HTML `` tag. Double `~`'s will be wrapped with an HTML `` tag. E.g., this input: - *single asterisks* + *single asterisks* - _single underscores_ + _single underscores_ - **double asterisks** + **double asterisks** - __double underscores__ + __double underscores__ - ~~strike through~~ + ~~double tildes~~ will produce: - single asterisks + single asterisks - single underscores + single underscores - double asterisks + double asterisks - double underscores + double underscores - strike through + strike through You can use whichever style you prefer; the lone restriction is that the same character must be used to open and close an emphasis span. @@ -774,7 +774,7 @@ Additionally `_` and double `_` are not recognized within words. Emphasis using `*`'s or `~`'s can be used in the middle of a word: - un*frigging*believable fan~~frigging~~tastic + un*frigging*believable fan~~frigging~~tastic But if you surround an `*`, `_` or `~` with spaces, it'll be treated as a literal asterisk, underscore or tilde. @@ -783,8 +783,7 @@ To produce a literal asterisk, underscore or tilde at a position where it would otherwise be used as an emphasis delimiter, you can backslash escape it: - \*this text is surrounded by literal asterisks\* - + \*this text is surrounded by literal asterisks\*

Code

@@ -793,54 +792,53 @@ To indicate a span of code, wrap it with backtick quotes (`` ` ``). Unlike a pre-formatted code block, a code span indicates code within a normal paragraph. For example: - Use the `printf()` function. + Use the `printf()` function. will produce: -

Use the printf() function.

+

Use the printf() function.

To include a literal backtick character within a code span, you can use multiple backticks as the opening and closing delimiters: - ``There is a literal backtick (`) here.`` + ``There is a literal backtick (`) here.`` which will produce this: -

There is a literal backtick (`) here.

+

There is a literal backtick (`) here.

The backtick delimiters surrounding a code span may include spaces -- one after the opening, one before the closing. This allows you to place literal backtick characters at the beginning or end of a code span: - A single backtick in a code span: `` ` `` - - A backtick-delimited string in a code span: `` `foo` `` + A single backtick in a code span: `` ` `` + + A backtick-delimited string in a code span: `` `foo` `` will produce: -

A single backtick in a code span: `

- -

A backtick-delimited string in a code span: `foo`

+

A single backtick in a code span: `

+ +

A backtick-delimited string in a code span: `foo`

With a code span, ampersands and angle brackets are encoded as HTML entities automatically, which makes it easy to include example HTML tags. Markdown will turn this: - Please don't use any `` tags. + Please don't use any `` tags. into: -

Please don't use any <blink> tags.

+

Please don't use any <blink> tags.

You can write this: - `—` is the decimal-encoded equivalent of `—`. + `—` is the decimal-encoded equivalent of `—`. to produce: -

&#8212; is the decimal-encoded - equivalent of &mdash;.

- +

&#8212; is the decimal-encoded + equivalent of &mdash;.

Images

@@ -853,9 +851,9 @@ for links, allowing for two styles: *inline* and *reference*. Inline image syntax looks like this: - ![Alt text](/path/to/img.jpg) + ![Alt text](/path/to/img.jpg) - ![Alt text](/path/to/img.jpg "Optional title") + ![Alt text](/path/to/img.jpg "Optional title") That is: @@ -868,19 +866,19 @@ That is: Reference-style image syntax looks like this: - ![Alt text][id] + ![Alt text][id] Where "id" is the name of a defined image reference. Image references are defined using syntax identical to link references: - [id]: url/to/image "Optional title attribute" + [id]: url/to/image "Optional title attribute" As of this writing, Markdown has no syntax for specifying the dimensions of an image; if this is important to you, you can simply use regular HTML `` tags. -* * * +- - - - -

Miscellaneous

@@ -889,25 +887,25 @@ use regular HTML `` tags. Markdown supports a shortcut style for creating "automatic" links for URLs and email addresses: simply surround the URL or email address with angle brackets. What this means is that if you want to show the actual text of a URL or email address, and also have it be a clickable link, you can do this: - - + + Markdown will turn this into: - http://example.com/ + http://example.com/ Automatic links for email addresses work similarly, except that Markdown will also perform a bit of randomized decimal and hex entity-encoding to help obscure your address from address-harvesting spambots. For example, Markdown will turn this: - + into something like this: - address@exa - mple.com + address@exa + mple.com which will render in a browser as a clickable link to "address@example.com". @@ -926,20 +924,20 @@ formatting syntax. For example, if you wanted to surround a word with literal asterisks (instead of an HTML `` tag), you can use backslashes before the asterisks, like this: - \*literal asterisks\* + \*literal asterisks\* Markdown provides backslash escapes for the following characters: - \ backslash - ` backtick - * asterisk - _ underscore - {} curly braces - [] square brackets - () parentheses - # hash mark - + plus sign - - minus sign (hyphen) - . dot - ! exclamation mark - + \ backslash + ` backtick + * asterisk + _ underscore + ~ tilde + {} curly braces + [] square brackets + () parentheses + # hash mark + + plus sign + - minus sign (hyphen) + . dot + ! exclamation mark