├── Han └── han.min.css ├── Makefile ├── Markdown_1.0.1 ├── License.text ├── Markdown Readme.text └── Markdown.pl ├── README.md ├── basic.html ├── basic_content.html ├── basics.md ├── basics.text ├── content.html ├── deploy.sh ├── footer.html ├── header.html ├── index.html ├── makrdown.html ├── stylesheets └── main.css ├── syntax.md └── syntax.text /Han/han.min.css: -------------------------------------------------------------------------------- 1 | @charset "utf-8"; 2 | 3 | /* 漢字標準格式 4 | * Han, the CSS Reset 5 | * 6 | * Version: 1.1 7 | * Lisence: MIT Lisence 8 | * Last-Modified: 2011/05/11 9 | */ 10 | 11 | 12 | 13 | /* setting fonts manually */ 14 | /*@font-face { font-family: ff-zhuyin; src: url(../fonts/zhuyin.eot) /* for MsIE */; } 15 | /*@font-face{ font-family: ff-zhuyin; src: url(../fonts/zhuyin.ttf); } 16 | /* 上述注音符號字體出自教育部標準楷書之注音字符,採創用CC 「姓名標示—禁止改作—3.0台灣版」授權。 */ 17 | 18 | @font-face { font-family: ff-cursive-han; src: local(STFangsong), local(STKaiti), local(Kai), local(DFKaiShu-SB-Estd-BF); } 19 | @font-face { font-family: ff-latin-serif-italic; src: local("Times New Roman Italic"), local("TimesNewRomanPS-ItalicMT"), local("Times-Italic"); } 20 | @font-face { font-family: ff-latin-sans-italic; src: local("Helvetica Oblique"), local("Helvetica-LightOblique"), local("Arial Italic"), local("Arial-ItalicMT"); } 21 | 22 | html,body,div,span,object,iframe,h1,h2,h3,h4,h5,h6,p,blockquote,pre,a,abbr,address,cite,code,del,dfn,em,img,ins,kbd,q,s,samp,small,strong,tt,var,b,u,i,dl,dt,dd,ol,ul,li,fieldset,form,label,legend{background:transparent;border:0;vertical-align:baseline;}html,body,div,span,object,iframe,blockquote,pre,a,abbr,address,cite,code,del,dfn,em,img,ins,kbd,q,s,samp,small,strong,sub,sup,tt,var,b,u,i,fieldset,form,label,legend,table,caption,tbody,tfoot,thead,tr,th,td{margin:0;padding:0;}body{line-height:1;}h1,h2,h3,h4,h5,h6{clear:both;font-weight:bold;}h1{margin:.67em 0;}h2{margin:.83em 0;}h4{margin:1.33em 0;}h5{margin:1.67em 0;}h6{margin:2.33em 0;}ol,ul{padding-left:2em;}sup{vertical-align:super;font-size:smaller;}sub{vertical-align:sub;font-size:smaller;}blockquote{quotes:none;}blockquote:before,blockquote:after{content:none;}table{border-collapse:collapse;border-spacing:0;}a img{border:none;}abbr[title],span[title]{border-bottom:1px dotted;}del{text-decoration:line-through;}pre code{display:block;overflow:auto;}html:lang(zh) a:link,html:lang(zh) a:visited,html:lang(zh) a:hover,html:lang(zh) a:active,html:lang(zh) ins{text-decoration:inherit;}html:lang(zh) ins{border-bottom:3px double lightgray;}u:lang(zh){letter-spacing:0;}u + u{margin-left:.125em;}b.pn{font-weight:inherit;}b.pn:lang(zh){border-bottom:1px solid;padding-bottom:-.05em;text-decoration:none;}b.pn:lang(zh-latn){border:inherit;}b.pn:lang(zh) + b.pn:lang(zh){margin-left:.1em;}article p,article li{line-height:2;}article:lang(zh) p:before,article:lang(ja) p:before{content:"  ";font-style:normal;font-weight:normal;text-decoration:none;}article:lang(ja) p:before{content:" ";}article:lang(zh) p.poem-like,article:lang(zh).poem-like p,blockquote:lang(zh).poem-like p,article:lang(ja) p.poem-like,article:lang(ja).poem-like p,blockquote:lang(ja).poem-like p{margin-left:2em;}cite:lang(zh),cite:lang(ja),cite:lang(en).piece{font-style:inherit;}cite:lang(zh):before,cite:lang(zh):after{content:"《";font-family:"Hiragino Mincho Pro", "LiSong Pro", STSong, PMingLiU, serif;}cite:lang(zh):after{content:"》";}cite:lang(zh).piece:before{content:"〈";}cite:lang(zh).piece:after{content:"〉";}cite:lang(en).piece:before{content:"“";}cite:lang(en).piece:after{content:"”";}em:lang(zh),em:lang(ja){border-bottom:2px dotted;font-style:normal;padding-bottom:.05em;}.han-js em:lang(zh),.han-js em:lang(ja){border-bottom:0 none;padding-bottom:auto;}.textemphasis em:lang(zh){text-emphasis:dot;-moz-text-emphasis:dot;-o-text-emphasis:dot;-webkit-text-emphasis:dot;text-emphasis-position:under;-moz-text-emphasis-position:under;-o-text-emphasis-position:under;-webkit-text-emphasis-position:under;}.textemphasis em:lang(ja){text-emphasis:sesame;-moz-text-emphasis:sesame;-o-text-emphasis:sesame;-webkit-text-emphasis:sesame;}.textemphasis em span.cjk.punc{text-emphasis:none;-moz-text-emphasis:none;-o-text-emphasis:none;-webkit-text-emphasis:none;}.no-textemphasis em:lang(zh) span.cjk,.no-textemphasis em:lang(ja) span.cjk,.no-textemphasis em:lang(zh) span.latin,.no-textemphasis em:lang(ja) span.latin{font-style:inherit;position:relative;}.no-textemphasis em:lang(zh) span.cjk:after,.no-textemphasis em:lang(ja) span.cjk:after,.no-textemphasis em:lang(zh) span.latin:after,.no-textemphasis em:lang(ja) span.latin:after{content:"・";display:inline-block;font-family:"Hiragino Mincho Pro", HiraMinPro-W3, "MS Mincho", MS-Mincho, serif!important;font-style:normal;font-weight:normal;height:.9em;left:0;line-height:1em;overflow:hidden;position:absolute;top:0;margin:.8em 0 0;}.no-textemphasis em:lang(ja) span.cjk:after,.no-textemphasis em:lang(ja) span.latin:after{content:"、";overflow:inherit;margin:-1.2em 0 0 .35em;}.no-textemphasis em:lang(zh) span.latin:after{margin-left:-.25em;}.no-textemphasis em:lang(ja) span.latin:after{margin-left:0;}i:lang(zh){font-family:ff-latin-serif-italic, "Times New Roman", ff-cursive-han, cursive, 標楷體, serif;font-style:inherit;}i:lang(zh-TW),i:lang(zh-HK){font-family:ff-latin-serif-italic, "Times New Roman", ff-cursive-han, cursive, 標楷體, serif;}i:lang(ja){font-family:ff-latin-serif-italic, "Times New Roman", cursive, serif;font-style:inherit;}article blockquote i:lang(zh),article blockquote i:lang(ja){font-family:ff-latin-sans-italic, Helvetica, Arial, sans-serif;font-style:inherit;}.msie i:lang(zh) span.latin,.msie i:lang(ja) span.latin{font-style:italic;}article p strong:lang(zh),article li strong:lang(zh){font-family:sans-serif;font-weight:600;}q:lang(zh),q:lang(ja){quotes:「 」 『 』 「 」 『 』 「 」 『 』;}q:lang(zh-CN),q:lang(zh-hans),q:lang(en){quotes:“ ” ‘ ’ “ ” ‘ ’ “ ” ‘ ’;}q:before{content:open-quote;}q:after{content:close-quote;}:lang(zh) article blockquote,:lang(ja) article blockquote{margin-left:2em;font-family:Times, "Times New Roman", ff-cursive-han, cursive, 標楷體, serif;width:auto;}article blockquote:lang(ja){font-family:Times, "Times New Roman", cursive, serif;}ruby rt{font-size:.5em;line-height:normal;}ruby rt:before{content:"(";}ruby rt:after{content:")";}ruby{display:inline-block;line-height:2em;}.han-js ruby,.han-js ruby .rt{text-indent:0;}.han-js ruby .rb{display:inline-block;padding-top:.5em;position:relative;text-align:center;}.han-js.msie ruby .rb{display:block;float:left;}.han-js ruby .rt{font-size:.6em;left:0;line-height:normal;position:absolute;text-align:center;top:0;white-space:nowrap;padding:0 .05em;}.han-js ruby.mps{display:inline;vertical-align:top;}.han-js.webkit ruby.mps,.han-js.msie ruby.mps{display:inline-block;}.han-js ruby.mps span.rb{padding-top:0;}.han-js ruby.mps .rt{display:inline-block;font-family:ff-zhuyin, 標楷體, DFKaiShu-SB-Estd-BF, cursive, serif;font-size:1em;line-height:.9!important;position:static!important;transform:scale(.6);-moz-transform:scale(.6);-ms-transform:scale(.6);-o-transform:scale(.6);-webkit-transform:scale(.6);vertical-align:middle;width:1.5em;white-space:pre-wrap;word-break:break-all;margin:-.5em -.2em 0 -.5em !important;}.han-js.msie-old ruby.mps .rt,.han-js.ie-8 ruby.mps .rt{font-size:.6em;}.han-js ruby.mps rt:empty,.han-js ruby.mps .rt:empty{width:auto;}.han-js ruby.mps span.tone{bottom:.6em;display:inline-block;position:absolute;right:-.4em;}.han-js ruby.mps span.tone-0{bottom:auto;margin-top:-.75em;right:.5em;}.webkit ruby.mps span.tone-0{bottom:auto;margin-top:-.7em;right:.25em;}.msie ruby.mps span.tone{bottom:3em;font-size:.6em;}.msie ruby.mps span.tone-0{bottom:auto;font-size:.6em;}ruby.mps-ltr rt,ruby.mps-ltr .rt{font-family:STKaiti, Kai, cursive, serif;}code:lang(zh),code:lang(ja){font-family:monospace, sans-serif;}header,hgroup,article,footer,nav,section{display:block;}dfn{font-style:normal;font-weight:bolder;}h3,p{margin:1em 0;}article:lang(zh) p.poem-like:before,article:lang(zh).poem-like p:before,blockquote:lang(zh).poem-like p:before,article:lang(ja) p.poem-like:before,article:lang(ja).poem-like p:before,blockquote:lang(ja).poem-like p:before,article:lang(zh) li p:before,.no-textemphasis em:lang(zh) span.space:after,.no-textemphasis em:lang(ja) span.space:after,.no-textemphasis em:lang(zh) span.cjk.punc:after,.no-textemphasis em:lang(ja) span.cjk.punc:after,rt:empty:before,rt:empty:after,.han-js ruby rt:before,.han-js ruby rt:after{content:"";}cite:lang(ja):before,.no-quotes q.double:lang(zh):before,.no-quotes q.double:lang(ja):before{content:"『";}cite:lang(ja):after,.no-quotes q.double:lang(zh):after,.no-quotes q.double:lang(ja):after{content:"』";}cite:lang(ja).piece:before,.no-quotes q:lang(zh):before,.no-quotes q:lang(ja):before{content:"「";}cite:lang(ja).piece:after,.no-quotes q:lang(zh):after,.no-quotes q:lang(ja):after{content:"」";}.no-cite-mark cite:before,.no-cite-mark cite:after,cite.no-cite-mark:before,cite.no-cite-mark:after,.textemphasis em span.cjk:after,.textemphasis em span.latin:after{content:""!important;}ruby rp,[hidden],details{display:none;}.webkit ruby,details[open],time{display:inline;} 23 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | all: index.html 2 | 3 | index.html: header.html footer.html content.html 4 | cat header.html content.html footer.html > index.html 5 | 6 | content.html: syntax.md 7 | perl Markdown_1.0.1/Markdown.pl syntax.md > content.html 8 | 9 | -------------------------------------------------------------------------------- /Markdown_1.0.1/License.text: -------------------------------------------------------------------------------- 1 | Copyright (c) 2004, John Gruber 2 | 3 | All rights reserved. 4 | 5 | Redistribution and use in source and binary forms, with or without 6 | modification, are permitted provided that the following conditions are 7 | met: 8 | 9 | * Redistributions of source code must retain the above copyright notice, 10 | this list of conditions and the following disclaimer. 11 | 12 | * Redistributions in binary form must reproduce the above copyright 13 | notice, this list of conditions and the following disclaimer in the 14 | documentation and/or other materials provided with the distribution. 15 | 16 | * Neither the name "Markdown" nor the names of its contributors may 17 | be used to endorse or promote products derived from this software 18 | without specific prior written permission. 19 | 20 | This software is provided by the copyright holders and contributors "as 21 | is" and any express or implied warranties, including, but not limited 22 | to, the implied warranties of merchantability and fitness for a 23 | particular purpose are disclaimed. In no event shall the copyright owner 24 | or contributors be liable for any direct, indirect, incidental, special, 25 | exemplary, or consequential damages (including, but not limited to, 26 | procurement of substitute goods or services; loss of use, data, or 27 | profits; or business interruption) however caused and on any theory of 28 | liability, whether in contract, strict liability, or tort (including 29 | negligence or otherwise) arising in any way out of the use of this 30 | software, even if advised of the possibility of such damage. 31 | -------------------------------------------------------------------------------- /Markdown_1.0.1/Markdown Readme.text: -------------------------------------------------------------------------------- 1 | Markdown 2 | ======== 3 | 4 | Version 1.0.1 - Tue 14 Dec 2004 5 | 6 | by John Gruber 7 | 8 | 9 | 10 | Introduction 11 | ------------ 12 | 13 | Markdown is a text-to-HTML conversion tool for web writers. Markdown 14 | allows you to write using an easy-to-read, easy-to-write plain text 15 | format, then convert it to structurally valid XHTML (or HTML). 16 | 17 | Thus, "Markdown" is two things: a plain text markup syntax, and a 18 | software tool, written in Perl, that converts the plain text markup 19 | to HTML. 20 | 21 | Markdown works both as a Movable Type plug-in and as a standalone Perl 22 | script -- which means it can also be used as a text filter in BBEdit 23 | (or any other application that supporst filters written in Perl). 24 | 25 | Full documentation of Markdown's syntax and configuration options is 26 | available on the web: . 27 | (Note: this readme file is formatted in Markdown.) 28 | 29 | 30 | 31 | Installation and Requirements 32 | ----------------------------- 33 | 34 | Markdown requires Perl 5.6.0 or later. Welcome to the 21st Century. 35 | Markdown also requires the standard Perl library module `Digest::MD5`. 36 | 37 | 38 | ### Movable Type ### 39 | 40 | Markdown works with Movable Type version 2.6 or later (including 41 | MT 3.0 or later). 42 | 43 | 1. Copy the "Markdown.pl" file into your Movable Type "plugins" 44 | directory. The "plugins" directory should be in the same directory 45 | as "mt.cgi"; if the "plugins" directory doesn't already exist, use 46 | your FTP program to create it. Your installation should look like 47 | this: 48 | 49 | (mt home)/plugins/Markdown.pl 50 | 51 | 2. Once installed, Markdown will appear as an option in Movable Type's 52 | Text Formatting pop-up menu. This is selectable on a per-post basis. 53 | Markdown translates your posts to HTML when you publish; the posts 54 | themselves are stored in your MT database in Markdown format. 55 | 56 | 3. If you also install SmartyPants 1.5 (or later), Markdown will offer 57 | a second text formatting option: "Markdown with SmartyPants". This 58 | option is the same as the regular "Markdown" formatter, except that 59 | automatically uses SmartyPants to create typographically correct 60 | curly quotes, em-dashes, and ellipses. See the SmartyPants web page 61 | for more information: 62 | 63 | 4. To make Markdown (or "Markdown with SmartyPants") your default 64 | text formatting option for new posts, go to Weblog Config -> 65 | Preferences. 66 | 67 | Note that by default, Markdown produces XHTML output. To configure 68 | Markdown to produce HTML 4 output, see "Configuration", below. 69 | 70 | 71 | ### Blosxom ### 72 | 73 | Markdown works with Blosxom version 2.x. 74 | 75 | 1. Rename the "Markdown.pl" plug-in to "Markdown" (case is 76 | important). Movable Type requires plug-ins to have a ".pl" 77 | extension; Blosxom forbids it. 78 | 79 | 2. Copy the "Markdown" plug-in file to your Blosxom plug-ins folder. 80 | If you're not sure where your Blosxom plug-ins folder is, see the 81 | Blosxom documentation for information. 82 | 83 | 3. That's it. The entries in your weblog will now automatically be 84 | processed by Markdown. 85 | 86 | 4. If you'd like to apply Markdown formatting only to certain posts, 87 | rather than all of them, see Jason Clark's instructions for using 88 | Markdown in conjunction with Blosxom's Meta plugin: 89 | 90 | 91 | 92 | 93 | ### BBEdit ### 94 | 95 | Markdown works with BBEdit 6.1 or later on Mac OS X. (It also works 96 | with BBEdit 5.1 or later and MacPerl 5.6.1 on Mac OS 8.6 or later.) 97 | 98 | 1. Copy the "Markdown.pl" file to appropriate filters folder in your 99 | "BBEdit Support" folder. On Mac OS X, this should be: 100 | 101 | BBEdit Support/Unix Support/Unix Filters/ 102 | 103 | See the BBEdit documentation for more details on the location of 104 | these folders. 105 | 106 | You can rename "Markdown.pl" to whatever you wish. 107 | 108 | 2. That's it. To use Markdown, select some text in a BBEdit document, 109 | then choose Markdown from the Filters sub-menu in the "#!" menu, or 110 | the Filters floating palette 111 | 112 | 113 | 114 | Configuration 115 | ------------- 116 | 117 | By default, Markdown produces XHTML output for tags with empty elements. 118 | E.g.: 119 | 120 |
121 | 122 | Markdown can be configured to produce HTML-style tags; e.g.: 123 | 124 |
125 | 126 | 127 | ### Movable Type ### 128 | 129 | You need to use a special `MTMarkdownOptions` container tag in each 130 | Movable Type template where you want HTML 4-style output: 131 | 132 | 133 | ... put your entry content here ... 134 | 135 | 136 | The easiest way to use MTMarkdownOptions is probably to put the 137 | opening tag right after your `` tag, and the closing tag right 138 | before ``. 139 | 140 | To suppress Markdown processing in a particular template, i.e. to 141 | publish the raw Markdown-formatted text without translation into 142 | (X)HTML, set the `output` attribute to 'raw': 143 | 144 | 145 | ... put your entry content here ... 146 | 147 | 148 | 149 | ### Command-Line ### 150 | 151 | Use the `--html4tags` command-line switch to produce HTML output from a 152 | Unix-style command line. E.g.: 153 | 154 | % perl Markdown.pl --html4tags foo.text 155 | 156 | Type `perldoc Markdown.pl`, or read the POD documentation within the 157 | Markdown.pl source code for more information. 158 | 159 | 160 | 161 | Bugs 162 | ---- 163 | 164 | To file bug reports or feature requests please send email to: 165 | . 166 | 167 | 168 | 169 | Version History 170 | --------------- 171 | 172 | 1.0.1 (14 Dec 2004): 173 | 174 | + Changed the syntax rules for code blocks and spans. Previously, 175 | backslash escapes for special Markdown characters were processed 176 | everywhere other than within inline HTML tags. Now, the contents 177 | of code blocks and spans are no longer processed for backslash 178 | escapes. This means that code blocks and spans are now treated 179 | literally, with no special rules to worry about regarding 180 | backslashes. 181 | 182 | **NOTE**: This changes the syntax from all previous versions of 183 | Markdown. Code blocks and spans involving backslash characters 184 | will now generate different output than before. 185 | 186 | + Tweaked the rules for link definitions so that they must occur 187 | within three spaces of the left margin. Thus if you indent a link 188 | definition by four spaces or a tab, it will now be a code block. 189 | 190 | [a]: /url/ "Indented 3 spaces, this is a link def" 191 | 192 | [b]: /url/ "Indented 4 spaces, this is a code block" 193 | 194 | **IMPORTANT**: This may affect existing Markdown content if it 195 | contains link definitions indented by 4 or more spaces. 196 | 197 | + Added `>`, `+`, and `-` to the list of backslash-escapable 198 | characters. These should have been done when these characters 199 | were added as unordered list item markers. 200 | 201 | + Trailing spaces and tabs following HTML comments and `
` tags 202 | are now ignored. 203 | 204 | + Inline links using `<` and `>` URL delimiters weren't working: 205 | 206 | like [this]() 207 | 208 | + Added a bit of tolerance for trailing spaces and tabs after 209 | Markdown hr's. 210 | 211 | + Fixed bug where auto-links were being processed within code spans: 212 | 213 | like this: `` 214 | 215 | + Sort-of fixed a bug where lines in the middle of hard-wrapped 216 | paragraphs, which lines look like the start of a list item, 217 | would accidentally trigger the creation of a list. E.g. a 218 | paragraph that looked like this: 219 | 220 | I recommend upgrading to version 221 | 8. Oops, now this line is treated 222 | as a sub-list. 223 | 224 | This is fixed for top-level lists, but it can still happen for 225 | sub-lists. E.g., the following list item will not be parsed 226 | properly: 227 | 228 | + I recommend upgrading to version 229 | 8. Oops, now this line is treated 230 | as a sub-list. 231 | 232 | Given Markdown's list-creation rules, I'm not sure this can 233 | be fixed. 234 | 235 | + Standalone HTML comments are now handled; previously, they'd get 236 | wrapped in a spurious `

` tag. 237 | 238 | + Fix for horizontal rules preceded by 2 or 3 spaces. 239 | 240 | + `


` HTML tags in must occur within three spaces of left 241 | margin. (With 4 spaces or a tab, they should be code blocks, but 242 | weren't before this fix.) 243 | 244 | + Capitalized "With" in "Markdown With SmartyPants" for 245 | consistency with the same string label in SmartyPants.pl. 246 | (This fix is specific to the MT plug-in interface.) 247 | 248 | + Auto-linked email address can now optionally contain 249 | a 'mailto:' protocol. I.e. these are equivalent: 250 | 251 | 252 | 253 | 254 | + Fixed annoying bug where nested lists would wind up with 255 | spurious (and invalid) `

