| blob | 72ab205f6a8fe2138733466d66d6c4c403de02a0 |
1 #!/usr/bin/env perl
3 #
4 # Markdown -- A text-to-HTML conversion tool for web writers
5 #
6 # Copyright (C) 2004 John Gruber
7 # Copyright (C) 2015,2016,2017,2018,2019,2020,2021 Kyle J. McKay
8 # All rights reserved.
9 # License is Modified BSD (aka 3-clause BSD) License\n";
10 # See LICENSE file (or <https://opensource.org/licenses/BSD-3-Clause>)
11 #
23 BEGIN {*COPYRIGHT =
25 Copyright (C) 2015,2016,2017,2018,2019,2020,2021 Kyle J. McKay
26 All rights reserved.
27 ";
30 }
32 use Exporter ();
43 }
53 }
60 }
62 #
63 # Global default settings:
64 #
73 }
76 #
77 # Globals:
78 #
80 # Style sheet template
83 # Permanent block id table
86 # Global hashes, used by various utility routines
99 # Return a "block id" to use to identify the block that does not contain
100 # any characters that could be misinterpreted by the rest of the code
101 # Originally this used md5_hex but that's unnecessarily slow
102 # Instead just use the refaddr of the scalar ref of the entry for that
103 # key in either the global or, if the optional second argument is true,
104 # permanent table. To avoid the result being confused with anything
105 # else, it's prefixed with a control character and suffixed with another
106 # both of which are not allowed by the XML standard or Unicode.
112 }
114 # Regex to match balanced [brackets]. See Friedl's
115 # "Mastering Regular Expressions", 2nd Ed., pp. 328-331.
121 |
122 \[
124 \]
125 )*
126 }ox
127 }
129 # Regex to match balanced (parentheses)
135 |
136 \(
138 \)
139 )*
140 }ox
141 }
143 # Table of hash values for escaped characters:
149 }
150 }
152 # Used to track when we're inside an ordered or unordered list
153 # (see _ProcessListItems() for details):
157 }
159 # Entity conversion table
411 ) }
414 #### Blosxom plug-in interface ##########################################
419 }
421 # Set $g_blosxom_use_meta to 1 to use Blosxom's meta plug-in to determine
422 # which posts Markdown should process, using a "meta-markup: markdown"
423 # header. If it's set to 0 (the default), Markdown will process all
424 # entries.
428 }
436 ) {
438 }
440 }
443 #### Movable Type plug-in interface #####################################
449 import MT;
460 });
462 }
472 }
477 });
491 }
495 }
499 }
500 }
503 },
504 });
506 # If SmartyPants is loaded, add a combo Markdown/SmartyPants text filter:
509 {
512 }
525 }
528 }
529 }
532 },
533 });
534 }
535 }
539 }
548 }
559 )}
569 )}
577 }
579 #### BBEdit/command-line text filter interface ##########################
584 #### Check for command-line switches: #################
590 GetOptions(
592 _require_pod_usage;
595 _require_pod_usage;
639 );
644 }
648 }
652 }
675 }
681 }
689 }
693 }
696 }
699 }
705 }
709 }
724 <!DOCTYPE html>
725 <html xmlns="http://www.w3.org/1999/xhtml">
726 <head>
727 <meta charset="utf-8" />
728 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
729 HTML5
732 <html>
733 <head>
734 <meta charset="utf-8">
735 <meta http-equiv="content-type" content="text/html; charset=utf-8">
736 HTML4
737 }
745 }
746 }
751 }
753 };
755 #### Process incoming text: ###########################
761 {
762 local $/; # Slurp the whole file
765 }
775 }
777 }
778 }
785 } else {
787 }
789 }
792 exit 0;
793 }
796 # INPUT
799 # that a value of undef turns off wiki links
800 # OUTPUT
803 #
804 sub SetWikiOpts {
810 # Parse wiki links option setting
815 } else {
817 }
826 }
831 }
833 }
836 # Return a copy of the fancy CSS style sheet that uses the
837 # passed in prefix as a prefix for the CSS style names.
838 # If no argument is passed in, use $g_style_prefix
839 # as the CSS style name prefix.
846 }
858 }
866 }
872 {
875 }
881 }
882 # Standardize line endings:
886 # Extract YAML front matter if requested
899 }
900 }
902 }
903 }
905 }
912 # only $ and/or @ present issues, map them
920 }
922 }
925 sub ProcessRaw {
928 # Any remaining arguments after the first are options; either a single
929 # hashref or a list of name, value pairs. See _SanitizeOpts comments.
933 );
937 } else {
939 }
942 }
945 # Sanitize all '<'...'>' tags if requested
948 # Eliminate known named character entities
952 # Convert to US-ASCII only if requested
963 }
965 }
969 #
970 # sanitize => any-false-value (no action), any-true-value (sanitize).
971 # note that a true value of xmlcheck or a true value of
972 # stripcomments or a urlfunc value that is a CODE ref
973 # always forces sanitize to activate.
975 # attributes (such as script attributes, unknown attributes
976 # and so forth) and normalizing the remaining ones (i.e.
977 # adding missing quotes and/or values etc.).
978 # effective for both ProcessRaw and Markdown.
979 # xmlcheck => 0 (no check), any-true-value (internal check).
980 # note that the default if xmlcheck is not set/valid is 2.
981 # note that a true value is effective for both ProcessRaw
982 # and Markdown. note that a true value automatically inserts
983 # the closing tag for auto-closing tags and converts empty tags
984 # to the correct format converting empty tags that shouldn't be
985 # to an open and close pair; since xmlcheck is a function of the
986 # sanitizer, tag attributes are also always sanitized whenever
987 # xmlcheck has a true value.
989 # detailed indication of the error(s) if xml validation fails
990 # in which case any line/column numbers refer to the text that
991 # would be produced by a sanitize=>0, xmlcheck=>0 call to
992 # either ProcessRaw or Markdown, NOT the original input text.
993 # htmlauto => any-false-value (no auto close), any-true-value (auto-close)
994 # only effective for ProcessRaw; always enabled for Markdown.
995 # when xmlcheck is set to 2 provide html automatic closing tag
996 # and optional closing tag semantics where closing tags are
997 # automatically inserted when encountering an opening tag that
998 # auto closes a currently open tag and tags with an optional
999 # closing tag that's missing have that inserted as appropriate.
1000 # a true value may result in some texts being rejected that
1003 # no longer validates).
1004 # stripcomments => any-false-value (no action), any-true-value (strip).
1005 # => 1 (strip-strict), 2 (strip-lax), 3 (strip-lax-only)
1006 # a non-numeric true value will be forced to 2.
1007 # a numeric value < 0 will be forced to 2.
1008 # a numeric value > 0 and < 1 will be forced to 2.
1009 # a numeric value > 3 will be forced to 3.
1010 # a non-integer value will forced to an integral value.
1011 # 1, 2, and 3 correspond to the command line options
1012 # --strip-comments-strict, --strip-comments-lax and
1013 # --strip-comments-lax-only respectively.
1014 # since the strip comments mechanism is a function of the
1015 # sanitizer, if stripcomments is set to any-true-value then
1016 # tag attributes will also always be sanitized.
1017 # if stripcomments is not set or is set to the empty string,
1018 # then it will be set to 3 if sanitize is true and 0 otherwise.
1019 # effective for both ProcessRaw and Markdown.
1022 # effective for both ProcessRaw and Markdown.
1025 # then known named character entities will be converted to
1026 # their equivalent numerical entity. Use of this option is
1027 # strongly discouraged to avoid strict XML validation failures.
1028 # us_ascii => if true, non-US-ASCII characters will be converted to
1029 # numerical character entities making the output US-ASCII only.
1030 # divwrap => if true, wrap output contents in <div>...</div>
1031 # divname => if defined and non-empty will be id of divwrap div tag
1032 # urlfunc => if set to a CODE ref, the function will be called with
1033 # seven arguments like so:
1041 # an empty string or the stripped off fragment if they were originally
1047 # to the other arguments like so:
1049 # All values passed to the urlfunc function have already been HTML
1050 # unescaped and the returned value will be automatically HTML escaped.
1051 # Any provided urlfunc should treat the %opts HASH as
1052 # read-only. Modifying the %opts HASH in urlfunc will
1053 # likely result in unpredictable behavior! Don't do it!
1054 # If urlfunc is set to a CODE ref then tags will also always be
1055 # sanitized.
1056 #
1057 # The remaining key value pairs are ignored by ProcessRaw and are only
1058 # effective when using Markdown or _main
1059 #
1060 # tab_width => 1..32 which is how many spaces tabs are expanded to.
1061 # will be forced to 8 if not in range.
1062 # indent_width => 1..32 how many spaces make a new "indent" level.
1063 # will be forced to 4 if not in range.
1064 # style_prefix => prefix to prepend to all CSS style names in the
1065 # fancy CSS style sheet.
1066 # defaults to $g_style_prefix if not defined.
1067 # note that _main actually adds the style sheet (when
1068 # requested); use GenerateStyleSheet to retrieve the
1069 # fancy style sheet when calling Markdown directly.
1070 # auto_number => <= 0 (default) no numbering, 1 number h1s,
1071 # 2 number h1s, h2s, 3 number h1-h3s, ... >= 6 number h1-h6s
1072 # anchors => existence of this key triggers return of anchors HASH
1073 # yamlmode => 0 (no YAML processing), > 0 (YAML on), < 0 (YAML ignore)
1074 # if 0, the YAML front matter processor is completely
1075 # disabled and any YAML front matter that might be present
1076 # will be treated as markup. if > 0 any YAML front matter
1077 # will be processed and any recognized options applied.
1078 # if < 0 any YAML front matter will be parsed but no
1079 # options will be applied at all. When != 0 the parsed
1080 # YAML front matter can be retrieved via the 'yaml' key.
1081 # defaults to 1 if not defined or not a number.
1082 # yamlvis => 0 (invisible), > 0 (visible), < 0 (vis if unknown)
1083 # if yamlmode == 0 then yamlvis has no effect. if > 0
1084 # then any parsed YAML front matter options will be shown
1085 # in the formatted output. if 0 then NO YAML front
1086 # matter options will be shown in the formatted output.
1087 # if < 0 then YAML front matter options will be shown in
1088 # the formatted output only if there are any unrecognized
1089 # options present.
1090 # defaults to -1 if not defined or not a number.
1091 # keepabs => any-false-value (no action), any-true-value (keep)
1092 # if true, any absolute path URLs remaining after applying
1093 # any abs_prefix value will be kept and not be subject
1094 # to modification by any url_prefix or img_prefix value.
1095 # abs_prefix => value to prefix to absolute path URLs (i.e. start with /).
1096 # note that this does NOT get prepended to //host/path URLs.
1097 # url_prefix => value to prefix to non-absolute URLs.
1098 # note that this does NOT get prepended to //host/path URLs.
1099 # img_prefix => value to prefix to non-absolute image URLs.
1100 # note that this does NOT get prepended to //host/path URLs.
1101 # note that if img_prefix is undef or empty ("") then
1102 # url_prefix will be prepended to image URLs.
1103 # base_prefix => value to prefix to fragment-only URLs (i.e. start with #).
1104 # note that fragment-only URLs are always left undisturbed
1105 # if this is not set. Fragment-only URLs are NOT affected by
1106 # any of abs_prefix, url_prefix or img_prefix.
1107 # wikipat => non-empty pattern string to enable wiki links.
1108 # best set with SetWikiOpts (see SetWikiOpts comments).
1109 # wikiopt => HASH ref of options affecting wiki links processing.
1110 # best set with SetWikiOpts (see SetWikiOpts comments).
1111 # wikifunc => if set to a CODE ref, the function will be called with
1112 # six arguments like so:
1113 # $result = &$wikifunc($iresult, \%opts, $link, $wbase, $qf, $io)
1114 # where on input $iresult is the result that would be produced
1115 # if no wikifunc was provided and on output $result will be
1116 # used as the wiki expansion. $link is the original wiki
1117 # destination as specified in the source, $wbase is the result
1118 # of stripping off any query string and/or fragment from $link
1119 # and then transforming that according to the wikiopt HASH ref.
1120 # $qf contains either an empty string or the stripped off
1121 # query string and/or fragment if one was originally present.
1122 # If $io is a HASH ref (otherwise it will be undef), then it's
1123 # a wiki image link and %$io contains the options (if any) where
1124 # the keys that might be present include "width", "height", "align"
1125 # and "alt". If present, width and height are guaranteed to be
1126 # positive integers and align is guaranteed to be "left", "right"
1127 # or "center". The value for "alt" may be the empty string.
1128 # The "imgflag" key has a SCALAR ref value and if the value it
1129 # refers to is changed to any false value the result will become
1130 # an A tag rather than an IMG tag.
1131 # The $iresult value is related to the other arguments like so:
1132 # $iresult = $opts->{wikipat};
1133 # $iresult =~ s/%\{\}.+$/%{}/ if ref($io) eq "HASH";
1134 # $iresult = s/%\{\}/$wbase/;
1135 # $iresult .= $qf;
1136 # Any provided wikifunc should treat the %opts HASH as
1137 # read-only. Modifying the %opts HASH in wikifunc will
1138 # likely result in unpredictable behavior! Don't do it!
1139 #
1140 # Special handling for abs_prefix, url_prefix, img_prefix and/or base_prefix
1141 # may be activated by setting any subset (or all) of the values for these
1142 # keys to a CODE ref. The single argument is the URL and the result must
1143 # be the adjusted URL. For example, the equivalent CODE ref to setting
1144 # url_prefix to $string is simply sub { $string.$_[0] }. By using a
1145 # CODE ref, behavior other than simply performing a prepend operation
1146 # can be realized when necessary for unusual situations.
1147 #
1148 # The following are OUTPUT values that can only be retrieved when
1149 # Markdown is called with a HASH ref as the second argument
1150 #
1151 # anchors => if the 'anchors' key exists in the input HASH ref
1152 # will be set to a HASH ref containing lookup keys
1153 # for valid fragment ids in the document (only those
1154 # created from Markdown markup) with the value the
1155 # actual fragment link to use. Do not use this directly
1156 # but pass it as the first argument to the ResolveFragment
1157 # function to resolve a "fuzzy" fragment name to its
1158 # actual fragment name in the generated output.
1159 # NOTE: to activate return of anchors the 'anchors' key
1160 # simply must exist in the input HASH ref passed to the
1161 # Markdown function, its value will be replaced on output.
1162 #
1163 # h1 => will be set to the tag-stripped value of the first
1164 # non-empty H1 generated by Markdown-style markup.
1165 # note that literal <h1>...</h1> values are NOT picked up.
1166 # will be left unchanged if no Markdown-style H1 detected.
1167 # note that the value is NOT xml escaped but should be
1168 # before embedding in an XHTML document. If yamlmode > 0
1169 # and a 'title' value has been encountered, then this
1170 # will be set to that 'title' value instead (and the
1171 # 'title' key and value will still be present in %$yaml).
1172 #
1173 # yaml => if yamlmode is != 0 then this will be set to a HASH
1174 # ref containing any parsed YAML front matter or left
1175 # unchanged if no YAML front matter was found. If the
1176 # parsed YAML front matter contains only whitespace and/or
1177 # comments then this will be set to a HASH ref that has
1178 # no keys or values.
1179 #
1198 # this is gross, but having the globals avoids unnecessary slowdown
1205 }
1226 }
1241 # Note that because Markdown makes a copy of the options
1242 # before calling this function, this does not actually remove
1243 # any "h1" key that might have been set by the caller of
1244 # the Markdown function. However, by deleting it here,
1245 # this guarantees that any found value will actually be
1246 # picked up and stored (which will not happen if the key
1247 # already exists).
1250 # Default is to silently strip any known YAML front matter
1251 # Same comment about "yaml" key as above for "h1" key
1256 # The anchors hash will only be returned if the key exists
1257 # (the key's value doesn't matter), set the value to an empty
1258 # HASH ref just in case to make sure it's always a HASH ref.
1260 }
1264 display_metadata
1265 header_enum
1266 title
1273 }
1279 # ignore display_metadata except in --yaml=enable mode
1281 }
1285 }
1286 }
1293 return !($v eq "" || $v eq "0" || $v eq "false" || $v eq "disable" || $v eq "off" || $v eq "no");
1294 }
1297 # Actually returns an empty string rather than a CODE ref
1298 # if an empty prefix is passed in. Trailing "/"s are trimmed
1299 # off if the second argument is positive or the string does NOT
1300 # consist of only "/"s. A trailing "/" is added unless the
1301 # trimmed prefix already has one or the second argument is true.
1302 # If the second argument is negative, the prefix is used as-is.
1311 }
1315 }
1319 #
1320 # Primary function. The order in which other subs are called here is
1321 # essential. Link and image substitutions need to happen before
1322 # _EscapeSpecialChars(), so that any *'s or _'s in the <a>
1323 # and <img> tags get encoded.
1324 #
1327 # Any remaining arguments after the first are options; either a single
1328 # hashref or a list of name, value pairs. See _SanitizeOpts comments.
1330 # set initial defaults
1339 );
1346 }
1349 }
1369 }
1371 }
1375 }
1376 }
1378 # Clear the globals. If we don't clear these, you get conflicts
1379 # from other articles when generating a page which contains more than
1380 # one article (e.g. an index page that shows the N most recent
1381 # articles):
1393 # Make sure $text ends with a couple of newlines:
1396 # Handle backticks-delimited code blocks
1399 # Convert all tabs to spaces.
1402 # Strip any lines consisting only of spaces.
1403 # This makes subsequent regexen easier to write, because we can
1404 # match consecutive blank lines with /\n+/ instead of something
1405 # contorted like / *\n+/ .
1408 # Turn block-level HTML blocks into hash entries
1411 # Strip link definitions, store in hashes.
1416 # Remove indentation markers
1419 # Expand auto number flags
1423 # Unhashify code blocks
1430 # Sanitize all '<'...'>' tags if requested
1433 # Eliminate known named character entities
1437 };
1439 # Convert to US-ASCII only if requested
1445 };
1453 }
1455 }
1463 }
1465 }
1469 #
1470 # Process Markdown backticks (```) delimited code blocks
1471 # Process some (limited recognition) tilde (~~~) delimited code blocks
1472 #
1482 )+?
1483 )
1484 # and ending with ``` or end of document
1486 }{
1495 $codeblock = "<div class=\"$opt{style_prefix}code-bt\"><pre style=\"display:none\"></pre><pre><code>"
1501 }egmx;
1507 (?:
1509 )+?
1510 )
1511 # and ending with ~~~ or end of document
1513 }{
1522 $codeblock = "<div class=\"$opt{style_prefix}code-bt\"><pre style=\"display:none\"></pre><pre><code>"
1528 }egmx;
1531 }
1534 sub _StripLinkDefinitions {
1535 #
1536 # Strips link definitions from text, stores the URLs and titles in
1537 # hash references.
1538 #
1542 # Link defs are in the form: ^[id]: url "optional title"
1545 [ ]*
1547 [ ]*
1549 [ ]*
1551 [ ]*
1552 (?:
1553 (?<=\s) # lookbehind for whitespace
1554 (?:(['"])|(\()) # title quote char
1556 (?(4)\)|\3) # match same quote
1557 [ ]*
1558 )? # title is optional
1560 }
1561 {}mx) {
1567 # These values always get passed through _MakeATag or _MakeIMGTag later
1571 }
1572 }
1573 }
1576 }
1580 BEGIN {
1581 $block_tags_a = qr/\020|p|div|center|h[1-6]|blockquote|pre|table|dl|ol|ul|script|noscript|form|fieldset|iframe|math|ins|del/io;
1582 $block_tags_b = qr/\020|p|div|center|h[1-6]|blockquote|pre|table|dl|ol|ul|script|noscript|form|fieldset|iframe|math/io;
1583 $block_tags_c = qr/div|center|h[1-6]|blockquote|pre|table|dl|ol|ul|script|noscript|form|fieldset|iframe|math/io;
1584 }
1586 sub _HashHTMLBlocks {
1594 # Hashify HTML blocks:
1595 # We only want to do this for block-level HTML tags, such as headers,
1596 # lists, and tables. That's because we still want to wrap <p>s around
1597 # "paragraphs" that are wrapped in non-block-level tags, such as anchors,
1598 # phrase emphasis, and spans. The list of tags we're looking for is
1599 # hard-coded:
1601 # First, look for nested blocks, e.g.:
1602 # <div>
1603 # <div>
1604 # tags for inner block must be indented.
1605 # </div>
1606 # </div>
1607 #
1608 # The outermost tags must start at the left margin for this to match, and
1609 # the inner nested divs must be indented.
1610 # We need to do this before the next, more liberal match, because the next
1614 ^ # start of line (with /m)
1619 \2</\3\s*> # the matching end tag
1620 [ ]* # trailing spaces
1622 )
1623 }{
1628 }eigmx;
1631 #
1633 #
1636 ^ # start of line (with /m)
1641 .*</\2\s*> # the matching end tag
1642 [ ]* # trailing spaces
1644 )
1645 }{
1650 }eigmx;
1652 #
1653 # Now match any empty block tags that should have been paired
1654 #
1657 ^ # start of line (with /m)
1661 (?:[^<>])*? #
1662 /?> # the matching end tag
1663 [ ]* # trailing spaces
1665 )
1666 }{
1670 }eigmx;
1672 # Special case just for <hr />. It was easier to make a special case than
1673 # to make the other regex more complicated.
1675 (?:
1677 | # or
1678 \A # the beginning of the doc
1679 )
1682 <(?:hr) # start tag
1684 (?:[^<>])*? #
1685 /?> # the matching end tag
1686 [ ]*
1688 )
1689 }{
1693 }eigx;
1695 # Special case for standalone XML comments:
1698 (?:
1700 | # or
1702 )
1705 (?s:
1706 <!--
1707 (?:[^-]|(?:-(?!-)))*
1708 -->
1709 (?:
1711 <!--
1712 (?:[^-]|(?:-(?!-)))*
1713 -->
1714 )*
1715 )
1716 [ ]*
1718 )
1719 }{
1726 }egx;
1728 # Special case for standalone XML-like comments:
1731 (?:
1733 | # or
1735 )
1738 (?s:
1739 <!--
1740 (?:[^-]|(?:-(?!->)))*
1741 -->
1742 (?:
1744 <!--
1745 (?:[^-]|(?:-(?!->)))*
1746 -->
1747 )*
1748 )
1749 [ ]*
1751 )
1752 }{
1757 }egx;
1761 }
1764 sub _RunBlockGamut {
1765 #
1766 # These are all the transformations that form block-level
1767 # tags like paragraphs, headers, and list items.
1768 #
1773 # Do Horizontal Rules:
1782 # We already ran _HashHTMLBlocks() before, in Markdown(), but that
1783 # was to escape raw HTML in the original Markdown source. This time,
1784 # we're escaping the markup we've just created, so that we don't wrap
1785 # <p> tags around block-level tags.
1791 }
1794 sub _DoBTListBlocks {
1796 }
1799 sub _DoListBlocks {
1801 }
1804 sub _RunSpanGamut {
1805 #
1806 # These are all the transformations that occur *within* block-level
1807 # tags like paragraphs, headers, and list items.
1808 #
1815 # Process anchor and image tags. Images must come first,
1816 # because ![foo][f] looks like an anchor.
1821 # Must come after _DoAnchors(), because you can use < and >
1822 # delimiters in inline links like [this](<url>).
1829 # Do hard breaks:
1836 }
1839 sub _EscapeSpecialChars {
1849 # Within tags, encode *, _ and ~ so they don't conflict
1850 # with their use in Markdown for italics and strong.
1851 # We're replacing each such character with its
1852 # corresponding block id value; this is likely
1853 # overkill, but it should prevent us from colliding
1854 # with the escape values by accident.
1857 } else {
1861 }
1862 }
1864 }
1867 sub _ProcessWikiLink {
1871 # Return the new link
1873 }
1878 # Return the new link
1880 }
1883 # Unrecognized scheme
1884 return undef;
1885 }
1898 } else {
1902 }
1904 }
1912 }
1914 $result = &{$opt{wikifunc}}($result, \%opt, ($img?$img_link:$link_loc), $base, $qsfrag, $imgopts)
1916 {
1917 use bytes;
1921 s/([\x00-\x1F <>"{}|\\^`x7F])/sprintf("%%%02X",ord($1))/soge;
1922 } else {
1924 s/([\x00-\x1F <>"{}|\\^`\x7F-\xFF])/sprintf("%%%02X",ord($1))/soge;
1925 }
1927 }
1928 # Return the new link
1930 }
1931 # leave it alone
1932 return undef;
1933 }
1936 sub _ParseWikiImgOpts {
1939 # alt= consumes the rest of the line, do it first
1944 }
1950 next;
1951 }
1954 next;
1955 }
1956 }
1957 }
1959 }
1962 sub _wxform {
1971 }
1972 } else {
1974 }
1975 }
1985 } else {
1988 }
1990 }
1993 # Return a suitably encoded <a...> tag string
1996 sub _MakeATag {
2007 # We've got to encode any of these remaining to avoid
2008 # conflicting with other italics, bold and strike through and links.
2013 }
2016 sub _DoAnchors {
2017 #
2018 # Turn Markdown link shortcuts into XHTML <a> tags.
2019 #
2022 #
2023 # First, handle wiki-style links: [[wiki style link]]
2024 #
2027 \[\[
2029 \]\]
2030 )
2031 }{
2040 }
2045 }xsge;
2047 #
2048 # Next, handle reference-style links: [link text] [id]
2049 #
2052 \[
2054 \]
2056 [ ]? # one optional space
2059 \[
2061 \]
2062 )
2063 }{
2070 # for shortcut links like [this][].
2073 }
2082 }
2083 else {
2085 }
2087 }xsge;
2089 #
2090 # Subsequently, inline-style links: [link text](url "optional title")
2091 #
2094 \[
2096 \]
2097 \( # literal paren
2099 \)
2100 )
2101 }{
2111 } else {
2112 # The href/title part didn't match the pattern
2114 }
2115 }xsge;
2117 #
2118 # Finally, handle reference-style implicit shortcut links: [link text]
2119 #
2122 \[
2124 \]
2125 )
2126 }{
2139 }
2140 else {
2142 }
2144 }xsge;
2147 }
2150 sub _PeelWrapped {
2154 }
2156 }
2159 sub _SplitUrlTitlePart {
2164 ^ # match beginning
2165 \s*?
2167 (?: # optional grouping
2168 \s+ # must be distinct from URL
2171 \2? # matching quote
2172 )? # title is optional
2173 \s*
2174 \z # match end
2175 }osx) {
2178 } else {
2179 return (undef, undef);
2180 }
2181 }
2184 sub _FindFragmentMatchInternal {
2187 # try very hard to find a match
2194 } else {
2199 } else {
2203 } else {
2207 }
2208 }
2209 }
2210 }
2211 }
2213 }
2216 sub _FindFragmentMatch {
2218 }
2221 sub _ToUTF8 {
2226 } else {
2228 }
2230 }
2235 # An empty string ("") or hash ("#") is returned as-is.
2236 # returns undef if no match otherwise resolved fragment name
2238 # This function can be used to connect up links to "implicit" anchors.
2239 # All Markdown-format H1-H6 headers have an implicit anchor added
2240 # based on the header item text. Passing that text to this function
2241 # will cough up the matching implicit anchor if there is one.
2242 sub ResolveFragment
2243 {
2254 }
2257 # Return a suitably encoded <img...> tag string
2260 sub _MakeIMGTag {
2278 }
2302 }
2305 sub _DoImages {
2306 #
2307 # Turn Markdown image shortcuts into <img> tags.
2308 #
2311 #
2312 # First, handle reference-style labeled images: ![alt text][id]
2313 #
2316 !\[
2318 \]
2320 [ ]? # one optional space
2323 \[
2325 \]
2327 )
2328 }{
2340 }
2341 else {
2342 # If there's no such link ID, leave intact:
2344 }
2347 }xsge;
2349 #
2350 # Next, handle inline images: 
2351 # Don't forget: encode * and _
2355 !\[
2357 \]
2358 \( # literal paren
2360 \)
2361 )
2362 }{
2367 }xsge;
2369 #
2370 # Finally, handle reference-style implicitly labeled links: ![alt text]
2371 #
2374 !\[
2376 \]
2377 )
2378 }{
2387 }
2388 else {
2389 # If there's no such link ID, leave intact:
2391 }
2394 }xsge;
2397 }
2399 sub _EncodeAttText {
2403 # We've got to encode these to avoid conflicting
2404 # with italics, bold and strike through.
2407 }
2410 sub _MakeAnchorId {
2411 use bytes;
2417 } else {
2419 }
2425 }
2428 sub _GetNewAnchorId {
2440 }
2449 }
2450 }
2452 }
2455 sub _DoHeaders {
2462 } : sub {};
2464 # atx-style headers:
2465 # # Header 1
2466 # ## Header 2
2467 # ## Header 2 with closing hashes ##
2468 # ...
2469 # ###### Header 6
2470 #
2473 [ ]*
2475 [ ]*
2477 }{
2488 }egmx;
2490 # Setext-style headers:
2491 # Header 1
2492 # ========
2493 #
2494 # Header 2
2495 # --------
2496 #
2497 # Header 3
2498 # ~~~~~~~~
2499 #
2508 }egmx;
2517 }egmx;
2526 }egmx;
2530 }
2533 sub _AutoHeaderFlag {
2538 }
2541 sub _AutoHeaderNum {
2549 }
2553 BEGIN {
2554 # Re-usable patterns to match list item bullets and number markers:
2556 [IiVvXx]|[Ii]{2,3}|[Ii][VvXx]|[VvXx][Ii]{1,3}|[Xx][Vv][Ii]{0,3}|
2557 [Xx][Ii][VvXx]|[Xx]{2}[Ii]{0,3}|[Xx]{2}[Ii]?[Vv]|[Xx]{2}[Vv][Ii]{1,2})/ox;
2562 }
2565 sub _GetListMarkerType {
2577 return "1";
2578 }
2581 sub _GetListItemTypeClass {
2592 return "decimal";
2593 }};
2595 }
2599 BEGIN {
2601 i => 1,
2602 ii => 2,
2603 iii => 3,
2604 iv => 4,
2605 v => 5,
2606 vi => 6,
2607 vii => 7,
2608 viii => 8,
2609 ix => 9,
2610 x => 10,
2611 xi => 11,
2612 xii => 12,
2613 xiii => 13,
2614 xiv => 14,
2615 xv => 15,
2616 xvi => 16,
2617 xvii => 17,
2618 xviii => 18,
2619 xix => 19,
2620 xx => 20,
2621 xxi => 21,
2622 xxii => 22,
2623 xxiii => 23,
2624 xxiv => 24,
2625 xxv => 25,
2626 xxvi => 26,
2627 xxvii => 27
2628 );
2629 }
2632 # Necessary because ς and σ are the same value grrr
2634 BEGIN {
2636 "\x{03b1}" => 1, # α
2637 "\x{03b2}" => 2, # β
2638 "\x{03b3}" => 3, # γ
2639 "\x{03b4}" => 4, # δ
2640 "\x{03b5}" => 5, # ε
2641 "\x{03b6}" => 6, # ζ
2642 "\x{03b7}" => 7, # η
2643 "\x{03b8}" => 8, # θ
2644 "\x{03b9}" => 9, # ι
2645 "\x{03ba}" => 10, # κ
2646 "\x{03bb}" => 11, # λ
2647 #"\x{00b5}"=> 12, # µ is "micro" not "mu"
2648 "\x{03bc}" => 12, # μ
2649 "\x{03bd}" => 13, # ν
2650 "\x{03be}" => 14, # ξ
2651 "\x{03bf}" => 15, # ο
2652 "\x{03c0}" => 16, # π
2653 "\x{03c1}" => 17, # ρ
2654 "\x{03c2}" => 18, # ς
2655 "\x{03c3}" => 18, # σ
2656 "\x{03c4}" => 19, # τ
2657 "\x{03c5}" => 20, # υ
2658 "\x{03c6}" => 21, # φ
2659 "\x{03c7}" => 22, # χ
2660 "\x{03c8}" => 23, # ψ
2661 "\x{03c9}" => 24 # ω
2662 );
2663 }
2666 sub _GetMarkerIntegerNum {
2679 return 1;
2680 }};
2683 }
2686 sub _IncrList {
2693 }
2697 }
2701 }
2705 }
2707 }
2710 sub _DoListsAndBlocks {
2711 #
2712 # Form HTML ordered (numbered) and unordered (bulleted) lists.
2713 #
2719 # Re-usable pattern to match any entire ul or ol list:
2726 [ ]+
2727 )
2728 (?s:.+?)
2730 \z
2731 |
2733 (?=\S)
2734 (?! # Negative lookahead for another list item marker
2735 ${marker_any}[ ]
2736 )
2737 )
2738 )
2739 }mx;
2747 # Turn double returns into triple returns, so that we can make a
2748 # paragraph for the last item in a list, if necessary:
2765 } else {
2769 }
2770 }
2772 $result = "$idt<$list_type$list_att$list_class>\n$list_incr" . $result . "$idt</$list_type>\n\n";
2774 };
2776 # We use a different prefix before nested lists than top-level lists.
2777 # See extended comment in _ProcessListItems().
2778 #
2779 # Note: (jg) There's a bit of duplication here. My original implementation
2780 # created a scalar regex pattern as the conditional result of the test on
2782 # substitution once, using the scalar as the pattern. This worked,
2783 # everywhere except when running under MT on my hosting account at Pair
2784 # Networks. There, this caused all rebuilds to be killed by the reaper (or
2785 # perhaps they crashed, but that seems incredibly unlikely given that the
2786 # same script on the same server ran fine *except* under MT. I've spent
2787 # more time trying to figure out why this is happening than I'd like to
2788 # admit. My only guess, backed up by the fact that this workaround works,
2789 # is that Perl optimizes the substition when it can figure out that the
2790 # pattern will never change, and when this optimization isn't on, we run
2791 # afoul of the reaper. Thus, the slightly redundant code to that uses two
2792 # static s/// patterns rather than one conditional pattern.
2793 #
2794 # Note: (kjm) With the addition of the two-of-the-same-kind-in-a-row-
2795 # starts-a-list-at-the-top-level rule the two patterns really are somewhat
2796 # different now, but the duplication has pretty much been eliminated via
2797 # use of a separate sub which has the side-effect of making the below
2798 # two cases much easier to grok all at once.
2806 if ($-[1] > $-[0]) {
2808 }
2810 }
2812 }
2813 else {
2829 )
2830 $whole_list
2831 }gmcx) {
2833 if ($-[1] > $-[0]) {
2835 }
2837 }
2839 }
2842 }
2845 sub _ProcessListItems {
2846 #
2847 # Process the contents of a single ordered or unordered list, splitting it
2848 # into individual list items.
2849 #
2855 # Each time we enter a list, we increment it; when we leave a list,
2856 # we decrement. If it's zero, we're not in a list anymore.
2857 #
2858 # We do this because when we're not inside a list, we want to treat
2859 # something like this:
2860 #
2861 # I recommend upgrading to version
2862 # 8. Oops, now this line is treated
2863 # as a sub-list.
2864 #
2865 # As a single paragraph, despite the fact that the second line starts
2866 # with a digit-period-space sequence.
2867 #
2868 # Whereas when we're inside a list (or sub-list), that line will be
2869 # treated as the start of a sub-list. What a kludge, huh? This is
2870 # an aspect of Markdown's syntax that's hard to parse perfectly
2871 # without resorting to mind-reading. Perhaps the solution is to
2872 # change the syntax rules such that sub-lists must start with a
2873 # starting cardinal number; e.g. "1." or "a.".
2887 # trim trailing blank lines:
2897 }cgmx) {
2906 }
2915 }
2917 # Wrong marker kind, "fix up" the marker to a correct "lazy" marker
2918 # But keep the old length in $list_marker_len
2920 }
2922 # Now grab the rest of this item's data upto but excluding the next
2923 # list marker at the SAME indent level, but sublists must be INCLUDED
2934 # If $3 has a left edge that is at the left edge of the previous
2935 # marker OR $3 has a right edge that is at the right edge of the
2936 # previous marker then we stop; otherwise we go on
2941 # move along, you're not the marker droid we're looking for...
2944 }
2945 # Remember where we parked
2948 # Process the $list_marker $item
2962 }
2964 $checkbox = "<span><span></span></span><span></span><span>[<tt>$checkbox_val</tt>] </span>";
2976 }
2988 }
2989 }
2998 }
3001 $item =~ s{(</[OUou][Ll]>)\s*\z}{$1} and $item .= "\n$idt<span style=\"display:none\"> </span>";
3002 }
3004 # Recursion for sub-lists:
3008 }
3010 # Append to $result
3012 }
3014 # remove "incrlevel=$g_list_level " parts
3018 # remove the $g_list_level incr spans entirely
3019 $result =~ s{<span incrlevel=$g_list_level class="$opt{style_prefix}ol-incr(?:-\d{1,2})?"></span>\n}{}g;
3020 # remove the class="$opt{style_prefix}lc-greek" if first_marker is greek
3022 if defined($first_marker_type) && $first_marker_type eq "a" && $first_marker =~ /^$greek_lower/o;
3023 }
3025 # Anything left over (similar to $') goes into result, but this should always be empty
3026 $result .= _RunBlockGamut(substr($list_str, pos($list_str))) if pos($list_str) < length($list_str);
3030 # After all that, if we only got an ordered list with a single item
3031 # and its first marker is a four-digit number >= 1492 and <= 2999
3032 # or an UPPERCASE letter, then pretend we didn't see any list at all.
3038 }
3039 }
3042 }
3046 #
3047 # Process Markdown `<pre><code>` blocks.
3048 #
3059 )+
3060 )
3061 (?:(?=(^[ ]{0,$less_than_indent}\S.*))|\Z) # Lookahead for non-space at line-start, or end of doc
3065 if (defined($n) && length($n) && (()=($codeblock =~ /\n/g)) == 1 && _IsTableStart($codeblock.$n."\n")) {
3067 }
3074 my $result = "<div class=\"$opt{style_prefix}code\"><pre style=\"display:none\"></pre><pre><code>"
3082 }
3086 #
3087 # * Backtick quotes are used for <code></code> spans.
3088 #
3089 # * You can use multiple backticks as the delimiters if you want to
3090 # include literal backticks in the code span. So, this input:
3091 #
3092 # Just type ``foo `bar` baz`` at the prompt.
3093 #
3094 # Will translate to:
3095 #
3096 # <p>Just type <code>foo `bar` baz</code> at the prompt.</p>
3097 #
3098 # There's no arbitrary limit to the number of backticks you
3099 # can use as delimters. If you need three consecutive backticks
3100 # in your code, use four for delimiters, etc.
3101 #
3102 # * You can use spaces to get literal backticks at the edges:
3103 #
3104 # ... type `` `bar` `` ...
3105 #
3106 # Turns to:
3107 #
3108 # ... type <code>`bar`</code> ...
3109 #
3117 \1 # Matching closer
3119 @
3128 }
3132 #
3133 # Encode/escape certain characters inside Markdown code runs.
3134 # The point is that in code, these characters are literals,
3135 # and lose their special Markdown meanings.
3136 #
3139 # Encode all ampersands; HTML entities are not
3140 # entities within a Markdown code span.
3143 # Encode $'s, but only if we're running under Blosxom.
3144 # (Blosxom interpolates Perl variables in article bodies.)
3147 # Do the angle bracket song and dance:
3151 # Now, escape characters that are magic in Markdown:
3155 }
3165 # We've got to encode any of these remaining to
3166 # avoid conflicting with other italics and bold.
3169 };
3174 # We've got to encode any of these remaining to
3175 # avoid conflicting with other italics and bold.
3178 };
3180 # <strong> must go first:
3195 }
3203 (
3208 )+
3209 )
3210 }{
3222 }
3233 }
3253 }
3256 }
3278 )*)
3279 )
3280 } {
3293 my $tab ="\n<table border=\"1\" cellspacing=\"0\" cellpadding=\"2\" class=\"$opt{style_prefix}table$nohdr\">\n";
3304 }
3308 }
3324 }
3330 }
3333 }
3334 }
3336 }
3343 }
3351 }
3369 }
3381 }
3383 }
3387 #
3388 # Params:
3389 # $text - string to process with html <p> tags
3390 #
3393 # Strip leading and trailing lines:
3399 #
3400 # Wrap <p> tags.
3401 #
3407 }
3408 }
3410 #
3411 # Strip standalone XML comments if requested
3412 #
3419 }
3421 #
3422 # Unhashify HTML blocks
3423 #
3427 }
3428 }
3431 }
3434 # %ok_tag_name declared previously
3437 # note: length("blockquote") == 10
3440 a abbr acronym address area
3441 b basefont bdo big blockquote br
3442 caption center cite code col colgroup
3443 dd del dfn div dl dt
3444 em
3445 font
3446 h1 h2 h3 h4 h5 h6 hr
3447 i img ins
3448 kbd
3449 li
3450 map
3451 ol
3452 p pre
3453 q
3454 s samp small span strike strong sub sup
3455 table tbody td tfoot th thead tr tt
3456 u ul
3457 var
3460 dir menu
3462 }
3469 }
3472 # Encode leading '<' of any non-tags
3473 # However, "<?", "<!" and "<$" are passed through (legacy on that "<$" thing)
3477 if (($tag =~ m{^<($g_possible_tag_name)(?:[\s>]|/>$)} || $tag =~ m{^</($g_possible_tag_name)\s*>}) &&
3483 }
3486 }
3488 # Strip out all tags that _DoTag would match
3494 if (($tag =~ m{^<($g_possible_tag_name)(?:[\s>]|/>$)} || $tag =~ m{^</($g_possible_tag_name)\s*>}) &&
3498 }
3500 };
3503 }
3536 # NO server-side image maps, therefore NOT ismap !
3544 'table' => { map({$_ => 1} qw(align bgcolor border cellpadding cellspacing frame rules summary width)) },
3548 'td' => { map({$_ => 1} qw(align bgcolor char charoff colspan height nowrap rowspan valign width)) },
3549 'th' => { map({$_ => 1} qw(align bgcolor char charoff colspan height nowrap rowspan valign width)) },
3552 );
3566 );
3567 %tagblk = map({$_ => 1} qw(address blockquote center div dl h1 h2 h3 h4 h5 h6 hr ol p pre table ul));
3572 align border cellpadding cellspacing checked clear color colspan
3573 compact coords height hspace ismap nohref noshade nowrap rowspan size
3574 span shape valign vspace width
3577 }
3580 # _SanitizeTags
3581 #
3582 # Inspect all '<'...'>' tags in the input and HTML encode those things
3583 # that cannot possibly be tags and at the same time sanitize them.
3584 #
3585 # $1 => text to process
3586 # <= sanitized text
3605 }
3621 }
3627 }
3628 }
3635 }
3641 }
3646 };
3650 }
3654 # pass "comments" through unless stripping them
3656 # strip any trailing whitespace + \n after comment if present
3659 # pass the "comment" on through
3661 }
3663 }
3666 # strip any trailing whitespace + \n after lax comment if present
3669 }
3676 {
3681 }
3690 };
3697 };
3702 };
3716 }
3717 }
3718 }
3726 }
3727 }
3728 # can only get here if "\G" char is an unmatched "<"
3732 }
3742 }
3744 }
3745 # Remove any unwanted extra leading <p></p> sections
3749 }
3759 }
3764 }
3775 }
3787 # pretend the "=" sign wasn't overlooked
3789 }
3791 # it's one of "those" attributes (e.g. compact) or not
3792 # _SanitizeAtt will fix it up if it is
3796 }
3801 }
3803 # what to do what to do what to do
3804 # trim trailing \s+ and magically add the missing quote
3810 }
3812 # auto quote it
3818 }
3819 # give it an empty value
3822 }
3836 }
3839 }
3852 }
3853 }
3855 }
3871 };
3877 }
3892 }
3894 }
3895 }
3904 }
3905 }
3922 }
3925 }
3927 }
3929 }
3934 }
3937 }
3944 # $_[0] => the value to XML escape
3945 # returns the XML escaped value
3946 # Encodes the five required entites (amp,lt,gt,quot,apos)
3947 # while preserving any pre-existing entities which means that
3948 # calling this repeatedly on already-escaped text should return
3949 # it unchanged (i.e. it's idempotent).
3950 #
3954 # Treat these accidents as though they had the needed ';'
3957 # Ampersand-encoding based entirely on Nat Irons's Amputator MT plugin:
3958 # http://bumppo.net/projects/amputator/
3961 # Remaining entities now
3968 }
3971 # $_[0] => value to be unescaped
3972 # returns unescaped value
3973 # The five required XML entities (amp,lt,gt,quot,apos) plus nbsp
3974 # are decoded as well as decimal (#d+) and hexadecimal (#xh+).
3975 #
3976 # While the escapeXML function tries to be idempotent when presented
3977 # with an already-escaped string, this function is NOT necessarily
3978 # idempotent when presented with an already decoded string unless it's
3979 # been decoded to the point there are no more recognizable entities left.
3980 # In other words given a string such as:
3981 #
3982 # &amp;amp;amp;
3983 #
3984 # Each call will only decode one layer of escaping and it will take four
3985 # successive calls to finally end up with just "&".
3986 #
3990 # Treat these accidents as though they had the needed ';'
4003 $_
4007 }
4010 # $_[0] => the input URL to split
4011 # $_[1] => if a true value, call unescapeXML before splitting
4012 # returns array:
4013 # [0] => scheme, name+password, host, port ("" if not present)
4014 # [1] => path in url (starts with "/" if absolute otherwise relative)
4015 # [2] => query string ("" if not present otherwise starts with "?")
4016 # [3] => fragment ("" if not present otherwise starts with "#")
4017 # The returned value recovers the (possibly unescapeXML'd) input
4018 # string by simply concatenating the returned array elements.
4019 #
4027 }
4031 }
4034 }
4041 } }
4044 # $_[0] => the input text to process
4045 # returns text with all known named character entities replaced
4046 # with their equivalent numerical entity
4053 }
4061 } }
4064 # $_[0] => the input text to process
4065 # returns text with non-US-ASCII characters replaced
4066 # with their equivalent numerical character entities,
4067 # but only if the input text has already been utf8::decode'd
4073 }
4079 # Treat these accidents as though they had the needed ';'
4082 # Ampersand-encoding based entirely on Nat Irons's Amputator MT plugin:
4083 # http://bumppo.net/projects/amputator/
4087 }
4091 # Smart processing for ampersands and angle brackets that need to be encoded.
4095 # Treat these accidents as though they had the needed ';'
4098 # Ampersand-encoding based entirely on Nat Irons's Amputator MT plugin:
4099 # http://bumppo.net/projects/amputator/
4102 # Encode naked <'s
4106 # Encode <'s that cannot possibly be a start or end tag
4110 }
4114 #
4115 # Parameter: String.
4116 # Returns: String after processing the following backslash escape sequences.
4117 #
4124 }
4132 # Email addresses: <address@domain.foo>
4133 s{
4134 <
4136 (
4138 \@
4140 )
4141 >
4142 }{
4146 # (kjm) I don't do "x" patterns
4147 s{(?:^|(?<=\s))((?:https?|ftps?)://(?:[-a-zA-Z0-9./?\&\%=_~!*;:\@+\$,\x23](?:(?<![.,:;])|(?=[^\s])))+)}
4153 }
4157 #
4158 # Input: an email address, e.g. "foo@example.com"
4159 #
4160 # Output: the email address as a mailto link, with each character
4161 # of the address encoded as either a decimal or hex entity, in
4162 # the hopes of foiling most address harvesting spam bots. E.g.:
4163 #
4164 # <a href="mailto:foo@e
4165 # xample.com">foo
4166 # @example.com</a>
4167 #
4168 # Based on a filter by Matthew Wickline, posted to the BBEdit-Talk
4169 # mailing list: <https://tinyurl.com/yu7ue>
4170 #
4181 );
4188 # this *must* be encoded. I insist.
4191 # leave ':' alone (to spot mailto: later)
4193 # roughly 10% raw, 45% hex, 45% dec
4198 );
4199 }
4203 # strip the mailto: from the visible part
4208 }
4212 #
4213 # Swap back in all the special characters we've hidden.
4214 #
4219 }
4221 }
4225 #
4226 # Parameter: String containing HTML markup.
4227 # Returns: Reference to an array of the tokens comprising the input
4228 # string. Each token is either a tag (possibly with nested,
4229 # tags contained therein, such as <a href="<MTFoo>">, or a
4230 # run of text between tags. Each element of the array is a
4231 # two-element array; the first is either 'tag' or 'text';
4232 # the second is the actual value.
4233 #
4234 #
4235 # Derived from the _tokenize() subroutine from Brad Choate's MTRegex plugin.
4236 # <https://web.archive.org/web/20041215155739/http://bradchoate.com/weblog/2002/07/27/mtregex>
4237 #
4256 }
4259 }
4262 }
4266 #
4267 # Remove one level of line-leading indent_width of spaces
4268 #
4273 }
4276 # _DeTab
4277 #
4278 # $1 => input text
4279 # $2 => optional tab width (default is $opt{tab_width})
4280 # $3 => leading spaces to strip off each line first (default is 0 aka none)
4281 # <= result with tabs expanded
4297 }
4299 # From the Perl camel book section "Fluent Perl" but modified a bit
4302 }
4304 }
4308 #
4309 # Add URL prefix if needed
4310 #
4329 }
4335 <style type="text/css">
4336 /* <![CDATA[ */
4338 /* Markdown.pl fancy style sheet
4339 ** Copyright (C) 2017,2018,2019,2020,2021 Kyle J. McKay.
4340 ** All rights reserved.
4341 **
4342 ** Redistribution and use in source and binary forms, with or without
4343 ** modification, are permitted provided that the following conditions are met:
4344 **
4345 ** 1. Redistributions of source code must retain the above copyright notice,
4346 ** this list of conditions and the following disclaimer.
4347 **
4348 ** 2. Redistributions in binary form must reproduce the above copyright
4349 ** notice, this list of conditions and the following disclaimer in the
4350 ** documentation and/or other materials provided with the distribution.
4351 **
4352 ** 3. Neither the name of the copyright holder nor the names of its
4353 ** contributors may be used to endorse or promote products derived from
4354 ** this software without specific prior written permission.
4355 **
4356 ** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
4357 ** AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
4358 ** IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
4359 ** ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
4360 ** LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
4361 ** CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
4362 ** SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
4363 ** INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
4364 ** CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
4365 ** ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
4366 ** POSSIBILITY OF SUCH DAMAGE.
4367 */
4369 div.%(base)code-bt > pre, div.%(base)code > pre {
4370 margin: 0;
4371 padding: 0;
4372 overflow: auto;
4373 }
4375 div.%(base)code-bt > pre > code, div.%(base)code > pre > code {
4376 display: inline-block;
4377 margin: 0;
4378 padding: 0.5em 0;
4379 border-top: thin dotted;
4380 border-bottom: thin dotted;
4381 }
4383 table.%(base)table {
4384 margin-bottom: 0.5em;
4385 }
4386 table.%(base)table, table.%(base)table th, table.%(base)table td {
4387 border-collapse: collapse;
4388 border-spacing: 0;
4389 border: thin solid;
4390 }
4391 table.%(base)yaml-table {
4392 border-collapse: collapse;
4393 }
4394 table.%(base)yaml-table * {
4395 border: thin solid;
4396 }
4397 table.%(base)yaml-table th {
4398 text-align: center;
4399 }
4400 table.%(base)yaml-table th, table.%(base)yaml-table td {
4401 padding-left: 0.5ex;
4402 padding-right: 0.5ex;
4403 }
4405 ol.%(base)ol {
4406 counter-reset: %(base)item;
4407 }
4408 ol.%(base)ol[start="0"] {
4409 counter-reset: %(base)item -1;
4410 }
4411 ol.%(base)ol[start="5"] {
4412 counter-reset: %(base)item 4;
4413 }
4414 ol.%(base)ol[start="10"] {
4415 counter-reset: %(base)item 9;
4416 }
4417 ol.%(base)ol > span.%(base)ol-incr {
4418 counter-increment: %(base)item;
4419 }
4420 ol.%(base)ol > span.%(base)ol-incr-2 {
4421 counter-increment: %(base)item 2;
4422 }
4423 ol.%(base)ol > span.%(base)ol-incr-5 {
4424 counter-increment: %(base)item 5;
4425 }
4426 ol.%(base)ol > span.%(base)ol-incr-10 {
4427 counter-increment: %(base)item 10;
4428 }
4429 ol.%(base)lc-greek, li.%(base)lc-greek {
4430 list-style-type: lower-greek;
4431 }
4432 ol.%(base)ol > li {
4433 counter-increment: %(base)item;
4434 }
4435 ol.%(base)ol > li.%(base)li,
4436 ol.%(base)ol > li.%(base)li-lc,
4437 ol.%(base)ol > li.%(base)li-lc-greek,
4438 ol.%(base)ol > li.%(base)li-uc {
4439 list-style-type: none;
4440 display: block;
4441 }
4442 ol.%(base)ol > li.%(base)li:before,
4443 ol.%(base)ol > li.%(base)li-lc:before,
4444 ol.%(base)ol > li.%(base)li-lc-greek:before,
4445 ol.%(base)ol > li.%(base)li-uc:before {
4446 position: absolute;
4447 text-align: right;
4448 white-space: nowrap;
4449 margin-left: -9ex;
4450 width: 9ex;
4451 }
4452 ol.%(base)ol > li.%(base)li[type="1"]:before {
4453 content: counter(%(base)item, decimal) ")\A0 \A0 ";
4454 }
4455 ol.%(base)ol > li.%(base)li-lc[type="i"]:before,
4456 ol.%(base)ol > li.%(base)li-lc[type="I"]:before {
4457 content: counter(%(base)item, lower-roman) ")\A0 \A0 ";
4458 }
4459 ol.%(base)ol > li.%(base)li-uc[type="I"]:before,
4460 ol.%(base)ol > li.%(base)li-uc[type="i"]:before {
4461 content: counter(%(base)item, upper-roman) ")\A0 \A0 ";
4462 }
4463 ol.%(base)ol > li.%(base)li-lc[type="a"]:before,
4464 ol.%(base)ol > li.%(base)li-lc[type="A"]:before {
4465 content: counter(%(base)item, lower-alpha) ")\A0 \A0 ";
4466 }
4467 ol.%(base)ol > li.%(base)li-lc-greek[type="a"]:before,
4468 ol.%(base)ol > li.%(base)li-lc-greek[type="A"]:before {
4469 content: counter(%(base)item, lower-greek) ")\A0 \A0 ";
4470 }
4471 ol.%(base)ol > li.%(base)li-uc[type="A"]:before,
4472 ol.%(base)ol > li.%(base)li-uc[type="a"]:before {
4473 content: counter(%(base)item, upper-alpha) ")\A0 \A0 ";
4474 }
4476 li.%(base)checkbox-on,
4477 li.%(base)checkbox-off {
4478 list-style-type: none;
4479 display: block;
4480 }
4481 li.%(base)checkbox-on > span:first-child + span + span,
4482 li.%(base)checkbox-off > span:first-child + span + span {
4483 position: absolute;
4484 clip: rect(0,0,0,0);
4485 }
4486 li.%(base)checkbox-on > span:first-child,
4487 li.%(base)checkbox-off > span:first-child,
4488 li.%(base)checkbox-on > span:first-child + span,
4489 li.%(base)checkbox-off > span:first-child + span {
4490 display: block;
4491 position: absolute;
4492 margin-left: -3ex;
4493 width: 1em;
4494 height: 1em;
4495 }
4496 li.%(base)checkbox-on > span:first-child > span:first-child,
4497 li.%(base)checkbox-off > span:first-child > span:first-child {
4498 display: block;
4499 position: absolute;
4500 left: 0.75pt; top: 0.75pt; right: 0.75pt; bottom: 0.75pt;
4501 }
4502 li.%(base)checkbox-on > span:first-child > span:first-child:before,
4503 li.%(base)checkbox-off > span:first-child > span:first-child:before {
4504 display: inline-block;
4505 position: relative;
4506 right: 1pt;
4507 width: 100%;
4508 height: 100%;
4509 border: 1pt solid;
4510 content: "";
4511 }
4512 li.%(base)checkbox-on > span:first-child + span:before {
4513 position: relative;
4514 left: 2pt;
4515 bottom: 1pt;
4516 font-size: 125%;
4517 line-height: 80%;
4518 vertical-align: text-top;
4520 }
4522 /* ]]> */
4523 </style>
4525 STYLESHEET
4529 }
4533 __DATA__
4535 =head1 NAME
4537 Markdown.pl - convert Markdown format text files to HTML
4539 =head1 SYNOPSIS
4541 B<Markdown.pl> [B<--help>] [B<--html4tags>] [B<--htmlroot>=I<prefix>]
4542 [B<--imageroot>=I<prefix>] [B<--version>] [B<--shortversion>]
4543 [B<--tabwidth>=I<num>] [B<--stylesheet>] [B<--stub>] [--]
4544 [I<file>...]
4546 Options:
4547 -h show short usage help
4548 --help show long detailed help
4549 --html4tags use <br> instead of <br />
4550 --deprecated allow <dir> and <menu> tags
4551 --sanitize sanitize tag attributes
4552 --no-sanitize do not sanitize tag attributes
4553 --validate-xml check if output is valid XML
4554 --validate-xml-internal fast basic check if output is valid XML
4555 --no-validate-xml do not check output for valid XML
4556 --strip-comments remove XML-like comments from output
4557 --strip-comments-lax remove XML-like comments from output
4558 --strip-comments-strict remove only strictly valid XML comments
4559 --strip-comments-lax-only remove only invalid XML-like comments
4560 --no-strip-comments do not remove any XML/XML-like comments
4561 --tabwidth=num expand tabs to num instead of 8
4562 --auto-number automatically number h1-h6 headers
4563 -k | --keep-abs keep abspath URLs despite -r/-i
4564 -a prefix | --absroot=prefix append abspath URLs to prefix
4565 -b prefix | --base=prefix prepend prefix to fragment-only URLs
4566 -r prefix | --htmlroot=prefix append relative non-img URLs to prefix
4567 -i prefix | --imageroot=prefix append relative img URLs to prefix
4568 -w [wikipat] | --wiki[=wikipat] activate wiki links using wikipat
4569 --yaml[=(enable|disable|strip|...)] select YAML front matter processing
4570 -V | --version show version, authors, license
4571 and copyright
4572 -s | --shortversion show just the version number
4573 --raw | --raw-xml input contains only raw xhtml
4574 --raw-html input contains only raw html
4575 --div[=id] wrap body in div with given id
4576 --stylesheet output the fancy style sheet
4577 --no-stylesheet do not output fancy style sheet
4578 --keep-named-character-entities do not convert named character entities
4579 --us-ascii convert non-ASCII to character entities
4580 --stub wrap output in stub document
4581 implies --stylesheet
4582 -- end options and treat next
4583 argument as file
4585 =head1 DESCRIPTION
4587 Markdown is a text-to-HTML filter; it translates an easy-to-read /
4588 easy-to-write structured text format into HTML. Markdown's text format
4589 is most similar to that of plain text email, and supports features such
4590 as headers, *emphasis*, code blocks, blockquotes, and links.
4592 Markdown's syntax is designed not as a generic markup language, but
4593 specifically to serve as a front-end to (X)HTML. You can use span-level
4594 HTML tags anywhere in a Markdown document, and you can use block level
4595 HTML tags (like <div> and <table> as well).
4597 For more information about Markdown's syntax, see the F<basics.md>
4598 and F<syntax.md> files included with F<Markdown.pl>.
4600 Input (auto-detected) may be either ISO-8859-1 or UTF-8. Output is always
4601 converted to the UTF-8 character set.
4604 =head1 OPTIONS
4606 Use "--" to end switch parsing. For example, to open a file named "-z", use:
4608 Markdown.pl -- -z
4610 =over
4613 =item B<--html4tags>
4615 Use HTML 4 style for empty element tags, e.g.:
4617 <br>
4619 instead of Markdown's default XHTML style tags, e.g.:
4621 <br />
4623 This option is I<NOT compatible> with the B<--validate-xml> option
4624 and will produce an immediate error if both are given.
4627 =item B<--deprecated>
4629 Both "<dir>" and "<menu>" are normally taken as literal text and the leading
4630 "<" will be automatically escaped.
4632 If this option is used, they are recognized as valid tags and passed through
4633 without being escaped.
4635 When dealing with program argument descriptions "<dir>" can be particularly
4636 problematic therefore use of this option is not recommended.
4638 Other deprecated tags (such as "<font>" and "<center>" for example) continue
4639 to be recognized and passed through even without using this option.
4642 =item B<--sanitize>
4644 Removes troublesome tag attributes from embedded tags. Only a very strictly
4645 limited set of tag attributes will be permitted, other attributes will be
4646 silently discarded. The set of allowed attributes varies by tag.
4648 Splits empty minimized elements that are not one of the HTML allowed empty
4649 elements (C<area> C<basefont> C<br> C<col> C<hr> C<img>) into separate begin
4650 and end tags. For example, C<< <p/> >> or C<< <p /> >> will be split into
4651 C<< <p></p> >>.
4653 Combines adjacent (whitespace separated only) opening and closing tags for
4654 the same HTML empty element into a single minimized tag. For example,
4655 C<< <br></br> >> will become C<< <br /> >>.
4657 Tags that require at least one attribute to be present to be meaningful
4658 (e.g. C<a>, C<area>, C<img>, C<map>) but have none will be treated as non-tags
4659 potentially creating unexpected errors. For example, the sequence
4660 C<< <a>text here</a> >> will be sanitized to C<< <a>text here</a> >> since
4661 an C<a> tag without any attributes is meaningless, but then the trailing
4662 close tag C<< </a> >> will become an error because it has no matching open
4663 C<< <a ...> >> tag.
4665 The point of this check is not to cause undue frustration, but to allow
4666 such constructs to be used as text without the need for escaping since they
4667 are meaningless as tags. For example, C<< <a><c><e> >> works just fine
4668 as plain text and so does C<< <A><C><E> >> because the
4669 C<< <a> >>/C<< <A> >> will be treated as a non-tag automatically. In fact,
4670 they can even appear inside links too such as
4671 C<< <a href="#somewhere">Link to <a><c><e> article</a> >>.
4673 Problematic C<&> characters are fixed up such as standalone C<&>s (or those not
4674 part of a valid entity reference) are turned into C<&>. Within attribute
4675 values, single and double quotes are turned into C<&> entity refs.
4677 This is enabled by default.
4680 =item B<--no-sanitize>
4682 Do not sanitize tag attributes. This option does not allow any tags that would
4683 not be allowed without this option, but it does completely suppress the
4684 attribute sanitation process. If this option is specified, no attributes will
4685 be removed from any tag (although C<img> and C<a> tags will still be affected
4686 by B<--imageroot>, B<--htmlroot>, B<--absroot> and/or B<--base> options).
4687 Use of this option is I<NOT RECOMMENDED>.
4690 =item B<--validate-xml>
4692 Perform XML validation on the output before it's output and die if
4693 it fails validation. This requires the C<XML::Simple> or C<XML::Parser>
4694 module be present (one is only required if this option is given).
4696 Any errors are reported to STDERR and the exit status will be
4697 non-zero on XML validation failure. Note that all line and column
4698 numbers in the error output refer to the entire output that would
4699 have been produced. Re-run with B<--no-validate-xml> to see what's
4700 actually present at those line and column positions.
4702 If the B<--stub> option has also been given, then the entire output is
4703 validated as-is. Without the B<--stub> option, the output will be wrapped
4704 in C<< <div>...</div> >> for validation purposes but that extra "div" added
4705 for validation will not be added to the final output.
4707 This option is I<NOT enabled by default>.
4709 This option is I<NOT compatible> with the B<--html4tags> option and will
4710 produce an immediate error if both are given.
4713 =item B<--validate-xml-internal>
4715 Perform XML validation on the output before it's output and die if
4716 it fails validation. This uses a simple internal consistency checker
4717 that finds unmatched and mismatched open/close tags.
4719 Non-empty elements that in HTML have optional closing tags (C<colgroup>
4720 C<dd> C<dt> C<li> C<p> C<tbody> C<td> C<tfoot> C<th> C<thead> C<tr>)
4721 will automatically have any omitted end tags inserted during the
4722 `--validate-xml-internal` process.
4724 Any errors are reported to STDERR and the exit status will be
4725 non-zero on XML validation failure. Note that all line and column
4726 numbers in the error output refer to the entire output that would
4727 have been produced before sanitization without any B<--stub> or
4728 B<--stylesheet> options. Re-run with B<--no-sanitize> and
4729 B<--no-validate-xml> and I<without> any B<--stub> or B<--stylesheet>
4730 options to see what's actually present at those line and column
4731 positions.
4733 This option validates the output I<prior to> adding any requested
4734 B<--stub> or B<--stylesheet>. As the built-in stub and stylesheet
4735 have already been validated that speeds things up. The output is
4736 I<NOT> wrapped (in a C<< <div>...</div> >>) for validation as that's
4737 not required for the internal checker.
4739 This option is I<IS enabled by default> unless B<--no-sanitize> is
4740 active.
4742 This option is I<IS compatible> with the B<--html4tags> option.
4744 This option requires the B<--sanitize> option and will produce an
4745 immediate error if both B<--no-sanitize> and B<--validate-xml-internal>
4746 are given.
4748 Note that B<--validate-xml-internal> is I<MUCH faster> than
4749 B<--validate-xml> and I<does NOT> require any extra XML modules to
4750 be present.
4753 =item B<--no-validate-xml>
4755 Do not perform XML validation on the output. Markdown.pl itself will
4756 normally generate valid XML sequences (unless B<--html4tags> has been
4757 used). However, any raw tags in the input (that are on the "approved"
4758 list), could potentially result in invalid XML output (i.e. mismatched
4759 start and end tags, missing start or end tag etc.).
4761 Markdown.pl can check for these issues itself using its own internal
4762 B<--validate-xml-internal> check or, with the B<--validate-xml>
4763 option, it can use C<XML::Simple> or C<XML::Parser> to do so.
4765 Note that B<--validate-xml-internal> is the default option unless
4766 B<--no-sanitize> is used in which case B<--no-validate-xml> is the
4767 default option.
4770 =item B<--strip-comments>/B<--strip-comments-lax>
4772 (N.B. B<--strip-comments> is just a short form of B<--strip-comments-lax>)
4774 Strip XML and XML-like comments from the output. Any XML or XML-like
4775 comments encountered will be omitted from the output if either of these
4776 options is given.
4778 Unlike the B<--strip-comments-strict> option, these options I<will>
4779 strip any XML-like comments that contain internal double hyphen
4780 (i.e. C<-->) sequences.
4782 This option requires the B<--sanitize> option to be used (which is
4783 the default).
4785 If either of these options is given, it will supersede any previous
4786 B<--strip-comments-strict>, B<--strip-comments-lax-only> or
4787 B<--no-strip-comments> options.
4790 =item B<--strip-comments-strict>
4792 Strip only strictly XML standard compliant comments from the output.
4794 Note that the XML standard section 2.5 specifically prohibits
4795 a C<--> sequence within an XML comment (i.e. C<--> cannot occur after
4796 the comment start tag C<< <!-- >> unless it is immediately followed
4797 by C<< > >> which makes it the comment end tag C<< --> >>).
4799 In other words, S<C<< <!-- --> >>>, S<C<< <!-- - --> >>>, S<C<< <!----> >>>,
4800 and S<C<< <!--- --> >>> are all valid XML comments, but S<C<< <!-----> >>>
4801 and S<C<< <!-- ---> >>> are not!
4803 As part of the "sanitation" process (triggered by the B<--sanitize>
4804 option), any invalid tags have their leading C<< < >> escaped (to
4805 C<< &#lt; >>) thus making them ordinary text and this I<includes>
4806 invalid XML comments.
4808 What this means is that the B<--strip-comments-strict> option I<will not>
4809 remove invalid XML comments (such as S<C<< <!-----> >>>)!
4811 But see the B<--strip-comments-lax> option for a solution.
4813 If this option is given, it will supersede any previous
4814 B<--strip-comments>, B<--strip-comments-lax>, B<--strip-comments-lax-only>
4815 or B<--no-strip-comments> options.
4818 =item B<--strip-comments-lax-only>
4820 This is the default option if no other strip comments options are given
4821 AND the B<--sanitize> option is active (the default).
4823 This is a compromise option. It works just like the B<--strip-comments-lax>
4824 option, but I<ONLY> on strictly invalid XML-like comments.
4826 In other words, if a strictly valid XML comment is present, it will be retained
4827 in the output. If a strictly invalid XML comment is present which would have
4828 been stripped by B<--strip-comments-lax> but would have had its leading C<< < >>
4829 escaped automatically by the B<--no-strip-comments> or B<--strip-comments-strict>
4830 modes (because it's not a strictly valid XML comment), then it I<will> be stripped
4831 by this mode.
4833 This option prevents ugly invalid XML comments from slipping through into the
4834 output as escaped plain text while still passing through valid XML comments
4835 without stripping them.
4837 If this option is given, it will supersede any previous
4838 B<--strip-comments>, B<--strip-comments-lax>, B<--strip-comments-lax-only>
4839 or B<--no-strip-comments> options.
4842 =item B<--no-strip-comments>
4844 Do not strip XML or XML-like comments from the output.
4846 This is the default option I<ONLY> when no other strip comments options have
4847 been give I<and> the B<--no-sanitize> option is in effect (which is I<not> the
4848 default).
4850 When B<--no-strip-comments> is active, strictly invalid XML comments such
4851 as those that contain an internal double hyphen (C<-->) sequence will end
4852 up having their leading C<< < >> escaped automatically and end up as plain
4853 text in the output!
4855 If this option is given, it will supersede any previous
4856 B<--strip-comments>, B<--strip-comments-lax>, B<--strip-comments-lax-only>
4857 or B<--no-strip-comments> options.
4860 =item B<--tabwidth>=I<num>
4862 Expand tabs to I<num> character wide tab stop positions instead of the default
4863 8. Don't use this; physical tabs should always be expanded to 8-character
4864 positions. This option does I<not> affect the number of spaces needed to
4865 start a new "indent level". That will always be 4 no matter what value is
4866 used (or implied by default) with this option. Also note that tabs inside
4867 backticks-delimited code blocks will always be expanded to 8-character tab
4868 stop positions no matter what value is used for this option.
4870 The value must be S<2 <= I<num> <= 32>.
4873 =item B<--auto-number>
4875 Automatically number all h1-h6 headings generated from Markdown markup.
4876 Explicit C<< <h1> >> ... C<< <h6> >> tag content remains unmolested.
4878 If this option is given, any YAML C<header_enum> setting will be ignored.
4881 =item B<-k>, B<--keep-abs>
4883 Normally any absolute path URLs (i.e. URLs without a scheme starting
4884 with "/" but not "//") are subject to modification by any
4885 B<-r>/B<--htmlroot> or B<-i>/B<--imageroot> option.
4887 If the B<-a>/B<--absroot> option is used and it transforms these
4888 absolute path URLs into a full absolute URL (i.e. starts with a
4889 scheme or "//") then any subsequent B<-r>/B<--htmlroot> or
4890 B<-i>/B<--imageroot> processing will be skipped because the URL is
4891 no longer relative.
4893 If the B<--keep-abs> option is given, then (after applying any
4894 B<-a>/B<--absroot> option if present) absolute path URLs will be
4895 kept as-is and will not be processed further by any B<-r>/B<--htmlroot>
4896 or B<-i>/B<--imageroot> option.
4898 Note that if the B<-a>/B<--absroot> option transforms an absolute
4899 path URL into a relative PATH URL it I<will> be subject to subsequent
4900 B<-r>/B<--htmlroot> or B<-i>/B<--imageroot> processing regardless
4901 of the B<-k>/B<--keep-abs> option.
4904 =item B<-a> I<prefix>, B<--absroot>=I<prefix>
4906 Any absolute path URLs (i.e. URLs without a scheme starting with "/" but not
4907 "//") have I<prefix> prepended which prevents them from being acted upon by the
4908 B<--htmlroot> and/or B<--imageroot> options provided the result is a full
4909 absolute URL. The default is to prepend nothing and leave them as absolute
4910 path URLs which will allow them to be processed by any B<--htmlroot> and/or
4911 B<--imageroot> options.
4913 This option can be helpful when documents are being formatted for display on a
4914 different system and the absolute path URLs need to be "fixed up".
4917 =item B<-b> I<prefix>, B<--base>=I<prefix>
4919 Any fragment-only URLs have I<prefix> prepended. The default is to prepend
4920 nothing and leave them as bare fragment URLs. Use of this option may be
4921 necessary when embedding the output of Markdown.pl into a document that makes
4922 use of the C<< <base> >> tag in order for intra-document fragment URL links to
4923 work properly in such a document.
4926 =item B<-r> I<prefix>, B<--htmlroot>=I<prefix>
4928 Any non-absolute URLs have I<prefix> prepended.
4931 =item B<-i> I<prefix>, B<--imageroot>=I<prefix>
4933 Any non-absolute URLs have I<prefix> prepended (overriding the B<-r> prefix
4934 if any) but only if they end in an image suffix.
4937 =item B<-w> [I<wikipat>], B<--wiki>[=I<wikipat>]
4939 Activate wiki links. Any link enclosed in double brackets (e.g. "[[link]]") is
4940 considered a wiki link. By default only absolute URL and fragment links are
4941 allowed in the "wiki link style" format. Any other double-bracketed strings
4942 are left unmolested.
4944 If this option is given, all other wiki links are enabled as well. Any
4945 non-absolute URL or fragment links will be transformed into a link using
4946 I<wikipat> where the default I<wikipat> if none is given is C<%{s(:md)}.html>.
4948 If the given I<wikipat> does not contain a C<%{...}> placeholder sequence
4949 then it will automatically have C<%{s(:md)}.html> suffixed to it.
4951 The C<...> part of the C<%{...}> sequence specifies zero or more
4952 case-insensitive single-letter options with the following effects:
4954 =over
4956 =item B<b>
4958 Retain blanks (aka spaces) in the output. They will become C<%20>
4959 in the final URL. Because spaces are always trimmed before processing
4960 wiki links, runs of multiple spaces will be collapsed into a single
4961 space and any leading or trailing spaces will be removed.
4963 =item B<d>
4965 Convert spaces to dashes (ASCII 0x2D) instead of underscore (ASCII
4966 0x5F). Note that if this option is given then runs of multiple
4967 dashes will be converted to a single dash I<instead> but runs of
4968 multiple underscores will be left untouched.
4970 =item B<f>
4972 Flatten the resulting name by replacing forward slashes (ASCII 0x2F)
4973 as well. They will be converted to underscores unless the C<d>
4974 option is given (in which case they will be converted to dashes).
4975 This conversion takes place before applying the runs-of-multiple
4976 reduction. This option is incompatible with the B<%> option.
4978 =item B<%>
4980 Flatten the resulting name by replacing runs of one or more forward
4981 slashes (ASCII 0x2F) with C<%2F>. Note that when encoded into a
4982 URL the C<%2F> actually becomes C<%252F>. This option is incompatible
4983 with the B<f> option.
4985 =item B<l>
4987 Convert link target (excluding any query string and/or fragment) to lowercase.
4988 Takes precedence over any C<u> option, but specifically excludes C<%>-escapes
4989 which are always UPPERCASE hexadecimal.
4991 =item B<r>
4993 Leave raw UTF-8 characters in the result. Normally anything not allowed
4994 directly in a URL ends up URL-encoded. With this option, raw valid UTF-8
4995 sequences will be left untouched. Use with care.
4997 =item B<s> or B<s(>I<< <ext> >>[B<,>I<< <ext> >>]...B<)>
4999 After (temporarily) removing any query string and/or fragment, strip any final
5000 "dot" suffix so long as it occurs after the last slash (if any slash was
5001 present before applying the C<f> option). The "dot" (ASCII 0x2E) and all
5002 following characters (if any) are removed. If the optional C<< (<ext>,...) >>
5003 part is present then only strip the extension if it consists of a "dot"
5004 followed by one of the case-insensitive I<< <ext> >> values. As a special
5005 case, using the value C<:md> for one of the I<< <ext> >> values causes that
5006 value to be expanded to all known markdown extensions.
5008 When processing wiki image links, this option is ignored.
5010 =item B<u>
5012 Convert link target (excluding any query string and/or fragment) to UPPERCASE.
5014 =item B<v>
5016 Leave runs-of-multiple characters alone (aka "verbatim"). Does not affect
5017 any of the other options except by eliminating the runs-of-multple reduction
5018 step. Also does I<not> inhibit the initial whitespace trimming.
5020 Does not affect the runs-of-multiple "/" replacement performed by the B<%>
5021 option.
5023 =back
5025 The URL target of the wiki link is created by first trimming whitespace
5026 (starting and ending whitespace is removed and all other runs of consecutive
5027 whitespace are replaced with a single space) from the wiki link target,
5028 removing (temporarily) any query string and/or fragment, if no options are
5029 present, spaces are converted to underscores (C<_>) and runs of multiple
5030 consecutive underscores are replaced with a single underscore (ASCII 0x5F).
5031 Finally, the I<wikipat> string gets its first placeholder (the C<%{...}>
5032 sequence) replaced with this computed value and the original query string
5033 and/or fragment is re-appended (if any were originally present) and
5034 URL-encoding is applied as needed to produce the actual final target URL.
5036 Note that when processing wiki image links, no extension stripping ever takes
5037 place (i.e. the "s" option is ignored) and anything after the placeholder (the
5038 C<%{...}> sequence) in the pattern is omitted from the result.
5040 See above option descriptions for possible available modifications.
5042 One of the commonly used hosting platforms does something substantially similar
5043 to using C<%{dfv}> as the placeholder.
5045 One of the commonly used wiki platforms does something similar to using C<%{%}>
5046 as the placeholder.
5049 =item B<--yaml>[=I<yamlmode>]
5051 Select YAML front matter processing. The optional I<yamlmode> value
5052 must be one of the following:
5054 =over
5056 =item B<enable>
5058 Recognize any YAML front matter and apply any options specified
5059 therein. If any unrecognized options are present, the options will
5060 also be shown in the formatted output.
5062 This is the default I<yamlmode> if omitted.
5064 =item B<disable>
5066 No YAML front matter processing at all takes place. If YAML front
5067 matter is present, it will be treated as regular non-YAML markup
5068 text to be processed.
5070 =item B<strip>
5072 If YAML front matter is present, it will be stripped and completely
5073 ignored before beginning to process the rest of the input.
5075 In this mode, any options in the YAML front matter that would have
5076 otherwise been recognized will I<not have any effect!>
5078 =item B<show>
5080 If YAML front matter is present and contains anything other than
5081 comments, the non-comments parts will be shown in the formatted
5082 output.
5084 In this mode, any options in the YAML front matter that would have
5085 otherwise been recognized will I<not have any effect!>
5087 This is a show-only mode.
5089 =item B<reveal>
5091 This mode works just like the B<enable> mode except that if the
5092 YAML front matter contains anything other than comments, then
5093 I<all> of the non-comments parts will be shown in the formatted
5094 output.
5096 In this mode, any recognized options in the YAML front matter I<are>
5097 processed the same way they would be in the B<enable> mode except
5098 that any option to suppress the B<reveal> mode is ignored.
5100 =item B<conceal>
5102 This mode works just like the B<enable> mode except that no options
5103 are ever shown in the formatted output regardless of whether or not
5104 there are any unrecognized options present.
5106 In this mode, any recognized options in the YAML front matter I<are>
5107 processed the same way they would be in the B<enable> mode except
5108 that any option to suppress the B<conceal> mode is ignored.
5110 =item B<unknown>
5112 This mode works just like the B<show> mode if any unrecognized
5113 YAML front matter options are present. Otherwise it works like
5114 the B<strip> mode.
5116 In this mode, any options in the YAML front matter that would have
5117 otherwise been recognized will I<not have any effect!>
5119 =back
5121 If B<--raw>, B<--raw-xml> or B<--raw-html> has been specified then
5122 the default if no B<--yaml> option has been given is B<--yaml=disable>.
5124 Otherwise the default if no B<--yaml> option has been given is
5125 B<--yaml=enable>.
5127 Note that only a limited subset of YAML is recognized. Specifically
5128 only comments, and top-level single-line S<C<key: value>> items
5129 where key must be plain (i.e. non-quoted), start with a letter or
5130 underscore and contain only letters, underscores, hyphens (C<->),
5131 periods (C<.>) and digits. Keys are case-insensitive (i.e. converted
5132 to lowercase). As with YAML, at least one whitespace is required
5133 between the ":" and the value (unless it's the empty value).
5135 Values may be either plain or double-quoted (single-quoted is not
5136 recognized). The double-quoted style may use C-style character
5137 escape codes but may not extend past the end of the line.
5139 For YAML front matter to be recognized, the very first line of the
5140 document must be exactly three hyphens (C<--->). The YAML terminates
5141 when a line of three hyphens (C<--->) or a line of three periods
5142 (C<...>) or the end of the file is encountered. Of course the YAML
5143 mode must also be something I<other> than B<--yaml=disable>.
5146 =item B<-V>, B<--version>
5148 Display Markdown's version number and copyright information.
5151 =item B<-s>, B<--shortversion>
5153 Display the short-form version number.
5156 =item B<--raw>, B<--raw-xml>
5158 Input contains only raw XHTML. All options other than B<--html4tags>,
5159 B<--deprecated>, B<--sanitize> (on by default), B<--strip-comments>,
5160 B<--div>, B<--keep-named-character-entities>, B<--validate-xml> and
5161 B<--validate-xml-internal> (and their B<--no-...> variants) are
5162 ignored.
5164 With this option, arbitrary XHTML input can be passed through
5165 the sanitizer and/or validator. If sanitation is requested (the
5166 default), input must only contain the contents of the "<body>"
5167 section (i.e. no "<head>" or "<html>"). Output I<will> be converted
5168 to UTF-8 regardless of the input encoding. All line endings will
5169 be normalized to C<\n> and input encodings other than UTF-8 or
5170 ISO-8859-1 or US-ASCII will end up mangled.
5172 Remember that any B<--stub> and/or B<--stylesheet> options are
5173 I<completely ignored> when B<--raw> is given.
5176 =item B<--raw-html>
5178 Input contains only raw HTML. All options other than
5179 B<--html4tags>, B<--deprecated>, B<--sanitize> (on by default),
5180 B<--strip-comments>, and B<--validate-xml-internal>
5181 (and their B<--no-...> variants) are ignored.
5183 Requires the (possibly implicit) B<--validate-xml-internal> option.
5185 Works just like B<--raw-xml> except that HTML auto closing and
5186 optional closing tag semantics are activated during the validation
5187 causing missing closing tags to be inserted where required by the
5188 standard. Non-raw mode always enables these semantics.
5190 This will transform HTML into valid XHTML or fail with an error message.
5192 Unfortunately, it will also fail to accept some documents that
5193 the plain B<--raw-xml> option will.
5195 For example, this document:
5197 <dt><li>a</li></dt>
5199 Will be rejected because upon encountering the C<< <li> >> open
5200 tag a closing C<< </dt> >> will automatically be inserted resulting
5201 in this document:
5203 <dt></dt><li>a</li></dt>
5205 Which, of course, no longer validates. Since C<li> blocks cannot
5206 directly be nested within C<dt> blocks (according to the standard),
5207 the input document is not strictly correct.
5209 Remember that any B<--stub> and/or B<--stylesheet> options are
5210 I<completely ignored> when B<--raw-html> is given.
5213 =item B<--div>[=I<divname>]
5215 Wrap the output contents in a C<div> tag. If I<divname> is given the
5216 tag will have that C<id> attribute value. If the B<--stub> option and/or
5217 the B<--stylesheet> option are active, they are applied I<after> wrapping
5218 the output contents in the C<div>. Note that if a YAML table ends up
5219 being generated, it I<will> be included I<inside> the C<div> wrapper.
5221 In contrast to the B<--stylesheet> and B<--stub> options, this option
5222 I<is> allowed with the B<--raw-xml> and B<--raw-html> options.
5225 =item B<--stylesheet>
5227 Include the fancy style sheet at the beginning of the output (or in the
5228 C<head> section with B<--stub>). This style sheet makes fancy checkboxes
5229 and makes a right parenthesis C<)> show instead of a C<.> for ordered lists
5230 that use them. Without it things will still look fine except that the
5231 fancy stuff won't be there.
5233 Use this option with no other arguments and redirect standard input to
5234 /dev/null to get just the style sheet and nothing else.
5237 =item B<--no-stylesheet>
5239 Overrides a previous B<--stylesheet> and disables implicit inclusion
5240 of the style sheet by the B<--stub> option.
5243 =item B<--keep-named-character-entities>
5245 Do not convert named character entities to their equivalent numerical character
5246 entity. Normally any occurrence of a named character entity such as
5247 C<…> would be converted to its equivalent character entity such as
5248 C<…>. If this option is given, that conversion is suppressed.
5250 The only always-valid named entities as far as XML is concerned are the five
5251 entities C<&>, C<<>, C<>>, C<"> and C<'>. Even that last
5252 one (C<'>) may not be universally supported in XHTML user agents (and it
5253 is converted to C<'> for that reason unless this option is given).
5255 Regardless of this option, C<&>, C<<>, C<>> and C<"> are always
5256 left alone since they are universally supported.
5258 Use of this option is I<NOT RECOMMENDED>.
5261 =item B<--us-ascii>/B<--ascii>
5263 (N.B. B<--ascii> is just a short form of B<--us-ascii>)
5265 Convert any non-US-ASCII characters to their equivalent numerical character
5266 entity. Any characters with a code point value greater than or equal to
5267 128 will be converted. Note that the output is still technically UTF-8 since
5268 the US-ASCII code points coincide with the same code points of UTF-8.
5270 Using this option will make the output strictly 7-bit and therefore it should
5271 survive just about any transport mechanism at the expense of an increase in
5272 size that depends on how many non-US-ASCII characters are present.
5275 =item B<--stub>
5277 Wrap the output in a full document stub (i.e. has C<html>, C<head> and C<body>
5278 tags). The style sheet I<will> be included in the C<head> section unless the
5279 B<--no-stylesheet> option is also used.
5281 The C<< <title> >> value for a document produced with the B<--stub> option
5282 comes from the first markdown markup C<h1> that's generated unless YAML
5283 processing has been enabled (the default) and a C<title> YAML value has
5284 been set in which case that always takes precedence.
5287 =item B<-h>, B<--help>
5289 Display Markdown's help. With B<--help> full help is shown, with B<-h> only
5290 the usage and options are shown.
5293 =back
5296 =head1 HTML CONTENT
5298 Markdown format documents are intended to be human readable without the use
5299 of XML-like markup.
5301 Nevertheless, html content can be included verbatim provided that the tags
5302 used are limited to those of the HTML 4 specification and only those tags
5303 that represent body content -- scripting tags and attributes are not allowed.
5305 The final version of the HTML specification (including a DTD) can be found
5306 here:
5308 =over
5310 =over
5312 =item L<https://www.w3.org/TR/1999/REC-html401-19991224/>
5314 =back
5316 =back
5318 Note that attempts to use any of the new tags from the "HTML Living Standard"
5319 will simply result in them being escaped into literal text.
5321 Stick to markdown-format text or HTML 4 tags to avoid unexpected output.
5324 =head1 PERL MODULE
5326 Markdown can be used as a Perl module and can be "use"d like so:
5328 use Markdown qw(...);
5330 Or like so:
5332 BEGIN {require "Markdown.pl" && Markdown->import(qw(...))}
5334 where the C<...> part is the list of desired imports.
5336 The Markdown module does not export any functions by default.
5338 The C<Markdown.pm> file is a symbolic link to C<Markdown.pl>.
5340 =head2 Markdown module functions
5342 Any of these functions may be imported, but none of them
5343 are imported by default.
5345 =over
5348 =item * $result = Markdown::Markdown($string[, options...])
5350 Converts Markdown-format C<$string> to UTF-8 encoded XHTML and
5351 returns it.
5353 The C<options...> may be either a single HASH ref or one or more
5354 pairs of C<< key => value >>.
5356 See the comments for the C<_SanitizeOpts> function for a list of
5357 possible option keys.
5360 =item * $result = Markdown::ProcessRaw($string[, options...])
5362 Converts raw XHTML in C<$string> to XHTML and returns it.
5364 The C<options...> may be either a single HASH ref or one or more
5365 pairs of C<< key => value >>.
5367 See the comments for the C<_SanitizeOpts> function for a list of
5368 possible option keys.
5370 This function provides the ability to apply the internal XML
5371 validation and sanitation functionality to arbitrary XHTML without
5372 performing any of the Markdown format interpretation.
5375 =item * $stylesheet = Markdown::GenerateStyleSheet([$prefix])
5377 Returns an XHTML style sheet that supports the fancy Markdown styles
5378 such as checkboxes and right parenthesis lists.
5380 All of the style class names have C<$prefix> prepended.
5382 If C<$prefix> is omitted or C<undef> then the default S<"_markdown-">
5383 prefix will be used which is the same default prefix that the
5384 C<Markdown> function uses.
5386 The returned string value consists of a C<< <style type="text/css"> >>
5387 tag, the contents of the style sheet and ends with a C<< </style> >> tag.
5390 =item * Markdown::SetWikiOpts($hashref, $wikioption)
5392 The value of C<$wikioption> should be the value of the C<wikipat> value
5393 from the B<--wiki> option. Use the empty string S<""> to enable wiki
5394 links using the defaults and use C<undef> to disable wiki links.
5396 The C<wikipat> and C<wikiopt> keys in C<$hashref> will both be
5397 affected by this call and they should be passed in to the Markdown
5398 function as options to enable processing of wiki links.
5400 The simplest way to do this is simply to pass a HASH ref as the
5401 second argument to the Markdown function after having used this
5402 function on it to properly set the C<wikipat> and C<wikiopt>
5403 keys and values.
5406 =back
5409 =head2 Example
5411 This rudimentary example approximates running
5412 S<C<Markdown.pl --stub --wiki>>
5413 on the input (files if given, standard input if not).
5415 use Markdown qw(Markdown SetWikiOpts GenerateStyleSheet escapeXML);
5417 my $string;
5418 {local $/; $string = <>;}
5419 my %opts = ( h1 => "default title" );
5420 SetWikiOpts(\%opts, ""); # enable default --wiki processing
5421 my $xhtml = Markdown($string, \%opts);
5422 print "<html xmlns=\"http://www.w3.org/1999/xhtml\">\n",
5423 "<head>\n<title>".escapeXML($opts{h1})."</title>\n",
5424 GenerateStyleSheet(),"</head>\n",
5425 "<body style=\"text-align:center\">\n",
5426 "<div style=\"".
5427 "display:inline-block;text-align:left;max-width:42pc\">\n",
5428 $xhtml, "</div></body></html>\n";
5431 =head1 VERSION HISTORY
5433 Z<> See the F<README> file for detailed release notes for this version.
5435 =over
5437 =item Z<> 1.1.15 - 15 Aug 2021
5439 =item Z<> 1.1.14 - 14 Jun 2021
5441 =item Z<> 1.1.13 - 13 Jun 2021
5443 =item Z<> 1.1.12 - 17 Mar 2021
5445 =item Z<> 1.1.11 - 05 Mar 2021
5447 =item Z<> 1.1.10 - 08 Jul 2020
5449 =item Z<> 1.1.9 - 15 Dec 2019
5451 =item Z<> 1.1.8 - 22 Nov 2019
5453 =item Z<> 1.1.7 - 14 Feb 2018
5455 =item Z<> 1.1.6 - 03 Jan 2018
5457 =item Z<> 1.1.5 - 07 Dec 2017
5459 =item Z<> 1.1.4 - 24 Jun 2017
5461 =item Z<> 1.1.3 - 13 Feb 2017
5463 =item Z<> 1.1.2 - 19 Jan 2017
5465 =item Z<> 1.1.1 - 12 Jan 2017
5467 =item Z<> 1.1.0 - 11 Jan 2017
5469 =item Z<> 1.0.4 - 05 Jun 2016
5471 =item Z<> 1.0.3 - 06 Sep 2015
5473 =item Z<> 1.0.2 - 03 Sep 2015
5475 =item Z<> 1.0.1 - 14 Dec 2004
5477 =item Z<> 1.0.0 - 28 Aug 2004
5479 =back
5481 =head1 AUTHORS
5483 =over
5485 =item John Gruber
5487 =item L<https://daringfireball.net>
5489 =item L<https://daringfireball.net/projects/markdown/>
5491 =item E<160>
5493 =back
5495 =over
5497 =item PHP port and other contributions by Michel Fortin
5499 =item L<https://michelf.ca>
5501 =item E<160>
5503 =back
5505 =over
5507 =item Additional enhancements and tweaks by Kyle J. McKay
5509 =item mackyle<at>gmail.com
5511 =item L<https://repo.or.cz/markdown.git>
5513 =back
5515 =head1 COPYRIGHT AND LICENSE
5517 =over
5519 =item Copyright (C) 2003-2004 John Gruber
5521 =item Copyright (C) 2015-2021 Kyle J. McKay
5523 =item All rights reserved.
5525 =back
5527 Redistribution and use in source and binary forms, with or without
5528 modification, are permitted provided that the following conditions are
5529 met:
5531 =over
5533 =item *
5535 Redistributions of source code must retain the above copyright
5536 notice, this list of conditions and the following disclaimer.
5538 =item *
5540 Redistributions in binary form must reproduce the above copyright
5541 notice, this list of conditions and the following disclaimer in the
5542 documentation and/or other materials provided with the distribution.
5544 =item *
5546 Neither the name "Markdown" nor the names of its contributors may
5547 be used to endorse or promote products derived from this software
5548 without specific prior written permission.
5550 =back
5552 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
5553 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
5554 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
5555 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
5556 OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
5557 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
5558 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
5559 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
5560 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
5561 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
5562 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
5564 =cut