newstile 1.0.1
Sign up to get free protection for your applications and to get access to all the features.
- data/AUTHORS +1 -0
- data/CONTRIBUTERS +6 -0
- data/COPYING +24 -0
- data/ChangeLog +5489 -0
- data/GPL +674 -0
- data/README +31 -0
- data/Rakefile +342 -0
- data/VERSION +1 -0
- data/benchmark/benchmark.rb +34 -0
- data/benchmark/generate_data.rb +112 -0
- data/benchmark/historic-jruby-1.4.0.dat +7 -0
- data/benchmark/historic-ruby-1.8.6.dat +7 -0
- data/benchmark/historic-ruby-1.8.7.dat +7 -0
- data/benchmark/historic-ruby-1.9.1p243.dat +7 -0
- data/benchmark/historic-ruby-1.9.2dev.dat +7 -0
- data/benchmark/mdbasics.text +306 -0
- data/benchmark/mdsyntax.text +888 -0
- data/benchmark/static-jruby-1.4.0.dat +7 -0
- data/benchmark/static-ruby-1.8.6.dat +7 -0
- data/benchmark/static-ruby-1.8.7.dat +7 -0
- data/benchmark/static-ruby-1.9.1p243.dat +7 -0
- data/benchmark/static-ruby-1.9.2dev.dat +7 -0
- data/benchmark/testing.sh +9 -0
- data/benchmark/timing.sh +10 -0
- data/bin/newstile +82 -0
- data/data/newstile/document.html +18 -0
- data/data/newstile/document.latex +43 -0
- data/doc/default.scss.css +519 -0
- data/doc/default.template +80 -0
- data/doc/documentation.page +72 -0
- data/doc/index.page +96 -0
- data/doc/installation.page +90 -0
- data/doc/links.markdown +6 -0
- data/doc/news.feed +10 -0
- data/doc/news.page +28 -0
- data/doc/quickref.page +564 -0
- data/doc/syntax.page +1615 -0
- data/doc/tests.page +51 -0
- data/doc/virtual +2 -0
- data/lib/newstile.rb +23 -0
- data/lib/newstile/compatibility.rb +34 -0
- data/lib/newstile/converter.rb +43 -0
- data/lib/newstile/converter/base.rb +111 -0
- data/lib/newstile/converter/html.rb +405 -0
- data/lib/newstile/converter/latex.rb +577 -0
- data/lib/newstile/converter/markdown.rb +426 -0
- data/lib/newstile/converter/newstile.rb +426 -0
- data/lib/newstile/document.rb +168 -0
- data/lib/newstile/error.rb +27 -0
- data/lib/newstile/options.rb +296 -0
- data/lib/newstile/parser.rb +39 -0
- data/lib/newstile/parser/base.rb +94 -0
- data/lib/newstile/parser/html.rb +499 -0
- data/lib/newstile/parser/newstile.rb +325 -0
- data/lib/newstile/parser/newstile/abbreviation.rb +66 -0
- data/lib/newstile/parser/newstile/attribute_list.rb +111 -0
- data/lib/newstile/parser/newstile/autolink.rb +54 -0
- data/lib/newstile/parser/newstile/blank_line.rb +43 -0
- data/lib/newstile/parser/newstile/block_boundary.rb +46 -0
- data/lib/newstile/parser/newstile/blockquote.rb +63 -0
- data/lib/newstile/parser/newstile/codeblock.rb +60 -0
- data/lib/newstile/parser/newstile/codespan.rb +57 -0
- data/lib/newstile/parser/newstile/emphasis.rb +70 -0
- data/lib/newstile/parser/newstile/eob.rb +39 -0
- data/lib/newstile/parser/newstile/escaped_chars.rb +38 -0
- data/lib/newstile/parser/newstile/extension.rb +116 -0
- data/lib/newstile/parser/newstile/footnote.rb +74 -0
- data/lib/newstile/parser/newstile/header.rb +84 -0
- data/lib/newstile/parser/newstile/horizontal_rule.rb +39 -0
- data/lib/newstile/parser/newstile/html.rb +175 -0
- data/lib/newstile/parser/newstile/html_entity.rb +39 -0
- data/lib/newstile/parser/newstile/line_break.rb +38 -0
- data/lib/newstile/parser/newstile/link.rb +177 -0
- data/lib/newstile/parser/newstile/list.rb +239 -0
- data/lib/newstile/parser/newstile/math.rb +64 -0
- data/lib/newstile/parser/newstile/paragraph.rb +55 -0
- data/lib/newstile/parser/newstile/smart_quotes.rb +214 -0
- data/lib/newstile/parser/newstile/table.rb +134 -0
- data/lib/newstile/parser/newstile/typographic_symbol.rb +54 -0
- data/lib/newstile/utils.rb +37 -0
- data/lib/newstile/utils/entities.rb +336 -0
- data/lib/newstile/utils/html.rb +75 -0
- data/lib/newstile/utils/ordered_hash.rb +79 -0
- data/lib/newstile/version.rb +28 -0
- data/man/man1/newstile.1 +246 -0
- data/setup.rb +1585 -0
- data/test/run_tests.rb +59 -0
- data/test/test_files.rb +162 -0
- data/test/testcases/block/01_blank_line/spaces.html +1 -0
- data/test/testcases/block/01_blank_line/spaces.text +3 -0
- data/test/testcases/block/01_blank_line/tabs.html +1 -0
- data/test/testcases/block/01_blank_line/tabs.text +6 -0
- data/test/testcases/block/02_eob/beginning.html +1 -0
- data/test/testcases/block/02_eob/beginning.text +3 -0
- data/test/testcases/block/02_eob/end.html +1 -0
- data/test/testcases/block/02_eob/end.text +3 -0
- data/test/testcases/block/02_eob/middle.html +1 -0
- data/test/testcases/block/02_eob/middle.text +5 -0
- data/test/testcases/block/03_paragraph/indented.html +18 -0
- data/test/testcases/block/03_paragraph/indented.text +19 -0
- data/test/testcases/block/03_paragraph/no_newline_at_end.html +5 -0
- data/test/testcases/block/03_paragraph/no_newline_at_end.text +5 -0
- data/test/testcases/block/03_paragraph/one_para.html +1 -0
- data/test/testcases/block/03_paragraph/one_para.text +1 -0
- data/test/testcases/block/03_paragraph/two_para.html +4 -0
- data/test/testcases/block/03_paragraph/two_para.text +4 -0
- data/test/testcases/block/04_header/atx_header.html +37 -0
- data/test/testcases/block/04_header/atx_header.text +34 -0
- data/test/testcases/block/04_header/atx_header_no_newline_at_end.html +1 -0
- data/test/testcases/block/04_header/atx_header_no_newline_at_end.text +1 -0
- data/test/testcases/block/04_header/setext_header.html +30 -0
- data/test/testcases/block/04_header/setext_header.html.19 +30 -0
- data/test/testcases/block/04_header/setext_header.text +36 -0
- data/test/testcases/block/04_header/setext_header_no_newline_at_end.html +1 -0
- data/test/testcases/block/04_header/setext_header_no_newline_at_end.text +2 -0
- data/test/testcases/block/04_header/with_auto_id_prefix.html +3 -0
- data/test/testcases/block/04_header/with_auto_id_prefix.options +2 -0
- data/test/testcases/block/04_header/with_auto_id_prefix.text +3 -0
- data/test/testcases/block/04_header/with_auto_ids.html +17 -0
- data/test/testcases/block/04_header/with_auto_ids.options +1 -0
- data/test/testcases/block/04_header/with_auto_ids.text +19 -0
- data/test/testcases/block/05_blockquote/indented.html +25 -0
- data/test/testcases/block/05_blockquote/indented.text +14 -0
- data/test/testcases/block/05_blockquote/lazy.html +34 -0
- data/test/testcases/block/05_blockquote/lazy.text +20 -0
- data/test/testcases/block/05_blockquote/nested.html +10 -0
- data/test/testcases/block/05_blockquote/nested.text +6 -0
- data/test/testcases/block/05_blockquote/no_newline_at_end.html +4 -0
- data/test/testcases/block/05_blockquote/no_newline_at_end.text +2 -0
- data/test/testcases/block/05_blockquote/with_code_blocks.html +15 -0
- data/test/testcases/block/05_blockquote/with_code_blocks.text +11 -0
- data/test/testcases/block/06_codeblock/error.html +4 -0
- data/test/testcases/block/06_codeblock/error.text +4 -0
- data/test/testcases/block/06_codeblock/lazy.html +4 -0
- data/test/testcases/block/06_codeblock/lazy.text +5 -0
- data/test/testcases/block/06_codeblock/no_newline_at_end.html +2 -0
- data/test/testcases/block/06_codeblock/no_newline_at_end.text +1 -0
- data/test/testcases/block/06_codeblock/no_newline_at_end_1.html +2 -0
- data/test/testcases/block/06_codeblock/no_newline_at_end_1.text +2 -0
- data/test/testcases/block/06_codeblock/normal.html +13 -0
- data/test/testcases/block/06_codeblock/normal.text +10 -0
- data/test/testcases/block/06_codeblock/tilde_syntax.html +7 -0
- data/test/testcases/block/06_codeblock/tilde_syntax.text +9 -0
- data/test/testcases/block/06_codeblock/whitespace.html +3 -0
- data/test/testcases/block/06_codeblock/whitespace.text +3 -0
- data/test/testcases/block/06_codeblock/with_blank_line.html +13 -0
- data/test/testcases/block/06_codeblock/with_blank_line.text +12 -0
- data/test/testcases/block/06_codeblock/with_eob_marker.html +6 -0
- data/test/testcases/block/06_codeblock/with_eob_marker.text +5 -0
- data/test/testcases/block/06_codeblock/with_ial.html +6 -0
- data/test/testcases/block/06_codeblock/with_ial.text +5 -0
- data/test/testcases/block/07_horizontal_rule/error.html +7 -0
- data/test/testcases/block/07_horizontal_rule/error.html.19 +7 -0
- data/test/testcases/block/07_horizontal_rule/error.text +7 -0
- data/test/testcases/block/07_horizontal_rule/normal.html +17 -0
- data/test/testcases/block/07_horizontal_rule/normal.text +17 -0
- data/test/testcases/block/07_horizontal_rule/sepspaces.html +3 -0
- data/test/testcases/block/07_horizontal_rule/sepspaces.text +3 -0
- data/test/testcases/block/07_horizontal_rule/septabs.html +3 -0
- data/test/testcases/block/07_horizontal_rule/septabs.text +3 -0
- data/test/testcases/block/08_list/escaping.html +17 -0
- data/test/testcases/block/08_list/escaping.text +17 -0
- data/test/testcases/block/08_list/item_ial.html +7 -0
- data/test/testcases/block/08_list/item_ial.text +5 -0
- data/test/testcases/block/08_list/lazy.html +39 -0
- data/test/testcases/block/08_list/lazy.text +29 -0
- data/test/testcases/block/08_list/list_and_hr.html +9 -0
- data/test/testcases/block/08_list/list_and_hr.text +5 -0
- data/test/testcases/block/08_list/list_and_others.html +40 -0
- data/test/testcases/block/08_list/list_and_others.text +26 -0
- data/test/testcases/block/08_list/mixed.html +117 -0
- data/test/testcases/block/08_list/mixed.text +66 -0
- data/test/testcases/block/08_list/nested.html +17 -0
- data/test/testcases/block/08_list/nested.text +7 -0
- data/test/testcases/block/08_list/other_first_element.html +39 -0
- data/test/testcases/block/08_list/other_first_element.text +18 -0
- data/test/testcases/block/08_list/simple_ol.html +19 -0
- data/test/testcases/block/08_list/simple_ol.text +13 -0
- data/test/testcases/block/08_list/simple_ul.html +48 -0
- data/test/testcases/block/08_list/simple_ul.text +36 -0
- data/test/testcases/block/08_list/single_item.html +3 -0
- data/test/testcases/block/08_list/single_item.text +1 -0
- data/test/testcases/block/08_list/special_cases.html +55 -0
- data/test/testcases/block/08_list/special_cases.text +35 -0
- data/test/testcases/block/09_html/comment.html +18 -0
- data/test/testcases/block/09_html/comment.text +15 -0
- data/test/testcases/block/09_html/content_model/deflists.html +6 -0
- data/test/testcases/block/09_html/content_model/deflists.options +1 -0
- data/test/testcases/block/09_html/content_model/deflists.text +6 -0
- data/test/testcases/block/09_html/content_model/tables.html +14 -0
- data/test/testcases/block/09_html/content_model/tables.options +1 -0
- data/test/testcases/block/09_html/content_model/tables.text +14 -0
- data/test/testcases/block/09_html/html_and_codeblocks.html +15 -0
- data/test/testcases/block/09_html/html_and_codeblocks.options +1 -0
- data/test/testcases/block/09_html/html_and_codeblocks.text +13 -0
- data/test/testcases/block/09_html/html_to_native/code.html +10 -0
- data/test/testcases/block/09_html/html_to_native/code.text +9 -0
- data/test/testcases/block/09_html/html_to_native/comment.html +7 -0
- data/test/testcases/block/09_html/html_to_native/comment.text +8 -0
- data/test/testcases/block/09_html/html_to_native/emphasis.html +3 -0
- data/test/testcases/block/09_html/html_to_native/emphasis.text +3 -0
- data/test/testcases/block/09_html/html_to_native/entity.html +1 -0
- data/test/testcases/block/09_html/html_to_native/entity.text +1 -0
- data/test/testcases/block/09_html/html_to_native/header.html +6 -0
- data/test/testcases/block/09_html/html_to_native/header.options +2 -0
- data/test/testcases/block/09_html/html_to_native/header.text +6 -0
- data/test/testcases/block/09_html/html_to_native/list_dl.html +8 -0
- data/test/testcases/block/09_html/html_to_native/list_dl.text +8 -0
- data/test/testcases/block/09_html/html_to_native/list_ol.html +15 -0
- data/test/testcases/block/09_html/html_to_native/list_ol.text +17 -0
- data/test/testcases/block/09_html/html_to_native/list_ul.html +19 -0
- data/test/testcases/block/09_html/html_to_native/list_ul.text +22 -0
- data/test/testcases/block/09_html/html_to_native/options +1 -0
- data/test/testcases/block/09_html/html_to_native/paragraph.html +3 -0
- data/test/testcases/block/09_html/html_to_native/paragraph.text +4 -0
- data/test/testcases/block/09_html/html_to_native/table_normal.html +14 -0
- data/test/testcases/block/09_html/html_to_native/table_normal.text +12 -0
- data/test/testcases/block/09_html/html_to_native/table_simple.html +48 -0
- data/test/testcases/block/09_html/html_to_native/table_simple.text +56 -0
- data/test/testcases/block/09_html/html_to_native/typography.html +1 -0
- data/test/testcases/block/09_html/html_to_native/typography.html.19 +1 -0
- data/test/testcases/block/09_html/html_to_native/typography.text +1 -0
- data/test/testcases/block/09_html/invalid_html_1.html +5 -0
- data/test/testcases/block/09_html/invalid_html_1.text +5 -0
- data/test/testcases/block/09_html/invalid_html_2.html +5 -0
- data/test/testcases/block/09_html/invalid_html_2.text +5 -0
- data/test/testcases/block/09_html/markdown_attr.html +38 -0
- data/test/testcases/block/09_html/markdown_attr.text +38 -0
- data/test/testcases/block/09_html/not_parsed.html +24 -0
- data/test/testcases/block/09_html/not_parsed.text +24 -0
- data/test/testcases/block/09_html/parse_as_raw.html +30 -0
- data/test/testcases/block/09_html/parse_as_raw.options +1 -0
- data/test/testcases/block/09_html/parse_as_raw.text +29 -0
- data/test/testcases/block/09_html/parse_as_span.html +12 -0
- data/test/testcases/block/09_html/parse_as_span.options +1 -0
- data/test/testcases/block/09_html/parse_as_span.text +9 -0
- data/test/testcases/block/09_html/parse_block_html.html +21 -0
- data/test/testcases/block/09_html/parse_block_html.options +1 -0
- data/test/testcases/block/09_html/parse_block_html.text +17 -0
- data/test/testcases/block/09_html/processing_instruction.html +13 -0
- data/test/testcases/block/09_html/processing_instruction.text +12 -0
- data/test/testcases/block/09_html/simple.html +64 -0
- data/test/testcases/block/09_html/simple.html.19 +64 -0
- data/test/testcases/block/09_html/simple.options +1 -0
- data/test/testcases/block/09_html/simple.text +59 -0
- data/test/testcases/block/10_ald/simple.html +2 -0
- data/test/testcases/block/10_ald/simple.text +8 -0
- data/test/testcases/block/11_ial/auto_id_and_ial.html +1 -0
- data/test/testcases/block/11_ial/auto_id_and_ial.options +1 -0
- data/test/testcases/block/11_ial/auto_id_and_ial.text +2 -0
- data/test/testcases/block/11_ial/simple.html +25 -0
- data/test/testcases/block/11_ial/simple.text +34 -0
- data/test/testcases/block/12_extension/comment.html +8 -0
- data/test/testcases/block/12_extension/comment.text +12 -0
- data/test/testcases/block/12_extension/ignored.html +8 -0
- data/test/testcases/block/12_extension/ignored.text +8 -0
- data/test/testcases/block/12_extension/nomarkdown.html +10 -0
- data/test/testcases/block/12_extension/nomarkdown.kramdown +20 -0
- data/test/testcases/block/12_extension/nomarkdown.latex +13 -0
- data/test/testcases/block/12_extension/nomarkdown.text +21 -0
- data/test/testcases/block/12_extension/options.html +21 -0
- data/test/testcases/block/12_extension/options.text +21 -0
- data/test/testcases/block/12_extension/options2.html +10 -0
- data/test/testcases/block/12_extension/options2.text +5 -0
- data/test/testcases/block/12_extension/options3.html +7 -0
- data/test/testcases/block/12_extension/options3.text +7 -0
- data/test/testcases/block/13_definition_list/definition_at_beginning.html +1 -0
- data/test/testcases/block/13_definition_list/definition_at_beginning.text +1 -0
- data/test/testcases/block/13_definition_list/item_ial.html +12 -0
- data/test/testcases/block/13_definition_list/item_ial.text +8 -0
- data/test/testcases/block/13_definition_list/multiple_terms.html +13 -0
- data/test/testcases/block/13_definition_list/multiple_terms.text +10 -0
- data/test/testcases/block/13_definition_list/no_def_list.html +2 -0
- data/test/testcases/block/13_definition_list/no_def_list.text +2 -0
- data/test/testcases/block/13_definition_list/para_wrapping.html +10 -0
- data/test/testcases/block/13_definition_list/para_wrapping.text +6 -0
- data/test/testcases/block/13_definition_list/separated_by_eob.html +8 -0
- data/test/testcases/block/13_definition_list/separated_by_eob.text +5 -0
- data/test/testcases/block/13_definition_list/simple.html +8 -0
- data/test/testcases/block/13_definition_list/simple.text +7 -0
- data/test/testcases/block/13_definition_list/styled_terms.html +4 -0
- data/test/testcases/block/13_definition_list/styled_terms.text +2 -0
- data/test/testcases/block/13_definition_list/too_much_space.html +3 -0
- data/test/testcases/block/13_definition_list/too_much_space.text +4 -0
- data/test/testcases/block/13_definition_list/with_blocks.html +38 -0
- data/test/testcases/block/13_definition_list/with_blocks.text +24 -0
- data/test/testcases/block/14_table/errors.html +8 -0
- data/test/testcases/block/14_table/errors.text +9 -0
- data/test/testcases/block/14_table/footer.html +65 -0
- data/test/testcases/block/14_table/footer.text +25 -0
- data/test/testcases/block/14_table/header.html +103 -0
- data/test/testcases/block/14_table/header.text +32 -0
- data/test/testcases/block/14_table/no_table.html +3 -0
- data/test/testcases/block/14_table/no_table.text +3 -0
- data/test/testcases/block/14_table/simple.html +139 -0
- data/test/testcases/block/14_table/simple.text +38 -0
- data/test/testcases/block/15_math/normal.html +26 -0
- data/test/testcases/block/15_math/normal.text +28 -0
- data/test/testcases/block/16_toc/no_toc_depth.html +33 -0
- data/test/testcases/block/16_toc/no_toc_depth.options +1 -0
- data/test/testcases/block/16_toc/no_toc_depth.text +16 -0
- data/test/testcases/block/16_toc/toc_depth_2.html +24 -0
- data/test/testcases/block/16_toc/toc_depth_2.options +1 -0
- data/test/testcases/block/16_toc/toc_depth_2.text +16 -0
- data/test/testcases/encoding.html +46 -0
- data/test/testcases/encoding.text +28 -0
- data/test/testcases/span/01_link/empty.html +5 -0
- data/test/testcases/span/01_link/empty.text +5 -0
- data/test/testcases/span/01_link/image_in_a.html +5 -0
- data/test/testcases/span/01_link/image_in_a.text +5 -0
- data/test/testcases/span/01_link/imagelinks.html +14 -0
- data/test/testcases/span/01_link/imagelinks.text +16 -0
- data/test/testcases/span/01_link/inline.html +46 -0
- data/test/testcases/span/01_link/inline.html.19 +46 -0
- data/test/testcases/span/01_link/inline.text +48 -0
- data/test/testcases/span/01_link/link_defs.html +9 -0
- data/test/testcases/span/01_link/link_defs.text +26 -0
- data/test/testcases/span/01_link/links_with_angle_brackets.html +3 -0
- data/test/testcases/span/01_link/links_with_angle_brackets.text +3 -0
- data/test/testcases/span/01_link/reference.html +35 -0
- data/test/testcases/span/01_link/reference.html.19 +35 -0
- data/test/testcases/span/01_link/reference.text +47 -0
- data/test/testcases/span/02_emphasis/empty.html +3 -0
- data/test/testcases/span/02_emphasis/empty.text +3 -0
- data/test/testcases/span/02_emphasis/errors.html +9 -0
- data/test/testcases/span/02_emphasis/errors.text +9 -0
- data/test/testcases/span/02_emphasis/nesting.html +38 -0
- data/test/testcases/span/02_emphasis/nesting.text +33 -0
- data/test/testcases/span/02_emphasis/normal.html +46 -0
- data/test/testcases/span/02_emphasis/normal.text +46 -0
- data/test/testcases/span/03_codespan/empty.html +5 -0
- data/test/testcases/span/03_codespan/empty.text +5 -0
- data/test/testcases/span/03_codespan/errors.html +1 -0
- data/test/testcases/span/03_codespan/errors.text +1 -0
- data/test/testcases/span/03_codespan/highlighting.html +1 -0
- data/test/testcases/span/03_codespan/highlighting.text +1 -0
- data/test/testcases/span/03_codespan/normal.html +16 -0
- data/test/testcases/span/03_codespan/normal.text +16 -0
- data/test/testcases/span/04_footnote/definitions.html +17 -0
- data/test/testcases/span/04_footnote/definitions.latex +17 -0
- data/test/testcases/span/04_footnote/definitions.text +24 -0
- data/test/testcases/span/04_footnote/footnote_nr.html +12 -0
- data/test/testcases/span/04_footnote/footnote_nr.latex +2 -0
- data/test/testcases/span/04_footnote/footnote_nr.options +1 -0
- data/test/testcases/span/04_footnote/footnote_nr.text +4 -0
- data/test/testcases/span/04_footnote/markers.html +46 -0
- data/test/testcases/span/04_footnote/markers.latex +23 -0
- data/test/testcases/span/04_footnote/markers.text +26 -0
- data/test/testcases/span/05_html/across_lines.html +1 -0
- data/test/testcases/span/05_html/across_lines.text +2 -0
- data/test/testcases/span/05_html/invalid.html +1 -0
- data/test/testcases/span/05_html/invalid.text +1 -0
- data/test/testcases/span/05_html/link_with_mailto.html +1 -0
- data/test/testcases/span/05_html/link_with_mailto.text +1 -0
- data/test/testcases/span/05_html/markdown_attr.html +6 -0
- data/test/testcases/span/05_html/markdown_attr.text +6 -0
- data/test/testcases/span/05_html/normal.html +30 -0
- data/test/testcases/span/05_html/normal.text +30 -0
- data/test/testcases/span/abbreviations/abbrev.html +8 -0
- data/test/testcases/span/abbreviations/abbrev.text +15 -0
- data/test/testcases/span/abbreviations/abbrev_defs.html +2 -0
- data/test/testcases/span/abbreviations/abbrev_defs.text +5 -0
- data/test/testcases/span/autolinks/url_links.html +12 -0
- data/test/testcases/span/autolinks/url_links.text +12 -0
- data/test/testcases/span/escaped_chars/normal.html +43 -0
- data/test/testcases/span/escaped_chars/normal.text +43 -0
- data/test/testcases/span/extension/comment.html +6 -0
- data/test/testcases/span/extension/comment.text +6 -0
- data/test/testcases/span/extension/ignored.html +1 -0
- data/test/testcases/span/extension/ignored.text +1 -0
- data/test/testcases/span/extension/nomarkdown.html +1 -0
- data/test/testcases/span/extension/nomarkdown.text +1 -0
- data/test/testcases/span/extension/options.html +1 -0
- data/test/testcases/span/extension/options.text +1 -0
- data/test/testcases/span/ial/simple.html +6 -0
- data/test/testcases/span/ial/simple.text +6 -0
- data/test/testcases/span/line_breaks/normal.html +11 -0
- data/test/testcases/span/line_breaks/normal.latex +12 -0
- data/test/testcases/span/line_breaks/normal.text +11 -0
- data/test/testcases/span/math/normal.html +5 -0
- data/test/testcases/span/math/normal.text +5 -0
- data/test/testcases/span/text_substitutions/entities.html +4 -0
- data/test/testcases/span/text_substitutions/entities.options +1 -0
- data/test/testcases/span/text_substitutions/entities.text +4 -0
- data/test/testcases/span/text_substitutions/entities_as_char.html +1 -0
- data/test/testcases/span/text_substitutions/entities_as_char.html.19 +1 -0
- data/test/testcases/span/text_substitutions/entities_as_char.options +1 -0
- data/test/testcases/span/text_substitutions/entities_as_char.text +1 -0
- data/test/testcases/span/text_substitutions/entities_as_input.html +1 -0
- data/test/testcases/span/text_substitutions/entities_as_input.options +1 -0
- data/test/testcases/span/text_substitutions/entities_as_input.text +1 -0
- data/test/testcases/span/text_substitutions/entities_numeric.html +1 -0
- data/test/testcases/span/text_substitutions/entities_numeric.options +1 -0
- data/test/testcases/span/text_substitutions/entities_numeric.text +1 -0
- data/test/testcases/span/text_substitutions/entities_symbolic.html +1 -0
- data/test/testcases/span/text_substitutions/entities_symbolic.options +1 -0
- data/test/testcases/span/text_substitutions/entities_symbolic.text +1 -0
- data/test/testcases/span/text_substitutions/greaterthan.html +1 -0
- data/test/testcases/span/text_substitutions/greaterthan.text +1 -0
- data/test/testcases/span/text_substitutions/lowerthan.html +1 -0
- data/test/testcases/span/text_substitutions/lowerthan.text +1 -0
- data/test/testcases/span/text_substitutions/typography.html +18 -0
- data/test/testcases/span/text_substitutions/typography.html.19 +18 -0
- data/test/testcases/span/text_substitutions/typography.text +18 -0
- metadata +476 -0
@@ -0,0 +1,7 @@
|
|
1
|
+
# newstile 0.1.0 || newstile 0.2.0 || kramdown 0.3.0 || kramdown 0.4.0 || kramdown 0.5.0 || kramdown 0.6.0
|
2
|
+
1 0.21300 0.31800 0.16800 0.30400 0.30800 0.17300
|
3
|
+
2 0.20700 0.22600 0.26700 0.23400 0.26800 0.39000
|
4
|
+
4 0.22000 0.21700 0.20400 0.19300 0.19400 0.19300
|
5
|
+
8 0.36300 0.44500 0.30100 0.29500 0.32800 0.31900
|
6
|
+
16 0.45400 0.53400 0.46200 0.48900 0.50200 0.51000
|
7
|
+
32 1.02800 0.98100 0.84600 0.81900 0.72200 0.68500
|
@@ -0,0 +1,7 @@
|
|
1
|
+
# newstile 0.1.0 || newstile 0.2.0 || kramdown 0.3.0 || kramdown 0.4.0 || kramdown 0.5.0 || kramdown 0.6.0
|
2
|
+
1 0.01211 0.01274 0.01385 0.01359 0.01539 0.01531
|
3
|
+
2 0.02449 0.02582 0.02924 0.02691 0.03194 0.03106
|
4
|
+
4 0.08228 0.08475 0.08600 0.09013 0.05768 0.05841
|
5
|
+
8 0.12842 0.13410 0.14426 0.13687 0.14952 0.15120
|
6
|
+
16 0.22743 0.27748 0.29497 0.28115 0.26786 0.27056
|
7
|
+
32 0.45690 0.51838 0.54252 0.51869 0.57976 0.51855
|
@@ -0,0 +1,7 @@
|
|
1
|
+
# newstile 0.1.0 || newstile 0.2.0 || kramdown 0.3.0 || kramdown 0.4.0 || kramdown 0.5.0 || kramdown 0.6.0
|
2
|
+
1 0.01259 0.01329 0.01580 0.01397 0.01554 0.01583
|
3
|
+
2 0.02472 0.02672 0.02858 0.02849 0.03387 0.03192
|
4
|
+
4 0.09610 0.08355 0.05439 0.05232 0.05801 0.06041
|
5
|
+
8 0.13269 0.13811 0.10869 0.10471 0.15673 0.15005
|
6
|
+
16 0.27243 0.27540 0.28680 0.27240 0.31712 0.31372
|
7
|
+
32 0.52890 0.55667 0.54547 0.52283 0.60766 0.59042
|
@@ -0,0 +1,7 @@
|
|
1
|
+
# newstile 0.1.0 || newstile 0.2.0 || kramdown 0.3.0 || kramdown 0.4.0 || kramdown 0.5.0 || kramdown 0.6.0
|
2
|
+
1 0.02062 0.02216 0.02152 0.02025 0.01289 0.01334
|
3
|
+
2 0.04097 0.04290 0.03939 0.03956 0.02890 0.02739
|
4
|
+
4 0.07696 0.08015 0.09122 0.07573 0.06272 0.06234
|
5
|
+
8 0.16986 0.16998 0.16856 0.16380 0.11127 0.11350
|
6
|
+
16 0.33684 0.34800 0.35242 0.33358 0.23528 0.23868
|
7
|
+
32 0.68273 0.70498 0.74138 0.66569 0.44669 0.45204
|
@@ -0,0 +1,7 @@
|
|
1
|
+
# newstile 0.1.0 || newstile 0.2.0 || kramdown 0.3.0 || kramdown 0.4.0 || kramdown 0.5.0 || kramdown 0.6.0
|
2
|
+
1 0.01827 0.02000 0.01830 0.02061 0.01632 0.01618
|
3
|
+
2 0.03951 0.04158 0.04056 0.04378 0.03590 0.03532
|
4
|
+
4 0.08055 0.08419 0.08363 0.08286 0.04809 0.04781
|
5
|
+
8 0.14925 0.15101 0.15830 0.14567 0.10250 0.10226
|
6
|
+
16 0.31483 0.31485 0.31176 0.30726 0.20651 0.20778
|
7
|
+
32 0.62318 0.64162 0.61918 0.59270 0.42345 0.42295
|
@@ -0,0 +1,306 @@
|
|
1
|
+
Markdown: Basics
|
2
|
+
================
|
3
|
+
|
4
|
+
<ul id="ProjectSubmenu">
|
5
|
+
<li><a href="/projects/markdown/" title="Markdown Project Page">Main</a></li>
|
6
|
+
<li><a class="selected" title="Markdown Basics">Basics</a></li>
|
7
|
+
<li><a href="/projects/markdown/syntax" title="Markdown Syntax Documentation">Syntax</a></li>
|
8
|
+
<li><a href="/projects/markdown/license" title="Pricing and License Information">License</a></li>
|
9
|
+
<li><a href="/projects/markdown/dingus" title="Online Markdown Web Form">Dingus</a></li>
|
10
|
+
</ul>
|
11
|
+
|
12
|
+
|
13
|
+
Getting the Gist of Markdown's Formatting Syntax
|
14
|
+
------------------------------------------------
|
15
|
+
|
16
|
+
This page offers a brief overview of what it's like to use Markdown.
|
17
|
+
The [syntax page] [s] provides complete, detailed documentation for
|
18
|
+
every feature, but Markdown should be very easy to pick up simply by
|
19
|
+
looking at a few examples of it in action. The examples on this page
|
20
|
+
are written in a before/after style, showing example syntax and the
|
21
|
+
HTML output produced by Markdown.
|
22
|
+
|
23
|
+
It's also helpful to simply try Markdown out; the [Dingus] [d] is a
|
24
|
+
web application that allows you type your own Markdown-formatted text
|
25
|
+
and translate it to XHTML.
|
26
|
+
|
27
|
+
**Note:** This document is itself written using Markdown; you
|
28
|
+
can [see the source for it by adding '.text' to the URL] [src].
|
29
|
+
|
30
|
+
[s]: /projects/markdown/syntax "Markdown Syntax"
|
31
|
+
[d]: /projects/markdown/dingus "Markdown Dingus"
|
32
|
+
[src]: /projects/markdown/basics.text
|
33
|
+
|
34
|
+
|
35
|
+
## Paragraphs, Headers, Blockquotes ##
|
36
|
+
|
37
|
+
A paragraph is simply one or more consecutive lines of text, separated
|
38
|
+
by one or more blank lines. (A blank line is any line that looks like a
|
39
|
+
blank line -- a line containing nothing spaces or tabs is considered
|
40
|
+
blank.) Normal paragraphs should not be intended with spaces or tabs.
|
41
|
+
|
42
|
+
Markdown offers two styles of headers: *Setext* and *atx*.
|
43
|
+
Setext-style headers for `<h1>` and `<h2>` are created by
|
44
|
+
"underlining" with equal signs (`=`) and hyphens (`-`), respectively.
|
45
|
+
To create an atx-style header, you put 1-6 hash marks (`#`) at the
|
46
|
+
beginning of the line -- the number of hashes equals the resulting
|
47
|
+
HTML header level.
|
48
|
+
|
49
|
+
Blockquotes are indicated using email-style '`>`' angle brackets.
|
50
|
+
|
51
|
+
Markdown:
|
52
|
+
|
53
|
+
A First Level Header
|
54
|
+
====================
|
55
|
+
|
56
|
+
A Second Level Header
|
57
|
+
---------------------
|
58
|
+
|
59
|
+
Now is the time for all good men to come to
|
60
|
+
the aid of their country. This is just a
|
61
|
+
regular paragraph.
|
62
|
+
|
63
|
+
The quick brown fox jumped over the lazy
|
64
|
+
dog's back.
|
65
|
+
|
66
|
+
### Header 3
|
67
|
+
|
68
|
+
> This is a blockquote.
|
69
|
+
>
|
70
|
+
> This is the second paragraph in the blockquote.
|
71
|
+
>
|
72
|
+
> ## This is an H2 in a blockquote
|
73
|
+
|
74
|
+
|
75
|
+
Output:
|
76
|
+
|
77
|
+
<h1>A First Level Header</h1>
|
78
|
+
|
79
|
+
<h2>A Second Level Header</h2>
|
80
|
+
|
81
|
+
<p>Now is the time for all good men to come to
|
82
|
+
the aid of their country. This is just a
|
83
|
+
regular paragraph.</p>
|
84
|
+
|
85
|
+
<p>The quick brown fox jumped over the lazy
|
86
|
+
dog's back.</p>
|
87
|
+
|
88
|
+
<h3>Header 3</h3>
|
89
|
+
|
90
|
+
<blockquote>
|
91
|
+
<p>This is a blockquote.</p>
|
92
|
+
|
93
|
+
<p>This is the second paragraph in the blockquote.</p>
|
94
|
+
|
95
|
+
<h2>This is an H2 in a blockquote</h2>
|
96
|
+
</blockquote>
|
97
|
+
|
98
|
+
|
99
|
+
|
100
|
+
### Phrase Emphasis ###
|
101
|
+
|
102
|
+
Markdown uses asterisks and underscores to indicate spans of emphasis.
|
103
|
+
|
104
|
+
Markdown:
|
105
|
+
|
106
|
+
Some of these words *are emphasized*.
|
107
|
+
Some of these words _are emphasized also_.
|
108
|
+
|
109
|
+
Use two asterisks for **strong emphasis**.
|
110
|
+
Or, if you prefer, __use two underscores instead__.
|
111
|
+
|
112
|
+
Output:
|
113
|
+
|
114
|
+
<p>Some of these words <em>are emphasized</em>.
|
115
|
+
Some of these words <em>are emphasized also</em>.</p>
|
116
|
+
|
117
|
+
<p>Use two asterisks for <strong>strong emphasis</strong>.
|
118
|
+
Or, if you prefer, <strong>use two underscores instead</strong>.</p>
|
119
|
+
|
120
|
+
|
121
|
+
|
122
|
+
## Lists ##
|
123
|
+
|
124
|
+
Unordered (bulleted) lists use asterisks, pluses, and hyphens (`*`,
|
125
|
+
`+`, and `-`) as list markers. These three markers are
|
126
|
+
interchangable; this:
|
127
|
+
|
128
|
+
* Candy.
|
129
|
+
* Gum.
|
130
|
+
* Booze.
|
131
|
+
|
132
|
+
this:
|
133
|
+
|
134
|
+
+ Candy.
|
135
|
+
+ Gum.
|
136
|
+
+ Booze.
|
137
|
+
|
138
|
+
and this:
|
139
|
+
|
140
|
+
- Candy.
|
141
|
+
- Gum.
|
142
|
+
- Booze.
|
143
|
+
|
144
|
+
all produce the same output:
|
145
|
+
|
146
|
+
<ul>
|
147
|
+
<li>Candy.</li>
|
148
|
+
<li>Gum.</li>
|
149
|
+
<li>Booze.</li>
|
150
|
+
</ul>
|
151
|
+
|
152
|
+
Ordered (numbered) lists use regular numbers, followed by periods, as
|
153
|
+
list markers:
|
154
|
+
|
155
|
+
1. Red
|
156
|
+
2. Green
|
157
|
+
3. Blue
|
158
|
+
|
159
|
+
Output:
|
160
|
+
|
161
|
+
<ol>
|
162
|
+
<li>Red</li>
|
163
|
+
<li>Green</li>
|
164
|
+
<li>Blue</li>
|
165
|
+
</ol>
|
166
|
+
|
167
|
+
If you put blank lines between items, you'll get `<p>` tags for the
|
168
|
+
list item text. You can create multi-paragraph list items by indenting
|
169
|
+
the paragraphs by 4 spaces or 1 tab:
|
170
|
+
|
171
|
+
* A list item.
|
172
|
+
|
173
|
+
With multiple paragraphs.
|
174
|
+
|
175
|
+
* Another item in the list.
|
176
|
+
|
177
|
+
Output:
|
178
|
+
|
179
|
+
<ul>
|
180
|
+
<li><p>A list item.</p>
|
181
|
+
<p>With multiple paragraphs.</p></li>
|
182
|
+
<li><p>Another item in the list.</p></li>
|
183
|
+
</ul>
|
184
|
+
|
185
|
+
|
186
|
+
|
187
|
+
### Links ###
|
188
|
+
|
189
|
+
Markdown supports two styles for creating links: *inline* and
|
190
|
+
*reference*. With both styles, you use square brackets to delimit the
|
191
|
+
text you want to turn into a link.
|
192
|
+
|
193
|
+
Inline-style links use parentheses immediately after the link text.
|
194
|
+
For example:
|
195
|
+
|
196
|
+
This is an [example link](http://example.com/).
|
197
|
+
|
198
|
+
Output:
|
199
|
+
|
200
|
+
<p>This is an <a href="http://example.com/">
|
201
|
+
example link</a>.</p>
|
202
|
+
|
203
|
+
Optionally, you may include a title attribute in the parentheses:
|
204
|
+
|
205
|
+
This is an [example link](http://example.com/ "With a Title").
|
206
|
+
|
207
|
+
Output:
|
208
|
+
|
209
|
+
<p>This is an <a href="http://example.com/" title="With a Title">
|
210
|
+
example link</a>.</p>
|
211
|
+
|
212
|
+
Reference-style links allow you to refer to your links by names, which
|
213
|
+
you define elsewhere in your document:
|
214
|
+
|
215
|
+
I get 10 times more traffic from [Google][1] than from
|
216
|
+
[Yahoo][2] or [MSN][3].
|
217
|
+
|
218
|
+
[1]: http://google.com/ "Google"
|
219
|
+
[2]: http://search.yahoo.com/ "Yahoo Search"
|
220
|
+
[3]: http://search.msn.com/ "MSN Search"
|
221
|
+
|
222
|
+
Output:
|
223
|
+
|
224
|
+
<p>I get 10 times more traffic from <a href="http://google.com/"
|
225
|
+
title="Google">Google</a> than from <a href="http://search.yahoo.com/"
|
226
|
+
title="Yahoo Search">Yahoo</a> or <a href="http://search.msn.com/"
|
227
|
+
title="MSN Search">MSN</a>.</p>
|
228
|
+
|
229
|
+
The title attribute is optional. Link names may contain letters,
|
230
|
+
numbers and spaces, but are *not* case sensitive:
|
231
|
+
|
232
|
+
I start my morning with a cup of coffee and
|
233
|
+
[The New York Times][NY Times].
|
234
|
+
|
235
|
+
[ny times]: http://www.nytimes.com/
|
236
|
+
|
237
|
+
Output:
|
238
|
+
|
239
|
+
<p>I start my morning with a cup of coffee and
|
240
|
+
<a href="http://www.nytimes.com/">The New York Times</a>.</p>
|
241
|
+
|
242
|
+
|
243
|
+
### Images ###
|
244
|
+
|
245
|
+
Image syntax is very much like link syntax.
|
246
|
+
|
247
|
+
Inline (titles are optional):
|
248
|
+
|
249
|
+
![alt text](/path/to/img.jpg "Title")
|
250
|
+
|
251
|
+
Reference-style:
|
252
|
+
|
253
|
+
![alt text][id]
|
254
|
+
|
255
|
+
[id]: /path/to/img.jpg "Title"
|
256
|
+
|
257
|
+
Both of the above examples produce the same output:
|
258
|
+
|
259
|
+
<img src="/path/to/img.jpg" alt="alt text" title="Title" />
|
260
|
+
|
261
|
+
|
262
|
+
|
263
|
+
### Code ###
|
264
|
+
|
265
|
+
In a regular paragraph, you can create code span by wrapping text in
|
266
|
+
backtick quotes. Any ampersands (`&`) and angle brackets (`<` or
|
267
|
+
`>`) will automatically be translated into HTML entities. This makes
|
268
|
+
it easy to use Markdown to write about HTML example code:
|
269
|
+
|
270
|
+
I strongly recommend against using any `<blink>` tags.
|
271
|
+
|
272
|
+
I wish SmartyPants used named entities like `—`
|
273
|
+
instead of decimal-encoded entites like `—`.
|
274
|
+
|
275
|
+
Output:
|
276
|
+
|
277
|
+
<p>I strongly recommend against using any
|
278
|
+
<code><blink></code> tags.</p>
|
279
|
+
|
280
|
+
<p>I wish SmartyPants used named entities like
|
281
|
+
<code>&mdash;</code> instead of decimal-encoded
|
282
|
+
entites like <code>&#8212;</code>.</p>
|
283
|
+
|
284
|
+
|
285
|
+
To specify an entire block of pre-formatted code, indent every line of
|
286
|
+
the block by 4 spaces or 1 tab. Just like with code spans, `&`, `<`,
|
287
|
+
and `>` characters will be escaped automatically.
|
288
|
+
|
289
|
+
Markdown:
|
290
|
+
|
291
|
+
If you want your page to validate under XHTML 1.0 Strict,
|
292
|
+
you've got to put paragraph tags in your blockquotes:
|
293
|
+
|
294
|
+
<blockquote>
|
295
|
+
<p>For example.</p>
|
296
|
+
</blockquote>
|
297
|
+
|
298
|
+
Output:
|
299
|
+
|
300
|
+
<p>If you want your page to validate under XHTML 1.0 Strict,
|
301
|
+
you've got to put paragraph tags in your blockquotes:</p>
|
302
|
+
|
303
|
+
<pre><code><blockquote>
|
304
|
+
<p>For example.</p>
|
305
|
+
</blockquote>
|
306
|
+
</code></pre>
|
@@ -0,0 +1,888 @@
|
|
1
|
+
Markdown: Syntax
|
2
|
+
================
|
3
|
+
|
4
|
+
<ul id="ProjectSubmenu">
|
5
|
+
<li><a href="/projects/markdown/" title="Markdown Project Page">Main</a></li>
|
6
|
+
<li><a href="/projects/markdown/basics" title="Markdown Basics">Basics</a></li>
|
7
|
+
<li><a class="selected" title="Markdown Syntax Documentation">Syntax</a></li>
|
8
|
+
<li><a href="/projects/markdown/license" title="Pricing and License Information">License</a></li>
|
9
|
+
<li><a href="/projects/markdown/dingus" title="Online Markdown Web Form">Dingus</a></li>
|
10
|
+
</ul>
|
11
|
+
|
12
|
+
|
13
|
+
* [Overview](#overview)
|
14
|
+
* [Philosophy](#philosophy)
|
15
|
+
* [Inline HTML](#html)
|
16
|
+
* [Automatic Escaping for Special Characters](#autoescape)
|
17
|
+
* [Block Elements](#block)
|
18
|
+
* [Paragraphs and Line Breaks](#p)
|
19
|
+
* [Headers](#header)
|
20
|
+
* [Blockquotes](#blockquote)
|
21
|
+
* [Lists](#list)
|
22
|
+
* [Code Blocks](#precode)
|
23
|
+
* [Horizontal Rules](#hr)
|
24
|
+
* [Span Elements](#span)
|
25
|
+
* [Links](#link)
|
26
|
+
* [Emphasis](#em)
|
27
|
+
* [Code](#code)
|
28
|
+
* [Images](#img)
|
29
|
+
* [Miscellaneous](#misc)
|
30
|
+
* [Backslash Escapes](#backslash)
|
31
|
+
* [Automatic Links](#autolink)
|
32
|
+
|
33
|
+
|
34
|
+
**Note:** This document is itself written using Markdown; you
|
35
|
+
can [see the source for it by adding '.text' to the URL][src].
|
36
|
+
|
37
|
+
[src]: /projects/markdown/syntax.text
|
38
|
+
|
39
|
+
* * *
|
40
|
+
|
41
|
+
<h2 id="overview">Overview</h2>
|
42
|
+
|
43
|
+
<h3 id="philosophy">Philosophy</h3>
|
44
|
+
|
45
|
+
Markdown is intended to be as easy-to-read and easy-to-write as is feasible.
|
46
|
+
|
47
|
+
Readability, however, is emphasized above all else. A Markdown-formatted
|
48
|
+
document should be publishable as-is, as plain text, without looking
|
49
|
+
like it's been marked up with tags or formatting instructions. While
|
50
|
+
Markdown's syntax has been influenced by several existing text-to-HTML
|
51
|
+
filters -- including [Setext] [1], [atx] [2], [Textile] [3], [reStructuredText] [4],
|
52
|
+
[Grutatext] [5], and [EtText] [6] -- the single biggest source of
|
53
|
+
inspiration for Markdown's syntax is the format of plain text email.
|
54
|
+
|
55
|
+
[1]: http://docutils.sourceforge.net/mirror/setext.html
|
56
|
+
[2]: http://www.aaronsw.com/2002/atx/
|
57
|
+
[3]: http://textism.com/tools/textile/
|
58
|
+
[4]: http://docutils.sourceforge.net/rst.html
|
59
|
+
[5]: http://www.triptico.com/software/grutatxt.html
|
60
|
+
[6]: http://ettext.taint.org/doc/
|
61
|
+
|
62
|
+
To this end, Markdown's syntax is comprised entirely of punctuation
|
63
|
+
characters, which punctuation characters have been carefully chosen so
|
64
|
+
as to look like what they mean. E.g., asterisks around a word actually
|
65
|
+
look like \*emphasis\*. Markdown lists look like, well, lists. Even
|
66
|
+
blockquotes look like quoted passages of text, assuming you've ever
|
67
|
+
used email.
|
68
|
+
|
69
|
+
|
70
|
+
|
71
|
+
<h3 id="html">Inline HTML</h3>
|
72
|
+
|
73
|
+
Markdown's syntax is intended for one purpose: to be used as a
|
74
|
+
format for *writing* for the web.
|
75
|
+
|
76
|
+
Markdown is not a replacement for HTML, or even close to it. Its
|
77
|
+
syntax is very small, corresponding only to a very small subset of
|
78
|
+
HTML tags. The idea is *not* to create a syntax that makes it easier
|
79
|
+
to insert HTML tags. In my opinion, HTML tags are already easy to
|
80
|
+
insert. The idea for Markdown is to make it easy to read, write, and
|
81
|
+
edit prose. HTML is a *publishing* format; Markdown is a *writing*
|
82
|
+
format. Thus, Markdown's formatting syntax only addresses issues that
|
83
|
+
can be conveyed in plain text.
|
84
|
+
|
85
|
+
For any markup that is not covered by Markdown's syntax, you simply
|
86
|
+
use HTML itself. There's no need to preface it or delimit it to
|
87
|
+
indicate that you're switching from Markdown to HTML; you just use
|
88
|
+
the tags.
|
89
|
+
|
90
|
+
The only restrictions are that block-level HTML elements -- e.g. `<div>`,
|
91
|
+
`<table>`, `<pre>`, `<p>`, etc. -- must be separated from surrounding
|
92
|
+
content by blank lines, and the start and end tags of the block should
|
93
|
+
not be indented with tabs or spaces. Markdown is smart enough not
|
94
|
+
to add extra (unwanted) `<p>` tags around HTML block-level tags.
|
95
|
+
|
96
|
+
For example, to add an HTML table to a Markdown article:
|
97
|
+
|
98
|
+
This is a regular paragraph.
|
99
|
+
|
100
|
+
<table>
|
101
|
+
<tr>
|
102
|
+
<td>Foo</td>
|
103
|
+
</tr>
|
104
|
+
</table>
|
105
|
+
|
106
|
+
This is another regular paragraph.
|
107
|
+
|
108
|
+
Note that Markdown formatting syntax is not processed within block-level
|
109
|
+
HTML tags. E.g., you can't use Markdown-style `*emphasis*` inside an
|
110
|
+
HTML block.
|
111
|
+
|
112
|
+
Span-level HTML tags -- e.g. `<span>`, `<cite>`, or `<del>` -- can be
|
113
|
+
used anywhere in a Markdown paragraph, list item, or header. If you
|
114
|
+
want, you can even use HTML tags instead of Markdown formatting; e.g. if
|
115
|
+
you'd prefer to use HTML `<a>` or `<img>` tags instead of Markdown's
|
116
|
+
link or image syntax, go right ahead.
|
117
|
+
|
118
|
+
Unlike block-level HTML tags, Markdown syntax *is* processed within
|
119
|
+
span-level tags.
|
120
|
+
|
121
|
+
|
122
|
+
<h3 id="autoescape">Automatic Escaping for Special Characters</h3>
|
123
|
+
|
124
|
+
In HTML, there are two characters that demand special treatment: `<`
|
125
|
+
and `&`. Left angle brackets are used to start tags; ampersands are
|
126
|
+
used to denote HTML entities. If you want to use them as literal
|
127
|
+
characters, you must escape them as entities, e.g. `<`, and
|
128
|
+
`&`.
|
129
|
+
|
130
|
+
Ampersands in particular are bedeviling for web writers. If you want to
|
131
|
+
write about 'AT&T', you need to write '`AT&T`'. You even need to
|
132
|
+
escape ampersands within URLs. Thus, if you want to link to:
|
133
|
+
|
134
|
+
http://images.google.com/images?num=30&q=larry+bird
|
135
|
+
|
136
|
+
you need to encode the URL as:
|
137
|
+
|
138
|
+
http://images.google.com/images?num=30&q=larry+bird
|
139
|
+
|
140
|
+
in your anchor tag `href` attribute. Needless to say, this is easy to
|
141
|
+
forget, and is probably the single most common source of HTML validation
|
142
|
+
errors in otherwise well-marked-up web sites.
|
143
|
+
|
144
|
+
Markdown allows you to use these characters naturally, taking care of
|
145
|
+
all the necessary escaping for you. If you use an ampersand as part of
|
146
|
+
an HTML entity, it remains unchanged; otherwise it will be translated
|
147
|
+
into `&`.
|
148
|
+
|
149
|
+
So, if you want to include a copyright symbol in your article, you can write:
|
150
|
+
|
151
|
+
©
|
152
|
+
|
153
|
+
and Markdown will leave it alone. But if you write:
|
154
|
+
|
155
|
+
AT&T
|
156
|
+
|
157
|
+
Markdown will translate it to:
|
158
|
+
|
159
|
+
AT&T
|
160
|
+
|
161
|
+
Similarly, because Markdown supports [inline HTML](#html), if you use
|
162
|
+
angle brackets as delimiters for HTML tags, Markdown will treat them as
|
163
|
+
such. But if you write:
|
164
|
+
|
165
|
+
4 < 5
|
166
|
+
|
167
|
+
Markdown will translate it to:
|
168
|
+
|
169
|
+
4 < 5
|
170
|
+
|
171
|
+
However, inside Markdown code spans and blocks, angle brackets and
|
172
|
+
ampersands are *always* encoded automatically. This makes it easy to use
|
173
|
+
Markdown to write about HTML code. (As opposed to raw HTML, which is a
|
174
|
+
terrible format for writing about HTML syntax, because every single `<`
|
175
|
+
and `&` in your example code needs to be escaped.)
|
176
|
+
|
177
|
+
|
178
|
+
* * *
|
179
|
+
|
180
|
+
|
181
|
+
<h2 id="block">Block Elements</h2>
|
182
|
+
|
183
|
+
|
184
|
+
<h3 id="p">Paragraphs and Line Breaks</h3>
|
185
|
+
|
186
|
+
A paragraph is simply one or more consecutive lines of text, separated
|
187
|
+
by one or more blank lines. (A blank line is any line that looks like a
|
188
|
+
blank line -- a line containing nothing but spaces or tabs is considered
|
189
|
+
blank.) Normal paragraphs should not be intended with spaces or tabs.
|
190
|
+
|
191
|
+
The implication of the "one or more consecutive lines of text" rule is
|
192
|
+
that Markdown supports "hard-wrapped" text paragraphs. This differs
|
193
|
+
significantly from most other text-to-HTML formatters (including Movable
|
194
|
+
Type's "Convert Line Breaks" option) which translate every line break
|
195
|
+
character in a paragraph into a `<br />` tag.
|
196
|
+
|
197
|
+
When you *do* want to insert a `<br />` break tag using Markdown, you
|
198
|
+
end a line with two or more spaces, then type return.
|
199
|
+
|
200
|
+
Yes, this takes a tad more effort to create a `<br />`, but a simplistic
|
201
|
+
"every line break is a `<br />`" rule wouldn't work for Markdown.
|
202
|
+
Markdown's email-style [blockquoting][bq] and multi-paragraph [list items][l]
|
203
|
+
work best -- and look better -- when you format them with hard breaks.
|
204
|
+
|
205
|
+
[bq]: #blockquote
|
206
|
+
[l]: #list
|
207
|
+
|
208
|
+
|
209
|
+
|
210
|
+
<h3 id="header">Headers</h3>
|
211
|
+
|
212
|
+
Markdown supports two styles of headers, [Setext] [1] and [atx] [2].
|
213
|
+
|
214
|
+
Setext-style headers are "underlined" using equal signs (for first-level
|
215
|
+
headers) and dashes (for second-level headers). For example:
|
216
|
+
|
217
|
+
This is an H1
|
218
|
+
=============
|
219
|
+
|
220
|
+
This is an H2
|
221
|
+
-------------
|
222
|
+
|
223
|
+
Any number of underlining `=`'s or `-`'s will work.
|
224
|
+
|
225
|
+
Atx-style headers use 1-6 hash characters at the start of the line,
|
226
|
+
corresponding to header levels 1-6. For example:
|
227
|
+
|
228
|
+
# This is an H1
|
229
|
+
|
230
|
+
## This is an H2
|
231
|
+
|
232
|
+
###### This is an H6
|
233
|
+
|
234
|
+
Optionally, you may "close" atx-style headers. This is purely
|
235
|
+
cosmetic -- you can use this if you think it looks better. The
|
236
|
+
closing hashes don't even need to match the number of hashes
|
237
|
+
used to open the header. (The number of opening hashes
|
238
|
+
determines the header level.) :
|
239
|
+
|
240
|
+
# This is an H1 #
|
241
|
+
|
242
|
+
## This is an H2 ##
|
243
|
+
|
244
|
+
### This is an H3 ######
|
245
|
+
|
246
|
+
|
247
|
+
<h3 id="blockquote">Blockquotes</h3>
|
248
|
+
|
249
|
+
Markdown uses email-style `>` characters for blockquoting. If you're
|
250
|
+
familiar with quoting passages of text in an email message, then you
|
251
|
+
know how to create a blockquote in Markdown. It looks best if you hard
|
252
|
+
wrap the text and put a `>` before every line:
|
253
|
+
|
254
|
+
> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
|
255
|
+
> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
|
256
|
+
> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
|
257
|
+
>
|
258
|
+
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
|
259
|
+
> id sem consectetuer libero luctus adipiscing.
|
260
|
+
|
261
|
+
Markdown allows you to be lazy and only put the `>` before the first
|
262
|
+
line of a hard-wrapped paragraph:
|
263
|
+
|
264
|
+
> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
|
265
|
+
consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
|
266
|
+
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
|
267
|
+
|
268
|
+
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
|
269
|
+
id sem consectetuer libero luctus adipiscing.
|
270
|
+
|
271
|
+
Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by
|
272
|
+
adding additional levels of `>`:
|
273
|
+
|
274
|
+
> This is the first level of quoting.
|
275
|
+
>
|
276
|
+
> > This is nested blockquote.
|
277
|
+
>
|
278
|
+
> Back to the first level.
|
279
|
+
|
280
|
+
Blockquotes can contain other Markdown elements, including headers, lists,
|
281
|
+
and code blocks:
|
282
|
+
|
283
|
+
> ## This is a header.
|
284
|
+
>
|
285
|
+
> 1. This is the first list item.
|
286
|
+
> 2. This is the second list item.
|
287
|
+
>
|
288
|
+
> Here's some example code:
|
289
|
+
>
|
290
|
+
> return shell_exec("echo $input | $markdown_script");
|
291
|
+
|
292
|
+
Any decent text editor should make email-style quoting easy. For
|
293
|
+
example, with BBEdit, you can make a selection and choose Increase
|
294
|
+
Quote Level from the Text menu.
|
295
|
+
|
296
|
+
|
297
|
+
<h3 id="list">Lists</h3>
|
298
|
+
|
299
|
+
Markdown supports ordered (numbered) and unordered (bulleted) lists.
|
300
|
+
|
301
|
+
Unordered lists use asterisks, pluses, and hyphens -- interchangably
|
302
|
+
-- as list markers:
|
303
|
+
|
304
|
+
* Red
|
305
|
+
* Green
|
306
|
+
* Blue
|
307
|
+
|
308
|
+
is equivalent to:
|
309
|
+
|
310
|
+
+ Red
|
311
|
+
+ Green
|
312
|
+
+ Blue
|
313
|
+
|
314
|
+
and:
|
315
|
+
|
316
|
+
- Red
|
317
|
+
- Green
|
318
|
+
- Blue
|
319
|
+
|
320
|
+
Ordered lists use numbers followed by periods:
|
321
|
+
|
322
|
+
1. Bird
|
323
|
+
2. McHale
|
324
|
+
3. Parish
|
325
|
+
|
326
|
+
It's important to note that the actual numbers you use to mark the
|
327
|
+
list have no effect on the HTML output Markdown produces. The HTML
|
328
|
+
Markdown produces from the above list is:
|
329
|
+
|
330
|
+
<ol>
|
331
|
+
<li>Bird</li>
|
332
|
+
<li>McHale</li>
|
333
|
+
<li>Parish</li>
|
334
|
+
</ol>
|
335
|
+
|
336
|
+
If you instead wrote the list in Markdown like this:
|
337
|
+
|
338
|
+
1. Bird
|
339
|
+
1. McHale
|
340
|
+
1. Parish
|
341
|
+
|
342
|
+
or even:
|
343
|
+
|
344
|
+
3. Bird
|
345
|
+
1. McHale
|
346
|
+
8. Parish
|
347
|
+
|
348
|
+
you'd get the exact same HTML output. The point is, if you want to,
|
349
|
+
you can use ordinal numbers in your ordered Markdown lists, so that
|
350
|
+
the numbers in your source match the numbers in your published HTML.
|
351
|
+
But if you want to be lazy, you don't have to.
|
352
|
+
|
353
|
+
If you do use lazy list numbering, however, you should still start the
|
354
|
+
list with the number 1. At some point in the future, Markdown may support
|
355
|
+
starting ordered lists at an arbitrary number.
|
356
|
+
|
357
|
+
List markers typically start at the left margin, but may be indented by
|
358
|
+
up to three spaces. List markers must be followed by one or more spaces
|
359
|
+
or a tab.
|
360
|
+
|
361
|
+
To make lists look nice, you can wrap items with hanging indents:
|
362
|
+
|
363
|
+
* Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
|
364
|
+
Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
|
365
|
+
viverra nec, fringilla in, laoreet vitae, risus.
|
366
|
+
* Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
|
367
|
+
Suspendisse id sem consectetuer libero luctus adipiscing.
|
368
|
+
|
369
|
+
But if you want to be lazy, you don't have to:
|
370
|
+
|
371
|
+
* Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
|
372
|
+
Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
|
373
|
+
viverra nec, fringilla in, laoreet vitae, risus.
|
374
|
+
* Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
|
375
|
+
Suspendisse id sem consectetuer libero luctus adipiscing.
|
376
|
+
|
377
|
+
If list items are separated by blank lines, Markdown will wrap the
|
378
|
+
items in `<p>` tags in the HTML output. For example, this input:
|
379
|
+
|
380
|
+
* Bird
|
381
|
+
* Magic
|
382
|
+
|
383
|
+
will turn into:
|
384
|
+
|
385
|
+
<ul>
|
386
|
+
<li>Bird</li>
|
387
|
+
<li>Magic</li>
|
388
|
+
</ul>
|
389
|
+
|
390
|
+
But this:
|
391
|
+
|
392
|
+
* Bird
|
393
|
+
|
394
|
+
* Magic
|
395
|
+
|
396
|
+
will turn into:
|
397
|
+
|
398
|
+
<ul>
|
399
|
+
<li><p>Bird</p></li>
|
400
|
+
<li><p>Magic</p></li>
|
401
|
+
</ul>
|
402
|
+
|
403
|
+
List items may consist of multiple paragraphs. Each subsequent
|
404
|
+
paragraph in a list item must be intended by either 4 spaces
|
405
|
+
or one tab:
|
406
|
+
|
407
|
+
1. This is a list item with two paragraphs. Lorem ipsum dolor
|
408
|
+
sit amet, consectetuer adipiscing elit. Aliquam hendrerit
|
409
|
+
mi posuere lectus.
|
410
|
+
|
411
|
+
Vestibulum enim wisi, viverra nec, fringilla in, laoreet
|
412
|
+
vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
|
413
|
+
sit amet velit.
|
414
|
+
|
415
|
+
2. Suspendisse id sem consectetuer libero luctus adipiscing.
|
416
|
+
|
417
|
+
It looks nice if you indent every line of the subsequent
|
418
|
+
paragraphs, but here again, Markdown will allow you to be
|
419
|
+
lazy:
|
420
|
+
|
421
|
+
* This is a list item with two paragraphs.
|
422
|
+
|
423
|
+
This is the second paragraph in the list item. You're
|
424
|
+
only required to indent the first line. Lorem ipsum dolor
|
425
|
+
sit amet, consectetuer adipiscing elit.
|
426
|
+
|
427
|
+
* Another item in the same list.
|
428
|
+
|
429
|
+
To put a blockquote within a list item, the blockquote's `>`
|
430
|
+
delimiters need to be indented:
|
431
|
+
|
432
|
+
* A list item with a blockquote:
|
433
|
+
|
434
|
+
> This is a blockquote
|
435
|
+
> inside a list item.
|
436
|
+
|
437
|
+
To put a code block within a list item, the code block needs
|
438
|
+
to be indented *twice* -- 8 spaces or two tabs:
|
439
|
+
|
440
|
+
* A list item with a code block:
|
441
|
+
|
442
|
+
<code goes here>
|
443
|
+
|
444
|
+
|
445
|
+
It's worth noting that it's possible to trigger an ordered list by
|
446
|
+
accident, by writing something like this:
|
447
|
+
|
448
|
+
1986. What a great season.
|
449
|
+
|
450
|
+
In other words, a *number-period-space* sequence at the beginning of a
|
451
|
+
line. To avoid this, you can backslash-escape the period:
|
452
|
+
|
453
|
+
1986\. What a great season.
|
454
|
+
|
455
|
+
|
456
|
+
|
457
|
+
<h3 id="precode">Code Blocks</h3>
|
458
|
+
|
459
|
+
Pre-formatted code blocks are used for writing about programming or
|
460
|
+
markup source code. Rather than forming normal paragraphs, the lines
|
461
|
+
of a code block are interpreted literally. Markdown wraps a code block
|
462
|
+
in both `<pre>` and `<code>` tags.
|
463
|
+
|
464
|
+
To produce a code block in Markdown, simply indent every line of the
|
465
|
+
block by at least 4 spaces or 1 tab. For example, given this input:
|
466
|
+
|
467
|
+
This is a normal paragraph:
|
468
|
+
|
469
|
+
This is a code block.
|
470
|
+
|
471
|
+
Markdown will generate:
|
472
|
+
|
473
|
+
<p>This is a normal paragraph:</p>
|
474
|
+
|
475
|
+
<pre><code>This is a code block.
|
476
|
+
</code></pre>
|
477
|
+
|
478
|
+
One level of indentation -- 4 spaces or 1 tab -- is removed from each
|
479
|
+
line of the code block. For example, this:
|
480
|
+
|
481
|
+
Here is an example of AppleScript:
|
482
|
+
|
483
|
+
tell application "Foo"
|
484
|
+
beep
|
485
|
+
end tell
|
486
|
+
|
487
|
+
will turn into:
|
488
|
+
|
489
|
+
<p>Here is an example of AppleScript:</p>
|
490
|
+
|
491
|
+
<pre><code>tell application "Foo"
|
492
|
+
beep
|
493
|
+
end tell
|
494
|
+
</code></pre>
|
495
|
+
|
496
|
+
A code block continues until it reaches a line that is not indented
|
497
|
+
(or the end of the article).
|
498
|
+
|
499
|
+
Within a code block, ampersands (`&`) and angle brackets (`<` and `>`)
|
500
|
+
are automatically converted into HTML entities. This makes it very
|
501
|
+
easy to include example HTML source code using Markdown -- just paste
|
502
|
+
it and indent it, and Markdown will handle the hassle of encoding the
|
503
|
+
ampersands and angle brackets. For example, this:
|
504
|
+
|
505
|
+
<div class="footer">
|
506
|
+
© 2004 Foo Corporation
|
507
|
+
</div>
|
508
|
+
|
509
|
+
will turn into:
|
510
|
+
|
511
|
+
<pre><code><div class="footer">
|
512
|
+
&copy; 2004 Foo Corporation
|
513
|
+
</div>
|
514
|
+
</code></pre>
|
515
|
+
|
516
|
+
Regular Markdown syntax is not processed within code blocks. E.g.,
|
517
|
+
asterisks are just literal asterisks within a code block. This means
|
518
|
+
it's also easy to use Markdown to write about Markdown's own syntax.
|
519
|
+
|
520
|
+
|
521
|
+
|
522
|
+
<h3 id="hr">Horizontal Rules</h3>
|
523
|
+
|
524
|
+
You can produce a horizontal rule tag (`<hr />`) by placing three or
|
525
|
+
more hyphens, asterisks, or underscores on a line by themselves. If you
|
526
|
+
wish, you may use spaces between the hyphens or asterisks. Each of the
|
527
|
+
following lines will produce a horizontal rule:
|
528
|
+
|
529
|
+
* * *
|
530
|
+
|
531
|
+
***
|
532
|
+
|
533
|
+
*****
|
534
|
+
|
535
|
+
- - -
|
536
|
+
|
537
|
+
---------------------------------------
|
538
|
+
|
539
|
+
_ _ _
|
540
|
+
|
541
|
+
|
542
|
+
* * *
|
543
|
+
|
544
|
+
<h2 id="span">Span Elements</h2>
|
545
|
+
|
546
|
+
<h3 id="link">Links</h3>
|
547
|
+
|
548
|
+
Markdown supports two style of links: *inline* and *reference*.
|
549
|
+
|
550
|
+
In both styles, the link text is delimited by [square brackets].
|
551
|
+
|
552
|
+
To create an inline link, use a set of regular parentheses immediately
|
553
|
+
after the link text's closing square bracket. Inside the parentheses,
|
554
|
+
put the URL where you want the link to point, along with an *optional*
|
555
|
+
title for the link, surrounded in quotes. For example:
|
556
|
+
|
557
|
+
This is [an example](http://example.com/ "Title") inline link.
|
558
|
+
|
559
|
+
[This link](http://example.net/) has no title attribute.
|
560
|
+
|
561
|
+
Will produce:
|
562
|
+
|
563
|
+
<p>This is <a href="http://example.com/" title="Title">
|
564
|
+
an example</a> inline link.</p>
|
565
|
+
|
566
|
+
<p><a href="http://example.net/">This link</a> has no
|
567
|
+
title attribute.</p>
|
568
|
+
|
569
|
+
If you're referring to a local resource on the same server, you can
|
570
|
+
use relative paths:
|
571
|
+
|
572
|
+
See my [About](/about/) page for details.
|
573
|
+
|
574
|
+
Reference-style links use a second set of square brackets, inside
|
575
|
+
which you place a label of your choosing to identify the link:
|
576
|
+
|
577
|
+
This is [an example][id] reference-style link.
|
578
|
+
|
579
|
+
You can optionally use a space to separate the sets of brackets:
|
580
|
+
|
581
|
+
This is [an example] [id] reference-style link.
|
582
|
+
|
583
|
+
Then, anywhere in the document, you define your link label like this,
|
584
|
+
on a line by itself:
|
585
|
+
|
586
|
+
[id]: http://example.com/ "Optional Title Here"
|
587
|
+
|
588
|
+
That is:
|
589
|
+
|
590
|
+
* Square brackets containing the link identifier (optionally
|
591
|
+
indented from the left margin using up to three spaces);
|
592
|
+
* followed by a colon;
|
593
|
+
* followed by one or more spaces (or tabs);
|
594
|
+
* followed by the URL for the link;
|
595
|
+
* optionally followed by a title attribute for the link, enclosed
|
596
|
+
in double or single quotes.
|
597
|
+
|
598
|
+
The link URL may, optionally, be surrounded by angle brackets:
|
599
|
+
|
600
|
+
[id]: <http://example.com/> "Optional Title Here"
|
601
|
+
|
602
|
+
You can put the title attribute on the next line and use extra spaces
|
603
|
+
or tabs for padding, which tends to look better with longer URLs:
|
604
|
+
|
605
|
+
[id]: http://example.com/longish/path/to/resource/here
|
606
|
+
"Optional Title Here"
|
607
|
+
|
608
|
+
Link definitions are only used for creating links during Markdown
|
609
|
+
processing, and are stripped from your document in the HTML output.
|
610
|
+
|
611
|
+
Link definition names may constist of letters, numbers, spaces, and punctuation -- but they are *not* case sensitive. E.g. these two links:
|
612
|
+
|
613
|
+
[link text][a]
|
614
|
+
[link text][A]
|
615
|
+
|
616
|
+
are equivalent.
|
617
|
+
|
618
|
+
The *implicit link name* shortcut allows you to omit the name of the
|
619
|
+
link, in which case the link text itself is used as the name.
|
620
|
+
Just use an empty set of square brackets -- e.g., to link the word
|
621
|
+
"Google" to the google.com web site, you could simply write:
|
622
|
+
|
623
|
+
[Google][]
|
624
|
+
|
625
|
+
And then define the link:
|
626
|
+
|
627
|
+
[Google]: http://google.com/
|
628
|
+
|
629
|
+
Because link names may contain spaces, this shortcut even works for
|
630
|
+
multiple words in the link text:
|
631
|
+
|
632
|
+
Visit [Daring Fireball][] for more information.
|
633
|
+
|
634
|
+
And then define the link:
|
635
|
+
|
636
|
+
[Daring Fireball]: http://daringfireball.net/
|
637
|
+
|
638
|
+
Link definitions can be placed anywhere in your Markdown document. I
|
639
|
+
tend to put them immediately after each paragraph in which they're
|
640
|
+
used, but if you want, you can put them all at the end of your
|
641
|
+
document, sort of like footnotes.
|
642
|
+
|
643
|
+
Here's an example of reference links in action:
|
644
|
+
|
645
|
+
I get 10 times more traffic from [Google] [1] than from
|
646
|
+
[Yahoo] [2] or [MSN] [3].
|
647
|
+
|
648
|
+
[1]: http://google.com/ "Google"
|
649
|
+
[2]: http://search.yahoo.com/ "Yahoo Search"
|
650
|
+
[3]: http://search.msn.com/ "MSN Search"
|
651
|
+
|
652
|
+
Using the implicit link name shortcut, you could instead write:
|
653
|
+
|
654
|
+
I get 10 times more traffic from [Google][] than from
|
655
|
+
[Yahoo][] or [MSN][].
|
656
|
+
|
657
|
+
[google]: http://google.com/ "Google"
|
658
|
+
[yahoo]: http://search.yahoo.com/ "Yahoo Search"
|
659
|
+
[msn]: http://search.msn.com/ "MSN Search"
|
660
|
+
|
661
|
+
Both of the above examples will produce the following HTML output:
|
662
|
+
|
663
|
+
<p>I get 10 times more traffic from <a href="http://google.com/"
|
664
|
+
title="Google">Google</a> than from
|
665
|
+
<a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a>
|
666
|
+
or <a href="http://search.msn.com/" title="MSN Search">MSN</a>.</p>
|
667
|
+
|
668
|
+
For comparison, here is the same paragraph written using
|
669
|
+
Markdown's inline link style:
|
670
|
+
|
671
|
+
I get 10 times more traffic from [Google](http://google.com/ "Google")
|
672
|
+
than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
|
673
|
+
[MSN](http://search.msn.com/ "MSN Search").
|
674
|
+
|
675
|
+
The point of reference-style links is not that they're easier to
|
676
|
+
write. The point is that with reference-style links, your document
|
677
|
+
source is vastly more readable. Compare the above examples: using
|
678
|
+
reference-style links, the paragraph itself is only 81 characters
|
679
|
+
long; with inline-style links, it's 176 characters; and as raw HTML,
|
680
|
+
it's 234 characters. In the raw HTML, there's more markup than there
|
681
|
+
is text.
|
682
|
+
|
683
|
+
With Markdown's reference-style links, a source document much more
|
684
|
+
closely resembles the final output, as rendered in a browser. By
|
685
|
+
allowing you to move the markup-related metadata out of the paragraph,
|
686
|
+
you can add links without interrupting the narrative flow of your
|
687
|
+
prose.
|
688
|
+
|
689
|
+
|
690
|
+
<h3 id="em">Emphasis</h3>
|
691
|
+
|
692
|
+
Markdown treats asterisks (`*`) and underscores (`_`) as indicators of
|
693
|
+
emphasis. Text wrapped with one `*` or `_` will be wrapped with an
|
694
|
+
HTML `<em>` tag; double `*`'s or `_`'s will be wrapped with an HTML
|
695
|
+
`<strong>` tag. E.g., this input:
|
696
|
+
|
697
|
+
*single asterisks*
|
698
|
+
|
699
|
+
_single underscores_
|
700
|
+
|
701
|
+
**double asterisks**
|
702
|
+
|
703
|
+
__double underscores__
|
704
|
+
|
705
|
+
will produce:
|
706
|
+
|
707
|
+
<em>single asterisks</em>
|
708
|
+
|
709
|
+
<em>single underscores</em>
|
710
|
+
|
711
|
+
<strong>double asterisks</strong>
|
712
|
+
|
713
|
+
<strong>double underscores</strong>
|
714
|
+
|
715
|
+
You can use whichever style you prefer; the lone restriction is that
|
716
|
+
the same character must be used to open and close an emphasis span.
|
717
|
+
|
718
|
+
Emphasis can be used in the middle of a word:
|
719
|
+
|
720
|
+
un*fucking*believable
|
721
|
+
|
722
|
+
But if you surround an `*` or `_` with spaces, it'll be treated as a
|
723
|
+
literal asterisk or underscore.
|
724
|
+
|
725
|
+
To produce a literal asterisk or underscore at a position where it
|
726
|
+
would otherwise be used as an emphasis delimiter, you can backslash
|
727
|
+
escape it:
|
728
|
+
|
729
|
+
\*this text is surrounded by literal asterisks\*
|
730
|
+
|
731
|
+
|
732
|
+
|
733
|
+
<h3 id="code">Code</h3>
|
734
|
+
|
735
|
+
To indicate a span of code, wrap it with backtick quotes (`` ` ``).
|
736
|
+
Unlike a pre-formatted code block, a code span indicates code within a
|
737
|
+
normal paragraph. For example:
|
738
|
+
|
739
|
+
Use the `printf()` function.
|
740
|
+
|
741
|
+
will produce:
|
742
|
+
|
743
|
+
<p>Use the <code>printf()</code> function.</p>
|
744
|
+
|
745
|
+
To include a literal backtick character within a code span, you can use
|
746
|
+
multiple backticks as the opening and closing delimiters:
|
747
|
+
|
748
|
+
``There is a literal backtick (`) here.``
|
749
|
+
|
750
|
+
which will produce this:
|
751
|
+
|
752
|
+
<p><code>There is a literal backtick (`) here.</code></p>
|
753
|
+
|
754
|
+
The backtick delimiters surrounding a code span may include spaces --
|
755
|
+
one after the opening, one before the closing. This allows you to place
|
756
|
+
literal backtick characters at the beginning or end of a code span:
|
757
|
+
|
758
|
+
A single backtick in a code span: `` ` ``
|
759
|
+
|
760
|
+
A backtick-delimited string in a code span: `` `foo` ``
|
761
|
+
|
762
|
+
will produce:
|
763
|
+
|
764
|
+
<p>A single backtick in a code span: <code>`</code></p>
|
765
|
+
|
766
|
+
<p>A backtick-delimited string in a code span: <code>`foo`</code></p>
|
767
|
+
|
768
|
+
With a code span, ampersands and angle brackets are encoded as HTML
|
769
|
+
entities automatically, which makes it easy to include example HTML
|
770
|
+
tags. Markdown will turn this:
|
771
|
+
|
772
|
+
Please don't use any `<blink>` tags.
|
773
|
+
|
774
|
+
into:
|
775
|
+
|
776
|
+
<p>Please don't use any <code><blink></code> tags.</p>
|
777
|
+
|
778
|
+
You can write this:
|
779
|
+
|
780
|
+
`—` is the decimal-encoded equivalent of `—`.
|
781
|
+
|
782
|
+
to produce:
|
783
|
+
|
784
|
+
<p><code>&#8212;</code> is the decimal-encoded
|
785
|
+
equivalent of <code>&mdash;</code>.</p>
|
786
|
+
|
787
|
+
|
788
|
+
|
789
|
+
<h3 id="img">Images</h3>
|
790
|
+
|
791
|
+
Admittedly, it's fairly difficult to devise a "natural" syntax for
|
792
|
+
placing images into a plain text document format.
|
793
|
+
|
794
|
+
Markdown uses an image syntax that is intended to resemble the syntax
|
795
|
+
for links, allowing for two styles: *inline* and *reference*.
|
796
|
+
|
797
|
+
Inline image syntax looks like this:
|
798
|
+
|
799
|
+
![Alt text](/path/to/img.jpg)
|
800
|
+
|
801
|
+
![Alt text](/path/to/img.jpg "Optional title")
|
802
|
+
|
803
|
+
That is:
|
804
|
+
|
805
|
+
* An exclamation mark: `!`;
|
806
|
+
* followed by a set of square brackets, containing the `alt`
|
807
|
+
attribute text for the image;
|
808
|
+
* followed by a set of parentheses, containing the URL or path to
|
809
|
+
the image, and an optional `title` attribute enclosed in double
|
810
|
+
or single quotes.
|
811
|
+
|
812
|
+
Reference-style image syntax looks like this:
|
813
|
+
|
814
|
+
![Alt text][id]
|
815
|
+
|
816
|
+
Where "id" is the name of a defined image reference. Image references
|
817
|
+
are defined using syntax identical to link references:
|
818
|
+
|
819
|
+
[id]: url/to/image "Optional title attribute"
|
820
|
+
|
821
|
+
As of this writing, Markdown has no syntax for specifying the
|
822
|
+
dimensions of an image; if this is important to you, you can simply
|
823
|
+
use regular HTML `<img>` tags.
|
824
|
+
|
825
|
+
|
826
|
+
* * *
|
827
|
+
|
828
|
+
|
829
|
+
<h2 id="misc">Miscellaneous</h2>
|
830
|
+
|
831
|
+
<h3 id="autolink">Automatic Links</h3>
|
832
|
+
|
833
|
+
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:
|
834
|
+
|
835
|
+
<http://example.com/>
|
836
|
+
|
837
|
+
Markdown will turn this into:
|
838
|
+
|
839
|
+
<a href="http://example.com/">http://example.com/</a>
|
840
|
+
|
841
|
+
Automatic links for email addresses work similarly, except that
|
842
|
+
Markdown will also perform a bit of randomized decimal and hex
|
843
|
+
entity-encoding to help obscure your address from address-harvesting
|
844
|
+
spambots. For example, Markdown will turn this:
|
845
|
+
|
846
|
+
<address@example.com>
|
847
|
+
|
848
|
+
into something like this:
|
849
|
+
|
850
|
+
<a href="mailto:addre
|
851
|
+
ss@example.co
|
852
|
+
m">address@exa
|
853
|
+
mple.com</a>
|
854
|
+
|
855
|
+
which will render in a browser as a clickable link to "address@example.com".
|
856
|
+
|
857
|
+
(This sort of entity-encoding trick will indeed fool many, if not
|
858
|
+
most, address-harvesting bots, but it definitely won't fool all of
|
859
|
+
them. It's better than nothing, but an address published in this way
|
860
|
+
will probably eventually start receiving spam.)
|
861
|
+
|
862
|
+
|
863
|
+
|
864
|
+
<h3 id="backslash">Backslash Escapes</h3>
|
865
|
+
|
866
|
+
Markdown allows you to use backslash escapes to generate literal
|
867
|
+
characters which would otherwise have special meaning in Markdown's
|
868
|
+
formatting syntax. For example, if you wanted to surround a word with
|
869
|
+
literal asterisks (instead of an HTML `<em>` tag), you can backslashes
|
870
|
+
before the asterisks, like this:
|
871
|
+
|
872
|
+
\*literal asterisks\*
|
873
|
+
|
874
|
+
Markdown provides backslash escapes for the following characters:
|
875
|
+
|
876
|
+
\ backslash
|
877
|
+
` backtick
|
878
|
+
* asterisk
|
879
|
+
_ underscore
|
880
|
+
{} curly braces
|
881
|
+
[] square brackets
|
882
|
+
() parentheses
|
883
|
+
# hash mark
|
884
|
+
+ plus sign
|
885
|
+
- minus sign (hyphen)
|
886
|
+
. dot
|
887
|
+
! exclamation mark
|
888
|
+
|