` tags. 256 | 257 | + You can now write empty links: 258 | 259 | [like this]() 260 | 261 | and they'll be turned into anchor tags with empty href attributes. 262 | This should have worked before, but didn't. 263 | 264 | + `***this***` and `___this___` are now turned into 265 | 266 | this 267 | 268 | Instead of 269 | 270 | this 271 | 272 | which isn't valid. (Thanks to Michel Fortin for the fix.) 273 | 274 | + Added a new substitution in `_EncodeCode()`: s/\$/$/g; This 275 | is only for the benefit of Blosxom users, because Blosxom 276 | (sometimes?) interpolates Perl scalars in your article bodies. 277 | 278 | + Fixed problem for links defined with urls that include parens, e.g.: 279 | 280 | [1]: http://sources.wikipedia.org/wiki/Middle_East_Policy_(Chomsky) 281 | 282 | "Chomsky" was being erroneously treated as the URL's title. 283 | 284 | + At some point during 1.0's beta cycle, I changed every sub's 285 | argument fetching from this idiom: 286 | 287 | my $text = shift; 288 | 289 | to: 290 | 291 | my $text = shift || return ''; 292 | 293 | The idea was to keep Markdown from doing any work in a sub 294 | if the input was empty. This introduced a bug, though: 295 | if the input to any function was the single-character string 296 | "0", it would also evaluate as false and return immediately. 297 | How silly. Now fixed. 298 | 299 | 300 | 301 | Donations 302 | --------- 303 | 304 | Donations to support Markdown's development are happily accepted. See: 305 | for details. 306 | 307 | 308 | 309 | Copyright and License 310 | --------------------- 311 | 312 | Copyright (c) 2003-2004 John Gruber 313 | 314 | All rights reserved. 315 | 316 | Redistribution and use in source and binary forms, with or without 317 | modification, are permitted provided that the following conditions are 318 | met: 319 | 320 | * Redistributions of source code must retain the above copyright notice, 321 | this list of conditions and the following disclaimer. 322 | 323 | * Redistributions in binary form must reproduce the above copyright 324 | notice, this list of conditions and the following disclaimer in the 325 | documentation and/or other materials provided with the distribution. 326 | 327 | * Neither the name "Markdown" nor the names of its contributors may 328 | be used to endorse or promote products derived from this software 329 | without specific prior written permission. 330 | 331 | This software is provided by the copyright holders and contributors "as 332 | is" and any express or implied warranties, including, but not limited 333 | to, the implied warranties of merchantability and fitness for a 334 | particular purpose are disclaimed. In no event shall the copyright owner 335 | or contributors be liable for any direct, indirect, incidental, special, 336 | exemplary, or consequential damages (including, but not limited to, 337 | procurement of substitute goods or services; loss of use, data, or 338 | profits; or business interruption) however caused and on any theory of 339 | liability, whether in contract, strict liability, or tort (including 340 | negligence or otherwise) arising in any way out of the use of this 341 | software, even if advised of the possibility of such damage. 342 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | ### \###[点击查看《Markdown 语法》](http://wowubuntu.com/markdown/) 2 | 3 | --- 4 | 简介: 5 | 6 | ## Markdown 语法 (简体中文版) 7 | 8 | **声明:** 这份文档派生于[繁体中文版](http://markdown.tw/),在此基础上进行了繁体转简体工作,并进行了适当的润色。此文档用 Markdown 语法编写,你可以到这里[查看它的源文件][src1]。 9 | 10 | **注:** 本项目托管于 [GitCafe][],请通过"派生"和"合并请求"来帮忙改进本项目。对 Markdown 语法内容的改善只需要修改 syntax.md 及 basics.md 这两个文件。 11 | 12 | **注意:**繁体中文版的原始文件可以[查看这里][src] 。 13 | 14 | [src1]: http://gitcafe.com/riku/Markdown-Syntax-CN/blob/master/syntax.md 15 | [src]: https://github.com/othree/markdown-syntax-zhtw/blob/master/syntax.md 16 | [GitCafe]: http://gitcafe.com/riku/Markdown-Syntax-CN/ 17 | 18 | ### 链接 19 | 20 | 项目主页: 21 | 22 | 繁体中文版主页: 23 | 24 | ### 附注 25 | 26 | By @riku - [twitter.com/riku](http://twitter.com/riku) 27 | -------------------------------------------------------------------------------- /basic.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Markdown 语法说明(简体中文版) 6 | 7 | 8 | 9 | 10 |

11 | 12 |

声明: 这份文档派生(fork)于繁体中文版,在此基础上进行了繁体转简体工作,并进行了适当的润色。此文档用 Markdown 语法编写,你可以到这里查看它的源文件。「繁体中文版的原始文件可以查看这里」--By @riku / 本项目托管于 GitCafe

13 | 14 |

注: 本项目同时也托管于 Github上,请通过 fork+pull request 方式来帮忙改进本项目。

15 | 16 |

Markdown: Basics (快速入门) / (点击查看完整语法说明)

17 | 18 |

Getting the Gist of Markdown's Formatting Syntax

19 | 20 |

此页提供了 Markdown 的简单概念, 语法说明 页提供了完整详细的文档,说明了每项功能。但是 Markdown 其实很简单就可以上手,此页文档提供了一些范例,并且每个范例都会提供输出的 HTML 结果。

21 | 22 |

其实直接试试看也是一个很不错的方法, Dingus 是一个网页应用程序,你可以把自已编写的 Markdown 文档转成 XHTML。

23 | 24 |

段落、标题、区块代码

25 | 26 |

一个段落是由一个以上的连接的行句组成,而一个以上的空行则会划分出不同的段落(空行的定义是显示上看起来像是空行,就被视为空行,例如有一行只有空白和 tab,那该行也会被视为空行),一般的段落不需要用空白或换行缩进。

27 | 28 |

Markdown 支持两种标题的语法,Setextatx 形式。Setext 形式是用底线的形式,利用 = (最高阶标题)和 - (第二阶标题),Atx 形式在行首插入 1 到 6 个 # ,对应到标题 1 到 6 阶。

29 | 30 |

区块引用则使用 email 形式的 '>' 角括号。

31 | 32 |

Markdown 语法:

33 | 34 |
A First Level Header
 35 | ====================
 36 | A Second Level Header
 37 | ---------------------
 38 | 
 39 | Now is the time for all good men to come to
 40 | the aid of their country. This is just a
 41 | regular paragraph.
 42 | 
 43 | The quick brown fox jumped over the lazy
 44 | dog's back.
 45 | ### Header 3
 46 | 
 47 | > This is a blockquote.
 48 | > 
 49 | > This is the second paragraph in the blockquote.
 50 | >
 51 | > ## This is an H2 in a blockquote
 52 | 
53 | 54 |

输出 HTML 为:

55 | 56 |
<h1>A First Level Header</h1>
 57 | <h2>A Second Level Header</h2>
 58 | <p>Now is the time for all good men to come to
 59 | the aid of their country. This is just a
 60 | regular paragraph.</p>
 61 | <p>The quick brown fox jumped over the lazy
 62 | dog's back.</p>
 63 | <h3>Header 3</h3>
 64 | <blockquote>
 65 | <p>This is a blockquote.</p>
 66 | <p>This is the second paragraph in the blockquote.</p>
 67 | <h2>This is an H2 in a blockquote</h2>
 68 | </blockquote>
 69 | 
70 | 71 |

修辞和强调

72 | 73 |

Markdown 使用星号和底线来标记需要强调的区段。

74 | 75 |

Markdown 语法:

76 | 77 |
Some of these words *are emphasized*.
 78 | Some of these words _are emphasized also_.
 79 | Use two asterisks for **strong emphasis**.
 80 | Or, if you prefer, __use two underscores instead__.
 81 | 
82 | 83 |

输出 HTML 为:

84 | 85 |
<p>Some of these words <em>are emphasized</em>.
 86 | Some of these words <em>are emphasized also</em>.</p>
 87 | <p>Use two asterisks for <strong>strong emphasis</strong>.
 88 | Or, if you prefer, <strong>use two underscores instead</strong>.</p>
 89 | 
90 | 91 |

列表

92 | 93 |

无序列表使用星号、加号和减号来做为列表的项目标记,这些符号是都可以使用的,使用星号:

94 | 95 |
* Candy.
 96 | * Gum.
 97 | * Booze.
 98 | 
99 | 100 |

加号:

101 | 102 |
+ Candy.
103 | + Gum.
104 | + Booze.
105 | 
106 | 107 |

和减号

108 | 109 |
- Candy.
110 | - Gum.
111 | - Booze.
112 | 
113 | 114 |

都会输出 HTML 为:

115 | 116 |
<ul>
117 | <li>Candy.</li>
118 | <li>Gum.</li>
119 | <li>Booze.</li>
120 | </ul>
121 | 
122 | 123 |

有序的列表则是使用一般的数字接着一个英文句点作为项目标记:

124 | 125 |
1. Red
126 | 2. Green
127 | 3. Blue
128 | 
129 | 130 |

输出 HTML 为:

131 | 132 |
<ol>
133 | <li>Red</li>
134 | <li>Green</li>
135 | <li>Blue</li>
136 | </ol>
137 | 
138 | 139 |

如果你在项目之间插入空行,那项目的内容会用 <p> 包起来,你也可以在一个项目内放上多个段落,只要在它前面缩排 4 个空白或 1 个 tab 。

140 | 141 |
* A list item.
142 | With multiple paragraphs.
143 | 
144 | * Another item in the list.
145 | 
146 | 147 |

输出 HTML 为:

148 | 149 |
<ul>
150 | <li><p>A list item.</p>
151 | <p>With multiple paragraphs.</p></li>
152 | <li><p>Another item in the list.</p></li>
153 | </ul>
154 | 
155 | 156 |

链接

157 | 158 |

Markdown 支援两种形式的链接语法: 行内参考 两种形式,两种都是使用角括号来把文字转成连结。

159 | 160 |

行内形式是直接在后面用括号直接接上链接:

161 | 162 |
This is an [example link](http://example.com/).
163 | 
164 | 165 |

输出 HTML 为:

166 | 167 |
<p>This is an <a href="http://example.com/">
168 | example link</a>.</p>
169 | 
170 | 171 |

你也可以选择性的加上 title 属性:

172 | 173 |
This is an [example link](http://example.com/ "With a Title").
174 | 
175 | 176 |

输出 HTML 为:

177 | 178 |
<p>This is an <a href="http://example.com/" title="With a Title">
179 | example link</a>.</p>
180 | 
181 | 182 |

参考形式的链接让你可以为链接定一个名称,之后你可以在文件的其他地方定义该链接的内容:

183 | 184 |
I get 10 times more traffic from [Google][1] than from
185 | [Yahoo][2] or [MSN][3].
186 | 
187 | [1]: http://google.com/ "Google"
188 | [2]: http://search.yahoo.com/ "Yahoo Search"
189 | [3]: http://search.msn.com/ "MSN Search"
190 | 
191 | 192 |

输出 HTML 为:

193 | 194 |
<p>I get 10 times more traffic from <a href="http://google.com/"
195 | title="Google">Google</a> than from <a href="http://search.yahoo.com/"
196 | title="Yahoo Search">Yahoo</a> or <a href="http://search.msn.com/"
197 | title="MSN Search">MSN</a>.</p>
198 | 
199 | 200 |

title 属性是选择性的,链接名称可以用字母、数字和空格,但是不分大小写:

201 | 202 |
I start my morning with a cup of coffee and
203 | [The New York Times][NY Times].
204 | 
205 | [ny times]: http://www.nytimes.com/
206 | 
207 | 208 |

输出 HTML 为:

209 | 210 |
<p>I start my morning with a cup of coffee and
211 | <a href="http://www.nytimes.com/">The New York Times</a>.</p>
212 | 
213 | 214 |

图片

215 | 216 |

图片的语法和链接很像。

217 | 218 |

行内形式(title 是选择性的):

219 | 220 |
![alt text](/path/to/img.jpg "Title")
221 | 
222 | 223 |

参考形式:

224 | 225 |
![alt text][id]
226 | 
227 | [id]: /path/to/img.jpg "Title"
228 | 
229 | 230 |

上面两种方法都会输出 HTML 为:

231 | 232 |
<img src="/path/to/img.jpg" alt="alt text" title="Title" />
233 | 
234 | 235 |

代码

236 | 237 |

在一般的段落文字中,你可以使用反引号 ` 来标记代码区段,区段内的 &<> 都会被自动的转换成 HTML 实体,这项特性让你可以很容易的在代码区段内插入 HTML 码:

238 | 239 |
I strongly recommend against using any `<blink>` tags.
240 | 
241 | I wish SmartyPants used named entities like `&mdash;`
242 | instead of decimal-encoded entites like `&#8212;`.
243 | 
244 | 245 |

输出 HTML 为:

246 | 247 |
<p>I strongly recommend against using any
248 | <code>&lt;blink&gt;</code> tags.</p>
249 | <p>I wish SmartyPants used named entities like
250 | <code>&amp;mdash;</code> instead of decimal-encoded
251 | entites like <code>&amp;#8212;</code>.</p>
252 | 
253 | 254 |

如果要建立一个已经格式化好的代码区块,只要每行都缩进 4 个空格或是一个 tab 就可以了,而 &<> 也一样会自动转成 HTML 实体。

255 | 256 |

Markdown 语法:

257 | 258 |
If you want your page to validate under XHTML 1.0 Strict,
259 | you've got to put paragraph tags in your blockquotes:
260 | 
261 | <blockquote>
262 | <p>For example.</p>
263 | </blockquote>
264 | 
265 | 266 |

输出 HTML 为:

267 | 268 |
<p>If you want your page to validate under XHTML 1.0 Strict,
269 | you've got to put paragraph tags in your blockquotes:</p>
270 | <pre><code>&lt;blockquote&gt;
271 | &lt;p&gt;For example.&lt;/p&gt;
272 | &lt;/blockquote&gt;
273 | </code></pre>
274 | 
275 | 276 | 277 |
278 | 279 |
280 | 281 |
282 | 293 | 294 | blog comments powered by Disqus 295 | 296 |
297 | 298 | 299 | 300 | -------------------------------------------------------------------------------- /basic_content.html: -------------------------------------------------------------------------------- 1 |

声明: 这份文档派生(fork)于繁体中文版,在此基础上进行了繁体转简体工作,并进行了适当的润色。此文档用 Markdown 语法编写,你可以到这里查看它的源文件。「繁体中文版的原始文件可以查看这里」--By @riku / 本项目托管于 GitCafe

2 | 3 |

注: 本项目同时也托管于 Github上,请通过 fork+pull request 方式来帮忙改进本项目。

4 | 5 |

Markdown: Basics (快速入门) / (点击查看完整语法说明)

6 | 7 |

Getting the Gist of Markdown's Formatting Syntax

8 | 9 |

此页提供了 Markdown 的简单概念, 语法说明 页提供了完整详细的文档,说明了每项功能。但是 Markdown 其实很简单就可以上手,此页文档提供了一些范例,并且每个范例都会提供输出的 HTML 结果。

10 | 11 |

其实直接试试看也是一个很不错的方法, Dingus 是一个网页应用程序,你可以把自已编写的 Markdown 文档转成 XHTML。

12 | 13 |

段落、标题、区块代码

14 | 15 |

一个段落是由一个以上的连接的行句组成,而一个以上的空行则会划分出不同的段落(空行的定义是显示上看起来像是空行,就被视为空行,例如有一行只有空白和 tab,那该行也会被视为空行),一般的段落不需要用空白或换行缩进。

16 | 17 |

Markdown 支持两种标题的语法,Setextatx 形式。Setext 形式是用底线的形式,利用 = (最高阶标题)和 - (第二阶标题),Atx 形式在行首插入 1 到 6 个 # ,对应到标题 1 到 6 阶。

18 | 19 |

区块引用则使用 email 形式的 '>' 角括号。

20 | 21 |

Markdown 语法:

22 | 23 |
A First Level Header
 24 | ====================
 25 | A Second Level Header
 26 | ---------------------
 27 | 
 28 | Now is the time for all good men to come to
 29 | the aid of their country. This is just a
 30 | regular paragraph.
 31 | 
 32 | The quick brown fox jumped over the lazy
 33 | dog's back.
 34 | ### Header 3
 35 | 
 36 | > This is a blockquote.
 37 | > 
 38 | > This is the second paragraph in the blockquote.
 39 | >
 40 | > ## This is an H2 in a blockquote
 41 | 
42 | 43 |

输出 HTML 为:

44 | 45 |
<h1>A First Level Header</h1>
 46 | <h2>A Second Level Header</h2>
 47 | <p>Now is the time for all good men to come to
 48 | the aid of their country. This is just a
 49 | regular paragraph.</p>
 50 | <p>The quick brown fox jumped over the lazy
 51 | dog's back.</p>
 52 | <h3>Header 3</h3>
 53 | <blockquote>
 54 | <p>This is a blockquote.</p>
 55 | <p>This is the second paragraph in the blockquote.</p>
 56 | <h2>This is an H2 in a blockquote</h2>
 57 | </blockquote>
 58 | 
59 | 60 |

修辞和强调

61 | 62 |

Markdown 使用星号和底线来标记需要强调的区段。

63 | 64 |

Markdown 语法:

65 | 66 |
Some of these words *are emphasized*.
 67 | Some of these words _are emphasized also_.
 68 | Use two asterisks for **strong emphasis**.
 69 | Or, if you prefer, __use two underscores instead__.
 70 | 
71 | 72 |

输出 HTML 为:

73 | 74 |
<p>Some of these words <em>are emphasized</em>.
 75 | Some of these words <em>are emphasized also</em>.</p>
 76 | <p>Use two asterisks for <strong>strong emphasis</strong>.
 77 | Or, if you prefer, <strong>use two underscores instead</strong>.</p>
 78 | 
79 | 80 |

列表

81 | 82 |

无序列表使用星号、加号和减号来做为列表的项目标记,这些符号是都可以使用的,使用星号:

83 | 84 |
* Candy.
 85 | * Gum.
 86 | * Booze.
 87 | 
88 | 89 |

加号:

90 | 91 |
+ Candy.
 92 | + Gum.
 93 | + Booze.
 94 | 
95 | 96 |

和减号

97 | 98 |
- Candy.
 99 | - Gum.
100 | - Booze.
101 | 
102 | 103 |

都会输出 HTML 为:

104 | 105 |
<ul>
106 | <li>Candy.</li>
107 | <li>Gum.</li>
108 | <li>Booze.</li>
109 | </ul>
110 | 
111 | 112 |

有序的列表则是使用一般的数字接着一个英文句点作为项目标记:

113 | 114 |
1. Red
115 | 2. Green
116 | 3. Blue
117 | 
118 | 119 |

输出 HTML 为:

120 | 121 |
<ol>
122 | <li>Red</li>
123 | <li>Green</li>
124 | <li>Blue</li>
125 | </ol>
126 | 
127 | 128 |

如果你在项目之间插入空行,那项目的内容会用 <p> 包起来,你也可以在一个项目内放上多个段落,只要在它前面缩排 4 个空白或 1 个 tab 。

129 | 130 |
* A list item.
131 | With multiple paragraphs.
132 | 
133 | * Another item in the list.
134 | 
135 | 136 |

输出 HTML 为:

137 | 138 |
<ul>
139 | <li><p>A list item.</p>
140 | <p>With multiple paragraphs.</p></li>
141 | <li><p>Another item in the list.</p></li>
142 | </ul>
143 | 
144 | 145 |

链接

146 | 147 |

Markdown 支援两种形式的链接语法: 行内参考 两种形式,两种都是使用角括号来把文字转成连结。

148 | 149 |

行内形式是直接在后面用括号直接接上链接:

