mdl 0.7.0 → 0.8.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (148) hide show
  1. checksums.yaml +4 -4
  2. data/lib/mdl/doc.rb +1 -1
  3. data/lib/mdl/version.rb +1 -1
  4. data/mdl.gemspec +3 -3
  5. metadata +4 -266
  6. data/.github/ISSUE_TEMPLATE/BUG_TEMPLATE.md +0 -22
  7. data/.github/ISSUE_TEMPLATE/DESIGN_PROPOSAL.md +0 -40
  8. data/.github/ISSUE_TEMPLATE/ENHANCEMENT_REQUEST.md +0 -20
  9. data/.github/ISSUE_TEMPLATE/RULE_REQUEST.md +0 -20
  10. data/.github/PULL_REQUEST_TEMPLATE.md +0 -23
  11. data/.gitignore +0 -13
  12. data/.pre-commit-hooks.yaml +0 -6
  13. data/.travis.yml +0 -12
  14. data/CHANGELOG.md +0 -218
  15. data/CONTRIBUTING.md +0 -76
  16. data/MAINTAINERS.md +0 -21
  17. data/README.md +0 -87
  18. data/Rakefile +0 -8
  19. data/docs/RULES.md +0 -1089
  20. data/docs/configuration.md +0 -99
  21. data/docs/creating_rules.md +0 -90
  22. data/docs/creating_styles.md +0 -47
  23. data/docs/rolling_a_release.md +0 -51
  24. data/example/markdown_spec.md +0 -897
  25. data/test/fixtures/default_mdlrc +0 -1
  26. data/test/fixtures/dir_with_md_and_markdown/bar.markdown +0 -1
  27. data/test/fixtures/dir_with_md_and_markdown/foo.md +0 -1
  28. data/test/fixtures/front_matter/jekyll_post.md +0 -16
  29. data/test/fixtures/front_matter/jekyll_post_2.md +0 -17
  30. data/test/fixtures/mdlrc_disable_rules +0 -1
  31. data/test/fixtures/mdlrc_disable_tags +0 -1
  32. data/test/fixtures/mdlrc_enable_rules +0 -1
  33. data/test/fixtures/mdlrc_enable_tags +0 -1
  34. data/test/fixtures/my_ruleset.rb +0 -6
  35. data/test/rule_tests/alternate_top_level_header.md +0 -3
  36. data/test/rule_tests/alternate_top_level_header_style.rb +0 -4
  37. data/test/rule_tests/atx_closed_header_spacing.md +0 -17
  38. data/test/rule_tests/atx_header_spacing.md +0 -5
  39. data/test/rule_tests/blockquote_blank_lines.md +0 -31
  40. data/test/rule_tests/blockquote_spaces.md +0 -23
  41. data/test/rule_tests/bulleted_list_2_space_indent.md +0 -6
  42. data/test/rule_tests/bulleted_list_2_space_indent_style.rb +0 -3
  43. data/test/rule_tests/bulleted_list_4_space_indent.md +0 -3
  44. data/test/rule_tests/bulleted_list_not_at_beginning_of_line.md +0 -14
  45. data/test/rule_tests/code_block_consistency.md +0 -11
  46. data/test/rule_tests/code_block_consistency_style.rb +0 -1
  47. data/test/rule_tests/code_block_dollar.md +0 -33
  48. data/test/rule_tests/code_block_dollar_fence.md +0 -29
  49. data/test/rule_tests/code_block_fenced.md +0 -17
  50. data/test/rule_tests/code_block_fenced_style.rb +0 -1
  51. data/test/rule_tests/code_block_indented.md +0 -17
  52. data/test/rule_tests/code_block_indented_style.rb +0 -1
  53. data/test/rule_tests/consecutive_blank_lines.md +0 -11
  54. data/test/rule_tests/consistent_bullet_styles_asterisk.md +0 -3
  55. data/test/rule_tests/consistent_bullet_styles_dash.md +0 -3
  56. data/test/rule_tests/consistent_bullet_styles_plus.md +0 -3
  57. data/test/rule_tests/default_test_style.rb +0 -5
  58. data/test/rule_tests/emphasis_instead_of_headers.md +0 -42
  59. data/test/rule_tests/empty_doc.md +0 -0
  60. data/test/rule_tests/fenced_code_blocks.md +0 -27
  61. data/test/rule_tests/fenced_code_with_nesting.md +0 -73
  62. data/test/rule_tests/fenced_code_without_blank_lines.md +0 -42
  63. data/test/rule_tests/fenced_code_without_blank_lines_style.rb +0 -3
  64. data/test/rule_tests/first_header_bad_atx.md +0 -1
  65. data/test/rule_tests/first_header_bad_setext.md +0 -2
  66. data/test/rule_tests/first_header_good_atx.md +0 -1
  67. data/test/rule_tests/first_header_good_setext.md +0 -2
  68. data/test/rule_tests/first_line_top_level_header_atx.md +0 -3
  69. data/test/rule_tests/first_line_top_level_header_atx_style.rb +0 -2
  70. data/test/rule_tests/first_line_top_level_header_setext.md +0 -4
  71. data/test/rule_tests/first_line_top_level_header_setext_style.rb +0 -2
  72. data/test/rule_tests/fix_102_extra_nodes_in_link_text.md +0 -8
  73. data/test/rule_tests/header_duplicate_content.md +0 -11
  74. data/test/rule_tests/header_duplicate_content_different_nesting.md +0 -11
  75. data/test/rule_tests/header_duplicate_content_different_nesting_style.rb +0 -1
  76. data/test/rule_tests/header_duplicate_content_no_different_nesting.md +0 -13
  77. data/test/rule_tests/header_multiple_toplevel.md +0 -3
  78. data/test/rule_tests/header_mutliple_h1_no_toplevel.md +0 -5
  79. data/test/rule_tests/header_trailing_punctuation.md +0 -11
  80. data/test/rule_tests/header_trailing_punctuation_customized.md +0 -14
  81. data/test/rule_tests/header_trailing_punctuation_customized_style.rb +0 -2
  82. data/test/rule_tests/headers_bad.md +0 -7
  83. data/test/rule_tests/headers_good.md +0 -5
  84. data/test/rule_tests/headers_good_setext_with_atx.md +0 -7
  85. data/test/rule_tests/headers_good_setext_with_atx_style.rb +0 -2
  86. data/test/rule_tests/headers_good_with_issue_numbers.md +0 -12
  87. data/test/rule_tests/headers_surrounding_space_atx.md +0 -12
  88. data/test/rule_tests/headers_surrounding_space_setext.md +0 -15
  89. data/test/rule_tests/headers_with_spaces_at_the_beginning.md +0 -20
  90. data/test/rule_tests/hr_style_dashes.md +0 -22
  91. data/test/rule_tests/hr_style_dashes_style.rb +0 -3
  92. data/test/rule_tests/hr_style_inconsistent.md +0 -22
  93. data/test/rule_tests/hr_style_long.md +0 -22
  94. data/test/rule_tests/hr_style_long_style.rb +0 -3
  95. data/test/rule_tests/hr_style_stars.md +0 -22
  96. data/test/rule_tests/hr_style_stars_style.rb +0 -3
  97. data/test/rule_tests/inconsistent_bullet_indent_same_level.md +0 -4
  98. data/test/rule_tests/inconsistent_bullet_styles_asterisk.md +0 -3
  99. data/test/rule_tests/inconsistent_bullet_styles_dash.md +0 -3
  100. data/test/rule_tests/inconsistent_bullet_styles_plus.md +0 -3
  101. data/test/rule_tests/incorrect_bullet_style_asterisk.md +0 -3
  102. data/test/rule_tests/incorrect_bullet_style_asterisk_style.rb +0 -3
  103. data/test/rule_tests/incorrect_bullet_style_dash.md +0 -3
  104. data/test/rule_tests/incorrect_bullet_style_dash_style.rb +0 -3
  105. data/test/rule_tests/incorrect_bullet_style_plus.md +0 -3
  106. data/test/rule_tests/incorrect_bullet_style_plus_style.rb +0 -3
  107. data/test/rule_tests/incorrect_header_atx.md +0 -6
  108. data/test/rule_tests/incorrect_header_atx_closed.md +0 -6
  109. data/test/rule_tests/incorrect_header_atx_closed_style.rb +0 -2
  110. data/test/rule_tests/incorrect_header_atx_style.rb +0 -2
  111. data/test/rule_tests/incorrect_header_setext.md +0 -6
  112. data/test/rule_tests/incorrect_header_setext_style.rb +0 -2
  113. data/test/rule_tests/inline_html.md +0 -13
  114. data/test/rule_tests/links.md +0 -9
  115. data/test/rule_tests/lists_without_blank_lines.md +0 -75
  116. data/test/rule_tests/long_lines.md +0 -3
  117. data/test/rule_tests/long_lines_100.md +0 -7
  118. data/test/rule_tests/long_lines_100_style.rb +0 -3
  119. data/test/rule_tests/long_lines_code.md +0 -45
  120. data/test/rule_tests/long_lines_code_style.rb +0 -3
  121. data/test/rule_tests/mixed_header_types_atx.md +0 -6
  122. data/test/rule_tests/mixed_header_types_atx_closed.md +0 -6
  123. data/test/rule_tests/mixed_header_types_setext.md +0 -6
  124. data/test/rule_tests/no_first_line_header.md +0 -1
  125. data/test/rule_tests/no_first_line_header_style.rb +0 -1
  126. data/test/rule_tests/no_first_line_top_level_header.md +0 -1
  127. data/test/rule_tests/no_first_line_top_level_header_style.rb +0 -1
  128. data/test/rule_tests/ordered_list_item_prefix.md +0 -13
  129. data/test/rule_tests/ordered_list_item_prefix_ordered.md +0 -13
  130. data/test/rule_tests/ordered_list_item_prefix_ordered_style.rb +0 -3
  131. data/test/rule_tests/reversed_link.md +0 -7
  132. data/test/rule_tests/spaces_after_list_marker.md +0 -74
  133. data/test/rule_tests/spaces_after_list_marker_style.rb +0 -5
  134. data/test/rule_tests/spaces_inside_codespan_elements.md +0 -7
  135. data/test/rule_tests/spaces_inside_emphasis_markers.md +0 -35
  136. data/test/rule_tests/spaces_inside_link_text.md +0 -28
  137. data/test/rule_tests/trailing_spaces_br.md +0 -4
  138. data/test/rule_tests/trailing_spaces_br_style.rb +0 -3
  139. data/test/rule_tests/whitespace_issues.md +0 -3
  140. data/test/setup_tests.rb +0 -5
  141. data/test/test_cli.rb +0 -301
  142. data/test/test_ruledocs.rb +0 -52
  143. data/test/test_rules.rb +0 -58
  144. data/tools/README.md +0 -3
  145. data/tools/docker/Dockerfile +0 -13
  146. data/tools/docker/README.md +0 -19
  147. data/tools/test_location.rb +0 -20
  148. data/tools/view_markdown.rb +0 -11