150 | 151 |
This is an [example link](http://example.com/).
152 | 
153 | 154 |

输出 HTML 为:

155 | 156 |
<p>This is an <a href="http://example.com/">
157 | example link</a>.</p>
158 | 
159 | 160 |

你也可以选择性的加上 title 属性:

161 | 162 |
This is an [example link](http://example.com/ "With a Title").
163 | 
164 | 165 |

输出 HTML 为:

166 | 167 |
<p>This is an <a href="http://example.com/" title="With a Title">
168 | example link</a>.</p>
169 | 
170 | 171 |

参考形式的链接让你可以为链接定一个名称,之后你可以在文件的其他地方定义该链接的内容:

172 | 173 |
I get 10 times more traffic from [Google][1] than from
174 | [Yahoo][2] or [MSN][3].
175 | 
176 | [1]: http://google.com/ "Google"
177 | [2]: http://search.yahoo.com/ "Yahoo Search"
178 | [3]: http://search.msn.com/ "MSN Search"
179 | 
180 | 181 |

输出 HTML 为:

182 | 183 |
<p>I get 10 times more traffic from <a href="http://google.com/"
184 | title="Google">Google</a> than from <a href="http://search.yahoo.com/"
185 | title="Yahoo Search">Yahoo</a> or <a href="http://search.msn.com/"
186 | title="MSN Search">MSN</a>.</p>
187 | 
188 | 189 |

title 属性是选择性的,链接名称可以用字母、数字和空格,但是不分大小写:

190 | 191 |
I start my morning with a cup of coffee and
192 | [The New York Times][NY Times].
193 | 
194 | [ny times]: http://www.nytimes.com/
195 | 
196 | 197 |

输出 HTML 为:

198 | 199 |
<p>I start my morning with a cup of coffee and
200 | <a href="http://www.nytimes.com/">The New York Times</a>.</p>
201 | 
202 | 203 |

图片

204 | 205 |

图片的语法和链接很像。

206 | 207 |

行内形式(title 是选择性的):

208 | 209 |
![alt text](/path/to/img.jpg "Title")
210 | 
211 | 212 |

参考形式:

213 | 214 |
![alt text][id]
215 | 
216 | [id]: /path/to/img.jpg "Title"
217 | 
218 | 219 |

上面两种方法都会输出 HTML 为:

220 | 221 |
<img src="/path/to/img.jpg" alt="alt text" title="Title" />
222 | 
223 | 224 |

代码

225 | 226 |

在一般的段落文字中,你可以使用反引号 ` 来标记代码区段,区段内的 &<> 都会被自动的转换成 HTML 实体,这项特性让你可以很容易的在代码区段内插入 HTML 码:

227 | 228 |
I strongly recommend against using any `<blink>` tags.
229 | 
230 | I wish SmartyPants used named entities like `&mdash;`
231 | instead of decimal-encoded entites like `&#8212;`.
232 | 
233 | 234 |

输出 HTML 为:

235 | 236 |
<p>I strongly recommend against using any
237 | <code>&lt;blink&gt;</code> tags.</p>
238 | <p>I wish SmartyPants used named entities like
239 | <code>&amp;mdash;</code> instead of decimal-encoded
240 | entites like <code>&amp;#8212;</code>.</p>
241 | 
242 | 243 |

如果要建立一个已经格式化好的代码区块,只要每行都缩进 4 个空格或是一个 tab 就可以了,而 &<> 也一样会自动转成 HTML 实体。

244 | 245 |

Markdown 语法:

246 | 247 |
If you want your page to validate under XHTML 1.0 Strict,
248 | you've got to put paragraph tags in your blockquotes:
249 | 
250 | <blockquote>
251 | <p>For example.</p>
252 | </blockquote>
253 | 
254 | 255 |

输出 HTML 为:

256 | 257 |
<p>If you want your page to validate under XHTML 1.0 Strict,
258 | you've got to put paragraph tags in your blockquotes:</p>
259 | <pre><code>&lt;blockquote&gt;
260 | &lt;p&gt;For example.&lt;/p&gt;
261 | &lt;/blockquote&gt;
262 | </code></pre>
263 | 
264 | -------------------------------------------------------------------------------- /basics.md: -------------------------------------------------------------------------------- 1 | << [访问 Wow!Ubuntu](http://wowubuntu.com) 2 | 3 | **声明:** 这份文档派生(fork)于[繁体中文版](http://markdown.tw/),在此基础上进行了繁体转简体工作,并进行了适当的润色。此文档用 Markdown 语法编写,你可以到这里[查看它的源文件][src1]。「繁体中文版的原始文件可以[查看这里][src]」--By @[riku][t] 4 | 5 | **注:** 本项目托管于 [GitCafe][]上,请通过"派生"和"合并请求"来帮忙改进本项目。 6 | 7 | [src1]:http://gitcafe.com/riku/Markdown-Syntax-CN/blob/master/basics.md 8 | [src]: https://github.com/othree/markdown-syntax-zhtw/blob/master/basics.md 9 | [t]: http://twitter.com/riku 10 | [g]: http://gitcafe.com/riku/Markdown-Syntax-CN 11 | [GitCafe]: http://gitcafe.com/riku/Markdown-Syntax-CN/ 12 | 13 | Markdown: Basics (快速入门) / ([点击查看完整语法说明](./index.html)) 14 | ================ 15 | 16 | Getting the Gist of Markdown's Formatting Syntax 17 | ------------------------------------------------ 18 | 19 | 此页提供了 Markdown 的简单概念, [语法说明][s] 页提供了完整详细的文档,说明了每项功能。但是 Markdown 其实很简单就可以上手,此页文档提供了一些范例,并且每个范例都会提供输出的 HTML 结果。 20 | 21 | [s]: http://gitcafe.com/riku/Markdown-Syntax-CN/blob/master/syntax.md "Markdown Syntax" 22 | [d]: http://daringfireball.net/projects/markdown/dingus "Markdown Dingus" 23 | 24 | 其实直接试试看也是一个很不错的方法, [Dingus][d] 是一个网页应用程序,你可以把自已编写的 Markdown 文档转成 XHTML。 25 | 26 | ## 段落、标题、区块代码 ## 27 | 28 | 一个段落是由一个以上的连接的行句组成,而一个以上的空行则会划分出不同的段落(空行的定义是显示上看起来像是空行,就被视为空行,例如有一行只有空白和 tab,那该行也会被视为空行),一般的段落不需要用空白或换行缩进。 29 | 30 | Markdown 支持两种标题的语法,[Setext] [1] 和 [atx] [2] 形式。Setext 形式是用底线的形式,利用 `=` (最高阶标题)和 `-` (第二阶标题),Atx 形式在行首插入 1 到 6 个 `#` ,对应到标题 1 到 6 阶。 31 | 32 | [1]: http://docutils.sourceforge.net/mirror/setext.html 33 | [2]: http://www.aaronsw.com/2002/atx/ 34 | 35 | 区块引用则使用 email 形式的 '`>`' 角括号。 36 | 37 | Markdown 语法: 38 | 39 | A First Level Header 40 | ==================== 41 | A Second Level Header 42 | --------------------- 43 | 44 | Now is the time for all good men to come to 45 | the aid of their country. This is just a 46 | regular paragraph. 47 | 48 | The quick brown fox jumped over the lazy 49 | dog's back. 50 | ### Header 3 51 | 52 | > This is a blockquote. 53 | > 54 | > This is the second paragraph in the blockquote. 55 | > 56 | > ## This is an H2 in a blockquote 57 | 58 | 输出 HTML 为: 59 | 60 |

A First Level Header

61 |

A Second Level Header

62 |

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

65 |

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

67 |

Header 3

68 |
69 |

This is a blockquote.

70 |

This is the second paragraph in the blockquote.

71 |

This is an H2 in a blockquote

72 |
73 | 74 | ### 修辞和强调 ### 75 | 76 | Markdown 使用星号和底线来标记需要强调的区段。 77 | 78 | Markdown 语法: 79 | 80 | Some of these words *are emphasized*. 81 | Some of these words _are emphasized also_. 82 | Use two asterisks for **strong emphasis**. 83 | Or, if you prefer, __use two underscores instead__. 84 | 85 | 输出 HTML 为: 86 | 87 |

Some of these words are emphasized. 88 | Some of these words are emphasized also.

89 |

Use two asterisks for strong emphasis. 90 | Or, if you prefer, use two underscores instead.

91 | 92 | ## 列表 ## 93 | 94 | 无序列表使用星号、加号和减号来做为列表的项目标记,这些符号是都可以使用的,使用星号: 95 | 96 | * Candy. 97 | * Gum. 98 | * Booze. 99 | 100 | 加号: 101 | 102 | + Candy. 103 | + Gum. 104 | + Booze. 105 | 106 | 和减号 107 | 108 | - Candy. 109 | - Gum. 110 | - Booze. 111 | 112 | 都会输出 HTML 为: 113 | 114 |
    115 |
  • Candy.
  • 116 |
  • Gum.
  • 117 |
  • Booze.
  • 118 |
119 | 120 | 有序的列表则是使用一般的数字接着一个英文句点作为项目标记: 121 | 122 | 1. Red 123 | 2. Green 124 | 3. Blue 125 | 126 | 输出 HTML 为: 127 | 128 |
    129 |
  1. Red
  2. 130 |
  3. Green
  4. 131 |
  5. Blue
  6. 132 |
133 | 134 | 如果你在项目之间插入空行,那项目的内容会用 `

` 包起来,你也可以在一个项目内放上多个段落,只要在它前面缩排 4 个空白或 1 个 tab 。 135 | 136 | * A list item. 137 | With multiple paragraphs. 138 | 139 | * Another item in the list. 140 | 141 | 输出 HTML 为: 142 | 143 |

    144 |
  • A list item.

    145 |

    With multiple paragraphs.

  • 146 |
  • Another item in the list.

  • 147 |
148 | ### 链接 ### 149 | 150 | Markdown 支援两种形式的链接语法: *行内* 和 *参考* 两种形式,两种都是使用角括号来把文字转成连结。 151 | 152 | 行内形式是直接在后面用括号直接接上链接: 153 | 154 | This is an [example link](http://example.com/). 155 | 156 | 输出 HTML 为: 157 | 158 |

This is an 159 | example link.

160 | 161 | 你也可以选择性的加上 title 属性: 162 | 163 | This is an [example link](http://example.com/ "With a Title"). 164 | 165 | 输出 HTML 为: 166 | 167 |

This is an 168 | example link.

169 | 170 | 参考形式的链接让你可以为链接定一个名称,之后你可以在文件的其他地方定义该链接的内容: 171 | 172 | I get 10 times more traffic from [Google][1] than from 173 | [Yahoo][2] or [MSN][3]. 174 | 175 | [1]: http://google.com/ "Google" 176 | [2]: http://search.yahoo.com/ "Yahoo Search" 177 | [3]: http://search.msn.com/ "MSN Search" 178 | 179 | 输出 HTML 为: 180 | 181 |

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

185 | 186 | title 属性是选择性的,链接名称可以用字母、数字和空格,但是不分大小写: 187 | 188 | I start my morning with a cup of coffee and 189 | [The New York Times][NY Times]. 190 | 191 | [ny times]: http://www.nytimes.com/ 192 | 193 | 输出 HTML 为: 194 | 195 |

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

197 | 198 | 199 | ### 图片 ### 200 | 201 | 图片的语法和链接很像。 202 | 203 | 行内形式(title 是选择性的): 204 | 205 | ![alt text](/path/to/img.jpg "Title") 206 | 207 | 参考形式: 208 | 209 | ![alt text][id] 210 | 211 | [id]: /path/to/img.jpg "Title" 212 | 213 | 上面两种方法都会输出 HTML 为: 214 | 215 | alt text 216 | 217 | ### 代码 ### 218 | 在一般的段落文字中,你可以使用反引号 `` ` `` 来标记代码区段,区段内的 `&`、`<` 和 `>` 都会被自动的转换成 HTML 实体,这项特性让你可以很容易的在代码区段内插入 HTML 码: 219 | 220 | I strongly recommend against using any `` tags. 221 | 222 | I wish SmartyPants used named entities like `—` 223 | instead of decimal-encoded entites like `—`. 224 | 225 | 输出 HTML 为: 226 | 227 |

I strongly recommend against using any 228 | <blink> tags.

229 |

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

232 | 233 | 如果要建立一个已经格式化好的代码区块,只要每行都缩进 4 个空格或是一个 tab 就可以了,而 `&`、`<` 和 `>` 也一样会自动转成 HTML 实体。 234 | 235 | Markdown 语法: 236 | 237 | If you want your page to validate under XHTML 1.0 Strict, 238 | you've got to put paragraph tags in your blockquotes: 239 | 240 |
241 |

For example.

242 |
243 | 244 | 输出 HTML 为: 245 | 246 |

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

248 |
<blockquote>
249 | 	<p>For example.</p>
250 | 	</blockquote>
251 | 	
252 | 253 | -------------------------------------------------------------------------------- /basics.text: -------------------------------------------------------------------------------- 1 | Markdown: Basics 2 | ================ 3 | 4 | 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 39 | a blank line -- a line containing nothing but spaces or tabs is 40 | considered blank.) Normal paragraphs should not be indented with 41 | spaces or tabs. 42 | 43 | Markdown offers two styles of headers: *Setext* and *atx*. 44 | Setext-style headers for `

` and `

` are created by 45 | "underlining" with equal signs (`=`) and hyphens (`-`), respectively. 46 | To create an atx-style header, you put 1-6 hash marks (`#`) at the 47 | beginning of the line -- the number of hashes equals the resulting 48 | HTML header level. 49 | 50 | Blockquotes are indicated using email-style '`>`' angle brackets. 51 | 52 | Markdown: 53 | 54 | A First Level Header 55 | ==================== 56 | 57 | A Second Level Header 58 | --------------------- 59 | 60 | Now is the time for all good men to come to 61 | the aid of their country. This is just a 62 | regular paragraph. 63 | 64 | The quick brown fox jumped over the lazy 65 | dog's back. 66 | 67 | ### Header 3 68 | 69 | > This is a blockquote. 70 | > 71 | > This is the second paragraph in the blockquote. 72 | > 73 | > ## This is an H2 in a blockquote 74 | 75 | 76 | Output: 77 | 78 |

A First Level Header

79 | 80 |

A Second Level Header

81 | 82 |

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

85 | 86 |

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

88 | 89 |

Header 3

90 | 91 |
92 |

This is a blockquote.

93 | 94 |

This is the second paragraph in the blockquote.

95 | 96 |

This is an H2 in a blockquote

97 |
98 | 99 | 100 | 101 | ### Phrase Emphasis ### 102 | 103 | Markdown uses asterisks and underscores to indicate spans of emphasis. 104 | 105 | Markdown: 106 | 107 | Some of these words *are emphasized*. 108 | Some of these words _are emphasized also_. 109 | 110 | Use two asterisks for **strong emphasis**. 111 | Or, if you prefer, __use two underscores instead__. 112 | 113 | Output: 114 | 115 |

Some of these words are emphasized. 116 | Some of these words are emphasized also.

117 | 118 |

Use two asterisks for strong emphasis. 119 | Or, if you prefer, use two underscores instead.

120 | 121 | 122 | 123 | ## Lists ## 124 | 125 | Unordered (bulleted) lists use asterisks, pluses, and hyphens (`*`, 126 | `+`, and `-`) as list markers. These three markers are 127 | interchangable; this: 128 | 129 | * Candy. 130 | * Gum. 131 | * Booze. 132 | 133 | this: 134 | 135 | + Candy. 136 | + Gum. 137 | + Booze. 138 | 139 | and this: 140 | 141 | - Candy. 142 | - Gum. 143 | - Booze. 144 | 145 | all produce the same output: 146 | 147 |
    148 |
  • Candy.
  • 149 |
  • Gum.
  • 150 |
  • Booze.
  • 151 |
152 | 153 | Ordered (numbered) lists use regular numbers, followed by periods, as 154 | list markers: 155 | 156 | 1. Red 157 | 2. Green 158 | 3. Blue 159 | 160 | Output: 161 | 162 |
    163 |
  1. Red
  2. 164 |
  3. Green
  4. 165 |
  5. Blue
  6. 166 |
167 | 168 | If you put blank lines between items, you'll get `

` tags for the 169 | list item text. You can create multi-paragraph list items by indenting 170 | the paragraphs by 4 spaces or 1 tab: 171 | 172 | * A list item. 173 | 174 | With multiple paragraphs. 175 | 176 | * Another item in the list. 177 | 178 | Output: 179 | 180 |

    181 |
  • A list item.

    182 |

    With multiple paragraphs.

  • 183 |
  • Another item in the list.

  • 184 |
185 | 186 | 187 | 188 | ### Links ### 189 | 190 | Markdown supports two styles for creating links: *inline* and 191 | *reference*. With both styles, you use square brackets to delimit the 192 | text you want to turn into a link. 193 | 194 | Inline-style links use parentheses immediately after the link text. 195 | For example: 196 | 197 | This is an [example link](http://example.com/). 198 | 199 | Output: 200 | 201 |

This is an 202 | example link.

203 | 204 | Optionally, you may include a title attribute in the parentheses: 205 | 206 | This is an [example link](http://example.com/ "With a Title"). 207 | 208 | Output: 209 | 210 |

This is an 211 | example link.

212 | 213 | Reference-style links allow you to refer to your links by names, which 214 | you define elsewhere in your document: 215 | 216 | I get 10 times more traffic from [Google][1] than from 217 | [Yahoo][2] or [MSN][3]. 218 | 219 | [1]: http://google.com/ "Google" 220 | [2]: http://search.yahoo.com/ "Yahoo Search" 221 | [3]: http://search.msn.com/ "MSN Search" 222 | 223 | Output: 224 | 225 |

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

229 | 230 | The title attribute is optional. Link names may contain letters, 231 | numbers and spaces, but are *not* case sensitive: 232 | 233 | I start my morning with a cup of coffee and 234 | [The New York Times][NY Times]. 235 | 236 | [ny times]: http://www.nytimes.com/ 237 | 238 | Output: 239 | 240 |

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

242 | 243 | 244 | ### Images ### 245 | 246 | Image syntax is very much like link syntax. 247 | 248 | Inline (titles are optional): 249 | 250 | ![alt text](/path/to/img.jpg "Title") 251 | 252 | Reference-style: 253 | 254 | ![alt text][id] 255 | 256 | [id]: /path/to/img.jpg "Title" 257 | 258 | Both of the above examples produce the same output: 259 | 260 | alt text 261 | 262 | 263 | 264 | ### Code ### 265 | 266 | In a regular paragraph, you can create code span by wrapping text in 267 | backtick quotes. Any ampersands (`&`) and angle brackets (`<` or 268 | `>`) will automatically be translated into HTML entities. This makes 269 | it easy to use Markdown to write about HTML example code: 270 | 271 | I strongly recommend against using any `` tags. 272 | 273 | I wish SmartyPants used named entities like `—` 274 | instead of decimal-encoded entites like `—`. 275 | 276 | Output: 277 | 278 |

I strongly recommend against using any 279 | <blink> tags.

280 | 281 |

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

284 | 285 | 286 | To specify an entire block of pre-formatted code, indent every line of 287 | the block by 4 spaces or 1 tab. Just like with code spans, `&`, `<`, 288 | and `>` characters will be escaped automatically. 289 | 290 | Markdown: 291 | 292 | If you want your page to validate under XHTML 1.0 Strict, 293 | you've got to put paragraph tags in your blockquotes: 294 | 295 |
296 |

For example.

297 |
298 | 299 | Output: 300 | 301 |

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

303 | 304 |
<blockquote>
305 |         <p>For example.</p>
306 |     </blockquote>
307 |     
308 | -------------------------------------------------------------------------------- /content.html: -------------------------------------------------------------------------------- 1 |

NOTE: This is Simplelified Chinese Edition Document of Markdown Syntax. If you are seeking for English Edition Document. Please refer to Markdown: Syntax.

2 | 3 |

声明: 这份文档派生(fork)于繁体中文版,在此基础上进行了繁体转简体工作,并进行了适当的润色。此文档用 Markdown 语法编写,你可以到这里查看它的源文件。「繁体中文版的原始文件可以查看这里 。」--By @riku / 本项目托管于 GitCafe

4 | 5 |

注: 本项目同时也托管于 Github 上,请通过 fork+pull request 方式来帮忙改进本项目。

6 | 7 |

Markdown 语法说明 (简体中文版) / (点击查看快速入门)

8 | 9 | 39 | 40 |
41 | 42 |

概述

43 | 44 |

宗旨

45 | 46 |

Markdown 的目标是实现「易读易写」。

47 | 48 |

可读性,无论如何,都是最重要的。一份使用 Markdown 格式撰写的文件应该可以直接以纯文本发布,并且看起来不会像是由许多标签或是格式指令所构成。Markdown 语法受到一些既有 text-to-HTML 格式的影响,包括 SetextatxTextilereStructuredTextGrutatextEtText,而最大灵感来源其实是纯文本电子邮件的格式。

49 | 50 |

总之, Markdown 的语法全由一些符号所组成,这些符号经过精挑细选,其作用一目了然。比如:在文字两旁加上星号,看起来就像*强调*。Markdown 的列表看起来,嗯,就是列表。Markdown 的区块引用看起来就真的像是引用一段文字,就像你曾在电子邮件中见过的那样。

51 | 52 |

兼容 HTML

53 | 54 |

Markdown 语法的目标是:成为一种适用于网络的书写语言。

55 | 56 |

Markdown 不是想要取代 HTML,甚至也没有要和它相近,它的语法种类很少,只对应 HTML 标记的一小部分。Markdown 的构想不是要使得 HTML 文档更容易书写。在我看来, HTML 已经很容易写了。Markdown 的理念是,能让文档更容易读、写和随意改。HTML 是一种发布的格式,Markdown 是一种书写的格式。就这样,Markdown 的格式语法只涵盖纯文本可以涵盖的范围。

57 | 58 |

不在 Markdown 涵盖范围之内的标签,都可以直接在文档里面用 HTML 撰写。不需要额外标注这是 HTML 或是 Markdown;只要直接加标签就可以了。

59 | 60 |

要制约的只有一些 HTML 区块元素――比如 <div><table><pre><p> 等标签,必须在前后加上空行与其它内容区隔开,还要求它们的开始标签与结尾标签不能用制表符或空格来缩进。Markdown 的生成器有足够智能,不会在 HTML 区块标签外加上不必要的 <p> 标签。

61 | 62 |

例子如下,在 Markdown 文件里加上一段 HTML 表格:

63 | 64 |
这是一个普通段落。
 65 | 
 66 | <table>
 67 |     <tr>
 68 |         <td>Foo</td>
 69 |     </tr>
 70 | </table>
 71 | 
 72 | 这是另一个普通段落。
 73 | 
74 | 75 |

请注意,在 HTML 区块标签间的 Markdown 格式语法将不会被处理。比如,你在 HTML 区块内使用 Markdown 样式的*强调*会没有效果。

76 | 77 |

HTML 的区段(行内)标签如 <span><cite><del> 可以在 Markdown 的段落、列表或是标题里随意使用。依照个人习惯,甚至可以不用 Markdown 格式,而直接采用 HTML 标签来格式化。举例说明:如果比较喜欢 HTML 的 <a><img> 标签,可以直接使用这些标签,而不用 Markdown 提供的链接或是图像标签语法。

78 | 79 |

和处在 HTML 区块标签间不同,Markdown 语法在 HTML 区段标签间是有效的。

80 | 81 |

特殊字符自动转换

82 | 83 |

在 HTML 文件中,有两个字符需要特殊处理: <&< 符号用于起始标签,& 符号则用于标记 HTML 实体,如果你只是想要显示这些字符的原型,你必须要使用实体的形式,像是 &lt;&amp;

84 | 85 |

& 字符尤其让网络文档编写者受折磨,如果你要打「AT&T」 ,你必须要写成「AT&amp;T」。而网址中的 & 字符也要转换。比如你要链接到:

86 | 87 |
http://images.google.com/images?num=30&q=larry+bird
 88 | 
89 | 90 |

你必须要把网址转换写为:

91 | 92 |
http://images.google.com/images?num=30&amp;q=larry+bird
 93 | 
94 | 95 |

才能放到链接标签的 href 属性里。不用说也知道这很容易忽略,这也可能是 HTML 标准检验所检查到的错误中,数量最多的。

96 | 97 |

Markdown 让你可以自然地书写字符,需要转换的由它来处理好了。如果你使用的 & 字符是 HTML 字符实体的一部分,它会保留原状,否则它会被转换成 &amp;。

98 | 99 |

所以你如果要在文档中插入一个版权符号 ©,你可以这样写:

100 | 101 |
&copy;
102 | 
103 | 104 |

Markdown 会保留它不动。而若你写:

105 | 106 |
AT&T
107 | 
108 | 109 |

Markdown 就会将它转为:

110 | 111 |
AT&amp;T
112 | 
113 | 114 |

类似的状况也会发生在 < 符号上,因为 Markdown 允许 兼容 HTML ,如果你是把 < 符号作为 HTML 标签的定界符使用,那 Markdown 也不会对它做任何转换,但是如果你写:

115 | 116 |
4 < 5
117 | 
118 | 119 |

Markdown 将会把它转换为:

120 | 121 |
4 &lt; 5
122 | 
123 | 124 |

不过需要注意的是,code 范围内,不论是行内还是区块, <& 两个符号都一定会被转换成 HTML 实体,这项特性让你可以很容易地用 Markdown 写 HTML code (和 HTML 相对而言, HTML 语法中,你要把所有的 <& 都转换为 HTML 实体,才能在 HTML 文件里面写出 HTML code。)

125 | 126 |
127 | 128 |

区块元素

129 | 130 |

段落和换行

131 | 132 |

一个 Markdown 段落是由一个或多个连续的文本行组成,它的前后要有一个以上的空行(空行的定义是显示上看起来像是空的,便会被视为空行。比方说,若某一行只包含空格和制表符,则该行也会被视为空行)。普通段落不该用空格或制表符来缩进。

133 | 134 |

「由一个或多个连续的文本行组成」这句话其实暗示了 Markdown 允许段落内的强迫换行(插入换行符),这个特性和其他大部分的 text-to-HTML 格式不一样(包括 Movable Type 的「Convert Line Breaks」选项),其它的格式会把每个换行符都转成 <br /> 标签。

135 | 136 |

如果你确实想要依赖 Markdown 来插入 <br /> 标签的话,在插入处先按入两个以上的空格然后回车。

137 | 138 |

的确,需要多费点事(多加空格)来产生 <br /> ,但是简单地「每个换行都转换为 <br />」的方法在 Markdown 中并不适合, Markdown 中 email 式的 区块引用 和多段落的 列表 在使用换行来排版的时候,不但更好用,还更方便阅读。

139 | 140 | 141 | 142 |

Markdown 支持两种标题的语法,类 Setext 和类 atx 形式。

143 | 144 |

类 Setext 形式是用底线的形式,利用 = (最高阶标题)和 - (第二阶标题),例如:

145 | 146 |
This is an H1
147 | =============
148 | 
149 | This is an H2
150 | -------------
151 | 
152 | 153 |

任何数量的 =- 都可以有效果。

154 | 155 |

类 Atx 形式则是在行首插入 1 到 6 个 # ,对应到标题 1 到 6 阶,例如:

156 | 157 |
# 这是 H1
158 | 
159 | ## 这是 H2
160 | 
161 | ###### 这是 H6
162 | 
163 | 164 |

你可以选择性地「闭合」类 atx 样式的标题,这纯粹只是美观用的,若是觉得这样看起来比较舒适,你就可以在行尾加上 #,而行尾的 # 数量也不用和开头一样(行首的井字符数量决定标题的阶数):

165 | 166 |
# 这是 H1 #
167 | 
168 | ## 这是 H2 ##
169 | 
170 | ### 这是 H3 ######
171 | 
172 | 173 |

区块引用 Blockquotes

174 | 175 |

Markdown 标记区块引用是使用类似 email 中用 > 的引用方式。如果你还熟悉在 email 信件中的引言部分,你就知道怎么在 Markdown 文件中建立一个区块引用,那会看起来像是你自己先断好行,然后在每行的最前面加上 >

176 | 177 |
> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
178 | > consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
179 | > Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
180 | > 
181 | > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
182 | > id sem consectetuer libero luctus adipiscing.
183 | 
184 | 185 |

Markdown 也允许你偷懒只在整个段落的第一行最前面加上 >

186 | 187 |
> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
188 | consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
189 | Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
190 | 
191 | > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
192 | id sem consectetuer libero luctus adipiscing.
193 | 
194 | 195 |

区块引用可以嵌套(例如:引用内的引用),只要根据层次加上不同数量的 >

196 | 197 |
> This is the first level of quoting.
198 | >
199 | > > This is nested blockquote.
200 | >
201 | > Back to the first level.
202 | 
203 | 204 |

引用的区块内也可以使用其他的 Markdown 语法,包括标题、列表、代码区块等:

205 | 206 |
> ## 这是一个标题。
207 | > 
208 | > 1.   这是第一行列表项。
209 | > 2.   这是第二行列表项。
210 | > 
211 | > 给出一些例子代码:
212 | > 
213 | >     return shell_exec("echo $input | $markdown_script");
214 | 
215 | 216 |

任何像样的文本编辑器都能轻松地建立 email 型的引用。例如在 BBEdit 中,你可以选取文字后然后从选单中选择增加引用阶层

217 | 218 |

列表

219 | 220 |

Markdown 支持有序列表和无序列表。

221 | 222 |

无序列表使用星号、加号或是减号作为列表标记:

223 | 224 |
*   Red
225 | *   Green
226 | *   Blue
227 | 
228 | 229 |

等同于:

230 | 231 |
+   Red
232 | +   Green
233 | +   Blue
234 | 
235 | 236 |

也等同于:

237 | 238 |
-   Red
239 | -   Green
240 | -   Blue
241 | 
242 | 243 |

有序列表则使用数字接着一个英文句点:

244 | 245 |
1.  Bird
246 | 2.  McHale
247 | 3.  Parish
248 | 
249 | 250 |

很重要的一点是,你在列表标记上使用的数字并不会影响输出的 HTML 结果,上面的列表所产生的 HTML 标记为:

251 | 252 |
<ol>
253 | <li>Bird</li>
254 | <li>McHale</li>
255 | <li>Parish</li>
256 | </ol>
257 | 
258 | 259 |

如果你的列表标记写成:

260 | 261 |
1.  Bird
262 | 1.  McHale
263 | 1.  Parish
264 | 
265 | 266 |

或甚至是:

267 | 268 |
3. Bird
269 | 1. McHale
270 | 8. Parish
271 | 
272 | 273 |

你都会得到完全相同的 HTML 输出。重点在于,你可以让 Markdown 文件的列表数字和输出的结果相同,或是你懒一点,你可以完全不用在意数字的正确性。

274 | 275 |

如果你使用懒惰的写法,建议第一个项目最好还是从 1. 开始,因为 Markdown 未来可能会支持有序列表的 start 属性。

276 | 277 |

列表项目标记通常是放在最左边,但是其实也可以缩进,最多 3 个空格,项目标记后面则一定要接着至少一个空格或制表符。

278 | 279 |

要让列表看起来更漂亮,你可以把内容用固定的缩进整理好:

280 | 281 |
*   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
282 |     Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
283 |     viverra nec, fringilla in, laoreet vitae, risus.
284 | *   Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
285 |     Suspendisse id sem consectetuer libero luctus adipiscing.
286 | 
287 | 288 |

但是如果你懒,那也行:

289 | 290 |
*   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
291 | Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
292 | viverra nec, fringilla in, laoreet vitae, risus.
293 | *   Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
294 | Suspendisse id sem consectetuer libero luctus adipiscing.
295 | 
296 | 297 |

如果列表项目间用空行分开,在输出 HTML 时 Markdown 就会将项目内容用 <p> 298 | 标签包起来,举例来说:

299 | 300 |
*   Bird
301 | *   Magic
302 | 
303 | 304 |

会被转换为:

305 | 306 |
<ul>
307 | <li>Bird</li>
308 | <li>Magic</li>
309 | </ul>
310 | 
311 | 312 |

但是这个:

313 | 314 |
*   Bird
315 | 
316 | *   Magic
317 | 
318 | 319 |

会被转换为:

320 | 321 |
<ul>
322 | <li><p>Bird</p></li>
323 | <li><p>Magic</p></li>
324 | </ul>
325 | 
326 | 327 |

列表项目可以包含多个段落,每个项目下的段落都必须缩进 4 个空格或是 1 个制表符:

328 | 329 |
1.  This is a list item with two paragraphs. Lorem ipsum dolor
330 |     sit amet, consectetuer adipiscing elit. Aliquam hendrerit
331 |     mi posuere lectus.
332 | 
333 |     Vestibulum enim wisi, viverra nec, fringilla in, laoreet
334 |     vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
335 |     sit amet velit.
336 | 
337 | 2.  Suspendisse id sem consectetuer libero luctus adipiscing.
338 | 
339 | 340 |

如果你每行都有缩进,看起来会看好很多,当然,再次地,如果你很懒惰,Markdown 也允许:

341 | 342 |
*   This is a list item with two paragraphs.
343 | 
344 |     This is the second paragraph in the list item. You're
345 | only required to indent the first line. Lorem ipsum dolor
346 | sit amet, consectetuer adipiscing elit.
347 | 
348 | *   Another item in the same list.
349 | 
350 | 351 |

如果要在列表项目内放进引用,那 > 就需要缩进:

352 | 353 |
*   A list item with a blockquote:
354 | 
355 |     > This is a blockquote
356 |     > inside a list item.
357 | 
358 | 359 |

如果要放代码区块的话,该区块就需要缩进两次,也就是 8 个空格或是 2 个制表符:

360 | 361 |
*   一列表项包含一个列表区块:
362 | 
363 |         <代码写在这>
364 | 
365 | 366 |

当然,项目列表很可能会不小心产生,像是下面这样的写法:

367 | 368 |
1986. What a great season.
369 | 
370 | 371 |

换句话说,也就是在行首出现数字-句点-空白,要避免这样的状况,你可以在句点前面加上反斜杠。

372 | 373 |
1986\. What a great season.
374 | 
375 | 376 |

代码区块

377 | 378 |

和程序相关的写作或是标签语言原始码通常会有已经排版好的代码区块,通常这些区块我们并不希望它以一般段落文件的方式去排版,而是照原来的样子显示,Markdown 会用 <pre><code> 标签来把代码区块包起来。

379 | 380 |

要在 Markdown 中建立代码区块很简单,只要简单地缩进 4 个空格或是 1 个制表符就可以,例如,下面的输入:

381 | 382 |
这是一个普通段落:
383 | 
384 |     这是一个代码区块。
385 | 
386 | 387 |

Markdown 会转换成:

388 | 389 |
<p>这是一个普通段落:</p>
390 | 
391 | <pre><code>这是一个代码区块。
392 | </code></pre>
393 | 
394 | 395 |

这个每行一阶的缩进(4 个空格或是 1 个制表符),都会被移除,例如:

396 | 397 |
Here is an example of AppleScript:
398 | 
399 |     tell application "Foo"
400 |         beep
401 |     end tell
402 | 
403 | 404 |

会被转换为:

405 | 406 |
<p>Here is an example of AppleScript:</p>
407 | 
408 | <pre><code>tell application "Foo"
409 |     beep
410 | end tell
411 | </code></pre>
412 | 
413 | 414 |

一个代码区块会一直持续到没有缩进的那一行(或是文件结尾)。

415 | 416 |

在代码区块里面, &<> 会自动转成 HTML 实体,这样的方式让你非常容易使用 Markdown 插入范例用的 HTML 原始码,只需要复制贴上,再加上缩进就可以了,剩下的 Markdown 都会帮你处理,例如:

417 | 418 |
    <div class="footer">
419 |         &copy; 2004 Foo Corporation
420 |     </div>
421 | 
422 | 423 |

会被转换为:

424 | 425 |
<pre><code>&lt;div class="footer"&gt;
426 |     &amp;copy; 2004 Foo Corporation
427 | &lt;/div&gt;
428 | </code></pre>
429 | 
430 | 431 |

代码区块中,一般的 Markdown 语法不会被转换,像是星号便只是星号,这表示你可以很容易地以 Markdown 语法撰写 Markdown 语法相关的文件。

432 | 433 |

分隔线

434 | 435 |

你可以在一行中用三个以上的星号、减号、底线来建立一个分隔线,行内不能有其他东西。你也可以在星号或是减号中间插入空格。下面每种写法都可以建立分隔线:

436 | 437 |
* * *
438 | 
439 | ***
440 | 
441 | *****
442 | 
443 | - - -
444 | 
445 | ---------------------------------------
446 | 
447 | 448 |
449 | 450 |

区段元素

451 | 452 | 453 | 454 |

Markdown 支持两种形式的链接语法: 行内式参考式两种形式。

455 | 456 |

不管是哪一种,链接文字都是用 [方括号] 来标记。

457 | 458 |

要建立一个行内式的链接,只要在方块括号后面紧接着圆括号并插入网址链接即可,如果你还想要加上链接的 title 文字,只要在网址后面,用双引号把 title 文字包起来即可,例如:

459 | 460 |
This is [an example](http://example.com/ "Title") inline link.
461 | 
462 | [This link](http://example.net/) has no title attribute.
463 | 
464 | 465 |

会产生:

466 | 467 |
<p>This is <a href="http://example.com/" title="Title">
468 | an example</a> inline link.</p>
469 | 
470 | <p><a href="http://example.net/">This link</a> has no
471 | title attribute.</p>
472 | 
473 | 474 |

如果你是要链接到同样主机的资源,你可以使用相对路径:

475 | 476 |
See my [About](/about/) page for details.
477 | 
478 | 479 |

参考式的链接是在链接文字的括号后面再接上另一个方括号,而在第二个方括号里面要填入用以辨识链接的标记:

480 | 481 |
This is [an example][id] reference-style link.
482 | 
483 | 484 |

你也可以选择性地在两个方括号中间加上一个空格:

485 | 486 |
This is [an example] [id] reference-style link.
487 | 
488 | 489 |

接着,在文件的任意处,你可以把这个标记的链接内容定义出来:

490 | 491 |
[id]: http://example.com/  "Optional Title Here"
492 | 
493 | 494 |

链接内容定义的形式为:

495 | 496 |
    497 |
  • 方括号(前面可以选择性地加上至多三个空格来缩进),里面输入链接文字
  • 498 |
  • 接着一个冒号
  • 499 |
  • 接着一个以上的空格或制表符
  • 500 |
  • 接着链接的网址
  • 501 |
  • 选择性地接着 title 内容,可以用单引号、双引号或是括弧包着
  • 502 |
503 | 504 |

下面这三种链接的定义都是相同:

505 | 506 |
[foo]: http://example.com/  "Optional Title Here"
507 | [foo]: http://example.com/  'Optional Title Here'
508 | [foo]: http://example.com/  (Optional Title Here)
509 | 
510 | 511 |

请注意:有一个已知的问题是 Markdown.pl 1.0.1 会忽略单引号包起来的链接 title。

512 | 513 |

链接网址也可以用方括号包起来:

514 | 515 |
[id]: <http://example.com/>  "Optional Title Here"
516 | 
517 | 518 |

你也可以把 title 属性放到下一行,也可以加一些缩进,若网址太长的话,这样会比较好看:

519 | 520 |
[id]: http://example.com/longish/path/to/resource/here
521 |     "Optional Title Here"
522 | 
523 | 524 |

网址定义只有在产生链接的时候用到,并不会直接出现在文件之中。

525 | 526 |

链接辨别标签可以有字母、数字、空白和标点符号,但是并区分大小写,因此下面两个链接是一样的:

527 | 528 |
[link text][a]
529 | [link text][A]
530 | 
531 | 532 |

隐式链接标记功能让你可以省略指定链接标记,这种情形下,链接标记会视为等同于链接文字,要用隐式链接标记只要在链接文字后面加上一个空的方括号,如果你要让 "Google" 链接到 google.com,你可以简化成:

533 | 534 |
[Google][]
535 | 
536 | 537 |

然后定义链接内容:

538 | 539 |
[Google]: http://google.com/
540 | 
541 | 542 |

由于链接文字可能包含空白,所以这种简化型的标记内也许包含多个单词:

543 | 544 |
Visit [Daring Fireball][] for more information.
545 | 
546 | 547 |

然后接着定义链接:

548 | 549 |
[Daring Fireball]: http://daringfireball.net/
550 | 
551 | 552 |

链接的定义可以放在文件中的任何一个地方,我比较偏好直接放在链接出现段落的后面,你也可以把它放在文件最后面,就像是注解一样。

553 | 554 |

下面是一个参考式链接的范例:

555 | 556 |
I get 10 times more traffic from [Google] [1] than from
557 | [Yahoo] [2] or [MSN] [3].
558 | 
559 |   [1]: http://google.com/        "Google"
560 |   [2]: http://search.yahoo.com/  "Yahoo Search"
561 |   [3]: http://search.msn.com/    "MSN Search"
562 | 
563 | 564 |

如果改成用链接名称的方式写:

565 | 566 |
I get 10 times more traffic from [Google][] than from
567 | [Yahoo][] or [MSN][].
568 | 
569 |   [google]: http://google.com/        "Google"
570 |   [yahoo]:  http://search.yahoo.com/  "Yahoo Search"
571 |   [msn]:    http://search.msn.com/    "MSN Search"
572 | 
573 | 574 |

上面两种写法都会产生下面的 HTML。

575 | 576 |
<p>I get 10 times more traffic from <a href="http://google.com/"
577 | title="Google">Google</a> than from
578 | <a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a>
579 | or <a href="http://search.msn.com/" title="MSN Search">MSN</a>.</p>
580 | 
581 | 582 |

下面是用行内式写的同样一段内容的 Markdown 文件,提供作为比较之用:

583 | 584 |
I get 10 times more traffic from [Google](http://google.com/ "Google")
585 | than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
586 | [MSN](http://search.msn.com/ "MSN Search").
587 | 
588 | 589 |

参考式的链接其实重点不在于它比较好写,而是它比较好读,比较一下上面的范例,使用参考式的文章本身只有 81 个字符,但是用行内形式的却会增加到 176 个字元,如果是用纯 HTML 格式来写,会有 234 个字元,在 HTML 格式中,标签比文本还要多。

590 | 591 |

使用 Markdown 的参考式链接,可以让文件更像是浏览器最后产生的结果,让你可以把一些标记相关的元数据移到段落文字之外,你就可以增加链接而不让文章的阅读感觉被打断。

592 | 593 |

强调

594 | 595 |

Markdown 使用星号(*)和底线(_)作为标记强调字词的符号,被 *_ 包围的字词会被转成用 <em> 标签包围,用两个 *_ 包起来的话,则会被转成 <strong>,例如:

596 | 597 |
*single asterisks*
598 | 
599 | _single underscores_
600 | 
601 | **double asterisks**
602 | 
603 | __double underscores__
604 | 
605 | 606 |

会转成:

607 | 608 |
<em>single asterisks</em>
609 | 
610 | <em>single underscores</em>
611 | 
612 | <strong>double asterisks</strong>
613 | 
614 | <strong>double underscores</strong>
615 | 
616 | 617 |

你可以随便用你喜欢的样式,唯一的限制是,你用什么符号开启标签,就要用什么符号结束。

618 | 619 |

强调也可以直接插在文字中间:

620 | 621 |
un*frigging*believable
622 | 
623 | 624 |

但是如果你的 *_ 两边都有空白的话,它们就只会被当成普通的符号

625 | 626 |

如果要在文字前后直接插入普通的星号或底线,你可以用反斜线:

627 | 628 |
\*this text is surrounded by literal asterisks\*
629 | 
630 | 631 |

代码

632 | 633 |

如果要标记一小段行内代码,你可以用反引号把它包起来(`),例如:

634 | 635 |
Use the `printf()` function.
636 | 
637 | 638 |

会产生:

639 | 640 |
<p>Use the <code>printf()</code> function.</p>
641 | 
642 | 643 |

如果要在代码区段内插入反引号,你可以用多个反引号来开启和结束代码区段:

644 | 645 |
``There is a literal backtick (`) here.``
646 | 
647 | 648 |

这段语法会产生:

649 | 650 |
<p><code>There is a literal backtick (`) here.</code></p>
651 | 
652 | 653 |

代码区段的起始和结束端都可以放入一个空白,起始端后面一个,结束端前面一个,这样你就可以在区段的一开始就插入反引号:

654 | 655 |
A single backtick in a code span: `` ` ``
656 | 
657 | A backtick-delimited string in a code span: `` `foo` ``
658 | 
659 | 660 |

会产生:

661 | 662 |
<p>A single backtick in a code span: <code>`</code></p>
663 | 
664 | <p>A backtick-delimited string in a code span: <code>`foo`</code></p>
665 | 
666 | 667 |

在代码区段内,& 和方括号会被自动地转成 HTML 实体,这使得插入 HTML 原始码变得很容易,Markdown 会把下面这段:

668 | 669 |
Please don't use any `<blink>` tags.
670 | 
671 | 672 |

转为:

673 | 674 |
<p>Please don't use any <code>&lt;blink&gt;</code> tags.</p>
675 | 
676 | 677 |

你也可以这样写:

678 | 679 |
`&#8212;` is the decimal-encoded equivalent of `&mdash;`.
680 | 
681 | 682 |

以产生:

683 | 684 |
<p><code>&amp;#8212;</code> is the decimal-encoded
685 | equivalent of <code>&amp;mdash;</code>.</p>
686 | 
687 | 688 |

图片

689 | 690 |

很明显地,要在纯文字应用中设计一个「自然」的语法来插入图片是有一定难度的。

691 | 692 |

Markdown 使用一种和链接很相似的语法来标记图片,同样也允许两种样式: 行内式参考式

693 | 694 |

行内式的图片语法看起来像是:

695 | 696 |
![Alt text](/path/to/img.jpg)
697 | 
698 | ![Alt text](/path/to/img.jpg "Optional title")
699 | 
700 | 701 |

详细叙述如下:

702 | 703 |
    704 |
  • 一个惊叹号 !
  • 705 |
  • 接着一个方括号,里面放上图片的替代文字
  • 706 |
  • 接着一个普通括号,里面放上图片的网址,最后还可以用引号包住并加上 707 | 选择性的 'title' 文字。
  • 708 |
709 | 710 |

参考式的图片语法则长得像这样:

711 | 712 |
![Alt text][id]
713 | 
714 | 715 |

「id」是图片参考的名称,图片参考的定义方式则和连结参考一样:

716 | 717 |
[id]: url/to/image  "Optional title attribute"
718 | 
719 | 720 |

到目前为止, Markdown 还没有办法指定图片的宽高,如果你需要的话,你可以使用普通的 <img> 标签。

721 | 722 |
723 | 724 |

其它

725 | 726 | 727 | 728 |

Markdown 支持以比较简短的自动链接形式来处理网址和电子邮件信箱,只要是用方括号包起来, Markdown 就会自动把它转成链接。一般网址的链接文字就和链接地址一样,例如:

729 | 730 |
<http://example.com/>
731 | 
732 | 733 |

Markdown 会转为:

734 | 735 |
<a href="http://example.com/">http://example.com/</a>
736 | 
737 | 738 |

邮址的自动链接也很类似,只是 Markdown 会先做一个编码转换的过程,把文字字符转成 16 进位码的 HTML 实体,这样的格式可以糊弄一些不好的邮址收集机器人,例如:

739 | 740 |
<address@example.com>
741 | 
742 | 743 |

Markdown 会转成:

744 | 745 |
<a href="&#x6D;&#x61;i&#x6C;&#x74;&#x6F;:&#x61;&#x64;&#x64;&#x72;&#x65;
746 | &#115;&#115;&#64;&#101;&#120;&#x61;&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;
747 | &#109;">&#x61;&#x64;&#x64;&#x72;&#x65;&#115;&#115;&#64;&#101;&#120;&#x61;
748 | &#109;&#x70;&#x6C;e&#x2E;&#99;&#111;&#109;</a>
749 | 
750 | 751 |

在浏览器里面,这段字串(其实是 <a href="mailto:address@example.com">address@example.com</a>)会变成一个可以点击的「address@example.com」链接。

752 | 753 |

(这种作法虽然可以糊弄不少的机器人,但并不能全部挡下来,不过总比什么都不做好些。不管怎样,公开你的信箱终究会引来广告信件的。)

754 | 755 |

反斜杠

756 | 757 |

Markdown 可以利用反斜杠来插入一些在语法中有其它意义的符号,例如:如果你想要用星号加在文字旁边的方式来做出强调效果(但不用 <em> 标签),你可以在星号的前面加上反斜杠:

758 | 759 |
\*literal asterisks\*
760 | 
761 | 762 |

Markdown 支持以下这些符号前面加上反斜杠来帮助插入普通的符号:

763 | 764 |
\   反斜线
765 | `   反引号
766 | *   星号
767 | _   底线
768 | {}  花括号
769 | []  方括号
770 | ()  括弧
771 | #   井字号
772 | +   加号
773 | -   减号
774 | .   英文句点
775 | !   惊叹号
776 | 
777 | 778 |

感谢

779 | 780 |

感谢 leafy7382 协助翻译,hlbRandylien 帮忙润稿,ethantw汉字标准格式・CSS ResetWM 回报文字错误。

781 | 782 |

感谢 fenpraceaddv

783 | -------------------------------------------------------------------------------- /deploy.sh: -------------------------------------------------------------------------------- 1 | #generate index.html 2 | perl Markdown_1.0.1/Markdown.pl syntax.md > content.html 3 | cat header.html content.html footer.html > index.html 4 | 5 | #generate basic.html 6 | perl Markdown_1.0.1/Markdown.pl basics.md > basic_content.html 7 | cat header.html basic_content.html footer.html > basic.html 8 | 9 | #commit and push to Gitcafe project 10 | #git add . 11 | #git commit -m "update and deploy to http://wowubuntu.com/markdown" 12 | #git push origin 13 | #git push github 14 | -------------------------------------------------------------------------------- /footer.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 |
6 | 7 |
8 | 19 | 20 | blog comments powered by Disqus 21 | 22 |
23 | 24 | 37 | 38 | 39 | 40 | 41 | -------------------------------------------------------------------------------- /header.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Markdown 语法说明(简体中文版) 6 | 7 | 8 | 9 | 10 |
11 | 12 | -------------------------------------------------------------------------------- /index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Markdown 语法说明(简体中文版) 6 | 7 | 8 | 9 | 10 |
11 | 12 |

NOTE: This is Simplelified Chinese Edition Document of Markdown Syntax. If you are seeking for English Edition Document. Please refer to Markdown: Syntax.

13 | 14 |

声明: 这份文档派生(fork)于繁体中文版,在此基础上进行了繁体转简体工作,并进行了适当的润色。此文档用 Markdown 语法编写,你可以到这里查看它的源文件。「繁体中文版的原始文件可以查看这里 。」--By @riku / 本项目托管于 GitCafe

15 | 16 |

注: 本项目同时也托管于 Github 上,请通过 fork+pull request 方式来帮忙改进本项目。

17 | 18 |

Markdown 语法说明 (简体中文版) / (点击查看快速入门)

19 | 20 | 50 | 51 |
52 | 53 |

概述

54 | 55 |

宗旨

56 | 57 |

Markdown 的目标是实现「易读易写」。

58 | 59 |

可读性,无论如何,都是最重要的。一份使用 Markdown 格式撰写的文件应该可以直接以纯文本发布,并且看起来不会像是由许多标签或是格式指令所构成。Markdown 语法受到一些既有 text-to-HTML 格式的影响,包括 SetextatxTextilereStructuredTextGrutatextEtText,而最大灵感来源其实是纯文本电子邮件的格式。

60 | 61 |

总之, Markdown 的语法全由一些符号所组成,这些符号经过精挑细选,其作用一目了然。比如:在文字两旁加上星号,看起来就像*强调*。Markdown 的列表看起来,嗯,就是列表。Markdown 的区块引用看起来就真的像是引用一段文字,就像你曾在电子邮件中见过的那样。

62 | 63 |

兼容 HTML

64 | 65 |

Markdown 语法的目标是:成为一种适用于网络的书写语言。

66 | 67 |

Markdown 不是想要取代 HTML,甚至也没有要和它相近,它的语法种类很少,只对应 HTML 标记的一小部分。Markdown 的构想不是要使得 HTML 文档更容易书写。在我看来, HTML 已经很容易写了。Markdown 的理念是,能让文档更容易读、写和随意改。HTML 是一种发布的格式,Markdown 是一种书写的格式。就这样,Markdown 的格式语法只涵盖纯文本可以涵盖的范围。

68 | 69 |

不在 Markdown 涵盖范围之内的标签,都可以直接在文档里面用 HTML 撰写。不需要额外标注这是 HTML 或是 Markdown;只要直接加标签就可以了。

70 | 71 |

要制约的只有一些 HTML 区块元素――比如 <div><table><pre><p> 等标签,必须在前后加上空行与其它内容区隔开,还要求它们的开始标签与结尾标签不能用制表符或空格来缩进。Markdown 的生成器有足够智能,不会在 HTML 区块标签外加上不必要的 <p> 标签。

72 | 73 |

例子如下,在 Markdown 文件里加上一段 HTML 表格:

74 | 75 |
这是一个普通段落。
 76 | 
 77 | <table>
 78 |     <tr>
 79 |         <td>Foo</td>
 80 |     </tr>
 81 | </table>
 82 | 
 83 | 这是另一个普通段落。
 84 | 
85 | 86 |

请注意,在 HTML 区块标签间的 Markdown 格式语法将不会被处理。比如,你在 HTML 区块内使用 Markdown 样式的*强调*会没有效果。

87 | 88 |

HTML 的区段(行内)标签如 <span><cite><del> 可以在 Markdown 的段落、列表或是标题里随意使用。依照个人习惯,甚至可以不用 Markdown 格式,而直接采用 HTML 标签来格式化。举例说明:如果比较喜欢 HTML 的 <a><img> 标签,可以直接使用这些标签,而不用 Markdown 提供的链接或是图像标签语法。

89 | 90 |

和处在 HTML 区块标签间不同,Markdown 语法在 HTML 区段标签间是有效的。

91 | 92 |

特殊字符自动转换

93 | 94 |

在 HTML 文件中,有两个字符需要特殊处理: <&< 符号用于起始标签,& 符号则用于标记 HTML 实体,如果你只是想要显示这些字符的原型,你必须要使用实体的形式,像是 &lt;&amp;

95 | 96 |

& 字符尤其让网络文档编写者受折磨,如果你要打「AT&T」 ,你必须要写成「AT&amp;T」。而网址中的 & 字符也要转换。比如你要链接到:

97 | 98 |
http://images.google.com/images?num=30&q=larry+bird
 99 | 
100 | 101 |

你必须要把网址转换写为:

102 | 103 |
http://images.google.com/images?num=30&amp;q=larry+bird
104 | 
105 | 106 |

才能放到链接标签的 href 属性里。不用说也知道这很容易忽略,这也可能是 HTML 标准检验所检查到的错误中,数量最多的。

107 | 108 |

Markdown 让你可以自然地书写字符,需要转换的由它来处理好了。如果你使用的 & 字符是 HTML 字符实体的一部分,它会保留原状,否则它会被转换成 &amp;。

109 | 110 |

所以你如果要在文档中插入一个版权符号 ©,你可以这样写:

111 | 112 |
&copy;
113 | 
114 | 115 |

Markdown 会保留它不动。而若你写:

116 | 117 |
AT&T
118 | 
119 | 120 |

Markdown 就会将它转为:

121 | 122 |
AT&amp;T
123 | 
124 | 125 |

类似的状况也会发生在 < 符号上,因为 Markdown 允许 兼容 HTML ,如果你是把 < 符号作为 HTML 标签的定界符使用,那 Markdown 也不会对它做任何转换,但是如果你写:

126 | 127 |
4 < 5
128 | 
129 | 130 |

Markdown 将会把它转换为:

131 | 132 |
4 &lt; 5
133 | 
134 | 135 |

不过需要注意的是,code 范围内,不论是行内还是区块, <& 两个符号都一定会被转换成 HTML 实体,这项特性让你可以很容易地用 Markdown 写 HTML code (和 HTML 相对而言, HTML 语法中,你要把所有的 <& 都转换为 HTML 实体,才能在 HTML 文件里面写出 HTML code。)

136 | 137 |
138 | 139 |

区块元素

140 | 141 |

段落和换行

142 | 143 |

一个 Markdown 段落是由一个或多个连续的文本行组成,它的前后要有一个以上的空行(空行的定义是显示上看起来像是空的,便会被视为空行。比方说,若某一行只包含空格和制表符,则该行也会被视为空行)。普通段落不该用空格或制表符来缩进。

144 | 145 |

「由一个或多个连续的文本行组成」这句话其实暗示了 Markdown 允许段落内的强迫换行(插入换行符),这个特性和其他大部分的 text-to-HTML 格式不一样(包括 Movable Type 的「Convert Line Breaks」选项),其它的格式会把每个换行符都转成 <br /> 标签。

146 | 147 |

如果你确实想要依赖 Markdown 来插入 <br /> 标签的话,在插入处先按入两个以上的空格然后回车。

148 | 149 |

的确,需要多费点事(多加空格)来产生 <br /> ,但是简单地「每个换行都转换为 <br />」的方法在 Markdown 中并不适合, Markdown 中 email 式的 区块引用 和多段落的 列表 在使用换行来排版的时候,不但更好用,还更方便阅读。

150 | 151 | 152 | 153 |

Markdown 支持两种标题的语法,类 Setext 和类 atx 形式。

154 | 155 |

类 Setext 形式是用底线的形式,利用 = (最高阶标题)和 - (第二阶标题),例如:

156 | 157 |
This is an H1
158 | =============
159 | 
160 | This is an H2
161 | -------------
162 | 
163 | 164 |

任何数量的 =- 都可以有效果。

165 | 166 |

类 Atx 形式则是在行首插入 1 到 6 个 # ,对应到标题 1 到 6 阶,例如:

167 | 168 |
# 这是 H1
169 | 
170 | ## 这是 H2
171 | 
172 | ###### 这是 H6
173 | 
174 | 175 |

你可以选择性地「闭合」类 atx 样式的标题,这纯粹只是美观用的,若是觉得这样看起来比较舒适,你就可以在行尾加上 #,而行尾的 # 数量也不用和开头一样(行首的井字符数量决定标题的阶数):

176 | 177 |
# 这是 H1 #
178 | 
179 | ## 这是 H2 ##
180 | 
181 | ### 这是 H3 ######
182 | 
183 | 184 |

区块引用 Blockquotes

185 | 186 |

Markdown 标记区块引用是使用类似 email 中用 > 的引用方式。如果你还熟悉在 email 信件中的引言部分,你就知道怎么在 Markdown 文件中建立一个区块引用,那会看起来像是你自己先断好行,然后在每行的最前面加上 >

187 | 188 |
> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
189 | > consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
190 | > Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
191 | > 
192 | > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
193 | > id sem consectetuer libero luctus adipiscing.
194 | 
195 | 196 |

Markdown 也允许你偷懒只在整个段落的第一行最前面加上 >

197 | 198 |
> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
199 | consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
200 | Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
201 | 
202 | > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
203 | id sem consectetuer libero luctus adipiscing.
204 | 
205 | 206 |

区块引用可以嵌套(例如:引用内的引用),只要根据层次加上不同数量的 >

207 | 208 |
> This is the first level of quoting.
209 | >
210 | > > This is nested blockquote.
211 | >
212 | > Back to the first level.
213 | 
214 | 215 |

引用的区块内也可以使用其他的 Markdown 语法,包括标题、列表、代码区块等:

216 | 217 |
> ## 这是一个标题。
218 | > 
219 | > 1.   这是第一行列表项。
220 | > 2.   这是第二行列表项。
221 | > 
222 | > 给出一些例子代码:
223 | > 
224 | >     return shell_exec("echo $input | $markdown_script");
225 | 
226 | 227 |

任何像样的文本编辑器都能轻松地建立 email 型的引用。例如在 BBEdit 中,你可以选取文字后然后从选单中选择增加引用阶层

228 | 229 |

列表

230 | 231 |

Markdown 支持有序列表和无序列表。

232 | 233 |

无序列表使用星号、加号或是减号作为列表标记:

234 | 235 |
*   Red
236 | *   Green
237 | *   Blue
238 | 
239 | 240 |

等同于:

241 | 242 |
+   Red
243 | +   Green
244 | +   Blue
245 | 
246 | 247 |

也等同于:

248 | 249 |
-   Red
250 | -   Green
251 | -   Blue
252 | 
253 | 254 |

有序列表则使用数字接着一个英文句点:

255 | 256 |
1.  Bird
257 | 2.  McHale
258 | 3.  Parish
259 | 
260 | 261 |

很重要的一点是,你在列表标记上使用的数字并不会影响输出的 HTML 结果,上面的列表所产生的 HTML 标记为:

262 | 263 |
<ol>
264 | <li>Bird</li>
265 | <li>McHale</li>
266 | <li>Parish</li>
267 | </ol>
268 | 
269 | 270 |

如果你的列表标记写成:

271 | 272 |
1.  Bird
273 | 1.  McHale
274 | 1.  Parish
275 | 
276 | 277 |

或甚至是:

278 | 279 |
3. Bird
280 | 1. McHale
281 | 8. Parish
282 | 
283 | 284 |

你都会得到完全相同的 HTML 输出。重点在于,你可以让 Markdown 文件的列表数字和输出的结果相同,或是你懒一点,你可以完全不用在意数字的正确性。

285 | 286 |

如果你使用懒惰的写法,建议第一个项目最好还是从 1. 开始,因为 Markdown 未来可能会支持有序列表的 start 属性。

287 | 288 |

列表项目标记通常是放在最左边,但是其实也可以缩进,最多 3 个空格,项目标记后面则一定要接着至少一个空格或制表符。

289 | 290 |

要让列表看起来更漂亮,你可以把内容用固定的缩进整理好:

291 | 292 |
*   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
293 |     Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
294 |     viverra nec, fringilla in, laoreet vitae, risus.
295 | *   Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
296 |     Suspendisse id sem consectetuer libero luctus adipiscing.
297 | 
298 | 299 |

但是如果你懒,那也行:

300 | 301 |
*   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
302 | Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
303 | viverra nec, fringilla in, laoreet vitae, risus.
304 | *   Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
305 | Suspendisse id sem consectetuer libero luctus adipiscing.
306 | 
307 | 308 |

如果列表项目间用空行分开,在输出 HTML 时 Markdown 就会将项目内容用 <p> 309 | 标签包起来,举例来说:

310 | 311 |
*   Bird
312 | *   Magic
313 | 
314 | 315 |

会被转换为:

316 | 317 |
<ul>
318 | <li>Bird</li>
319 | <li>Magic</li>
320 | </ul>
321 | 
322 | 323 |

但是这个:

324 | 325 |
*   Bird
326 | 
327 | *   Magic
328 | 
329 | 330 |

会被转换为:

331 | 332 |
<ul>
333 | <li><p>Bird</p></li>
334 | <li><p>Magic</p></li>
335 | </ul>
336 | 
337 | 338 |

列表项目可以包含多个段落,每个项目下的段落都必须缩进 4 个空格或是 1 个制表符:

339 | 340 |
1.  This is a list item with two paragraphs. Lorem ipsum dolor
341 |     sit amet, consectetuer adipiscing elit. Aliquam hendrerit
342 |     mi posuere lectus.
343 | 
344 |     Vestibulum enim wisi, viverra nec, fringilla in, laoreet
345 |     vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
346 |     sit amet velit.
347 | 
348 | 2.  Suspendisse id sem consectetuer libero luctus adipiscing.
349 | 
350 | 351 |

如果你每行都有缩进,看起来会看好很多,当然,再次地,如果你很懒惰,Markdown 也允许:

352 | 353 |
*   This is a list item with two paragraphs.
354 | 
355 |     This is the second paragraph in the list item. You're
356 | only required to indent the first line. Lorem ipsum dolor
357 | sit amet, consectetuer adipiscing elit.
358 | 
359 | *   Another item in the same list.
360 | 
361 | 362 |

如果要在列表项目内放进引用,那 > 就需要缩进:

363 | 364 |
*   A list item with a blockquote:
365 | 
366 |     > This is a blockquote
367 |     > inside a list item.
368 | 
369 | 370 |

如果要放代码区块的话,该区块就需要缩进两次,也就是 8 个空格或是 2 个制表符:

371 | 372 |
*   一列表项包含一个列表区块:
373 | 
374 |         <代码写在这>
375 | 
376 | 377 |

当然,项目列表很可能会不小心产生,像是下面这样的写法:

378 | 379 |
1986. What a great season.
380 | 
381 | 382 |

换句话说,也就是在行首出现数字-句点-空白,要避免这样的状况,你可以在句点前面加上反斜杠。

383 | 384 |
1986\. What a great season.
385 | 
386 | 387 |

代码区块

388 | 389 |

和程序相关的写作或是标签语言原始码通常会有已经排版好的代码区块,通常这些区块我们并不希望它以一般段落文件的方式去排版,而是照原来的样子显示,Markdown 会用 <pre><code> 标签来把代码区块包起来。

390 | 391 |

要在 Markdown 中建立代码区块很简单,只要简单地缩进 4 个空格或是 1 个制表符就可以,例如,下面的输入:

392 | 393 |
这是一个普通段落:
394 | 
395 |     这是一个代码区块。
396 | 
397 | 398 |

Markdown 会转换成:

399 | 400 |
<p>这是一个普通段落:</p>
401 | 
402 | <pre><code>这是一个代码区块。
403 | </code></pre>
404 | 
405 | 406 |

这个每行一阶的缩进(4 个空格或是 1 个制表符),都会被移除,例如:

407 | 408 |
Here is an example of AppleScript:
409 | 
410 |     tell application "Foo"
411 |         beep
412 |     end tell
413 | 
414 | 415 |

会被转换为:

416 | 417 |
<p>Here is an example of AppleScript:</p>
418 | 
419 | <pre><code>tell application "Foo"
420 |     beep
421 | end tell
422 | </code></pre>
423 | 
424 | 425 |

一个代码区块会一直持续到没有缩进的那一行(或是文件结尾)。

426 | 427 |

在代码区块里面, &<> 会自动转成 HTML 实体,这样的方式让你非常容易使用 Markdown 插入范例用的 HTML 原始码,只需要复制贴上,再加上缩进就可以了,剩下的 Markdown 都会帮你处理,例如:

428 | 429 |
    <div class="footer">
430 |         &copy; 2004 Foo Corporation
431 |     </div>
432 | 
433 | 434 |

会被转换为:

435 | 436 |
<pre><code>&lt;div class="footer"&gt;
437 |     &amp;copy; 2004 Foo Corporation
438 | &lt;/div&gt;
439 | </code></pre>
440 | 
441 | 442 |

代码区块中,一般的 Markdown 语法不会被转换,像是星号便只是星号,这表示你可以很容易地以 Markdown 语法撰写 Markdown 语法相关的文件。

443 | 444 |

分隔线

445 | 446 |

你可以在一行中用三个以上的星号、减号、底线来建立一个分隔线,行内不能有其他东西。你也可以在星号或是减号中间插入空格。下面每种写法都可以建立分隔线:

447 | 448 |
* * *
449 | 
450 | ***
451 | 
452 | *****
453 | 
454 | - - -
455 | 
456 | ---------------------------------------
457 | 
458 | 459 |
460 | 461 |

区段元素

462 | 463 | 464 | 465 |

Markdown 支持两种形式的链接语法: 行内式参考式两种形式。

466 | 467 |

不管是哪一种,链接文字都是用 [方括号] 来标记。

468 | 469 |

要建立一个行内式的链接,只要在方块括号后面紧接着圆括号并插入网址链接即可,如果你还想要加上链接的 title 文字,只要在网址后面,用双引号把 title 文字包起来即可,例如:

470 | 471 |
This is [an example](http://example.com/ "Title") inline link.
472 | 
473 | [This link](http://example.net/) has no title attribute.
474 | 
475 | 476 |

会产生:

477 | 478 |
<p>This is <a href="http://example.com/" title="Title">
479 | an example</a> inline link.</p>
480 | 
481 | <p><a href="http://example.net/">This link</a> has no
482 | title attribute.</p>
483 | 
484 | 485 |

如果你是要链接到同样主机的资源,你可以使用相对路径:

486 | 487 |
See my [About](/about/) page for details.
488 | 
489 | 490 |

参考式的链接是在链接文字的括号后面再接上另一个方括号,而在第二个方括号里面要填入用以辨识链接的标记:

491 | 492 |
This is [an example][id] reference-style link.
493 | 
494 | 495 |

你也可以选择性地在两个方括号中间加上一个空格:

496 | 497 |
This is [an example] [id] reference-style link.
498 | 
499 | 500 |

接着,在文件的任意处,你可以把这个标记的链接内容定义出来:

501 | 502 |
[id]: http://example.com/  "Optional Title Here"
503 | 
504 | 505 |

链接内容定义的形式为:

506 | 507 |
    508 |
  • 方括号(前面可以选择性地加上至多三个空格来缩进),里面输入链接文字
  • 509 |
  • 接着一个冒号
  • 510 |
  • 接着一个以上的空格或制表符
  • 511 |
  • 接着链接的网址
  • 512 |
  • 选择性地接着 title 内容,可以用单引号、双引号或是括弧包着
  • 513 |
514 | 515 |

下面这三种链接的定义都是相同:

516 | 517 |
[foo]: http://example.com/  "Optional Title Here"
518 | [foo]: http://example.com/  'Optional Title Here'
519 | [foo]: http://example.com/  (Optional Title Here)
520 | 
521 | 522 |

请注意:有一个已知的问题是 Markdown.pl 1.0.1 会忽略单引号包起来的链接 title。

523 | 524 |

链接网址也可以用方括号包起来:

525 | 526 |
[id]: <http://example.com/>  "Optional Title Here"
527 | 
528 | 529 |

你也可以把 title 属性放到下一行,也可以加一些缩进,若网址太长的话,这样会比较好看:

530 | 531 |
[id]: http://example.com/longish/path/to/resource/here
532 |     "Optional Title Here"
533 | 
534 | 535 |

网址定义只有在产生链接的时候用到,并不会直接出现在文件之中。

536 | 537 |

链接辨别标签可以有字母、数字、空白和标点符号,但是并区分大小写,因此下面两个链接是一样的:

538 | 539 |
[link text][a]
540 | [link text][A]
541 | 
542 | 543 |

隐式链接标记功能让你可以省略指定链接标记,这种情形下,链接标记会视为等同于链接文字,要用隐式链接标记只要在链接文字后面加上一个空的方括号,如果你要让 "Google" 链接到 google.com,你可以简化成:

544 | 545 |
[Google][]
546 | 
547 | 548 |

然后定义链接内容:

549 | 550 |
[Google]: http://google.com/
551 | 
552 | 553 |

由于链接文字可能包含空白,所以这种简化型的标记内也许包含多个单词:

554 | 555 |
Visit [Daring Fireball][] for more information.
556 | 
557 | 558 |

然后接着定义链接:

559 | 560 |
[Daring Fireball]: http://daringfireball.net/
561 | 
562 | 563 |

链接的定义可以放在文件中的任何一个地方,我比较偏好直接放在链接出现段落的后面,你也可以把它放在文件最后面,就像是注解一样。

564 | 565 |

下面是一个参考式链接的范例:

566 | 567 |
I get 10 times more traffic from [Google] [1] than from
568 | [Yahoo] [2] or [MSN] [3].
569 | 
570 |   [1]: http://google.com/        "Google"
571 |   [2]: http://search.yahoo.com/  "Yahoo Search"
572 |   [3]: http://search.msn.com/    "MSN Search"
573 | 
574 | 575 |

如果改成用链接名称的方式写:

576 | 577 |
I get 10 times more traffic from [Google][] than from
578 | [Yahoo][] or [MSN][].
579 | 
580 |   [google]: http://google.com/        "Google"
581 |   [yahoo]:  http://search.yahoo.com/  "Yahoo Search"
582 |   [msn]:    http://search.msn.com/    "MSN Search"
583 | 
584 | 585 |

上面两种写法都会产生下面的 HTML。

586 | 587 |
<p>I get 10 times more traffic from <a href="http://google.com/"
588 | title="Google">Google</a> than from
589 | <a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a>
590 | or <a href="http://search.msn.com/" title="MSN Search">MSN</a>.</p>
591 | 
592 | 593 |

下面是用行内式写的同样一段内容的 Markdown 文件,提供作为比较之用:

594 | 595 |
I get 10 times more traffic from [Google](http://google.com/ "Google")
596 | than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
597 | [MSN](http://search.msn.com/ "MSN Search").
598 | 
599 | 600 |

参考式的链接其实重点不在于它比较好写,而是它比较好读,比较一下上面的范例,使用参考式的文章本身只有 81 个字符,但是用行内形式的却会增加到 176 个字元,如果是用纯 HTML 格式来写,会有 234 个字元,在 HTML 格式中,标签比文本还要多。

601 | 602 |

使用 Markdown 的参考式链接,可以让文件更像是浏览器最后产生的结果,让你可以把一些标记相关的元数据移到段落文字之外,你就可以增加链接而不让文章的阅读感觉被打断。

603 | 604 |

强调

605 | 606 |

Markdown 使用星号(*)和底线(_)作为标记强调字词的符号,被 *_ 包围的字词会被转成用 <em> 标签包围,用两个 *_ 包起来的话,则会被转成 <strong>,例如:

607 | 608 |
*single asterisks*
609 | 
610 | _single underscores_
611 | 
612 | **double asterisks**
613 | 
614 | __double underscores__
615 | 
616 | 617 |

会转成:

618 | 619 |
<em>single asterisks</em>
620 | 
621 | <em>single underscores</em>
622 | 
623 | <strong>double asterisks</strong>
624 | 
625 | <strong>double underscores</strong>
626 | 
627 | 628 |

你可以随便用你喜欢的样式,唯一的限制是,你用什么符号开启标签,就要用什么符号结束。

629 | 630 |

强调也可以直接插在文字中间:

631 | 632 |
un*frigging*believable
633 | 
634 | 635 |

但是如果你的 *_ 两边都有空白的话,它们就只会被当成普通的符号

636 | 637 |

如果要在文字前后直接插入普通的星号或底线,你可以用反斜线:

638 | 639 |
\*this text is surrounded by literal asterisks\*
640 | 
641 | 642 |

代码

643 | 644 |

如果要标记一小段行内代码,你可以用反引号把它包起来(`),例如:

645 | 646 |
Use the `printf()` function.
647 | 
648 | 649 |

会产生:

650 | 651 |
<p>Use the <code>printf()</code> function.</p>
652 | 
653 | 654 |

如果要在代码区段内插入反引号,你可以用多个反引号来开启和结束代码区段:

655 | 656 |
``There is a literal backtick (`) here.``
657 | 
658 | 659 |

这段语法会产生:

660 | 661 |
<p><code>There is a literal backtick (`) here.</code></p>
662 | 
663 | 664 |

代码区段的起始和结束端都可以放入一个空白,起始端后面一个,结束端前面一个,这样你就可以在区段的一开始就插入反引号:

665 | 666 |
A single backtick in a code span: `` ` ``
667 | 
668 | A backtick-delimited string in a code span: `` `foo` ``
669 | 
670 | 671 |

会产生:

672 | 673 |
<p>A single backtick in a code span: <code>`</code></p>
674 | 
675 | <p>A backtick-delimited string in a code span: <code>`foo`</code></p>
676 | 
677 | 678 |

在代码区段内,& 和方括号会被自动地转成 HTML 实体,这使得插入 HTML 原始码变得很容易,Markdown 会把下面这段:

679 | 680 |
Please don't use any `<blink>` tags.
681 | 
682 | 683 |

转为:

684 | 685 |
<p>Please don't use any <code>&lt;blink&gt;</code> tags.</p>
686 | 
687 | 688 |

你也可以这样写:

689 | 690 |
`&#8212;` is the decimal-encoded equivalent of `&mdash;`.
691 | 
692 | 693 |

以产生:

694 | 695 |
<p><code>&amp;#8212;</code> is the decimal-encoded
696 | equivalent of <code>&amp;mdash;</code>.</p>
697 | 
698 | 699 |

图片

700 | 701 |

很明显地,要在纯文字应用中设计一个「自然」的语法来插入图片是有一定难度的。

702 | 703 |

Markdown 使用一种和链接很相似的语法来标记图片,同样也允许两种样式: 行内式参考式

704 | 705 |

行内式的图片语法看起来像是:

706 | 707 |
![Alt text](/path/to/img.jpg)
708 | 
709 | ![Alt text](/path/to/img.jpg "Optional title")
710 | 
711 | 712 |

详细叙述如下:

713 | 714 |
    715 |
  • 一个惊叹号 !
  • 716 |
  • 接着一个方括号,里面放上图片的替代文字
  • 717 |
  • 接着一个普通括号,里面放上图片的网址,最后还可以用引号包住并加上 718 | 选择性的 'title' 文字。
  • 719 |
720 | 721 |

参考式的图片语法则长得像这样:

722 | 723 |
![Alt text][id]
724 | 
725 | 726 |

「id」是图片参考的名称,图片参考的定义方式则和连结参考一样:

727 | 728 |
[id]: url/to/image  "Optional title attribute"
729 | 
730 | 731 |

到目前为止, Markdown 还没有办法指定图片的宽高,如果你需要的话,你可以使用普通的 <img> 标签。

732 | 733 |
734 | 735 |

其它

736 | 737 | 738 | 739 |

Markdown 支持以比较简短的自动链接形式来处理网址和电子邮件信箱,只要是用方括号包起来, Markdown 就会自动把它转成链接。一般网址的链接文字就和链接地址一样,例如:

740 | 741 |
<http://example.com/>
742 | 
743 | 744 |

Markdown 会转为:

745 | 746 |
<a href="http://example.com/">http://example.com/</a>
747 | 
748 | 749 |

邮址的自动链接也很类似,只是 Markdown 会先做一个编码转换的过程,把文字字符转成 16 进位码的 HTML 实体,这样的格式可以糊弄一些不好的邮址收集机器人,例如:

750 | 751 |
<address@example.com>
752 | 
753 | 754 |

Markdown 会转成:

755 | 756 |
<a href="&#x6D;&#x61;i&#x6C;&#x74;&#x6F;:&#x61;&#x64;&#x64;&#x72;&#x65;
757 | &#115;&#115;&#64;&#101;&#120;&#x61;&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;
758 | &#109;">&#x61;&#x64;&#x64;&#x72;&#x65;&#115;&#115;&#64;&#101;&#120;&#x61;
759 | &#109;&#x70;&#x6C;e&#x2E;&#99;&#111;&#109;</a>
760 | 
761 | 762 |

在浏览器里面,这段字串(其实是 <a href="mailto:address@example.com">address@example.com</a>)会变成一个可以点击的「address@example.com」链接。

763 | 764 |

(这种作法虽然可以糊弄不少的机器人,但并不能全部挡下来,不过总比什么都不做好些。不管怎样,公开你的信箱终究会引来广告信件的。)

765 | 766 |

反斜杠

767 | 768 |

Markdown 可以利用反斜杠来插入一些在语法中有其它意义的符号,例如:如果你想要用星号加在文字旁边的方式来做出强调效果(但不用 <em> 标签),你可以在星号的前面加上反斜杠:

769 | 770 |
\*literal asterisks\*
771 | 
772 | 773 |

Markdown 支持以下这些符号前面加上反斜杠来帮助插入普通的符号:

774 | 775 |
\   反斜线
776 | `   反引号
777 | *   星号
778 | _   底线
779 | {}  花括号
780 | []  方括号
781 | ()  括弧
782 | #   井字号
783 | +   加号
784 | -   减号
785 | .   英文句点
786 | !   惊叹号
787 | 
788 | 789 |

感谢

790 | 791 |

感谢 leafy7382 协助翻译,hlbRandylien 帮忙润稿,ethantw汉字标准格式・CSS ResetWM 回报文字错误。

792 | 793 |

感谢 fenpraceaddv

794 | 795 | 796 |
797 | 798 |
799 | 800 |
801 | 812 | 813 | blog comments powered by Disqus 814 | 815 |
816 | 817 | 818 | 819 | -------------------------------------------------------------------------------- /makrdown.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | syntax 7 | 8 | 9 | 10 | 11 | 12 | 13 |
14 | 15 |

NOTE: This is Simplelified Chinese Edition Document of Markdown Syntax. If you are seeking for English Edition Document. Please refer to Markdown: Syntax.

16 |

Markdown 语法 (简体中文版)

17 | 47 |

注意: 这份文档派生于繁体中文版,在此基础上进行了繁体转简体工作,并进行了适当的润色。此文档用 Markdown 语法编写,你可以到这里查看它的源文件

48 |

注意:繁体中文版的原始文件可以查看这里

49 |
50 |

概述

51 | 52 |

哲学

53 | 54 |

Markdown 的目标是实现「易读易写」。

55 |

不过最需要强调的便是它的可读性。一份使用 Markdown 格式撰写的文件应该可以直接以纯文本发布,并且看起来不会像是由许多标签或是格式指令所构成。Markdown 语法受到一些既有 text-to-HTML 格式的影响,包括 SetextatxTextilereStructuredTextGrutatextEtText,然而最大灵感来源其实是纯文字的电子邮件格式。

56 |

因此 Markdown 的语法全由标点符号所组成,并经过严谨慎选,是为了让它们看起来就像所要表达的意思。像是在文字两旁加上星号,看起来就像*强调*。Markdown 的清单看起来,嗯,就是清单。假如你有使用过电子邮件,区块引言看起来就真的像是引用一段文字。

57 |

行内 HTML

58 | 59 |

Markdown 的语法有个主要的目的:用来作为一种网路内容的写作用语言。

60 |

Markdown 不是要来取代 HTML,甚至也没有要和它相似,它的语法种类不多,只和 HTML 的一部分有关系,重点不是要创造一种更容易写作 HTML 文件的语法,我认为 HTML 已经很容易写了,Markdown 的重点在于,它能让文件更容易阅读、编写。HTML 是一种发布的格式,Markdown 是一种编写的格式,因此,Markdown 的格式语法只涵盖纯文字可以涵盖的范围。

61 |

不在 Markdown 涵盖范围之外的标签,都可以直接在文件里面用 HTML 撰写。不需要额外标注这是 HTML 或是 Markdown;只要直接加标签就可以了。

62 |

只有区块元素――比如 <div><table><pre><p> 等标签,必需在前后加上空白,以利与内容区隔。而且这些(元素)的开始与结尾标签,不可以用 tab 或是空白来缩排。Markdown 的产生器有智慧型判断,可以避免在区块标签前后加上没有必要的 <p> 标签。

63 |

举例来说,在 Markdown 文件里加上一段 HTML 表格:

64 |
This is a regular paragraph.
 65 | 
 66 | <table>
 67 |     <tr>
 68 |         <td>Foo</td>
 69 |     </tr>
 70 | </table>
 71 | 
 72 | This is another regular paragraph.
 73 | 
74 |

请注意,Markdown 语法在 HTML 区块标签中将不会被进行处理。例如,你无法在 HTML 区块内使用 Markdown 形式的*强调*

75 |

HTML 的区段标签如 <span><cite><del> 则不受限制,可以在 Markdown 的段落、清单或是标题里任意使用。依照个人习惯,甚至可以不用Markdown 格式,而采用 HTML 标签来格式化。举例说明:如果比较喜欢 HTML 的 <a><img> 标签,可以直接使用这些标签,而不用 Markdown 提供的连结或是影像标示语法。

76 |

HTML 区段标签和区块标签不同,在区段标签的范围内, Markdown 的语法是有效的。

77 |

特殊字元自动转换

78 | 79 |

在 HTML 文件中,有两个字元需要特殊处理: <&< 符号用于起始标签,& 符号则用于标记 HTML 实体,如果你只是想要使用这些符号,你必须要使用实体的形式,像是 &lt;&amp;

80 |

& 符号其实很让写作网路文件的人感到困扰,如果你要打「AT&T」 ,你必须要写成「AT&amp;T」 ,还得转换网址内的 & 符号,如果你要连结到:

81 |
http://images.google.com/images?num=30&q=larry+bird
 82 | 
83 |

你必须要把网址转成:

84 |
http://images.google.com/images?num=30&amp;q=larry+bird
 85 | 
86 |

才能放到连结标签的 href 属性里。不用说也知道这很容易忘记,这也可能是 HTML 标准检查所检查到的错误中,数量最多的。

87 |

Markdown 允许你直接使用这些符号,但是你要小心跳脱字元的使用,如果你是在HTML 实体中使用 & 符号的话,它不会被转换,而在其它情形下,它则会被转换成 &amp;。所以你如果要在文件中插入一个着作权的符号,你可以这样写:

88 |
&copy;
 89 | 
90 |

Markdown 将不会对这段文字做修改,但是如果你这样写:

91 |
AT&T
 92 | 
93 |

Markdown 就会将它转为:

94 |
AT&amp;T
 95 | 
96 |

类似的状况也会发生在 < 符号上,因为 Markdown 支援 行内 HTML ,如果你是使用 < 符号作为 HTML 标签使用,那 Markdown 也不会对它做任何转换,但是如果你是写:

97 |
4 < 5
 98 | 
99 |

Markdown 将会把它转换为:

100 |
4 &lt; 5
101 | 
102 |

不过需要注意的是,code 范围内,不论是行内还是区块, <& 两个符号都一定会被转换成 HTML 实体,这项特性让你可以很容易地用 Markdown 写 HTML code (和 HTML 相对而言, HTML 语法中,你要把所有的 <& 都转换为 HTML 实体,才能在 HTML 文件里面写出 HTML code。)

103 |
104 |

区块元素

105 | 106 |

段落和换行

107 | 108 |

一个段落是由一个以上相连接的行句组成,而一个以上的空行则会切分出不同的段落(空行的定义是显示上看起来像是空行,便会被视为空行。比方说,若某一行只包含空白和 tab,则该行也会被视为空行),一般的段落不需要用空白或断行缩排。

109 |

「一个以上相连接的行句组成」这句话其实暗示了 Markdown 允许段落内的强迫断行,这个特性和其他大部分的 text-to-HTML 格式不一样(包括 MovableType 的「Convert Line Breaks」选项),其它的格式会把每个断行都转成 <br /> 标签。

110 |

如果你真的想要插入 <br /> 标签的话,在行尾加上两个以上的空白,然后按 enter。

111 |

是的,这确实需要花比较多功夫来插入 <br /> ,但是「每个换行都转换为 <br />」的方法在 Markdown 中并不适合, Markdown 中 email 式的 区块引言 和多段落的 清单 在使用换行来排版的时候,不但更好用,还更好阅读。

112 | 113 | 114 |

Markdown 支援两种标题的语法,Setextatx 形式。

115 |

Setext 形式是用底线的形式,利用 = (最高阶标题)和 - (第二阶标题),例如:

116 |
This is an H1
117 | =============
118 | 
119 | This is an H2
120 | -------------
121 | 
122 |

任何数量的 =- 都可以有效果。

123 |

Atx 形式则是在行首插入 1 到 6 个 # ,对应到标题 1 到 6 阶,例如:

124 |
# This is an H1
125 | 
126 | ## This is an H2
127 | 
128 | ###### This is an H6
129 | 
130 |

你可以选择性地「关闭」atx 样式的标题,这纯粹只是美观用的,若是觉得这样看起来比较舒适,你就可以在行尾加上 #,而行尾的 # 数量也不用和开头一样(行首的井字数量决定标题的阶数):

131 |
# This is an H1 #
132 | 
133 | ## This is an H2 ##
134 | 
135 | ### This is an H3 ######
136 | 
137 |

Blockquotes

138 | 139 |

Markdown 使用 email 形式的区块引言,如果你很熟悉如何在 email 信件中引言,你就知道怎么在 Markdown 文件中建立一个区块引言,那会看起来像是你强迫断行,然后在每行的最前面加上 >

140 |
> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
141 | > consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
142 | > Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
143 | > 
144 | > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
145 | > id sem consectetuer libero luctus adipiscing.
146 | 
147 |

Markdown 也允许你只在整个段落的第一行最前面加上 >

148 |
> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
149 | consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
150 | Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
151 | 
152 | > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
153 | id sem consectetuer libero luctus adipiscing.
154 | 
155 |

区块引言可以有阶层(例如:引言内的引言),只要根据层数加上不同数量的 >

156 |
> This is the first level of quoting.
157 | >
158 | > > This is nested blockquote.
159 | >
160 | > Back to the first level.
161 | 
162 |

引言的区块内也可以使用其他的 Markdown 语法,包括标题、清单、程式码区块等:

163 |
> ## This is a header.
164 | > 
165 | > 1.   This is the first list item.
166 | > 2.   This is the second list item.
167 | > 
168 | > Here's some example code:
169 | > 
170 | >     return shell_exec("echo $input | $markdown_script");
171 | 
172 |

任何标准的文字编辑器都能简单地建立 email 样式的引言,例如 BBEdit ,你可以选取文字后然后从选单中选择增加引言阶层

173 |

清单

174 | 175 |

Markdown 支援有序清单和无序清单。

176 |

无序清单使用星号、加号或是减号作为清单标记:

177 |
*   Red
178 | *   Green
179 | *   Blue
180 | 
181 |

等同于:

182 |
+   Red
183 | +   Green
184 | +   Blue
185 | 
186 |

也等同于:

187 |
-   Red
188 | -   Green
189 | -   Blue
190 | 
191 |

有序清单则使用数字接着一个英文句点:

192 |
1.  Bird
193 | 2.  McHale
194 | 3.  Parish
195 | 
196 |

很重要的一点是,你在清单标记上使用的数字并不会影响输出的 HTML 结果,上面的清单所产生的 HTML 标记为:

197 |
<ol>
198 | <li>Bird</li>
199 | <li>McHale</li>
200 | <li>Parish</li>
201 | </ol>
202 | 
203 |

如果你的清单标记写成:

204 |
1.  Bird
205 | 1.  McHale
206 | 1.  Parish
207 | 
208 |

或甚至是:

209 |
3. Bird
210 | 1. McHale
211 | 8. Parish
212 | 
213 |

你都会得到完全相同的 HTML 输出。重点在于,你可以让 Markdown 文件的清单数字和输出的结果相同,或是你懒一点,你可以完全不用在意数字的正确性。

214 |

如果你使用懒惰的写法,建议第一个项目最好还是从 1. 开始,因为 Markdown 未来可能会支援有序清单的 start 属性。

215 |

清单项目标记通常是放在最左边,但是其实也可以缩排,最多三个空白,项目标记后面则一定要接着至少一个空白或 tab。

216 |

要让清单看起来更漂亮,你可以把内容用固定的缩排整理好:

217 |
*   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
218 |     Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
219 |     viverra nec, fringilla in, laoreet vitae, risus.
220 | *   Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
221 |     Suspendisse id sem consectetuer libero luctus adipiscing.
222 | 
223 |

但是如果你很懒,那也不一定需要:

224 |
*   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
225 | Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
226 | viverra nec, fringilla in, laoreet vitae, risus.
227 | *   Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
228 | Suspendisse id sem consectetuer libero luctus adipiscing.
229 | 
230 |

如果清单项目间用空行分开, Markdown 会把项目的内容在输出时用 <p> 231 | 标签包起来,举例来说:

232 |
*   Bird
233 | *   Magic
234 | 
235 |

会被转换为:

236 |
<ul>
237 | <li>Bird</li>
238 | <li>Magic</li>
239 | </ul>
240 | 
241 |

但是这个:

242 |
*   Bird
243 | 
244 | *   Magic
245 | 
246 |

会被转换为:

247 |
<ul>
248 | <li><p>Bird</p></li>
249 | <li><p>Magic</p></li>
250 | </ul>
251 | 
252 |

清单项目可以包含多个段落,每个项目下的段落都必须缩排 4 个空白或是一个 tab :

253 |
1.  This is a list item with two paragraphs. Lorem ipsum dolor
254 |     sit amet, consectetuer adipiscing elit. Aliquam hendrerit
255 |     mi posuere lectus.
256 | 
257 |     Vestibulum enim wisi, viverra nec, fringilla in, laoreet
258 |     vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
259 |     sit amet velit.
260 | 
261 | 2.  Suspendisse id sem consectetuer libero luctus adipiscing.
262 | 
263 |

如果你每行都有缩排,看起来会看好很多,当然,再次地,如果你很懒惰,Markdown 也允许:

264 |
*   This is a list item with two paragraphs.
265 | 
266 |     This is the second paragraph in the list item. You're
267 | only required to indent the first line. Lorem ipsum dolor
268 | sit amet, consectetuer adipiscing elit.
269 | 
270 | *   Another item in the same list.
271 | 
272 |

如果要在清单项目内放进引言,那 > 就需要缩排:

273 |
*   A list item with a blockquote:
274 | 
275 |     > This is a blockquote
276 |     > inside a list item.
277 | 
278 |

如果要放程式码区块的话,该区块就需要缩排两次,也就是 8 个空白或是两个 tab:

279 |
*   A list item with a code block:
280 | 
281 |         <code goes here>
282 | 
283 |

当然,项目清单很可能会不小心产生,像是下面这样的写法:

284 |
1986. What a great season.
285 | 
286 |

换句话说,也就是在行首出现数字-句点-空白,要避免这样的状况,你可以在句点前面加上反斜线。

287 |
1986\. What a great season.
288 | 
289 |

程式码区块

290 | 291 |

和程式相关的写作或是标签语言原始码通常会有已经排版好的程式码区块,通常这些区块我们并不希望它以一般段落文件的方式去排版,而是照原来的样子显示,Markdown 会用 <pre><code> 标签来把程式码区块包起来。

292 |

要在 Markdown 中建立程式码区块很简单,只要简单地缩排 4 个空白或是 1 个 tab 就可以,例如,下面的输入:

293 |
This is a normal paragraph:
294 | 
295 |     This is a code block.
296 | 
297 |

Markdown 会转换成:

298 |
<p>This is a normal paragraph:</p>
299 | 
300 | <pre><code>This is a code block.
301 | </code></pre>
302 | 
303 |

这个每行一阶的缩排(4 个空白或是 1 个 tab),都会被移除,例如:

304 |
Here is an example of AppleScript:
305 | 
306 |     tell application "Foo"
307 |         beep
308 |     end tell
309 | 
310 |

会被转换为:

311 |
<p>Here is an example of AppleScript:</p>
312 | 
313 | <pre><code>tell application "Foo"
314 |     beep
315 | end tell
316 | </code></pre>
317 | 
318 |

一个程式码区块会一直持续到没有缩排的那一行(或是文件结尾)。

319 |

在程式码区块里面, &<> 会自动转成 HTML 实体,这样的方式让你非常容易使用 Markdown 插入范例用的 HTML 原始码,只需要复制贴上,再加上缩排就可以了,剩下的 Markdown 都会帮你处理,例如:

320 |
    <div class="footer">
321 |         &copy; 2004 Foo Corporation
322 |     </div>
323 | 
324 |

会被转换为:

325 |
<pre><code>&lt;div class="footer"&gt;
326 |     &amp;copy; 2004 Foo Corporation
327 | &lt;/div&gt;
328 | </code></pre>
329 | 
330 |

程式码区块中,一般的 Markdown 语法不会被转换,像是星号便只是星号,这表示你可以很容易地以 Markdown 语法撰写 Markdown 语法相关的文件。

331 |

分隔线

332 | 333 |

你可以在一行中用三个或以上的星号、减号、底线来建立一个分隔线,行内不能有其他东西。你也可以在星号中间插入空白。下面每种写法都可以建立分隔线:

334 |
* * *
335 | 
336 | ***
337 | 
338 | *****
339 | 
340 | - - -
341 | 
342 | ---------------------------------------
343 | 
344 |
345 |

区段元素

346 | 347 | 348 | 349 |

Markdown 支援两种形式的连结语法: 行内参考两种形式。

350 |

不管是哪一种,连结的文字都是用 [方括号] 来标记。

351 |

要建立一个行内形式的连结,只要在方块括号后面马上接着括号并插入网址连结即可,如果你还想要加上连结的 title 文字,只要在网址后面,用双引号把 title 文字包起来即可,例如:

352 |
This is [an example](http://example.com/ "Title") inline link.
353 | 
354 | [This link](http://example.net/) has no title attribute.
355 | 
356 |

会产生:

357 |
<p>This is <a href="http://example.com/" title="Title">
358 | an example</a> inline link.</p>
359 | 
360 | <p><a href="http://example.net/">This link</a> has no
361 | title attribute.</p>
362 | 
363 |

如果你是要连结到同样主机的资源,你可以使用相对路径:

364 |
See my [About](/about/) page for details.
365 | 
366 |

参考形式的连结使用另外一个方括号接在连结文字的括号后面,而在第二个方括号里面要填入用以辨识连结的标签:

367 |
This is [an example][id] reference-style link.
368 | 
369 |

你也可以选择性地在两个方括号中间加上空白:

370 |
This is [an example] [id] reference-style link.
371 | 
372 |

接着,在文件的任意处,你可以把这个标签的连结内容定义出来:

373 |
[id]: http://example.com/  "Optional Title Here"
374 | 
375 |

连结定义的形式为:

376 |
    377 |
  • 方括号,里面输入连结的辨识用标签
  • 378 |
  • 接着一个冒号
  • 379 |
  • 接着一个以上的空白或 tab
  • 380 |
  • 接着连结的网址
  • 381 |
  • 选择性地接着 title 内容,可以用单引号、双引号或是括弧包着
  • 382 |
383 |

下面这三种连结的定义都是相同:

384 |
[foo]: http://example.com/  "Optional Title Here"
385 | [foo]: http://example.com/  'Optional Title Here'
386 | [foo]: http://example.com/  (Optional Title Here)
387 | 
388 |

请注意:有一个已知的问题是 Markdown.pl 1.0.1 会忽略单引号包起来的连结 title。

389 |

连结网址也可以用方括号包起来:

390 |
[id]: <http://example.com/>  "Optional Title Here"
391 | 
392 |

你也可以把 title 属性放到下一行,也可以加一些缩排,网址太长的话,这样会比较好看:

393 |
[id]: http://example.com/longish/path/to/resource/here
394 |     "Optional Title Here"
395 | 
396 |

网址定义只有在产生连结的时候用到,并不会直接出现在文件之中。

397 |

连结辨识标签可以有字母、数字、空白和标点符号,但是并区分大小写,因此下面两个连结是一样的:

398 |
[link text][a]
399 | [link text][A]
400 | 
401 |

预设的连结标签功能让你可以省略指定连结标签,这种情形下,连结标签和连结文字会视为相同,要用预设连结标签只要在连结文字后面加上一个空的方括号,如果你要让 "Google" 连结到 google.com,你可以简化成:

402 |
[Google][]
403 | 
404 |

然后定义连结内容:

405 |
[Google]: http://google.com/
406 | 
407 |

由于连结文字可能包含空白,所以这种简化的标签内也可以包含多个文字:

408 |
Visit [Daring Fireball][] for more information.
409 | 
410 |

然后接着定义连结:

411 |
[Daring Fireball]: http://daringfireball.net/
412 | 
413 |

连结的定义可以放在文件中的任何一个地方,我比较偏好直接放在连结出现段落的后面,你也可以把它放在文件最后面,就像是注解一样。

414 |

下面是一个参考式连结的范例:

415 |
I get 10 times more traffic from [Google] [1] than from
416 | [Yahoo] [2] or [MSN] [3].
417 | 
418 |   [1]: http://google.com/        "Google"
419 |   [2]: http://search.yahoo.com/  "Yahoo Search"
420 |   [3]: http://search.msn.com/    "MSN Search"
421 | 
422 |

如果改成用连结名称的方式写:

423 |
I get 10 times more traffic from [Google][] than from
424 | [Yahoo][] or [MSN][].
425 | 
426 |   [google]: http://google.com/        "Google"
427 |   [yahoo]:  http://search.yahoo.com/  "Yahoo Search"
428 |   [msn]:    http://search.msn.com/    "MSN Search"
429 | 
430 |

上面两种写法都会产生下面的 HTML。

431 |
<p>I get 10 times more traffic from <a href="http://google.com/"
432 | title="Google">Google</a> than from
433 | <a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a>
434 | or <a href="http://search.msn.com/" title="MSN Search">MSN</a>.</p>
435 | 
436 |

下面是用行内形式写的同样一段内容的 Markdown 文件,提供作为比较之用:

437 |
I get 10 times more traffic from [Google](http://google.com/ "Google")
438 | than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
439 | [MSN](http://search.msn.com/ "MSN Search").
440 | 
441 |

参考式的连结其实重点不在于它比较好写,而是它比较好读,比较一下上面的范例,使用参考式的文章本身只有 81 个字元,但是用行内形式的连结却会增加到 176 个字元,如果是用纯 HTML 格式来写,会有 234 个字元,在 HTML 格式中,标签比文字还要多。

442 |

使用 Markdown 的参考式连结,可以让文件更像是浏览器最后产生的结果,让你可以把一些标记相关的资讯移到段落文字之外,你就可以增加连结而不让文章的阅读感觉被打断。

443 |

强调

444 | 445 |

Markdown 使用星号(*)和底线(_)作为标记强调字词的符号,被 *_ 包围的字词会被转成用 <em> 标签包围,用两个 *_ 包起来的话,则会被转成 <strong>,例如:

446 |
*single asterisks*
447 | 
448 | _single underscores_
449 | 
450 | **double asterisks**
451 | 
452 | __double underscores__
453 | 
454 |

会转成:

455 |
<em>single asterisks</em>
456 | 
457 | <em>single underscores</em>
458 | 
459 | <strong>double asterisks</strong>
460 | 
461 | <strong>double underscores</strong>
462 | 
463 |

你可以随便用你喜欢的样式,唯一的限制是,你用什么符号开启标签,就要用什么符号结束。

464 |

强调也可以直接插在文字中间:

465 |
un*frigging*believable
466 | 
467 |

但是如果你的 *_ 两边都有空白的话,它们就只会被当成普通的符号。

468 |

如果要在文字前后直接插入普通的星号或底线,你可以用反斜线:

469 |
\*this text is surrounded by literal asterisks\*
470 | 
471 |

程式码

472 | 473 |

如果要标记一小段行内程式码,你可以用反引号把它包起来(`),例如:

474 |
Use the `printf()` function.
475 | 
476 |

会产生:

477 |
<p>Use the <code>printf()</code> function.</p>
478 | 
479 |

如果要在程式码区段内插入反引号,你可以用多个反引号来开启和结束程式码区段:

480 |
``There is a literal backtick (`) here.``
481 | 
482 |

这段语法会产生:

483 |
<p><code>There is a literal backtick (`) here.</code></p>
484 | 
485 |

程式码区段的起始和结束端都可以放入一个空白,起始端后面一个,结束端前面一个,这样你就可以在区段的一开始就插入反引号:

486 |
A single backtick in a code span: `` ` ``
487 | 
488 | A backtick-delimited string in a code span: `` `foo` ``
489 | 
490 |

会产生:

491 |
<p>A single backtick in a code span: <code>`</code></p>
492 | 
493 | <p>A backtick-delimited string in a code span: <code>`foo`</code></p>
494 | 
495 |

在程式码区段内,& 和方括号都会被转成 HTML 实体,这样会比较容易插入 HTML 原始码,Markdown 会把下面这段:

496 |
Please don't use any `<blink>` tags.
497 | 
498 |

转为:

499 |
<p>Please don't use any <code>&lt;blink&gt;</code> tags.</p>
500 | 
501 |

你也可以这样写:

502 |
`&#8212;` is the decimal-encoded equivalent of `&mdash;`.
503 | 
504 |

以产生:

505 |
<p><code>&amp;#8212;</code> is the decimal-encoded
506 | equivalent of <code>&amp;mdash;</code>.</p>
507 | 
508 |

图片

509 | 510 |

很明显地,要在纯文字应用中设计一个 「自然」的语法来插入图片是有一定难度的。

511 |

Markdown 使用一种和连结很相似的语法来标记图片,同样也允许两种样式: 行内参考

512 |

行内图片的语法看起来像是:

513 |
![Alt text](/path/to/img.jpg)
514 | 
515 | ![Alt text](/path/to/img.jpg "Optional title")
516 | 
517 |

详细叙述如下:

518 |
    519 |
  • 一个惊叹号 !
  • 520 |
  • 接着一个方括号,里面放上图片的替代文字
  • 521 |
  • 接着一个普通括号,里面放上图片的网址,最后还可以用引号包住并加上 522 | 选择性的 'title' 文字。
  • 523 |
524 |

参考式的图片语法则长得像这样:

525 |
![Alt text][id]
526 | 
527 |

「id」是图片参考的名称,图片参考的定义方式则和连结参考一样:

528 |
[id]: url/to/image  "Optional title attribute"
529 | 
530 |