@@ -1,99 +0,0 @@
1
- # Mdl configuration
2
-
3
- Markdownlint has several options you can configure both on the command line,
4
- or in markdownlint's configuration file: `.mdlrc`, first looked for in the
5
- working directory, then in your home directory.
6
- While markdownlint will work perfectly well out of the box, this page
7
- documents some of the options you can change to suit your needs.
8
-
9
- In general, anything you pass on the command line can also be put into
10
- `~/.mdlrc` with the same option. For example, if you pass `--style foo` on the
11
- command line, you can make this the default by putting `style "foo"` into your
12
- `~/.mdlrc` file.
13
-
14
- ## Configuration options
15
-
16
- ### General options
17
-
18
- Verbose - Print additional information about what markdownlint is doing.
19
-
20
- * Command line: `-v`, `--verbose`
21
- * Config file: `verbose true`
22
- * Default: false
23
-
24
- Show warnings - Kramdown will generate warnings of its own for some issues
25
- found with documents during parsing, and markdownlint can print these out in
26
- addition to using the built in rules. This option enables/disables that
27
- behavior.
28
-
29
- * Command line: `-w`, `--warnings`
30
- * Config file: `show_kramdown_warnings true`
31
- * Default: true
32
-
33
- Recurse using files known to git - When mdl is given a directory name on the
34
- command line, it will recurse into that directory looking for markdown files
35
- to process. If this option is enabled, it will use git to look for files
36
- instead, and ignore any files git doesn't know about.
37
-
38
- * Command line: `-g`, `--git-recurse`
39
- * Config file: `git_recurse true`
40
- * Default: false
41
-
42
- Ignore YAML front matter - If this option is enabled markdownlint will ignore
43
- content within valid
44
- [YAML front matter](https://jekyllrb.com/docs/frontmatter/). Reported line
45
- numbers will still match the file contents but markdownlint will consider the
46
- line following front matter to be the first line.
47
-
48
- * Command line: `-i`, `--ignore-front-matter`
49
- * Config file: `ignore_front_matter true`
50
- * Default: false
51
-
52
- ### Specifying which rules mdl processes
53
-
54
- Tags - Limit the rules mdl enables to those containing the provided tags.
55
-
56
- * Command line: `-t tag1,tag2`, `--tags tag1,tag2`, `-t ~tag1,~tag2`
57
- * Config file: `tags "tag1", "tag2"`
58
- * Default: process all rules (no tag limit)
59
-
60
- Rules - Limit the rules mdl enables to those provided in this option.
61
-
62
- * Command line: `-r MD001,MD002`, `--rules MD001,MD002`, `-r ~MD001,~MD002`
63
- * Config file: `rules "MD001", "MD002"`
64
- * Default: process all rules (no rule limit)
65
-
66
- If a rule or tag ID is preceded by a tilde (`~`), then it _disables_ the
67
- matching rules instead of enabling them, starting with all rules being enabled.
68
-
69
- Note: If both `--rules` and `--tags` are provided, then a given rule has to
70
- both be in the list of enabled rules, as well as be tagged with one of the
71
- tags provided with the `--tags` option. Use the `-l/--list-rules` option to
72
- test this behavior.
73
-
74
- Style - Select which style mdl uses. A 'style' is a file containing a list of
75
- enabled/disable rules, as well as options for some rules that take them. For
76
- example, one style might enforce a line length of 80 characters, while another
77
- might choose 72 characters, and another might have no line length limit at all
78
- (rule MD013).
79
-
80
- * Command line: `-s style_name`, `--style style_name`
81
- * Config file: `style "style_name"`
82
- * Default: Use the style called 'default'
83
-
84
- Note: The value for `style_name` must either end with `.rb` or have `/` in it
85
- in order to tell `mdl` to look for a custom style, and not a built-in style.
86
-
87
- Rulesets - Load a custom ruleset file. This option allows you to load custom
88
- rules in addition to those included with markdownlint.
89
-
90
- * Command line: `-u ruleset.rb,ruleset2.rb`, `--rules ruleset.rb,ruleset2.rb`
91
- * Config file: `rulesets 'ruleset.rb', 'ruleset2.rb'`
92
- * Default: Don't load any additional rulesets
93
-
94
- No default ruleset - Skip loading the default ruleset file included with
95
- markdownlint. Use this option if you only want to load custom rulesets.
96
-
97
- * Command line: `-d`, `--skip-default-ruleset`
98
- * Config file: `skip_default_ruleset true`
99
- * Default: Load the default ruleset.
@@ -1,90 +0,0 @@
1
- # Creating Rules
2
-
3
- Rules are written in ruby, using a rule DSL for defining rules. A rule looks
4
- like:
5
-
6
- rule "MY000", "Rule description" do
7
- tags :foo, :bar
8
- aliases 'rule-name'
9
- params :style => :foo
10
- check do |doc|
11
- # check code goes here
12
- # return a list of line numbers that break the rule, or an empty list
13
- # (or nil) if there are no problems.
14
- end
15
- end
16
-
17
- The first line specifies the rule name and description. By convention, built
18
- in markdownlint rules use the prefix 'MD' followed by a number to identify
19
- rules. Any custom rules should use an alternate prefix to avoid conflicting
20
- with current or future rules. The description is simply a short description
21
- explaining what the rule is checking, which will be printed alongside the rule
22
- name when rules are triggered.
23
-
24
- Next, the rule's tags are specified. These are simply ruby symbols, and can be
25
- used by a user to limit which rules are checks. For example, if your rule
26
- checks whitespace usage in a document, you can add the `:whitespace` tag, and
27
- users who don't care about whitespace can exclude that tag on the command line
28
- or in style files.
29
-
30
- You can also specify aliases for the rule, which can be used to refer to the
31
- rule with a human-readable name rather than MD000. To do this, add then with
32
- the 'aliases' directive. Whenever you refer to a rule, such as for
33
- including/excluding in the configuration or in style files, you can use an
34
- alias for the rule instead of its ID.
35
-
36
- After that, any parameters the rule takes are specified. If your rule checks
37
- for a specific number of things, or if you can envision multiple variants of
38
- the same rule, then you should add parameters to allow your rule to be
39
- customized in a style file. Any parameters specified here are accessible
40
- inside the check itself using `params[:foo]`.
41
-
42
- Finally, the check itself is specified. This is simply a ruby block that
43
- should return a list of line numbers for any issues found. If no line numbers
44
- are found, you can either return an empty list, or nil, whichever is easiest
45
- for your check.
46
-
47
- ## Document objects
48
-
49
- The check takes a single parameter `doc`, which is an object containing a
50
- representation of the markdown document along with several helper functions
51
- used for making rules. The [doc.rb](../lib/mdl/doc.rb) file is documented
52
- using rdoc, and you will want to take a look there to see all the methods you
53
- can use, as well as look at some of the existing rules, but a quick summary is
54
- as follows:
55
-
56
- * `doc` - Object containing a representation of the markdown document
57
- * `doc.lines` - The raw markdown file as an array of lines
58
- * You can also look up a line given an element with
59
- `doc.element_line(element)`
60
- * `doc.parsed` - The kramdown internal representation of the doc. Most of the
61
- time you will want to interact with the parsed version of the document
62
- rather than looking at `doc.lines`.
63
- * `doc.find_type_elements` - A method to find all elements of a given type.
64
- You pass the type as a symbol, such as `:ul` or `:p`. Most element types
65
- match the name of the element in HTML output. This method returns a list of
66
- the matching elements.
67
- * `doc.find_type` - This is like `doc.find_type_elements`, but returns just
68
- the options hashes (see below) for each element. This is useful if you don't
69
- need all the element information, but you do need the line numbers.
70
- * `doc.element_line_number` - Pass in an element (or an options hash), and
71
- this will return the line number for the element. You need to return the
72
- line number in the list of errors.
73
-
74
- ## Element objects
75
-
76
- The document contains an internal representation of the markdown document as
77
- parsed by kramdown. Kramdown's representation of the document is as a tree of
78
- 'element' objects. The following is a quick summary of those objects:
79
-
80
- * element.type - a symbol denoting the type of the element, such as `:li`,
81
- `:p`, `:text`
82
- * element.value - the value of the element. Note that most block level
83
- elements such as paragraphs don't have any value themselves, but have child
84
- text elements containing their contents instead.
85
- * element.children - A list of the element's child elements.
86
- * element.options - A hash containing:
87
- * `:location` - line number of element
88
- * `:element_level` - A value filled in by markdownlint to denote the nesting
89
- level of the element, i.e. how deep in the tree is it.
90
- * Other options that are element type specific.
@@ -1,47 +0,0 @@
1
- # Creating styles
2
-
3
- A 'style' in markdownlint is simply a ruby file specifying the list of enabled
4
- and disabled rules, as well as specifying parameters for any rules that need
5
- parameters different than the defaults.
6
-
7
- The various options you can use in a style file are:
8
-
9
- * `all` - include all rules
10
- * `rule` - include a specific rule.
11
-
12
- rule 'MD001'
13
-
14
- * `exclude_rule` - exclude a previously included rule. Used if you want to
15
- include all except for a few rules.
16
-
17
- exclude_rule 'MD000'
18
-
19
- * `tag` - include all rules that are tagged with a specific value
20
-
21
- tag :whitespace
22
-
23
- * `exclude_tag` - exclude all rules tagged with the specified tag
24
-
25
- exclude_tag :line_length
26
-
27
- Note that tags are specified as symbols, and rule names as strings, just as
28
- in the rule definitions themselves.
29
-
30
- The last matching option wins, so you should always put `all` at the top of
31
- the file (if you want to include all rules), then tags (and tag excludes),
32
- then specific rules. In other words, go from least to most specific.
33
-
34
- ## Parameters
35
-
36
- If you specify any parameters after a rule ID, then those values will be used
37
- for the rules instead of the default. You only need to specify parameters for
38
- any values you wish to override. For example, the default values for the
39
- parameters in MD030 (spaces after list markers) are all 1. If you still want
40
- the spaces after the list markers to be 1 in some cases, then you can exclude
41
- those parameters:
42
-
43
- rule 'MD030', :ol_multi => 2, :ul_multi => 3
44
-
45
- Even if a rule is included already by a tag specification (or `all`), it is
46
- not a problem to add a specific `rule` entry in order to set custom
47
- parameters, and is in fact necessary to do so.
@@ -1,51 +0,0 @@
1
- # Rolling a new release
2
-
3
- Bump the version. Markdownlint uses semantic versioning. From
4
- <http://semver.org/>:
5
-
6
- * Major version for backwards-incompatible changes
7
- * Minor version for functionality added in a backwards-compatible manner
8
- * Patch version for backwards-compatible bug fixes
9
- * Exception: Versions < 1.0 may introduce backwards-incompatible changes in a
10
- minor version.
11
-
12
- To bump the version, edit `lib/mdl/version.rb` and commit to the master
13
- branch.
14
-
15
- Update the changelog:
16
-
17
- * Add a new header and link for the new release, replacing any 'Unreleased'
18
- header.
19
-
20
- ## [v0.2.0] (2015-04-13)
21
-
22
- This goes at the bottom:
23
-
24
- [v0.2.0]: https://github.com/markdownlint/markdownlint/tree/v0.2.0
25
-
26
- * Changelog entries can and should be added in an 'Unreleased' section as
27
- commits are made. However, the following steps can be performed before each
28
- release to catch anything that was missed.
29
- * Add a 'Rules added' section, listing every new rule added for this version.
30
- * Use `git diff v0.1.0..v0.2.0 docs/RULES.md | grep '## MD'` to discover
31
- what these are.
32
- * Search for closed issues:
33
- * Go to <https://github.com/markdownlint/markdownlint/issues>
34
- * Search for `closed:>1900-01-01`, changing the date to the date
35
- of the last release.
36
- * From this list of issues, make sections for:
37
- * Added - for new features
38
- * Changed - for changes in existing functionality
39
- * Deprecated - for once-stable features removed in upcoming releases
40
- * Removed - for deprecated features removed in this release
41
- * Fixed - for any bug fixes
42
- * Security - for any security issues
43
-
44
- Next, run `rake release`. This will:
45
-
46
- * Tag vX.Y.Z in git
47
- * Upload the new gem to rubygems.org
48
-
49
- Then `git push --tags upstream` to push the tag.
50
-
51
- Finally, add a new 'Unreleased' section to the changelog for the next release.
@@ -1,897 +0,0 @@
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. `&lt;`, and
128
- `&amp;`.
129
-
130
- Ampersands in particular are bedeviling for web writers. If you want to
131
- write about 'AT&T', you need to write '`AT&amp;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&amp;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 `&amp;`.
148
-
149
- So, if you want to include a copyright symbol in your article, you can write:
150
-
151
- &copy;
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&amp;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 &lt; 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 indented 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 indented 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
- &copy; 2004 Foo Corporation
507
- </div>
508
-
509
- will turn into:
510
-
511
- <pre><code>&lt;div class="footer"&gt;
512
- &amp;copy; 2004 Foo Corporation
513
- &lt;/div&gt;
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
- <h2 id="span">Span Elements</h2>
543
-
544
- <h3 id="link">Links</h3>
545
-
546
- Markdown supports two style of links: *inline* and *reference*.
547
-
548
- In both styles, the link text is delimited by [square brackets].
549
-
550
- To create an inline link, use a set of regular parentheses immediately
551
- after the link text's closing square bracket. Inside the parentheses,
552
- put the URL where you want the link to point, along with an *optional*
553
- title for the link, surrounded in quotes. For example:
554
-
555
- This is [an example](http://example.com/ "Title") inline link.
556
-
557
- [This link](http://example.net/) has no title attribute.
558
-
559
- Will produce:
560
-
561
- <p>This is <a href="http://example.com/" title="Title">
562
- an example</a> inline link.</p>
563
-
564
- <p><a href="http://example.net/">This link</a> has no
565
- title attribute.</p>
566
-
567
- If you're referring to a local resource on the same server, you can
568
- use relative paths:
569
-
570
- See my [About](/about/) page for details.
571
-
572
- Reference-style links use a second set of square brackets, inside
573
- which you place a label of your choosing to identify the link:
574
-
575
- This is [an example][id] reference-style link.
576
-
577
- You can optionally use a space to separate the sets of brackets:
578
-
579
- This is [an example] [id] reference-style link.
580
-
581
- Then, anywhere in the document, you define your link label like this,
582
- on a line by itself:
583
-
584
- [id]: http://example.com/ "Optional Title Here"
585
-
586
- That is:
587
-
588
- * Square brackets containing the link identifier (optionally
589
- indented from the left margin using up to three spaces);
590
- * followed by a colon;
591
- * followed by one or more spaces (or tabs);
592
- * followed by the URL for the link;
593
- * optionally followed by a title attribute for the link, enclosed
594
- in double or single quotes, or enclosed in parentheses.
595
-
596
- The following three link definitions are equivalent:
597
-
598
- [foo]: http://example.com/ "Optional Title Here"
599
- [foo]: http://example.com/ 'Optional Title Here'
600
- [foo]: http://example.com/ (Optional Title Here)
601
-
602
- **Note:** There is a known bug in Markdown.pl 1.0.1 which prevents
603
- single quotes from being used to delimit link titles.
604
-
605
- The link URL may, optionally, be surrounded by angle brackets:
606
-
607
- [id]: <http://example.com/> "Optional Title Here"
608
-
609
- You can put the title attribute on the next line and use extra spaces
610
- or tabs for padding, which tends to look better with longer URLs:
611
-
612
- [id]: http://example.com/longish/path/to/resource/here
613
- "Optional Title Here"
614
-
615
- Link definitions are only used for creating links during Markdown
616
- processing, and are stripped from your document in the HTML output.
617
-
618
- Link definition names may consist of letters, numbers, spaces, and
619
- punctuation -- but they are *not* case sensitive. E.g. these two
620
- links:
621
-
622
- [link text][a]
623
- [link text][A]
624
-
625
- are equivalent.
626
-
627
- The *implicit link name* shortcut allows you to omit the name of the
628
- link, in which case the link text itself is used as the name.
629
- Just use an empty set of square brackets -- e.g., to link the word
630
- "Google" to the google.com web site, you could simply write:
631
-
632
- [Google][]
633
-
634
- And then define the link:
635
-
636
- [Google]: http://google.com/
637
-
638
- Because link names may contain spaces, this shortcut even works for
639
- multiple words in the link text:
640
-
641
- Visit [Daring Fireball][] for more information.
642
-
643
- And then define the link:
644
-
645
- [Daring Fireball]: http://daringfireball.net/
646
-
647
- Link definitions can be placed anywhere in your Markdown document. I
648
- tend to put them immediately after each paragraph in which they're
649
- used, but if you want, you can put them all at the end of your
650
- document, sort of like footnotes.
651
-
652
- Here's an example of reference links in action:
653
-
654
- I get 10 times more traffic from [Google] [1] than from
655
- [Yahoo] [2] or [MSN] [3].
656
-
657
- [1]: http://google.com/ "Google"
658
- [2]: http://search.yahoo.com/ "Yahoo Search"
659
- [3]: http://search.msn.com/ "MSN Search"
660
-
661
- Using the implicit link name shortcut, you could instead write:
662
-
663
- I get 10 times more traffic from [Google][] than from
664
- [Yahoo][] or [MSN][].
665
-
666
- [google]: http://google.com/ "Google"
667
- [yahoo]: http://search.yahoo.com/ "Yahoo Search"
668
- [msn]: http://search.msn.com/ "MSN Search"
669
-
670
- Both of the above examples will produce the following HTML output:
671
-
672
- <p>I get 10 times more traffic from <a href="http://google.com/"
673
- title="Google">Google</a> than from
674
- <a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a>
675
- or <a href="http://search.msn.com/" title="MSN Search">MSN</a>.</p>
676
-
677
- For comparison, here is the same paragraph written using
678
- Markdown's inline link style:
679
-
680
- I get 10 times more traffic from [Google](http://google.com/ "Google")
681
- than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
682
- [MSN](http://search.msn.com/ "MSN Search").
683
-
684
- The point of reference-style links is not that they're easier to
685
- write. The point is that with reference-style links, your document
686
- source is vastly more readable. Compare the above examples: using
687
- reference-style links, the paragraph itself is only 81 characters
688
- long; with inline-style links, it's 176 characters; and as raw HTML,
689
- it's 234 characters. In the raw HTML, there's more markup than there
690
- is text.
691
-
692
- With Markdown's reference-style links, a source document much more
693
- closely resembles the final output, as rendered in a browser. By
694
- allowing you to move the markup-related metadata out of the paragraph,
695
- you can add links without interrupting the narrative flow of your
696
- prose.
697
-
698
-
699
- <h3 id="em">Emphasis</h3>
700
-
701
- Markdown treats asterisks (`*`) and underscores (`_`) as indicators of
702
- emphasis. Text wrapped with one `*` or `_` will be wrapped with an
703
- HTML `<em>` tag; double `*`'s or `_`'s will be wrapped with an HTML
704
- `<strong>` tag. E.g., this input:
705
-
706
- *single asterisks*
707
-
708
- _single underscores_
709
-
710
- **double asterisks**
711
-
712
- __double underscores__
713
-
714
- will produce:
715
-
716
- <em>single asterisks</em>
717
-
718
- <em>single underscores</em>
719
-
720
- <strong>double asterisks</strong>
721
-
722
- <strong>double underscores</strong>
723
-
724
- You can use whichever style you prefer; the lone restriction is that
725
- the same character must be used to open and close an emphasis span.
726
-
727
- Emphasis can be used in the middle of a word:
728
-
729
- un*frigging*believable
730
-
731
- But if you surround an `*` or `_` with spaces, it'll be treated as a
732
- literal asterisk or underscore.
733
-
734
- To produce a literal asterisk or underscore at a position where it
735
- would otherwise be used as an emphasis delimiter, you can backslash
736
- escape it:
737
-
738
- \*this text is surrounded by literal asterisks\*
739
-
740
-
741
-
742
- <h3 id="code">Code</h3>
743
-
744
- To indicate a span of code, wrap it with backtick quotes (`` ` ``).
745
- Unlike a pre-formatted code block, a code span indicates code within a
746
- normal paragraph. For example:
747
-
748
- Use the `printf()` function.
749
-
750
- will produce:
751
-
752
- <p>Use the <code>printf()</code> function.</p>
753
-
754
- To include a literal backtick character within a code span, you can use
755
- multiple backticks as the opening and closing delimiters:
756
-
757
- ``There is a literal backtick (`) here.``
758
-
759
- which will produce this:
760
-
761
- <p><code>There is a literal backtick (`) here.</code></p>
762
-
763
- The backtick delimiters surrounding a code span may include spaces --
764
- one after the opening, one before the closing. This allows you to place
765
- literal backtick characters at the beginning or end of a code span:
766
-
767
- A single backtick in a code span: `` ` ``
768
-
769
- A backtick-delimited string in a code span: `` `foo` ``
770
-
771
- will produce:
772
-
773
- <p>A single backtick in a code span: <code>`</code></p>
774
-
775
- <p>A backtick-delimited string in a code span: <code>`foo`</code></p>
776
-
777
- With a code span, ampersands and angle brackets are encoded as HTML
778
- entities automatically, which makes it easy to include example HTML
779
- tags. Markdown will turn this:
780
-
781
- Please don't use any `<blink>` tags.
782
-
783
- into:
784
-
785
- <p>Please don't use any <code>&lt;blink&gt;</code> tags.</p>
786
-
787
- You can write this:
788
-
789
- `&#8212;` is the decimal-encoded equivalent of `&mdash;`.
790
-
791
- to produce:
792
-
793
- <p><code>&amp;#8212;</code> is the decimal-encoded
794
- equivalent of <code>&amp;mdash;</code>.</p>
795
-
796
-
797
-
798
- <h3 id="img">Images</h3>
799
-
800
- Admittedly, it's fairly difficult to devise a "natural" syntax for
801
- placing images into a plain text document format.
802
-
803
- Markdown uses an image syntax that is intended to resemble the syntax
804
- for links, allowing for two styles: *inline* and *reference*.
805
-
806
- Inline image syntax looks like this:
807
-
808
- ![Alt text](/path/to/img.jpg)
809
-
810
- ![Alt text](/path/to/img.jpg "Optional title")
811
-
812
- That is:
813
-
814
- * An exclamation mark: `!`;
815
- * followed by a set of square brackets, containing the `alt`
816
- attribute text for the image;
817
- * followed by a set of parentheses, containing the URL or path to
818
- the image, and an optional `title` attribute enclosed in double
819
- or single quotes.
820
-
821
- Reference-style image syntax looks like this:
822
-
823
- ![Alt text][id]
824
-
825
- Where "id" is the name of a defined image reference. Image references
826
- are defined using syntax identical to link references:
827
-
828
- [id]: url/to/image "Optional title attribute"
829
-
830
- As of this writing, Markdown has no syntax for specifying the
831
- dimensions of an image; if this is important to you, you can simply
832
- use regular HTML `<img>` tags.
833
-
834
-
835
- * * *
836
-
837
-
838
- <h2 id="misc">Miscellaneous</h2>
839
-
840
- <h3 id="autolink">Automatic Links</h3>
841
-
842
- 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:
843
-
844
- <http://example.com/>
845
-
846
- Markdown will turn this into:
847
-
848
- <a href="http://example.com/">http://example.com/</a>
849
-
850
- Automatic links for email addresses work similarly, except that
851
- Markdown will also perform a bit of randomized decimal and hex
852
- entity-encoding to help obscure your address from address-harvesting
853
- spambots. For example, Markdown will turn this:
854
-
855
- <address@example.com>
856
-
857
- into something like this:
858
-
859
- <a href="&#x6D;&#x61;i&#x6C;&#x74;&#x6F;:&#x61;&#x64;&#x64;&#x72;&#x65;
860
- &#115;&#115;&#64;&#101;&#120;&#x61;&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;
861
- &#109;">&#x61;&#x64;&#x64;&#x72;&#x65;&#115;&#115;&#64;&#101;&#120;&#x61;
862
- &#109;&#x70;&#x6C;e&#x2E;&#99;&#111;&#109;</a>
863
-
864
- which will render in a browser as a clickable link to "address@example.com".
865
-
866
- (This sort of entity-encoding trick will indeed fool many, if not
867
- most, address-harvesting bots, but it definitely won't fool all of
868
- them. It's better than nothing, but an address published in this way
869
- will probably eventually start receiving spam.)
870
-
871
-
872
-
873
- <h3 id="backslash">Backslash Escapes</h3>
874
-
875
- Markdown allows you to use backslash escapes to generate literal
876
- characters which would otherwise have special meaning in Markdown's
877
- formatting syntax. For example, if you wanted to surround a word
878
- with literal asterisks (instead of an HTML `<em>` tag), you can use
879
- backslashes before the asterisks, like this:
880
-
881
- \*literal asterisks\*
882
-
883
- Markdown provides backslash escapes for the following characters:
884
-
885
- \ backslash
886
- ` backtick
887
- * asterisk
888
- _ underscore
889
- {} curly braces
890
- [] square brackets
891
- () parentheses
892
- # hash mark
893
- + plus sign
894
- - minus sign (hyphen)
895
- . dot
896
- ! exclamation mark
897
-