到目前为止, Markdown 还没有办法指定图片的宽高,如果你需要的话,你可以使用普通的 <img> 标签。

531 |
532 |

其它

533 | 534 | 535 | 536 |

Markdown 支援比较简短的自动连结形式来处理网址和电子邮件信箱,只要是用方括号包起来, Markdown 就会自动把它转成连结,连结的文字就和连结位置一样,例如:

537 |
<http://example.com/>
538 | 
539 |

Markdown 会转为:

540 |
<a href="http://example.com/">http://example.com/</a>
541 | 
542 |

自动的邮件连结也很类似,只是 Markdown 会先做一个编码转换的过程,把文字字元转成 16 进位码的 HTML 实体,这样的格式可以混淆一些不好的信箱地址收集机器人,例如:

543 |
<address@example.com>
544 | 
545 |

Markdown 会转成:

546 |
<a href="&#x6D;&#x61;i&#x6C;&#x74;&#x6F;:&#x61;&#x64;&#x64;&#x72;&#x65;
547 | &#115;&#115;&#64;&#101;&#120;&#x61;&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;
548 | &#109;">&#x61;&#x64;&#x64;&#x72;&#x65;&#115;&#115;&#64;&#101;&#120;&#x61;
549 | &#109;&#x70;&#x6C;e&#x2E;&#99;&#111;&#109;</a>
550 | 
551 |

在浏览器里面,这段字串会变成一个可以点击的「address@example.com」连结。

552 |

(这种作法虽然可以混淆不少的机器人,但并无法全部挡下来,不过这样也比什么都不做好些。无论如何,公开你的信箱终究会引来广告信件的。)

553 |

跳脱字元

554 | 555 |

Markdown 可以利用反斜线来插入一些在语法中有其它意义的符号,例如:如果你想要用星号加在文字旁边的方式来做出强调效果(但不用 <em> 标签),你可以在星号的前面加上反斜线:

556 |
\*literal asterisks\*
557 | 
558 |

Markdown 支援在下面这些符号前面加上反斜线来帮助插入普通的符号:

559 |
\   反斜线
560 | `   反引号
561 | *   星号
562 | _   底线
563 | {}  大括号
564 | []  方括号
565 | ()  括号
566 | #   井字号
567 | +   加号
568 | -   减号
569 | .   英文句点
570 | !   惊叹号
571 | 
572 |

感谢

573 | 574 |

感谢 leafy7382 协助翻译,hlbRandylien 帮忙润稿,ethantw汉字标准格式・CSS ResetWM 回报文字错误。

575 | 576 |
577 | 578 | 579 | 580 | -------------------------------------------------------------------------------- /stylesheets/main.css: -------------------------------------------------------------------------------- 1 | html { 2 | font-family: sans-serif; 3 | } 4 | 5 | html.hasFontSmoothing-true { 6 | font-family: "微軟正黑體", "Microsoft JhengHei", sans-serif; 7 | } 8 | 9 | body { 10 | padding: 1em; 11 | } 12 | div.wikistyle, #comments{ 13 | width:960px; 14 | margin: 0 auto; 15 | } 16 | #comments { 17 | margin-top: 1em; 18 | } 19 | div.wikistyle, #comments{background-color:#f8f8f8;padding:.7em;} 20 | div.wikistyle, #comments{border:1px solid #e9e9e9;} 21 | 22 | .wikistyle h1,.wikistyle h2,.wikistyle h3,.wikistyle h4,.wikistyle h5,.wikistyle h6{border:0!important;} 23 | .wikistyle h1{font-size:170%!important;border-top:4px solid #aaa!important;padding-top:.5em!important;margin-top:1.5em!important;} 24 | .wikistyle h1:first-child{margin-top:0!important;padding-top:.25em!important;border-top:none!important;} 25 | .wikistyle h2{font-size:150%!important;margin-top:1.5em!important;border-top:4px solid #e0e0e0!important;padding-top:.5em!important;} 26 | .wikistyle h3{margin-top:1em!important;} 27 | .wikistyle p{margin:1em 0!important;line-height:1.5em!important;} 28 | .wikistyle a.absent{color:#a00;} 29 | .wikistyle ul,#wiki-form .content-body ul{margin:1em 0 1em 2em!important;} 30 | .wikistyle ol,#wiki-form .content-body ol{margin:1em 0 1em 2em!important;} 31 | .wikistyle ul li,#wiki-form .content-body ul li,.wikistyle ol li,#wiki-form .content-body ol li{margin-top:.5em;margin-bottom:.5em;} 32 | .wikistyle ul ul,.wikistyle ul ol,.wikistyle ol ol,.wikistyle ol ul,#wiki-form .content-body ul ul,#wiki-form .content-body ul ol,#wiki-form .content-body ol ol,#wiki-form .content-body ol ul{margin-top:0!important;margin-bottom:0!important;} 33 | .wikistyle blockquote{margin:1em 0!important;border-left:5px solid #ddd!important;padding-left:.6em!important;color:#555!important;} 34 | .wikistyle dt{font-weight:bold!important;margin-left:1em!important;} 35 | .wikistyle dd{margin-left:2em!important;margin-bottom:1em!important;} 36 | .wikistyle table{margin:1em 0!important;} 37 | .wikistyle table th{border-bottom:1px solid #bbb!important;padding:.2em 1em!important;} 38 | .wikistyle table td{border-bottom:1px solid #ddd!important;padding:.2em 1em!important;} 39 | .wikistyle pre{margin:1em 0;font-size:12px;background-color:#eee;border:1px solid #ddd;padding:5px;line-height:1.5em;color:#444;overflow:auto;-webkit-box-shadow:rgba(0,0,0,0.07) 0 1px 2px inset;-webkit-border-radius:3px;-moz-border-radius:3px;border-radius:3px;} 40 | .wikistyle pre::-webkit-scrollbar{height:8px;width:8px;} 41 | .wikistyle pre::-webkit-scrollbar-track-piece{margin-bottom:10px;background-color:#e5e5e5;border-bottom-left-radius:4px 4px;border-bottom-right-radius:4px 4px;border-top-left-radius:4px 4px;border-top-right-radius:4px 4px;} 42 | .wikistyle pre::-webkit-scrollbar-thumb:vertical{height:25px;background-color:#ccc;-webkit-border-radius:4px;-webkit-box-shadow:0 1px 1px rgba(255,255,255,1);} 43 | .wikistyle pre::-webkit-scrollbar-thumb:horizontal{width:25px;background-color:#ccc;-webkit-border-radius:4px;} 44 | .wikistyle pre code{padding:0!important;font-size:12px!important;background-color:#eee!important;border:none!important;} 45 | .wikistyle code{font-size:14px!important;background-color:#f8f8ff!important;color:#444!important;padding:0 .2em!important;border:1px solid #dedede!important;} 46 | .wikistyle a code,.wikistyle a:link code,.wikistyle a:visited code{color:#4183c4!important;} 47 | .wikistyle img{max-width:100%;} 48 | .wikistyle pre.console{margin:1em 0!important;font-size:12px!important;background-color:black!important;padding:.5em!important;line-height:1.5em!important;color:white!important;} 49 | .wikistyle pre.console code{padding:0!important;font-size:12px!important;background-color:black!important;border:none!important;color:white!important;} 50 | .wikistyle pre.console span{color:#888!important;} 51 | .wikistyle pre.console span.command{color:yellow!important;} 52 | .wikistyle .frame{margin:0;display:inline-block;} 53 | .wikistyle .frame img{display:block;} 54 | .wikistyle .frame>span{display:block;border:1px solid #aaa;padding:4px;} 55 | .wikistyle .frame span span{display:block;font-size:10pt;margin:0;padding:4px 0 2px 0;text-align:center;line-height:10pt;font-family:'Helvetica Neue',Helvetica,Arial,sans-serif;} 56 | .wikistyle .float-left{float:left;padding:.5em 1em .25em 0;} 57 | .wikistyle .float-right{float:right;padding:.5em 0 .25em 1em;} 58 | .wikistyle .align-left{display:block;text-align:left;} 59 | .wikistyle .align-center{display:block;text-align:center;} 60 | .wikistyle .align-right{display:block;text-align:right;} 61 | -------------------------------------------------------------------------------- /syntax.md: -------------------------------------------------------------------------------- 1 | << [访问 Wow!Ubuntu](http://wowubuntu.com) 2 | 3 | **NOTE:** This is Simplelified Chinese Edition Document of Markdown Syntax. If you are seeking for English Edition Document. Please refer to [Markdown: Syntax][eng-doc]. 4 | 5 | [eng-doc]:http://daringfireball.net/projects/markdown/syntax 6 | 7 | **声明:** 这份文档派生(fork)于[繁体中文版](http://markdown.tw/),在此基础上进行了繁体转简体工作,并进行了适当的润色。此文档用 Markdown 语法编写,你可以到这里[查看它的源文件][src1]。「繁体中文版的原始文件可以[查看这里][src] 。」--By @[riku][t] 8 | 9 | **注:** 本项目托管于 [GitCafe][]上,请通过"派生"和"合并请求"来帮忙改进本项目。 10 | 11 | [src1]: http://gitcafe.com/riku/Markdown-Syntax-CN/blob/master/syntax.md 12 | [src]: https://github.com/othree/markdown-syntax-zhtw/blob/master/syntax.md 13 | [t]: http://twitter.com/riku 14 | [g]: http://gitcafe.com/riku/Markdown-Syntax-CN 15 | [Github]: https://github.com/riku/Markdown-Syntax-CN 16 | [GitCafe]: http://gitcafe.com/riku/Markdown-Syntax-CN/ 17 | 18 | Markdown 语法说明 (简体中文版) / ([点击查看快速入门](./basic.html)) 19 | ================ 20 | 21 | * [概述](#overview) 22 | * [宗旨](#philosophy) 23 | * [兼容 HTML](#html) 24 | * [特殊字符自动转换](#autoescape) 25 | * [区块元素](#block) 26 | * [段落和换行](#p) 27 | * [标题](#header) 28 | * [区块引用](#blockquote) 29 | * [列表](#list) 30 | * [代码区块](#precode) 31 | * [分隔线](#hr) 32 | * [区段元素](#span) 33 | * [链接](#link) 34 | * [强调](#em) 35 | * [代码](#code) 36 | * [图片](#img) 37 | * [其它](#misc) 38 | * [反斜杠](#backslash) 39 | * [自动链接](#autolink) 40 | * [感谢](#acknowledgement) 41 | * [Markdown 免费编辑器](#editor) 42 | 43 | * * * 44 | 45 |

概述

46 | 47 |

宗旨

48 | 49 | Markdown 的目标是实现「易读易写」。 50 | 51 | 可读性,无论如何,都是最重要的。一份使用 Markdown 格式撰写的文件应该可以直接以纯文本发布,并且看起来不会像是由许多标签或是格式指令所构成。Markdown 语法受到一些既有 text-to-HTML 格式的影响,包括 [Setext] [1]、[atx] [2]、[Textile] [3]、[reStructuredText] [4]、[Grutatext] [5] 和 [EtText] [6],而最大灵感来源其实是纯文本电子邮件的格式。 52 | 53 | [1]: http://docutils.sourceforge.net/mirror/setext.html 54 | [2]: http://www.aaronsw.com/2002/atx/ 55 | [3]: http://textism.com/tools/textile/ 56 | [4]: http://docutils.sourceforge.net/rst.html 57 | [5]: http://www.triptico.com/software/grutatxt.html 58 | [6]: http://ettext.taint.org/doc/ 59 | 60 | 总之, Markdown 的语法全由一些符号所组成,这些符号经过精挑细选,其作用一目了然。比如:在文字两旁加上星号,看起来就像\*强调\*。Markdown 的列表看起来,嗯,就是列表。Markdown 的区块引用看起来就真的像是引用一段文字,就像你曾在电子邮件中见过的那样。 61 | 62 |

兼容 HTML

63 | 64 | Markdown 语法的目标是:成为一种适用于网络的*书写*语言。 65 | 66 | Markdown 不是想要取代 HTML,甚至也没有要和它相近,它的语法种类很少,只对应 HTML 标记的一小部分。Markdown 的构想*不是*要使得 HTML 文档更容易书写。在我看来, HTML 已经很容易写了。Markdown 的理念是,能让文档更容易读、写和随意改。HTML 是一种*发布*的格式,Markdown 是一种*书写*的格式。就这样,Markdown 的格式语法只涵盖纯文本可以涵盖的范围。 67 | 68 | 不在 Markdown 涵盖范围之内的标签,都可以直接在文档里面用 HTML 撰写。不需要额外标注这是 HTML 或是 Markdown;只要直接加标签就可以了。 69 | 70 | 要制约的只有一些 HTML 区块元素――比如 `
`、``、`
`、`

` 等标签,必须在前后加上空行与其它内容区隔开,还要求它们的开始标签与结尾标签不能用制表符或空格来缩进。Markdown 的生成器有足够智能,不会在 HTML 区块标签外加上不必要的 `

` 标签。 71 | 72 | 例子如下,在 Markdown 文件里加上一段 HTML 表格: 73 | 74 | 这是一个普通段落。 75 | 76 |

77 | 78 | 79 | 80 |
Foo
81 | 82 | 这是另一个普通段落。 83 | 84 | 请注意,在 HTML 区块标签间的 Markdown 格式语法将不会被处理。比如,你在 HTML 区块内使用 Markdown 样式的`*强调*`会没有效果。 85 | 86 | HTML 的区段(行内)标签如 ``、``、`` 可以在 Markdown 的段落、列表或是标题里随意使用。依照个人习惯,甚至可以不用 Markdown 格式,而直接采用 HTML 标签来格式化。举例说明:如果比较喜欢 HTML 的 `` 或 `` 标签,可以直接使用这些标签,而不用 Markdown 提供的链接或是图像标签语法。 87 | 88 | 和处在 HTML 区块标签间不同,Markdown 语法在 HTML 区段标签间是有效的。 89 | 90 |

特殊字符自动转换

91 | 92 | 在 HTML 文件中,有两个字符需要特殊处理: `<` 和 `&` 。 `<` 符号用于起始标签,`&` 符号则用于标记 HTML 实体,如果你只是想要显示这些字符的原型,你必须要使用实体的形式,像是 `<` 和 `&`。 93 | 94 | `&` 字符尤其让网络文档编写者受折磨,如果你要打「`AT&T`」 ,你必须要写成「`AT&T`」。而网址中的 `&` 字符也要转换。比如你要链接到: 95 | 96 | http://images.google.com/images?num=30&q=larry+bird 97 | 98 | 你必须要把网址转换写为: 99 | 100 | http://images.google.com/images?num=30&q=larry+bird 101 | 102 | 才能放到链接标签的 `href` 属性里。不用说也知道这很容易忽略,这也可能是 HTML 标准检验所检查到的错误中,数量最多的。 103 | 104 | Markdown 让你可以自然地书写字符,需要转换的由它来处理好了。如果你使用的 `&` 字符是 HTML 字符实体的一部分,它会保留原状,否则它会被转换成 `&`;。 105 | 106 | 所以你如果要在文档中插入一个版权符号 `©`,你可以这样写: 107 | 108 | © 109 | 110 | Markdown 会保留它不动。而若你写: 111 | 112 | AT&T 113 | 114 | Markdown 就会将它转为: 115 | 116 | AT&T 117 | 118 | 类似的状况也会发生在 `<` 符号上,因为 Markdown 允许 [兼容 HTML](#html) ,如果你是把 `<` 符号作为 HTML 标签的定界符使用,那 Markdown 也不会对它做任何转换,但是如果你写: 119 | 120 | 4 < 5 121 | 122 | Markdown 将会把它转换为: 123 | 124 | 4 < 5 125 | 126 | 不过需要注意的是,code 范围内,不论是行内还是区块, `<` 和 `&` 两个符号都*一定*会被转换成 HTML 实体,这项特性让你可以很容易地用 Markdown 写 HTML code (和 HTML 相对而言, HTML 语法中,你要把所有的 `<` 和 `&` 都转换为 HTML 实体,才能在 HTML 文件里面写出 HTML code。) 127 | 128 | * * * 129 | 130 |

区块元素

131 | 132 | 133 |

段落和换行

134 | 135 | 一个 Markdown 段落是由一个或多个连续的文本行组成,它的前后要有一个以上的空行(空行的定义是显示上看起来像是空的,便会被视为空行。比方说,若某一行只包含空格和制表符,则该行也会被视为空行)。普通段落不该用空格或制表符来缩进。 136 | 137 | 「由一个或多个连续的文本行组成」这句话其实暗示了 Markdown 允许段落内的强迫换行(插入换行符),这个特性和其他大部分的 text-to-HTML 格式不一样(包括 Movable Type 的「Convert Line Breaks」选项),其它的格式会把每个换行符都转成 `
` 标签。 138 | 139 | 如果你*确实*想要依赖 Markdown 来插入 `
` 标签的话,在插入处先按入两个以上的空格然后回车。 140 | 141 | 的确,需要多费点事(多加空格)来产生 `
` ,但是简单地「每个换行都转换为 `
`」的方法在 Markdown 中并不适合, Markdown 中 email 式的 [区块引用][bq] 和多段落的 [列表][l] 在使用换行来排版的时候,不但更好用,还更方便阅读。 142 | 143 | [bq]: #blockquote 144 | [l]: #list 145 | 146 | 147 | 148 | Markdown 支持两种标题的语法,类 [Setext] [1] 和类 [atx] [2] 形式。 149 | 150 | 类 Setext 形式是用底线的形式,利用 `=` (最高阶标题)和 `-` (第二阶标题),例如: 151 | 152 | This is an H1 153 | ============= 154 | 155 | This is an H2 156 | ------------- 157 | 158 | 任何数量的 `=` 和 `-` 都可以有效果。 159 | 160 | 类 Atx 形式则是在行首插入 1 到 6 个 `#` ,对应到标题 1 到 6 阶,例如: 161 | 162 | # 这是 H1 163 | 164 | ## 这是 H2 165 | 166 | ###### 这是 H6 167 | 168 | 你可以选择性地「闭合」类 atx 样式的标题,这纯粹只是美观用的,若是觉得这样看起来比较舒适,你就可以在行尾加上 `#`,而行尾的 `#` 数量也不用和开头一样(行首的井字符数量决定标题的阶数): 169 | 170 | # 这是 H1 # 171 | 172 | ## 这是 H2 ## 173 | 174 | ### 这是 H3 ###### 175 | 176 | 177 |

区块引用 Blockquotes

178 | 179 | Markdown 标记区块引用是使用类似 email 中用 `>` 的引用方式。如果你还熟悉在 email 信件中的引言部分,你就知道怎么在 Markdown 文件中建立一个区块引用,那会看起来像是你自己先断好行,然后在每行的最前面加上 `>` : 180 | 181 | > This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, 182 | > consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. 183 | > Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus. 184 | > 185 | > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse 186 | > id sem consectetuer libero luctus adipiscing. 187 | 188 | Markdown 也允许你偷懒只在整个段落的第一行最前面加上 `>` : 189 | 190 | > This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, 191 | consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. 192 | Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus. 193 | 194 | > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse 195 | id sem consectetuer libero luctus adipiscing. 196 | 197 | 区块引用可以嵌套(例如:引用内的引用),只要根据层次加上不同数量的 `>` : 198 | 199 | > This is the first level of quoting. 200 | > 201 | > > This is nested blockquote. 202 | > 203 | > Back to the first level. 204 | 205 | 引用的区块内也可以使用其他的 Markdown 语法,包括标题、列表、代码区块等: 206 | 207 | > ## 这是一个标题。 208 | > 209 | > 1. 这是第一行列表项。 210 | > 2. 这是第二行列表项。 211 | > 212 | > 给出一些例子代码: 213 | > 214 | > return shell_exec("echo $input | $markdown_script"); 215 | 216 | 任何像样的文本编辑器都能轻松地建立 email 型的引用。例如在 BBEdit 中,你可以选取文字后然后从选单中选择*增加引用阶层*。 217 | 218 |

列表

219 | 220 | Markdown 支持有序列表和无序列表。 221 | 222 | 无序列表使用星号、加号或是减号作为列表标记: 223 | 224 | * Red 225 | * Green 226 | * Blue 227 | 228 | 等同于: 229 | 230 | + Red 231 | + Green 232 | + Blue 233 | 234 | 也等同于: 235 | 236 | - Red 237 | - Green 238 | - Blue 239 | 240 | 有序列表则使用数字接着一个英文句点: 241 | 242 | 1. Bird 243 | 2. McHale 244 | 3. Parish 245 | 246 | 很重要的一点是,你在列表标记上使用的数字并不会影响输出的 HTML 结果,上面的列表所产生的 HTML 标记为: 247 | 248 |
    249 |
  1. Bird
  2. 250 |
  3. McHale
  4. 251 |
  5. Parish
  6. 252 |
253 | 254 | 如果你的列表标记写成: 255 | 256 | 1. Bird 257 | 1. McHale 258 | 1. Parish 259 | 260 | 或甚至是: 261 | 262 | 3. Bird 263 | 1. McHale 264 | 8. Parish 265 | 266 | 你都会得到完全相同的 HTML 输出。重点在于,你可以让 Markdown 文件的列表数字和输出的结果相同,或是你懒一点,你可以完全不用在意数字的正确性。 267 | 268 | 如果你使用懒惰的写法,建议第一个项目最好还是从 1. 开始,因为 Markdown 未来可能会支持有序列表的 start 属性。 269 | 270 | 列表项目标记通常是放在最左边,但是其实也可以缩进,最多 3 个空格,项目标记后面则一定要接着至少一个空格或制表符。 271 | 272 | 要让列表看起来更漂亮,你可以把内容用固定的缩进整理好: 273 | 274 | * Lorem ipsum dolor sit amet, consectetuer adipiscing elit. 275 | Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, 276 | viverra nec, fringilla in, laoreet vitae, risus. 277 | * Donec sit amet nisl. Aliquam semper ipsum sit amet velit. 278 | Suspendisse id sem consectetuer libero luctus adipiscing. 279 | 280 | 但是如果你懒,那也行: 281 | 282 | * Lorem ipsum dolor sit amet, consectetuer adipiscing elit. 283 | Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, 284 | viverra nec, fringilla in, laoreet vitae, risus. 285 | * Donec sit amet nisl. Aliquam semper ipsum sit amet velit. 286 | Suspendisse id sem consectetuer libero luctus adipiscing. 287 | 288 | 如果列表项目间用空行分开,在输出 HTML 时 Markdown 就会将项目内容用 `

` 289 | 标签包起来,举例来说: 290 | 291 | * Bird 292 | * Magic 293 | 294 | 会被转换为: 295 | 296 |

    297 |
  • Bird
  • 298 |
  • Magic
  • 299 |
300 | 301 | 但是这个: 302 | 303 | * Bird 304 | 305 | * Magic 306 | 307 | 会被转换为: 308 | 309 |
    310 |
  • Bird

  • 311 |
  • Magic

  • 312 |
313 | 314 | 列表项目可以包含多个段落,每个项目下的段落都必须缩进 4 个空格或是 1 个制表符: 315 | 316 | 1. This is a list item with two paragraphs. Lorem ipsum dolor 317 | sit amet, consectetuer adipiscing elit. Aliquam hendrerit 318 | mi posuere lectus. 319 | 320 | Vestibulum enim wisi, viverra nec, fringilla in, laoreet 321 | vitae, risus. Donec sit amet nisl. Aliquam semper ipsum 322 | sit amet velit. 323 | 324 | 2. Suspendisse id sem consectetuer libero luctus adipiscing. 325 | 326 | 如果你每行都有缩进,看起来会看好很多,当然,再次地,如果你很懒惰,Markdown 也允许: 327 | 328 | * This is a list item with two paragraphs. 329 | 330 | This is the second paragraph in the list item. You're 331 | only required to indent the first line. Lorem ipsum dolor 332 | sit amet, consectetuer adipiscing elit. 333 | 334 | * Another item in the same list. 335 | 336 | 如果要在列表项目内放进引用,那 `>` 就需要缩进: 337 | 338 | * A list item with a blockquote: 339 | 340 | > This is a blockquote 341 | > inside a list item. 342 | 343 | 如果要放代码区块的话,该区块就需要缩进*两次*,也就是 8 个空格或是 2 个制表符: 344 | 345 | * 一列表项包含一个列表区块: 346 | 347 | <代码写在这> 348 | 349 | 350 | 当然,项目列表很可能会不小心产生,像是下面这样的写法: 351 | 352 | 1986. What a great season. 353 | 354 | 换句话说,也就是在行首出现*数字-句点-空白*,要避免这样的状况,你可以在句点前面加上反斜杠。 355 | 356 | 1986\. What a great season. 357 | 358 |

代码区块

359 | 360 | 和程序相关的写作或是标签语言原始码通常会有已经排版好的代码区块,通常这些区块我们并不希望它以一般段落文件的方式去排版,而是照原来的样子显示,Markdown 会用 `
` 和 `` 标签来把代码区块包起来。
361 | 
362 | 要在 Markdown 中建立代码区块很简单,只要简单地缩进 4 个空格或是 1 个制表符就可以,例如,下面的输入:
363 | 
364 |     这是一个普通段落:
365 | 
366 |         这是一个代码区块。
367 | 
368 | Markdown 会转换成:
369 | 
370 |     

这是一个普通段落:

371 | 372 |
这是一个代码区块。
373 |     
374 | 375 | 这个每行一阶的缩进(4 个空格或是 1 个制表符),都会被移除,例如: 376 | 377 | Here is an example of AppleScript: 378 | 379 | tell application "Foo" 380 | beep 381 | end tell 382 | 383 | 会被转换为: 384 | 385 |

Here is an example of AppleScript:

386 | 387 |
tell application "Foo"
388 |         beep
389 |     end tell
390 |     
391 | 392 | 一个代码区块会一直持续到没有缩进的那一行(或是文件结尾)。 393 | 394 | 在代码区块里面, `&` 、 `<` 和 `>` 会自动转成 HTML 实体,这样的方式让你非常容易使用 Markdown 插入范例用的 HTML 原始码,只需要复制贴上,再加上缩进就可以了,剩下的 Markdown 都会帮你处理,例如: 395 | 396 | 399 | 400 | 会被转换为: 401 | 402 |
<div class="footer">
403 |         &copy; 2004 Foo Corporation
404 |     </div>
405 |     
406 | 407 | 代码区块中,一般的 Markdown 语法不会被转换,像是星号便只是星号,这表示你可以很容易地以 Markdown 语法撰写 Markdown 语法相关的文件。 408 | 409 |

分隔线

410 | 411 | 你可以在一行中用三个以上的星号、减号、底线来建立一个分隔线,行内不能有其他东西。你也可以在星号或是减号中间插入空格。下面每种写法都可以建立分隔线: 412 | 413 | * * * 414 | 415 | *** 416 | 417 | ***** 418 | 419 | - - - 420 | 421 | --------------------------------------- 422 | 423 | 424 | * * * 425 | 426 |

区段元素

427 | 428 | 429 | 430 | Markdown 支持两种形式的链接语法: *行内式*和*参考式*两种形式。 431 | 432 | 不管是哪一种,链接文字都是用 [方括号] 来标记。 433 | 434 | 要建立一个*行内式*的链接,只要在方块括号后面紧接着圆括号并插入网址链接即可,如果你还想要加上链接的 title 文字,只要在网址后面,用双引号把 title 文字包起来即可,例如: 435 | 436 | This is [an example](http://example.com/ "Title") inline link. 437 | 438 | [This link](http://example.net/) has no title attribute. 439 | 440 | 会产生: 441 | 442 |

This is 443 | an example inline link.

444 | 445 |

This link has no 446 | title attribute.

447 | 448 | 如果你是要链接到同样主机的资源,你可以使用相对路径: 449 | 450 | See my [About](/about/) page for details. 451 | 452 | *参考式*的链接是在链接文字的括号后面再接上另一个方括号,而在第二个方括号里面要填入用以辨识链接的标记: 453 | 454 | This is [an example][id] reference-style link. 455 | 456 | 你也可以选择性地在两个方括号中间加上一个空格: 457 | 458 | This is [an example] [id] reference-style link. 459 | 460 | 接着,在文件的任意处,你可以把这个标记的链接内容定义出来: 461 | 462 | [id]: http://example.com/ "Optional Title Here" 463 | 464 | 链接内容定义的形式为: 465 | 466 | * 方括号(前面可以选择性地加上至多三个空格来缩进),里面输入链接文字 467 | * 接着一个冒号 468 | * 接着一个以上的空格或制表符 469 | * 接着链接的网址 470 | * 选择性地接着 title 内容,可以用单引号、双引号或是括弧包着 471 | 472 | 下面这三种链接的定义都是相同: 473 | 474 | [foo]: http://example.com/ "Optional Title Here" 475 | [foo]: http://example.com/ 'Optional Title Here' 476 | [foo]: http://example.com/ (Optional Title Here) 477 | 478 | **请注意:**有一个已知的问题是 Markdown.pl 1.0.1 会忽略单引号包起来的链接 title。 479 | 480 | 链接网址也可以用方括号包起来: 481 | 482 | [id]: "Optional Title Here" 483 | 484 | 你也可以把 title 属性放到下一行,也可以加一些缩进,若网址太长的话,这样会比较好看: 485 | 486 | [id]: http://example.com/longish/path/to/resource/here 487 | "Optional Title Here" 488 | 489 | 网址定义只有在产生链接的时候用到,并不会直接出现在文件之中。 490 | 491 | 链接辨别标签可以有字母、数字、空白和标点符号,但是并*不*区分大小写,因此下面两个链接是一样的: 492 | 493 | [link text][a] 494 | [link text][A] 495 | 496 | *隐式链接标记*功能让你可以省略指定链接标记,这种情形下,链接标记会视为等同于链接文字,要用隐式链接标记只要在链接文字后面加上一个空的方括号,如果你要让 "Google" 链接到 google.com,你可以简化成: 497 | 498 | [Google][] 499 | 500 | 然后定义链接内容: 501 | 502 | [Google]: http://google.com/ 503 | 504 | 由于链接文字可能包含空白,所以这种简化型的标记内也许包含多个单词: 505 | 506 | Visit [Daring Fireball][] for more information. 507 | 508 | 然后接着定义链接: 509 | 510 | [Daring Fireball]: http://daringfireball.net/ 511 | 512 | 链接的定义可以放在文件中的任何一个地方,我比较偏好直接放在链接出现段落的后面,你也可以把它放在文件最后面,就像是注解一样。 513 | 514 | 下面是一个参考式链接的范例: 515 | 516 | I get 10 times more traffic from [Google] [1] than from 517 | [Yahoo] [2] or [MSN] [3]. 518 | 519 | [1]: http://google.com/ "Google" 520 | [2]: http://search.yahoo.com/ "Yahoo Search" 521 | [3]: http://search.msn.com/ "MSN Search" 522 | 523 | 如果改成用链接名称的方式写: 524 | 525 | I get 10 times more traffic from [Google][] than from 526 | [Yahoo][] or [MSN][]. 527 | 528 | [google]: http://google.com/ "Google" 529 | [yahoo]: http://search.yahoo.com/ "Yahoo Search" 530 | [msn]: http://search.msn.com/ "MSN Search" 531 | 532 | 上面两种写法都会产生下面的 HTML。 533 | 534 |

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

538 | 539 | 下面是用行内式写的同样一段内容的 Markdown 文件,提供作为比较之用: 540 | 541 | I get 10 times more traffic from [Google](http://google.com/ "Google") 542 | than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or 543 | [MSN](http://search.msn.com/ "MSN Search"). 544 | 545 | 参考式的链接其实重点不在于它比较好写,而是它比较好读,比较一下上面的范例,使用参考式的文章本身只有 81 个字符,但是用行内形式的却会增加到 176 个字元,如果是用纯 HTML 格式来写,会有 234 个字元,在 HTML 格式中,标签比文本还要多。 546 | 547 | 使用 Markdown 的参考式链接,可以让文件更像是浏览器最后产生的结果,让你可以把一些标记相关的元数据移到段落文字之外,你就可以增加链接而不让文章的阅读感觉被打断。 548 | 549 |

强调

550 | 551 | Markdown 使用星号(`*`)和底线(`_`)作为标记强调字词的符号,被 `*` 或 `_` 包围的字词会被转成用 `` 标签包围,用两个 `*` 或 `_` 包起来的话,则会被转成 ``,例如: 552 | 553 | *single asterisks* 554 | 555 | _single underscores_ 556 | 557 | **double asterisks** 558 | 559 | __double underscores__ 560 | 561 | 会转成: 562 | 563 | single asterisks 564 | 565 | single underscores 566 | 567 | double asterisks 568 | 569 | double underscores 570 | 571 | 你可以随便用你喜欢的样式,唯一的限制是,你用什么符号开启标签,就要用什么符号结束。 572 | 573 | 强调也可以直接插在文字中间: 574 | 575 | un*frigging*believable 576 | 577 | 但是**如果你的 `*` 和 `_` 两边都有空白的话,它们就只会被当成普通的符号**。 578 | 579 | 如果要在文字前后直接插入普通的星号或底线,你可以用反斜线: 580 | 581 | \*this text is surrounded by literal asterisks\* 582 | 583 |

代码

584 | 585 | 如果要标记一小段行内代码,你可以用反引号把它包起来(`` ` ``),例如: 586 | 587 | Use the `printf()` function. 588 | 589 | 会产生: 590 | 591 |

Use the printf() function.

592 | 593 | 如果要在代码区段内插入反引号,你可以用多个反引号来开启和结束代码区段: 594 | 595 | ``There is a literal backtick (`) here.`` 596 | 597 | 这段语法会产生: 598 | 599 |

There is a literal backtick (`) here.

600 | 601 | 代码区段的起始和结束端都可以放入一个空白,起始端后面一个,结束端前面一个,这样你就可以在区段的一开始就插入反引号: 602 | 603 | A single backtick in a code span: `` ` `` 604 | 605 | A backtick-delimited string in a code span: `` `foo` `` 606 | 607 | 会产生: 608 | 609 |

A single backtick in a code span: `

610 | 611 |

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

612 | 613 | 在代码区段内,`&` 和方括号**都**会被自动地转成 HTML 实体,这使得插入 HTML 原始码变得很容易,Markdown 会把下面这段: 614 | 615 | Please don't use any `` tags. 616 | 617 | 转为: 618 | 619 |

Please don't use any <blink> tags.

620 | 621 | 你也可以这样写: 622 | 623 | `—` is the decimal-encoded equivalent of `—`. 624 | 625 | 以产生: 626 | 627 |

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

629 | 630 | 631 | 632 |

图片

633 | 634 | 很明显地,要在纯文字应用中设计一个「自然」的语法来插入图片是有一定难度的。 635 | 636 | Markdown 使用一种和链接很相似的语法来标记图片,同样也允许两种样式: *行内式*和*参考式*。 637 | 638 | 行内式的图片语法看起来像是: 639 | 640 | ![Alt text](/path/to/img.jpg) 641 | 642 | ![Alt text](/path/to/img.jpg "Optional title") 643 | 644 | 详细叙述如下: 645 | 646 | * 一个惊叹号 `!` 647 | * 接着一个方括号,里面放上图片的替代文字 648 | * 接着一个普通括号,里面放上图片的网址,最后还可以用引号包住并加上 649 | 选择性的 'title' 文字。 650 | 651 | 参考式的图片语法则长得像这样: 652 | 653 | ![Alt text][id] 654 | 655 | 「id」是图片参考的名称,图片参考的定义方式则和连结参考一样: 656 | 657 | [id]: url/to/image "Optional title attribute" 658 | 659 | 到目前为止, Markdown 还没有办法指定图片的宽高,如果你需要的话,你可以使用普通的 `` 标签。 660 | 661 | * * * 662 | 663 |

其它

664 | 665 | 666 | 667 | Markdown 支持以比较简短的自动链接形式来处理网址和电子邮件信箱,只要是用方括号包起来, Markdown 就会自动把它转成链接。一般网址的链接文字就和链接地址一样,例如: 668 | 669 | 670 | 671 | Markdown 会转为: 672 | 673 | http://example.com/ 674 | 675 | 邮址的自动链接也很类似,只是 Markdown 会先做一个编码转换的过程,把文字字符转成 16 进位码的 HTML 实体,这样的格式可以糊弄一些不好的邮址收集机器人,例如: 676 | 677 | 678 | 679 | Markdown 会转成: 680 | 681 | address@exa 684 | mple.com 685 | 686 | 在浏览器里面,这段字串(其实是 `address@example.com`)会变成一个可以点击的「address@example.com」链接。 687 | 688 | (这种作法虽然可以糊弄不少的机器人,但并不能全部挡下来,不过总比什么都不做好些。不管怎样,公开你的信箱终究会引来广告信件的。) 689 | 690 |

反斜杠

691 | 692 | Markdown 可以利用反斜杠来插入一些在语法中有其它意义的符号,例如:如果你想要用星号加在文字旁边的方式来做出强调效果(但不用 `` 标签),你可以在星号的前面加上反斜杠: 693 | 694 | \*literal asterisks\* 695 | 696 | Markdown 支持以下这些符号前面加上反斜杠来帮助插入普通的符号: 697 | 698 | \ 反斜线 699 | ` 反引号 700 | * 星号 701 | _ 底线 702 | {} 花括号 703 | [] 方括号 704 | () 括弧 705 | # 井字号 706 | + 加号 707 | - 减号 708 | . 英文句点 709 | ! 惊叹号 710 | 711 |

感谢

712 | 713 | 感谢 [leafy7382][] 协助翻译,[hlb][]、[Randylien][] 帮忙润稿,[ethantw][] 的[汉字标准格式・CSS Reset][], [WM][] 回报文字错误。 714 | 715 | [leafy7382]:https://twitter.com/#!/leafy7382 716 | [hlb]:http://iamhlb.com/ 717 | [Randylien]:http://twitter.com/randylien 718 | [ethantw]:https://twitter.com/#!/ethantw 719 | [汉字标准格式・CSS Reset]:http://ethantw.net/projects/han/ 720 | [WM]:http://kidwm.net/ 721 | 722 | 感谢 [fenprace][],[addv][]。 723 | 724 | [fenprace]:https://github.com/fenprace 725 | [addv]:https://github.com/addv 726 | 727 | ---------- 728 |

Markdown 免费编辑器

729 | 730 | Windows 平台 731 | 732 | * [MarkdownPad](http://markdownpad.com/) 733 | * [MarkPad](http://code52.org/DownmarkerWPF/) 734 | 735 | Linux 平台 736 | 737 | * [ReText](http://sourceforge.net/p/retext/home/ReText/) 738 | 739 | Mac 平台 740 | 741 | * [Mou](http://mouapp.com/) 742 | 743 | 在线编辑器 744 | 745 | * [Markable.in](http://markable.in/) 746 | * [Dillinger.io](http://dillinger.io/) 747 | 748 | 浏览器插件 749 | 750 | * [MaDe](https://chrome.google.com/webstore/detail/oknndfeeopgpibecfjljjfanledpbkog) (Chrome) 751 | 752 | 高级应用 753 | 754 | * [Sublime Text 2](http://www.sublimetext.com/2) + [MarkdownEditing](http://ttscoff.github.com/MarkdownEditing/) / [教程](http://lucifr.com/2012/07/12/markdownediting-for-sublime-text-2/) 755 | 756 | \*** 如有更好的 Markdown 免费编辑器推荐,请到[这里反馈](https://gitcafe.com/riku/Markdown-Syntax-CN/tickets/1),谢谢! -------------------------------------------------------------------------------- /syntax.text: -------------------------------------------------------------------------------- 1 | Markdown: Syntax 2 | ================ 3 | 4 | 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 |

Overview

42 | 43 |

Philosophy

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 |

Inline HTML

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. `
`, 91 | ``, `
`, `

`, 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) `

` 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 |

101 | 102 | 103 | 104 |
Foo
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. ``, ``, or `` -- 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 `` or `` 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 |

Automatic Escaping for Special Characters

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 |

Block Elements

182 | 183 | 184 |

Paragraphs and Line Breaks

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 `
` tag. 196 | 197 | When you *do* want to insert a `
` 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 `
`, but a simplistic 201 | "every line break is a `
`" 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 | 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 |

Blockquotes

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 |

Lists

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 |
    331 |
  1. Bird
  2. 332 |
  3. McHale
  4. 333 |
  5. Parish
  6. 334 |
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 `

` tags in the HTML output. For example, this input: 379 | 380 | * Bird 381 | * Magic 382 | 383 | will turn into: 384 | 385 |

    386 |
  • Bird
  • 387 |
  • Magic
  • 388 |
389 | 390 | But this: 391 | 392 | * Bird 393 | 394 | * Magic 395 | 396 | will turn into: 397 | 398 |
    399 |
  • Bird

  • 400 |
  • Magic

  • 401 |
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 | 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 |

Code Blocks

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 `
` and `` 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 |     

This is a normal paragraph:

474 | 475 |
This is a code block.
476 |     
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 |

Here is an example of AppleScript:

490 | 491 |
tell application "Foo"
492 |         beep
493 |     end tell
494 |     
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 | 508 | 509 | will turn into: 510 | 511 |
<div class="footer">
512 |         &copy; 2004 Foo Corporation
513 |     </div>
514 |     
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 |

Horizontal Rules

523 | 524 | You can produce a horizontal rule tag (`
`) 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 |

Span Elements

543 | 544 | 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 |

This is 562 | an example inline link.

563 | 564 |

This link has no 565 | title attribute.

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]: "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 |

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

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 |

Emphasis

700 | 701 | Markdown treats asterisks (`*`) and underscores (`_`) as indicators of 702 | emphasis. Text wrapped with one `*` or `_` will be wrapped with an 703 | HTML `` tag; double `*`'s or `_`'s will be wrapped with an HTML 704 | `` 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 | single asterisks 717 | 718 | single underscores 719 | 720 | double asterisks 721 | 722 | double underscores 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 |

Code

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 |

Use the printf() function.

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 |

There is a literal backtick (`) here.

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 |

A single backtick in a code span: `

774 | 775 |

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

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 `` tags. 782 | 783 | into: 784 | 785 |

Please don't use any <blink> tags.

786 | 787 | You can write this: 788 | 789 | `—` is the decimal-encoded equivalent of `—`. 790 | 791 | to produce: 792 | 793 |

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

795 | 796 | 797 | 798 |

Images

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 `` tags. 833 | 834 | 835 | * * * 836 | 837 | 838 |

Miscellaneous

839 | 840 | 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 | 845 | 846 | Markdown will turn this into: 847 | 848 | http://example.com/ 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 | 856 | 857 | into something like this: 858 | 859 | address@exa 862 | mple.com 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 |

Backslash Escapes

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 `` 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 | 898 | --------------------------------------------------------------------------------