├── .hgignore ├── .hgtags ├── LICENSE ├── Makefile ├── README.md ├── cmd └── markdown │ ├── main.go │ └── pprof.go ├── doc.go ├── elemheap.go ├── markdown.go ├── markdown_test.go ├── misc ├── benchmark.rc ├── bmprepare.rc ├── c2go.sed ├── devel.mk ├── func-name2line.rc └── gofmt.rc ├── out-groffmm.go ├── output.go ├── parser.leg ├── parser.leg.go ├── portid └── tests ├── README.md ├── gen.rc ├── issues ├── footnotes-10.html ├── footnotes-10.mm └── footnotes-10.text └── md1.0.3 ├── Amps and angle encoding.html ├── Amps and angle encoding.mm ├── Amps and angle encoding.text ├── Auto links.html ├── Auto links.mm ├── Auto links.text ├── Backslash escapes.html ├── Backslash escapes.mm ├── Backslash escapes.text ├── Blockquotes with code blocks.html ├── Blockquotes with code blocks.mm ├── Blockquotes with code blocks.text ├── Code Blocks.html ├── Code Blocks.mm ├── Code Blocks.text ├── Code Spans.html ├── Code Spans.mm ├── Code Spans.text ├── Hard-wrapped paragraphs with list-like lines.html ├── Hard-wrapped paragraphs with list-like lines.mm ├── Hard-wrapped paragraphs with list-like lines.text ├── Horizontal rules.html ├── Horizontal rules.mm ├── Horizontal rules.text ├── Inline HTML (Advanced).html ├── Inline HTML (Advanced).mm ├── Inline HTML (Advanced).text ├── Inline HTML (Simple).html ├── Inline HTML (Simple).mm ├── Inline HTML (Simple).text ├── Inline HTML comments.html ├── Inline HTML comments.mm ├── Inline HTML comments.text ├── Links, inline style.mm ├── Links, reference style.mm ├── Links, shortcut references.mm ├── Literal quotes in titles.html ├── Literal quotes in titles.mm ├── Literal quotes in titles.text ├── Markdown Documentation - Basics.html ├── Markdown Documentation - Basics.mm ├── Markdown Documentation - Basics.text ├── Markdown Documentation - Syntax.html ├── Markdown Documentation - Syntax.mm ├── Markdown Documentation - Syntax.text ├── Nested blockquotes.html ├── Nested blockquotes.mm ├── Nested blockquotes.text ├── Ordered and unordered lists.html ├── Ordered and unordered lists.mm ├── Ordered and unordered lists.text ├── Strong and em together.html ├── Strong and em together.mm ├── Strong and em together.text ├── Tabs.html ├── Tabs.mm ├── Tabs.text ├── Tidyness.html ├── Tidyness.mm └── Tidyness.text /.hgignore: -------------------------------------------------------------------------------- 1 | # use glob syntax. 2 | syntax: glob 3 | 4 | parser.leg.go 5 | cmd/markdown 6 | orig-c-src 7 | core 8 | +* 9 | *.orig 10 | [58].* 11 | *.[58] 12 | ,* 13 | *~ 14 | [#]* 15 | -------------------------------------------------------------------------------- /.hgtags: -------------------------------------------------------------------------------- 1 | 967ded207024eabaabfc910339eb2f96220634f7 go.r58 2 | 8f1973a5e0863401f09c338b4a822310fd288fc8 go.r59 3 | 8f1973a5e0863401f09c338b4a822310fd288fc8 go.r60 4 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | markdown in Go, implemented using PEG grammar 2 | 3 | Copyright (c) 2010 Michael Teichgräber 4 | 5 | This is a translation of peg-markdown, written 6 | by John MacFarlane, into Go: 7 | 8 | Copyright (c) 2008 John MacFarlane 9 | 10 | peg-markdown is released under both the GPL and MIT licenses. 11 | You may pick the license that best fits your needs. 12 | 13 | The GPL 14 | 15 | This program is free software; you can redistribute it and/or modify 16 | it under the terms of the GNU General Public License as published by 17 | the Free Software Foundation; either version 2 of the License, or 18 | (at your option) any later version. 19 | 20 | This program is distributed in the hope that it will be useful, 21 | but WITHOUT ANY WARRANTY; without even the implied warranty of 22 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 23 | GNU General Public License for more details. 24 | 25 | You should have received a copy of the GNU General Public License 26 | along with this program; if not, write to the Free Software 27 | Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA 28 | 29 | The MIT License 30 | 31 | Permission is hereby granted, free of charge, to any person obtaining a copy 32 | of this software and associated documentation files (the "Software"), to deal 33 | in the Software without restriction, including without limitation the rights 34 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 35 | copies of the Software, and to permit persons to whom the Software is 36 | furnished to do so, subject to the following conditions: 37 | 38 | The above copyright notice and this permission notice shall be included in 39 | all copies or substantial portions of the Software. 40 | 41 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 42 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 43 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 44 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 45 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 46 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 47 | THE SOFTWARE. 48 | 49 | * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 50 | 51 | peg (http://github.com/pointlander/peg), 52 | based on http://piumarta.com/software/peg/, 53 | written by Andrew J Snodgrass. 54 | 55 | Modifications to support LE grammars by Michael Teichgräber 56 | 57 | Copyright (c) 2010, Go Authors 58 | All rights reserved. 59 | 60 | Redistribution and use in source and binary forms, with or without modification, 61 | are permitted provided that the following conditions are met: 62 | * Redistributions of source code must retain the above copyright notice, 63 | this list of conditions and the following disclaimer. 64 | * Redistributions in binary form must reproduce the above copyright notice, 65 | this list of conditions and the following disclaimer in the documentation and/or 66 | other materials provided with the distribution. 67 | * Neither the name of the Go Authors nor the names of its contributors may be used to 68 | endorse or promote products derived from this software without specific prior written permission. 69 | 70 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY 71 | EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 72 | MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL 73 | THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 74 | SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 75 | SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 76 | HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 77 | OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 78 | EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 79 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | all: 2 | @echo 'targets: nuke parser clean' 3 | 4 | cmd: package 5 | cd cmd/markdown && go build -v 6 | 7 | package: parser.leg.go 8 | go install -v 9 | 10 | clean: 11 | go clean . ./... 12 | rm -rf ,,prevmd ,,pmd 13 | 14 | parser: parser.leg.go 15 | 16 | nuke: 17 | rm -f parser.leg.go 18 | 19 | 20 | # LEG parser rules 21 | # 22 | ifeq ($(MAKECMDGOALS),parser) 23 | include $(shell go list -f '{{.Dir}}' github.com/knieriem/peg)/Make.inc 24 | %.leg.go: %.leg $(LEG) 25 | $(LEG) -verbose -switch -O all $< > $@ 26 | 27 | endif 28 | 29 | 30 | include misc/devel.mk 31 | 32 | .PHONY: \ 33 | all\ 34 | cmd\ 35 | nuke\ 36 | package\ 37 | parser\ 38 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | This is an implementation of John Gruber's [markdown][] in 2 | [Go][]. It is a translation of [peg-markdown][], written by 3 | John MacFarlane in C, into Go. It is using a modified version 4 | of Andrew J Snodgrass' PEG parser [peg][] -- now supporting 5 | LEG grammars --, which itself is based on the parser used 6 | by peg-markdown. 7 | 8 | [markdown]: http://daringfireball.net/projects/markdown/ 9 | [peg-markdown]: https://github.com/jgm/peg-markdown 10 | [peg]: https://github.com/pointlander/peg 11 | [Go]: http://golang.org/ 12 | 13 | Support for HTML and groff mm output is implemented, but LaTeX 14 | output has not been ported. The output is identical 15 | to that of peg-markdown. 16 | 17 | I try to keep the grammar in sync with the C version, by 18 | cherry-picking relevant changes. In the commit history the 19 | corresponding revisions have a suffix *[jgm/peg-markdown].* 20 | 21 | The Markdown parser has a performance similar to that of 22 | the original C version, and consumes less memory. 23 | 24 | ## Installation 25 | 26 | Provided you have a copy of Go 1, and git is available, 27 | 28 | go get github.com/knieriem/markdown 29 | 30 | should download and install the package according to 31 | your GOPATH settings. 32 | 33 | See doc.go for an example how to use the package. 34 | 35 | --- 36 | 37 | To create the command line program *markdown,* run 38 | 39 | go build github.com/knieriem/markdown/cmd/markdown 40 | 41 | the binary should then be available in the current directory. 42 | 43 | To run tests, type 44 | 45 | go test github.com/knieriem/markdown 46 | 47 | At the moment, tests are based on the .text files from the 48 | Markdown 1.0.3 test suite created by John Gruber, [imported from 49 | peg-markdown][testsuite]. The output of the conversion of these 50 | .text files to html is compared to the output of peg-markdown. 51 | 52 | [testsuite]: https://github.com/jgm/peg-markdown/tree/master/MarkdownTest_1.0.3 53 | 54 | ## Development 55 | 56 | There is not yet a way to create a Go source file like 57 | `parser.leg.go` automatically from another file, `parser.leg`, 58 | when building packages and commands using the Go tool. To make 59 | *markdown* installable using `go get`, `parser.leg.go` has 60 | been added to the VCS. 61 | 62 | `Make parser` will update `parser.leg.go` using `leg` – which 63 | is part of [knieriem/peg][] at github –, if parser.leg has 64 | been changed, or if the Go file is missing. If a copy of *peg* 65 | is not yet present on your system, run 66 | 67 | go get github.com/knieriem/peg 68 | 69 | Then `make parser` should succeed. 70 | 71 | [knieriem/peg]: https://github.com/knieriem/peg 72 | 73 | 74 | ## Extensions 75 | 76 | In addition to the extensions already present in peg-markdown, 77 | this package also supports definition lists (option `-dlists`) 78 | similar to the way they are described in the documentation of 79 | [PHP Markdown Extra][]. 80 | 81 | Definitions (`
...
`) are implemented using [`ListTight`][ListTight] 82 | and `ListLoose`, on which bullet lists and ordered lists are based 83 | already. If there is an empty line between the definition title and 84 | the first definition, a loose list is expected, a tight list otherwise. 85 | 86 | As definition item markers both `:` and `~` can be used. 87 | 88 | [PHP Markdown Extra]: http://michelf.com/projects/php-markdown/extra/#def-list 89 | [ListTight]: https://github.com/knieriem/markdown/blob/master/parser.leg#L191 90 | 91 | 92 | ## Todo 93 | 94 | * Port tables and perhaps other extensions from [fletcher/peg-multimarkdown][mmd]. 95 | 96 | ## Subdirectory Index 97 | 98 | * cmd/markdown – command line program `markdown` 99 | 100 | [mmd]: https://github.com/fletcher/peg-multimarkdown 101 | -------------------------------------------------------------------------------- /cmd/markdown/main.go: -------------------------------------------------------------------------------- 1 | package main 2 | 3 | import ( 4 | "bufio" 5 | "flag" 6 | "fmt" 7 | "github.com/knieriem/markdown" 8 | "log" 9 | "os" 10 | ) 11 | 12 | var format = flag.String("t", "html", "output format") 13 | 14 | func main() { 15 | var opt markdown.Extensions 16 | flag.BoolVar(&opt.Notes, "notes", false, "turn on footnote syntax") 17 | flag.BoolVar(&opt.Smart, "smart", false, "turn on smart quotes, dashes, and ellipses") 18 | flag.BoolVar(&opt.Strike, "strike", false, "turn on strike-through syntax") 19 | flag.BoolVar(&opt.Dlists, "dlists", false, "support definitions lists") 20 | 21 | flag.Usage = func() { 22 | fmt.Fprintf(os.Stderr, "Usage: %s [FILE]\n", os.Args[0]) 23 | flag.PrintDefaults() 24 | } 25 | flag.Parse() 26 | 27 | r := os.Stdin 28 | if flag.NArg() > 0 { 29 | f, err := os.Open(flag.Arg(0)) 30 | if err != nil { 31 | log.Fatal(err) 32 | } 33 | defer f.Close() 34 | r = f 35 | } 36 | 37 | p := markdown.NewParser(&opt) 38 | 39 | startPProf() 40 | defer stopPProf() 41 | 42 | w := bufio.NewWriter(os.Stdout) 43 | 44 | switch *format { 45 | case "groff-mm": 46 | p.Markdown(r, markdown.ToGroffMM(w)) 47 | default: 48 | p.Markdown(r, markdown.ToHTML(w)) 49 | } 50 | w.Flush() 51 | } 52 | -------------------------------------------------------------------------------- /cmd/markdown/pprof.go: -------------------------------------------------------------------------------- 1 | package main 2 | 3 | import ( 4 | "flag" 5 | "log" 6 | "os" 7 | "runtime/pprof" 8 | ) 9 | 10 | var cpuprofile = flag.String("cpuprofile", "", "write cpu profile to file") 11 | var memprofile = flag.String("memprofile", "", "write memory profile to file") 12 | 13 | func startPProf() { 14 | if *cpuprofile != "" { 15 | f, err := os.Create(*cpuprofile) 16 | if err != nil { 17 | log.Fatal(err) 18 | } 19 | pprof.StartCPUProfile(f) 20 | } 21 | } 22 | 23 | func stopPProf() { 24 | if *cpuprofile != "" { 25 | pprof.StopCPUProfile() 26 | } 27 | if *memprofile != "" { 28 | f, err := os.Create(*memprofile) 29 | if err != nil { 30 | log.Fatal(err) 31 | } 32 | pprof.WriteHeapProfile(f) 33 | f.Close() 34 | } 35 | } 36 | -------------------------------------------------------------------------------- /doc.go: -------------------------------------------------------------------------------- 1 | /* 2 | A translation of peg-markdown [1] into Go. 3 | 4 | Usage example: 5 | 6 | package main 7 | 8 | import ( 9 | "github.com/knieriem/markdown" 10 | "os" 11 | "bufio" 12 | ) 13 | 14 | func main() { 15 | p := markdown.NewParser(&markdown.Extensions{Smart: true}) 16 | 17 | w := bufio.NewWriter(os.Stdout) 18 | p.Markdown(os.Stdin, markdown.ToHTML(w)) 19 | w.Flush() 20 | } 21 | 22 | [1]: https://github.com/jgm/peg-markdown/ 23 | */ 24 | package markdown 25 | -------------------------------------------------------------------------------- /elemheap.go: -------------------------------------------------------------------------------- 1 | package markdown 2 | 3 | /* 4 | Elements are not allocated one at a time, but in rows of 5 | elemHeap.RowSize elements. After N elements have been 6 | requested, a row is exhausted, and the next one will 7 | be allocated. Previously allocated rows are tracked in 8 | elemHeap.rows. 9 | 10 | The Reset() method allows to reset the current position (row, and 11 | position within the row), which allows reusing elements. Whether 12 | elements can be reused, depends on the value of the hasGlobals 13 | field. 14 | */ 15 | 16 | type elemHeap struct { 17 | rows [][]element 18 | heapPos 19 | rowSize int 20 | 21 | base heapPos 22 | hasGlobals bool 23 | } 24 | 25 | type heapPos struct { 26 | iRow int 27 | row []element 28 | } 29 | 30 | func (h *elemHeap) nextRow() []element { 31 | h.iRow++ 32 | if h.iRow == len(h.rows) { 33 | h.rows = append(h.rows, make([]element, h.rowSize)) 34 | } 35 | h.row = h.rows[h.iRow] 36 | return h.row 37 | } 38 | 39 | func (h *elemHeap) init(size int) { 40 | h.rowSize = size 41 | h.rows = [][]element{make([]element, size)} 42 | h.row = h.rows[h.iRow] 43 | h.base = h.heapPos 44 | } 45 | 46 | func (h *elemHeap) Reset() { 47 | if !h.hasGlobals { 48 | h.heapPos = h.base 49 | } else { 50 | /* Don't restore saved position in case elements added 51 | * after the previous Reset call are needed in 52 | * global context, like notes. 53 | */ 54 | h.hasGlobals = false 55 | h.base = h.heapPos 56 | } 57 | } 58 | -------------------------------------------------------------------------------- /markdown.go: -------------------------------------------------------------------------------- 1 | /* Original C version https://github.com/jgm/peg-markdown/ 2 | * Copyright 2008 John MacFarlane (jgm at berkeley dot edu). 3 | * 4 | * Modifications and translation from C into Go 5 | * based on markdown_lib.c and parsing_functions.c 6 | * Copyright 2010 Michael Teichgräber (mt at wmipf dot de) 7 | * 8 | * This program is free software; you can redistribute it and/or modify 9 | * it under the terms of the GNU General Public License or the MIT 10 | * license. See LICENSE for details. 11 | * 12 | * This program is distributed in the hope that it will be useful, 13 | * but WITHOUT ANY WARRANTY; without even the implied warranty of 14 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 15 | * GNU General Public License for more details. 16 | */ 17 | 18 | package markdown 19 | 20 | import ( 21 | "bytes" 22 | "io" 23 | "log" 24 | "strings" 25 | ) 26 | 27 | const ( 28 | // If you get a build error message saying that 29 | // parserIfaceVersion_N is undefined, parser.leg.go 30 | // either is not present or it is out of date. You should 31 | // rebuild it using 32 | // make nuke 33 | // make parser 34 | needParserIfaceVersion = parserIfaceVersion_18 35 | ) 36 | 37 | // Markdown Extensions. 38 | type Extensions struct { 39 | Smart bool 40 | Notes bool 41 | FilterHTML bool 42 | FilterStyles bool 43 | Strike bool 44 | Dlists bool 45 | } 46 | 47 | type Parser struct { 48 | yy yyParser 49 | preformatBuf *bytes.Buffer 50 | } 51 | 52 | // NewParser creates an instance of a parser. It can be reused 53 | // so that stacks and buffers need not be allocated anew for 54 | // each Markdown call. 55 | func NewParser(x *Extensions) (p *Parser) { 56 | p = new(Parser) 57 | if x != nil { 58 | p.yy.state.extension = *x 59 | } 60 | p.yy.Init() 61 | p.yy.state.heap.init(1024) 62 | p.preformatBuf = bytes.NewBuffer(make([]byte, 0, 32768)) 63 | return 64 | } 65 | 66 | // A Formatter is called repeatedly, one Markdown block at a time, 67 | // while the document is parsed. At the end of a document the Finish 68 | // method is called, which may, for example, print footnotes. 69 | // A Formatter can be reused. 70 | type Formatter interface { 71 | FormatBlock(*element) 72 | Finish() 73 | } 74 | 75 | // Markdown parses input from an io.Reader into a tree, and sends 76 | // parsed blocks to a Formatter 77 | func (p *Parser) Markdown(src io.Reader, f Formatter) { 78 | s := p.preformat(src) 79 | 80 | p.parseRule(ruleReferences, s) 81 | if p.yy.extension.Notes { 82 | p.parseRule(ruleNotes, s) 83 | } 84 | p.yy.state.heap.Reset() 85 | 86 | for { 87 | tree := p.parseRule(ruleDocblock, s) 88 | if tree == nil { 89 | break 90 | } 91 | s = p.yy.ResetBuffer("") 92 | tree = p.processRawBlocks(tree) 93 | f.FormatBlock(tree) 94 | 95 | p.yy.state.heap.Reset() 96 | } 97 | f.Finish() 98 | } 99 | 100 | func (p *Parser) parseRule(rule int, s string) (tree *element) { 101 | old := p.yy.ResetBuffer(s) 102 | if old != "" && strings.Trim(old, "\r\n ") != "" { 103 | log.Fatalln("Buffer not empty", "["+old+"]") 104 | } 105 | err := p.yy.Parse(rule) 106 | switch rule { 107 | case ruleDoc, ruleDocblock: 108 | if err == nil { 109 | tree = p.yy.state.tree 110 | } 111 | p.yy.state.tree = nil 112 | } 113 | return 114 | } 115 | 116 | /* process_raw_blocks - traverses an element list, replacing any RAW elements with 117 | * the result of parsing them as markdown text, and recursing into the children 118 | * of parent elements. The result should be a tree of elements without any RAWs. 119 | */ 120 | func (p *Parser) processRawBlocks(input *element) *element { 121 | 122 | for current := input; current != nil; current = current.next { 123 | if current.key == RAW { 124 | /* \001 is used to indicate boundaries between nested lists when there 125 | * is no blank line. We split the string by \001 and parse 126 | * each chunk separately. 127 | */ 128 | current.key = LIST 129 | current.children = nil 130 | listEnd := ¤t.children 131 | for _, contents := range strings.Split(current.contents.str, "\001") { 132 | if list := p.parseRule(ruleDoc, contents); list != nil { 133 | *listEnd = list 134 | for list.next != nil { 135 | list = list.next 136 | } 137 | listEnd = &list.next 138 | } 139 | } 140 | current.contents.str = "" 141 | } 142 | if current.children != nil { 143 | current.children = p.processRawBlocks(current.children) 144 | } 145 | } 146 | return input 147 | } 148 | 149 | const ( 150 | TABSTOP = 4 151 | ) 152 | 153 | /* preformat - allocate and copy text buffer while 154 | * performing tab expansion. 155 | */ 156 | func (p *Parser) preformat(r io.Reader) (s string) { 157 | charstotab := TABSTOP 158 | buf := make([]byte, 32768) 159 | 160 | b := p.preformatBuf 161 | b.Reset() 162 | for { 163 | n, err := r.Read(buf) 164 | if err != nil { 165 | break 166 | } 167 | i0 := 0 168 | for i, c := range buf[:n] { 169 | switch c { 170 | case '\t': 171 | b.Write(buf[i0:i]) 172 | for ; charstotab > 0; charstotab-- { 173 | b.WriteByte(' ') 174 | } 175 | i0 = i + 1 176 | case '\n': 177 | b.Write(buf[i0 : i+1]) 178 | i0 = i + 1 179 | charstotab = TABSTOP 180 | default: 181 | charstotab-- 182 | } 183 | if charstotab == 0 { 184 | charstotab = TABSTOP 185 | } 186 | } 187 | b.Write(buf[i0:n]) 188 | } 189 | 190 | b.WriteString("\n\n") 191 | return b.String() 192 | } 193 | -------------------------------------------------------------------------------- /markdown_test.go: -------------------------------------------------------------------------------- 1 | package markdown 2 | 3 | import ( 4 | "bytes" 5 | "fmt" 6 | "os" 7 | "path/filepath" 8 | "strings" 9 | "testing" 10 | ) 11 | 12 | // for each pair of .text/.html files in the given subdirectory 13 | // of `./tests' compare the expected html output with 14 | // the output of Parser.Markdown. 15 | func runDirTests(dir string, opt *Extensions, t *testing.T) { 16 | 17 | dirPath := filepath.Join("tests", dir) 18 | f, err := os.Open(dirPath) 19 | if err != nil { 20 | t.Fatal(err) 21 | } 22 | defer f.Close() 23 | 24 | names, err := f.Readdirnames(-1) 25 | if err != nil { 26 | t.Fatal(err) 27 | } 28 | 29 | var buf bytes.Buffer 30 | fHTML := ToHTML(&buf) 31 | fGroff := ToGroffMM(&buf) 32 | p := NewParser(opt) 33 | for _, name := range names { 34 | if filepath.Ext(name) != ".text" { 35 | continue 36 | } 37 | if err = compareOutput(&buf, fHTML, ".html", filepath.Join(dirPath, name), p); err != nil { 38 | t.Error(err) 39 | } 40 | if err = compareOutput(&buf, fGroff, ".mm", filepath.Join(dirPath, name), p); err != nil { 41 | t.Error(err) 42 | } 43 | } 44 | } 45 | 46 | // Compare the output of the C-based peg-markdown, which 47 | // is, for each test, available in either a .html or a .mm file accompanying 48 | // the .text file, with the output of this package's Markdown processor. 49 | func compareOutput(w *bytes.Buffer, f Formatter, ext string, textPath string, p *Parser) (err error) { 50 | var bOrig bytes.Buffer 51 | 52 | r, err := os.Open(textPath) 53 | if err != nil { 54 | return 55 | } 56 | defer r.Close() 57 | 58 | w.Reset() 59 | p.Markdown(r, f) 60 | 61 | // replace .text extension by `ext' 62 | base := textPath[:len(textPath)-len(".text")] 63 | refPath := base + ext 64 | 65 | r, err = os.Open(refPath) 66 | if err != nil { 67 | return 68 | } 69 | defer r.Close() 70 | bOrig.ReadFrom(r) 71 | if bytes.Compare(bOrig.Bytes(), w.Bytes()) != 0 { 72 | err = fmt.Errorf("test %q failed", refPath) 73 | } 74 | return 75 | } 76 | 77 | func TestMarkdown103(t *testing.T) { 78 | runDirTests("md1.0.3", nil, t) 79 | } 80 | 81 | func TestMarkdownIssues(t *testing.T) { 82 | runDirTests("issues", &Extensions{Notes: true}, t) 83 | } 84 | 85 | // This test will make the test run fail with a 86 | // message like "Buffer not empty" under the 87 | // following condition: 88 | // 89 | // There exists an unprocessed, remaining portion of the 90 | // input buffer after the previous parser call, which 91 | // consists only of whitespace. 92 | // This whitespace should have been ignored, but, due to 93 | // a bug, hasn't. 94 | func TestTrailingWhitespaceBug(t *testing.T) { 95 | const input = `* foo 96 | 97 | # bar 98 | 99 | * baz 100 | ` 101 | var buf bytes.Buffer 102 | p := NewParser(nil) 103 | p.Markdown(strings.NewReader(input), ToHTML(&buf)) 104 | } 105 | -------------------------------------------------------------------------------- /misc/benchmark.rc: -------------------------------------------------------------------------------- 1 | #!/usr/local/plan9/bin/rc 2 | 3 | nrun=20 4 | md=./cmd/markdown/markdown 5 | 6 | fn timego{ 7 | run $md go 8 | } 9 | fn timegoprev{ 10 | run ./,,prevmd/src/github.com/knieriem/markdown/$md goprev 11 | } 12 | 13 | fn timec{ 14 | run ,,pmd/markdown c 15 | } 16 | 17 | fn run{ 18 | xtime $1 < m >[2=1] > /tmp/,,out.$2 19 | } 20 | 21 | fn xtime{ 22 | # /usr/bin/time -f '%Uu %Ss %er %MkB %C' $* 23 | /usr/bin/time -f '%U %M' $* 24 | } 25 | 26 | fn cmpout{ 27 | if (! cmp /tmp/,,out.$1 /tmp/,,out.$2) { 28 | echo not equal: $1 $2 >[1=2] 29 | exit -1 30 | } 31 | } 32 | 33 | { 34 | start = 1 35 | for (i in `{seq 1 $nrun}) { 36 | echo `{timec} `{timego} `{timegoprev} 37 | if (~ $start 1){ 38 | cmpout go c 39 | cmpout go goprev 40 | start = 0 41 | } 42 | } 43 | } | awk ' 44 | BEGIN { 45 | pfx = "#" 46 | } 47 | { 48 | tc = $1 49 | mc = $2 50 | tgo = $3 51 | mgo = $4 52 | tprev = $5 53 | mprev = 46 54 | } 55 | { 56 | print pfx, "c:", tc, "go:" tgo, "frac:", tgo/tc, "go,prev:", tgo/tprev*100, " %", "mem:", mgo/mc 57 | } 58 | NR < 5 { next } 59 | { 60 | pfx = "" 61 | csum += tc 62 | gosum += tgo 63 | goprevsum += tprev 64 | n++ 65 | } 66 | END { 67 | print "SUM" 68 | print "c:", csum, "go:", gosum, "n:", n, "frac", gosum/csum, gosum/goprevsum*100, " %" 69 | } 70 | ' 71 | -------------------------------------------------------------------------------- /misc/bmprepare.rc: -------------------------------------------------------------------------------- 1 | #!/usr/local/plan9/bin/rc 2 | 3 | flag e + 4 | 5 | fn updatetree{ # hg-id dir hg-url make-target 6 | wd=`{pwd} 7 | if (test -d $2) { 8 | cd $2 9 | if (! ~ `{hg id -n} $1) { 10 | hg update $1 11 | make $4 12 | } 13 | cd $wd 14 | } 15 | if (! test -d $2) { 16 | hg clone $3 $2 17 | cd $2 18 | hg update $1 19 | make $4 20 | cd $wd 21 | } 22 | ~ 0 0 23 | } 24 | 25 | test -f portid 26 | test -f previd 27 | mkdir -p ,,prevmd/src/github.com/knieriem 28 | 29 | id=`{cat portid} 30 | echo '*' prepare original c-based peg-markdown $id 31 | updatetree $id ,,pmd git://github.com/jgm/peg-markdown.git () 32 | 33 | id=`{cat previd} 34 | echo '*' prepare "previous version" $id 35 | cd ,,prevmd 36 | GOPATH=`{pwd} 37 | updatetree $id src/github.com/knieriem/markdown .. cmd 38 | -------------------------------------------------------------------------------- /misc/c2go.sed: -------------------------------------------------------------------------------- 1 | # this sed script replaces some bits of the original leg file 2 | # to make it more similar to the Go version, thus avoiding 3 | # to many differences 4 | 5 | /\$\$/ { 6 | s,\$\$->,$$.,g 7 | /\$\$[^}]*$/s,\; *$,,g 8 | } 9 | 10 | s,parse_result,p.tree, 11 | s,references,p.references, 12 | s,notes,p.notes, 13 | s,find_reference,p.findReference,g 14 | 15 | s,->key,.key,g 16 | s,->children,.children,g 17 | s,->contents.str,.contents.str,g 18 | 19 | /{ *if (extens/ { 20 | s,if (,if , 21 | s,)),), 22 | } 23 | /EXT/ s,if extension,if p.extension, 24 | /EXT/ s,{ *extension,{ p.extension,g 25 | /EXT/ s,{ *!extension,{ !p.extension,g 26 | /EXT/ { 27 | s,extension.EXT_FILTER_HTML.,extension.FilterHTML,g 28 | s,extension.EXT_FILTER_STYLES.,extension.FilterStyles,g 29 | s,extension.EXT_SMART.,extension.Smart,g 30 | s,extension.EXT_NOTES.,extension.Notes,g 31 | } 32 | 33 | s,{ *element \*[a-z]*\; *$,{, 34 | 35 | /raw\.key =/ s,;$,, 36 | /result =/ s,;$,, 37 | s,result = mk_el,result := mk_el, 38 | 39 | s,NULL,nil,g 40 | 41 | s, *\; *}, },g 42 | 43 | s,strlen(,len(,g 44 | 45 | s/mk_element/p.mkElem/ 46 | s/mk_str_from_list/p.mkStringFromList/ 47 | s/mk_str/p.mkString/g 48 | s/mk_list/p.mkList/ 49 | s/mk_link/p.mkLink/ 50 | -------------------------------------------------------------------------------- /misc/devel.mk: -------------------------------------------------------------------------------- 1 | MD=./cmd/markdown/markdown 2 | 3 | # 4 | # development utilities 5 | # 6 | gofmt: 7 | rc ./misc/gofmt.rc 8 | 9 | diff: ,,c 10 | tkdiff $< parser.leg 11 | 12 | ,,c: ,,pmd/markdown_parser.leg 13 | sed -f misc/c2go.sed < $< > $@ 14 | 15 | orig-c-src/markdown_parser.leg: orig-c-src 16 | 17 | 18 | bmprepare: 19 | rc ./misc/bmprepare.rc 20 | 21 | benchmark: cmd m ,,pmd ,,prevmd 22 | rc ./misc/benchmark.rc 23 | 24 | 25 | # 26 | # pprof 27 | # 28 | pprof: cmd m 29 | $(MD) -cpuprofile /tmp/md.prof /tmp/,,md.out 30 | @echo go tool pprof \'--nodefraction=0.1\' $(MD) /tmp/md.prof 31 | @echo go tool pprof $(MD) /tmp/md.prof 32 | 33 | .PHONY:\ 34 | diff\ 35 | gofmt\ 36 | pprof\ 37 | -------------------------------------------------------------------------------- /misc/func-name2line.rc: -------------------------------------------------------------------------------- 1 | # print file and line number of closure func_$1 2 | 3 | fnid=$1 4 | pkg=markdown 5 | 6 | account=github.com/knieriem 7 | objpfx=$GOROOT/src/pkg/$account/+m/_obj 8 | prj=$account 9 | cmd=(info line $objpfx/$prj/$pkg._func_$fnid) 10 | cmd=`{echo $cmd | sed 's,\.com,%2ecom,g'} 11 | echo $cmd 12 | gdb --batch --eval-command $"cmd ./cmd/markdown >[2] /dev/null | 13 | grep '^Line.*of' | 14 | awk ' 15 | { 16 | gsub("\"", "", $4) 17 | print $4 ":" $2 18 | } 19 | ' 20 | -------------------------------------------------------------------------------- /misc/gofmt.rc: -------------------------------------------------------------------------------- 1 | fmtopts=('-spaces=false' '-tabwidth=4') 2 | 3 | fn f{ 4 | gofmt $fmtopts -s ../$1 > $1 5 | diff $1 6 | } 7 | 8 | fn diff{ 9 | if (! cmp -s ../$1 $1) { 10 | echo tkdiff $1 ,,fmt/$1 11 | } 12 | } 13 | 14 | if(! test -d ,,fmt) 15 | mkdir ,,fmt 16 | cd ,,fmt 17 | 18 | 19 | # split parser.leg into Go and leg parts, gofmt the Go parts, 20 | # and combine pieces to form a parser.leg again 21 | p=../parser.leg 22 | <$p >,,leg awk ' 23 | /^%%/ { copy=0 } 24 | copy { print } 25 | /^%}/ { copy=1 } 26 | ' 27 | 28 | <$p >,,p.go awk ' 29 | /^%%/ { copy=1; $0 = "//" $0 } 30 | /^%}/ { copy=0 } 31 | copy { print } 32 | /^%{/ { copy=1 } 33 | ' 34 | gofmt $fmtopts -w -s ,,p.go 35 | 36 | >parser.leg { 37 | echo '%{' 38 | cat ,,p.go | sed '/^\/\/%%/,$d' 39 | echo '%}' 40 | cat ,,leg 41 | echo %% 42 | cat ,,p.go | sed '1,/^\/\/%%/d' 43 | } 44 | 45 | 46 | f doc.go 47 | f markdown.go 48 | f output.go 49 | diff parser.leg 50 | 51 | ~ 0 0 52 | -------------------------------------------------------------------------------- /out-groffmm.go: -------------------------------------------------------------------------------- 1 | /* Original C version https://github.com/jgm/peg-markdown/ 2 | * Copyright 2008 John MacFarlane (jgm at berkeley dot edu). 3 | * 4 | * Modifications and translation from C into Go 5 | * based on markdown_output.c 6 | * Copyright 2010 Michael Teichgräber (mt at wmipf dot de) 7 | * 8 | * This program is free software; you can redistribute it and/or modify 9 | * it under the terms of the GNU General Public License or the MIT 10 | * license. See LICENSE for details. 11 | * 12 | * This program is distributed in the hope that it will be useful, 13 | * but WITHOUT ANY WARRANTY; without even the implied warranty of 14 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 15 | * GNU General Public License for more details. 16 | */ 17 | 18 | package markdown 19 | 20 | // groff mm output functions 21 | 22 | import ( 23 | "log" 24 | "strings" 25 | ) 26 | 27 | type troffOut struct { 28 | baseWriter 29 | strikeMacroWritten bool 30 | inListItem bool 31 | escape *strings.Replacer 32 | } 33 | 34 | // Returns a formatter that writes the document in groff mm format. 35 | func ToGroffMM(w Writer) Formatter { 36 | f := new(troffOut) 37 | f.baseWriter = baseWriter{w, 2} 38 | f.escape = strings.NewReplacer(`\`, `\e`) 39 | return f 40 | } 41 | func (f *troffOut) FormatBlock(tree *element) { 42 | f.elist(tree) 43 | } 44 | func (f *troffOut) Finish() { 45 | f.WriteByte('\n') 46 | f.padded = 2 47 | } 48 | 49 | func (h *troffOut) sp() *troffOut { 50 | h.pad(2) 51 | return h 52 | } 53 | func (h *troffOut) br() *troffOut { 54 | h.pad(1) 55 | return h 56 | } 57 | 58 | func (h *troffOut) skipPadding() *troffOut { 59 | h.padded = 2 60 | return h 61 | } 62 | 63 | // write a string 64 | func (w *troffOut) s(s string) *troffOut { 65 | w.WriteString(s) 66 | return w 67 | } 68 | 69 | // write string, escape '\' 70 | func (w *troffOut) str(s string) *troffOut { 71 | if strings.HasPrefix(s, ".") { 72 | w.WriteString(`\[char46]`) 73 | s = s[1:] 74 | } 75 | w.escape.WriteString(w, s) 76 | return w 77 | } 78 | 79 | func (w *troffOut) children(el *element) *troffOut { 80 | return w.elist(el.children) 81 | } 82 | func (w *troffOut) inline(pfx string, el *element, sfx string) *troffOut { 83 | return w.s(pfx).children(el).s(sfx) 84 | } 85 | 86 | func (w *troffOut) req(name string) *troffOut { 87 | return w.br().s(".").s(name) 88 | } 89 | 90 | // write a list of elements 91 | func (w *troffOut) elist(list *element) *troffOut { 92 | for i := 0; list != nil; i++ { 93 | w.elem(list, i == 0) 94 | list = list.next 95 | } 96 | return w 97 | } 98 | 99 | func (w *troffOut) elem(elt *element, isFirst bool) *troffOut { 100 | var s string 101 | 102 | switch elt.key { 103 | case SPACE: 104 | s = elt.contents.str 105 | case LINEBREAK: 106 | w.req("br\n") 107 | case STR: 108 | w.str(elt.contents.str) 109 | case ELLIPSIS: 110 | s = "..." 111 | case EMDASH: 112 | s = `\[em]` 113 | case ENDASH: 114 | s = `\[en]` 115 | case APOSTROPHE: 116 | s = "'" 117 | case SINGLEQUOTED: 118 | w.inline("`", elt, "'") 119 | case DOUBLEQUOTED: 120 | w.inline(`\[lq]`, elt, `\[rq]`) 121 | case CODE: 122 | w.s(`\fC`).str(elt.contents.str).s(`\fR`) 123 | case HTML: 124 | /* don't print HTML */ 125 | case LINK: 126 | link := elt.contents.link 127 | w.elist(link.label) 128 | w.s(" (").s(link.url).s(")") 129 | case IMAGE: 130 | w.s("[IMAGE: ").elist(elt.contents.link.label).s("]") 131 | /* not supported */ 132 | case EMPH: 133 | w.inline(`\fI`, elt, `\fR`) 134 | case STRONG: 135 | w.inline(`\fB`, elt, `\fR`) 136 | case STRIKE: 137 | w.s("\\c\n") 138 | if !w.strikeMacroWritten { 139 | w.s(`.de ST 140 | .nr width \w'\\$1' 141 | \Z@\v'-.25m'\l'\\n[width]u'@\\$1\c 142 | .. 143 | `) 144 | w.strikeMacroWritten = true 145 | } 146 | w.inline(".ST \"", elt, `"`).br() 147 | case LIST: 148 | w.children(elt) 149 | case RAW: 150 | /* Shouldn't occur - these are handled by process_raw_blocks() */ 151 | log.Fatalf("RAW") 152 | case H1, H2, H3, H4, H5, H6: 153 | h := ".H " + string('1'+elt.key-H1) + ` "` /* assumes H1 ... H6 are in order */ 154 | w.br().inline(h, elt, `"`) 155 | case PLAIN: 156 | w.br().children(elt) 157 | case PARA: 158 | if !w.inListItem || !isFirst { 159 | w.req("P\n").children(elt) 160 | } else { 161 | w.br().children(elt) 162 | } 163 | case HRULE: 164 | w.br().s(`\l'\n(.lu*8u/10u'`) 165 | case HTMLBLOCK: 166 | /* don't print HTML block */ 167 | case VERBATIM: 168 | w.req("VERBON 2\n") 169 | w.str(elt.contents.str) 170 | w.s(".VERBOFF") 171 | case BULLETLIST: 172 | w.req("BL").children(elt).req("LE 1") 173 | case ORDEREDLIST: 174 | w.req("AL").children(elt).req("LE 1") 175 | case DEFINITIONLIST: 176 | w.req(`BVL \\n(Pin`).children(elt).req("LE 1") 177 | case DEFTITLE: 178 | w.req(`DLI "`).children(elt).s(`"`) 179 | case DEFDATA: 180 | w.children(elt) 181 | w.req("br") 182 | case LISTITEM: 183 | w.req("LI\n") 184 | w.inListItem = true 185 | w.skipPadding() 186 | w.children(elt) 187 | w.inListItem = false 188 | case BLOCKQUOTE: 189 | w.req("DS I\n") 190 | w.skipPadding() 191 | w.children(elt) 192 | w.req("DE") 193 | case NOTE: 194 | /* if contents.str == 0, then print note; else ignore, since this 195 | * is a note block that has been incorporated into the notes list */ 196 | if elt.contents.str == "" { 197 | w.s("\\*F\n") 198 | w.s(".FS\n") 199 | w.skipPadding() 200 | w.children(elt) 201 | w.req("FE\n") 202 | } 203 | case REFERENCE: 204 | /* Nonprinting */ 205 | default: 206 | log.Fatalf("troffOut.elem encountered unknown element key = %d\n", elt.key) 207 | } 208 | if s != "" { 209 | w.s(s) 210 | } 211 | return w 212 | } 213 | -------------------------------------------------------------------------------- /output.go: -------------------------------------------------------------------------------- 1 | /* Original C version https://github.com/jgm/peg-markdown/ 2 | * Copyright 2008 John MacFarlane (jgm at berkeley dot edu). 3 | * 4 | * Modifications and translation from C into Go 5 | * based on markdown_output.c 6 | * Copyright 2010 Michael Teichgräber (mt at wmipf dot de) 7 | * 8 | * This program is free software; you can redistribute it and/or modify 9 | * it under the terms of the GNU General Public License or the MIT 10 | * license. See LICENSE for details. 11 | * 12 | * This program is distributed in the hope that it will be useful, 13 | * but WITHOUT ANY WARRANTY; without even the implied warranty of 14 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 15 | * GNU General Public License for more details. 16 | */ 17 | 18 | package markdown 19 | 20 | // HTML output functions 21 | 22 | import ( 23 | "fmt" 24 | "log" 25 | "math/rand" 26 | "strings" 27 | ) 28 | 29 | type Writer interface { 30 | Write([]byte) (int, error) 31 | WriteString(string) (int, error) 32 | WriteRune(rune) (int, error) 33 | WriteByte(byte) error 34 | } 35 | 36 | type baseWriter struct { 37 | Writer 38 | padded int 39 | } 40 | 41 | type htmlOut struct { 42 | baseWriter 43 | obfuscate bool 44 | 45 | notenum int 46 | endNotes []*element /* List of endnotes to print after main content. */ 47 | } 48 | 49 | func ToHTML(w Writer) Formatter { 50 | f := new(htmlOut) 51 | f.baseWriter = baseWriter{w, 2} 52 | return f 53 | } 54 | func (f *htmlOut) FormatBlock(tree *element) { 55 | f.elist(tree) 56 | } 57 | func (f *htmlOut) Finish() { 58 | if len(f.endNotes) != 0 { 59 | f.sp() 60 | f.printEndnotes() 61 | } 62 | f.WriteByte('\n') 63 | f.padded = 2 64 | } 65 | 66 | // pad - add a number of newlines, the value of the 67 | // argument minus the value of `padded' 68 | // One newline means a line break, similar to troff's .br 69 | // request, two newlines mean a line break plus an 70 | // empty line, similar to troff's .sp request 71 | func (w *baseWriter) pad(n int) { 72 | for ; n > w.padded; n-- { 73 | w.WriteByte('\n') 74 | } 75 | w.padded = 0 76 | } 77 | 78 | func (h *htmlOut) br() *htmlOut { 79 | h.pad(1) 80 | return h 81 | } 82 | 83 | func (h *htmlOut) sp() *htmlOut { 84 | h.pad(2) 85 | return h 86 | } 87 | 88 | func (h *htmlOut) skipPadding() *htmlOut { 89 | h.padded = 2 90 | return h 91 | } 92 | 93 | // print a string 94 | func (w *htmlOut) s(s string) *htmlOut { 95 | w.WriteString(s) 96 | return w 97 | } 98 | 99 | /* print string, escaping for HTML 100 | * If obfuscate selected, convert characters to hex or decimal entities at random 101 | */ 102 | func (w *htmlOut) str(s string) *htmlOut { 103 | var ws string 104 | var i0 = 0 105 | 106 | o := w.obfuscate 107 | for i, r := range s { 108 | switch r { 109 | case '&': 110 | ws = "&" 111 | case '<': 112 | ws = "<" 113 | case '>': 114 | ws = ">" 115 | case '"': 116 | ws = """ 117 | default: 118 | if o && r < 128 && r >= 0 { 119 | if rand.Intn(2) == 0 { 120 | ws = fmt.Sprintf("&#%d;", r) 121 | } else { 122 | ws = fmt.Sprintf("&#%x;", r) 123 | } 124 | } else { 125 | if i0 == -1 { 126 | i0 = i 127 | } 128 | continue 129 | } 130 | } 131 | if i0 != -1 { 132 | w.WriteString(s[i0:i]) 133 | i0 = -1 134 | } 135 | w.WriteString(ws) 136 | } 137 | if i0 != -1 { 138 | w.WriteString(s[i0:]) 139 | } 140 | return w 141 | } 142 | 143 | func (w *htmlOut) children(el *element) *htmlOut { 144 | return w.elist(el.children) 145 | } 146 | func (w *htmlOut) inline(tag string, el *element) *htmlOut { 147 | return w.s(tag).children(el).s("\n" 175 | case STR: 176 | w.str(elt.contents.str) 177 | case ELLIPSIS: 178 | s = "…" 179 | case EMDASH: 180 | s = "—" 181 | case ENDASH: 182 | s = "–" 183 | case APOSTROPHE: 184 | s = "’" 185 | case SINGLEQUOTED: 186 | w.s("‘").children(elt).s("’") 187 | case DOUBLEQUOTED: 188 | w.s("“").children(elt).s("”") 189 | case CODE: 190 | w.s("").str(elt.contents.str).s("") 191 | case HTML: 192 | s = elt.contents.str 193 | case LINK: 194 | o := w.obfuscate 195 | if strings.Index(elt.contents.link.url, "mailto:") == 0 { 196 | w.obfuscate = true /* obfuscate mailto: links */ 197 | } 198 | w.s(` 0 { 200 | w.s(` title="`).str(elt.contents.link.title).s(`"`) 201 | } 202 | w.s(">").elist(elt.contents.link.label).s("") 203 | w.obfuscate = o 204 | case IMAGE: 205 | w.s(``)
206 | 		w.elist(elt.contents.link.label).s(` 0 { 208 | w.s(` title="`).str(elt.contents.link.title).s(`"`) 209 | } 210 | w.s(" />") 211 | case EMPH: 212 | w.inline("", elt) 213 | case STRONG: 214 | w.inline("", elt) 215 | case STRIKE: 216 | w.inline("", elt) 217 | case LIST: 218 | w.children(elt) 219 | case RAW: 220 | /* Shouldn't occur - these are handled by process_raw_blocks() */ 221 | log.Fatalf("RAW") 222 | case H1, H2, H3, H4, H5, H6: 223 | h := "" /* assumes H1 ... H6 are in order */ 224 | w.sp().inline(h, elt) 225 | case PLAIN: 226 | w.br().children(elt) 227 | case PARA: 228 | w.sp().inline("

", elt) 229 | case HRULE: 230 | w.sp().s("


") 231 | case HTMLBLOCK: 232 | w.sp().s(elt.contents.str) 233 | case VERBATIM: 234 | w.sp().s("
").str(elt.contents.str).s("
") 235 | case BULLETLIST: 236 | w.listBlock("
    ", elt) 237 | case ORDEREDLIST: 238 | w.listBlock("
      ", elt) 239 | case DEFINITIONLIST: 240 | w.listBlock("
      ", elt) 241 | case DEFTITLE: 242 | w.listItem("
      ", elt) 243 | case DEFDATA: 244 | w.listItem("
      ", elt) 245 | case LISTITEM: 246 | w.listItem("
    1. ", elt) 247 | case BLOCKQUOTE: 248 | w.sp().s("
      \n").skipPadding().children(elt).br().s("
      ") 249 | case REFERENCE: 250 | /* Nonprinting */ 251 | case NOTE: 252 | /* if contents.str == 0, then print note; else ignore, since this 253 | * is a note block that has been incorporated into the notes list 254 | */ 255 | if elt.contents.str == "" { 256 | w.endNotes = append(w.endNotes, elt) /* add an endnote to global endnotes list */ 257 | w.notenum++ 258 | nn := w.notenum 259 | s = fmt.Sprintf(`[%d]`, 260 | nn, nn, nn, nn) 261 | } 262 | default: 263 | log.Fatalf("htmlOut.elem encountered unknown element key = %d\n", elt.key) 264 | } 265 | if s != "" { 266 | w.s(s) 267 | } 268 | return w 269 | } 270 | 271 | func (w *htmlOut) printEndnotes() { 272 | extraNewline := func() { 273 | // add an extra newline to maintain 274 | // compatibility with the C version. 275 | w.padded-- 276 | } 277 | 278 | counter := 0 279 | 280 | w.s("
      \n
        ") 281 | for _, elt := range w.endNotes { 282 | counter++ 283 | extraNewline() 284 | w.br().s(fmt.Sprintf("
      1. \n", counter)).skipPadding() 285 | w.children(elt) 286 | w.s(fmt.Sprintf(" [back]", counter)) 287 | w.br().s("
      2. ") 288 | } 289 | extraNewline() 290 | w.br().s("
      ") 291 | } 292 | -------------------------------------------------------------------------------- /portid: -------------------------------------------------------------------------------- 1 | 6b367c802475 2 | -------------------------------------------------------------------------------- /tests/README.md: -------------------------------------------------------------------------------- 1 | This directory contains test files used by ../markdown_test.go. 2 | 3 | ## INDEX 4 | 5 | * *md1.0.3* 6 | 7 | Files from John Gruber's test suite MarkdownTest_1.0.3, 8 | imported from https://github.com/jgm/peg-markdown/. 9 | -------------------------------------------------------------------------------- /tests/gen.rc: -------------------------------------------------------------------------------- 1 | pmd=../../,,pmd/markdown 2 | 3 | for (i in *.text) { 4 | stem=`{echo $i | sed 's,.text$,,'} 5 | $pmd < $i >$"stem.html 6 | $pmd -t groff-mm < $i >$"stem.mm 7 | } 8 | -------------------------------------------------------------------------------- /tests/issues/footnotes-10.html: -------------------------------------------------------------------------------- 1 |

      Here is a footnote reference,[1] and another.[2]

      2 | 3 |

      This paragraph won't be part of the note, because it 4 | isn't indented.

      5 | 6 |
      7 |
        8 | 9 |
      1. 10 |

        Here is the footnote.

        [back] 11 |
      2. 12 | 13 |
      3. 14 |

        Here's one with multiple blocks.

        15 | 16 |

        Subsequent paragraphs are indented to show that they 17 | belong to the previous footnote.

        18 | 19 |
        { some.code }
        20 | 
        21 | 22 |

        The whole paragraph can be indented, or just the first 23 | line. In this way, multi-paragraph footnotes work like 24 | multi-paragraph list items.

        [back] 25 |
      4. 26 | 27 |
      28 | -------------------------------------------------------------------------------- /tests/issues/footnotes-10.mm: -------------------------------------------------------------------------------- 1 | .P 2 | Here is a footnote reference,\*F 3 | .FS 4 | .P 5 | Here is the footnote. 6 | .FE 7 | and another.\*F 8 | .FS 9 | .P 10 | Here's one with multiple blocks. 11 | .P 12 | Subsequent paragraphs are indented to show that they 13 | belong to the previous footnote. 14 | .VERBON 2 15 | { some.code } 16 | .VERBOFF 17 | .P 18 | The whole paragraph can be indented, or just the first 19 | line. In this way, multi-paragraph footnotes work like 20 | multi-paragraph list items. 21 | .FE 22 | 23 | .P 24 | This paragraph won't be part of the note, because it 25 | isn't indented. 26 | -------------------------------------------------------------------------------- /tests/issues/footnotes-10.text: -------------------------------------------------------------------------------- 1 | Here is a footnote reference,[^1] and another.[^longnote] 2 | 3 | [^1]: Here is the footnote. 4 | 5 | [^longnote]: Here's one with multiple blocks. 6 | 7 | Subsequent paragraphs are indented to show that they 8 | belong to the previous footnote. 9 | 10 | { some.code } 11 | 12 | The whole paragraph can be indented, or just the first 13 | line. In this way, multi-paragraph footnotes work like 14 | multi-paragraph list items. 15 | 16 | This paragraph won't be part of the note, because it 17 | isn't indented. 18 | -------------------------------------------------------------------------------- /tests/md1.0.3/Amps and angle encoding.html: -------------------------------------------------------------------------------- 1 |

      AT&T has an ampersand in their name.

      2 | 3 |

      AT&T is another way to write it.

      4 | 5 |

      This & that.

      6 | 7 |

      4 < 5.

      8 | 9 |

      6 > 5.

      10 | 11 |

      Here's a link with an ampersand in the URL.

      12 | 13 |

      Here's a link with an amersand in the link text: AT&T.

      14 | 15 |

      Here's an inline link.

      16 | 17 |

      Here's an inline link.

      18 | -------------------------------------------------------------------------------- /tests/md1.0.3/Amps and angle encoding.mm: -------------------------------------------------------------------------------- 1 | .P 2 | AT&T has an ampersand in their name. 3 | .P 4 | ATT is another way to write it. 5 | .P 6 | This & that. 7 | .P 8 | 4 < 5. 9 | .P 10 | 6 > 5. 11 | .P 12 | Here's a link (http://example.com/?foo=1&bar=2) with an ampersand in the URL. 13 | .P 14 | Here's a link with an amersand in the link text: AT&T (http://att.com/)\[char46] 15 | .P 16 | Here's an inline link (/script?foo=1&bar=2)\[char46] 17 | .P 18 | Here's an inline link (/script?foo=1&bar=2)\[char46] 19 | -------------------------------------------------------------------------------- /tests/md1.0.3/Amps and angle encoding.text: -------------------------------------------------------------------------------- 1 | AT&T has an ampersand in their name. 2 | 3 | AT&T is another way to write it. 4 | 5 | This & that. 6 | 7 | 4 < 5. 8 | 9 | 6 > 5. 10 | 11 | Here's a [link] [1] with an ampersand in the URL. 12 | 13 | Here's a link with an amersand in the link text: [AT&T] [2]. 14 | 15 | Here's an inline [link](/script?foo=1&bar=2). 16 | 17 | Here's an inline [link](). 18 | 19 | 20 | [1]: http://example.com/?foo=1&bar=2 21 | [2]: http://att.com/ "AT&T" -------------------------------------------------------------------------------- /tests/md1.0.3/Auto links.html: -------------------------------------------------------------------------------- 1 |

      Link: http://example.com/.

      2 | 3 |

      With an ampersand: http://example.com/?foo=1&bar=2

      4 | 5 | 10 | 11 |
      12 |

      Blockquoted: http://example.com/

      13 |
      14 | 15 |

      Auto-links should not occur here: <http://example.com/>

      16 | 17 |
      or here: <http://example.com/>
      18 | 
      19 | -------------------------------------------------------------------------------- /tests/md1.0.3/Auto links.mm: -------------------------------------------------------------------------------- 1 | .P 2 | Link: http://example.com/ (http://example.com/)\[char46] 3 | .P 4 | With an ampersand: http://example.com/?foo=1&bar=2 (http://example.com/?foo=1&bar=2) 5 | .BL 6 | .LI 7 | In a list? 8 | .LI 9 | http://example.com/ (http://example.com/) 10 | .LI 11 | It should. 12 | .LE 1 13 | .DS I 14 | .P 15 | Blockquoted: http://example.com/ (http://example.com/) 16 | .DE 17 | .P 18 | Auto-links should not occur here: \fC\fR 19 | .VERBON 2 20 | or here: 21 | .VERBOFF 22 | -------------------------------------------------------------------------------- /tests/md1.0.3/Auto links.text: -------------------------------------------------------------------------------- 1 | Link: . 2 | 3 | With an ampersand: 4 | 5 | * In a list? 6 | * 7 | * It should. 8 | 9 | > Blockquoted: 10 | 11 | Auto-links should not occur here: `` 12 | 13 | or here: -------------------------------------------------------------------------------- /tests/md1.0.3/Backslash escapes.html: -------------------------------------------------------------------------------- 1 |

      These should all get escaped:

      2 | 3 |

      Backslash: \

      4 | 5 |

      Backtick: `

      6 | 7 |

      Asterisk: *

      8 | 9 |

      Underscore: _

      10 | 11 |

      Left brace: {

      12 | 13 |

      Right brace: }

      14 | 15 |

      Left bracket: [

      16 | 17 |

      Right bracket: ]

      18 | 19 |

      Left paren: (

      20 | 21 |

      Right paren: )

      22 | 23 |

      Greater-than: >

      24 | 25 |

      Hash: #

      26 | 27 |

      Period: .

      28 | 29 |

      Bang: !

      30 | 31 |

      Plus: +

      32 | 33 |

      Minus: -

      34 | 35 |

      These should not, because they occur within a code block:

      36 | 37 |
      Backslash: \\
       38 | 
       39 | Backtick: \`
       40 | 
       41 | Asterisk: \*
       42 | 
       43 | Underscore: \_
       44 | 
       45 | Left brace: \{
       46 | 
       47 | Right brace: \}
       48 | 
       49 | Left bracket: \[
       50 | 
       51 | Right bracket: \]
       52 | 
       53 | Left paren: \(
       54 | 
       55 | Right paren: \)
       56 | 
       57 | Greater-than: \>
       58 | 
       59 | Hash: \#
       60 | 
       61 | Period: \.
       62 | 
       63 | Bang: \!
       64 | 
       65 | Plus: \+
       66 | 
       67 | Minus: \-
       68 | 
      69 | 70 |

      Nor should these, which occur in code spans:

      71 | 72 |

      Backslash: \\

      73 | 74 |

      Backtick: \`

      75 | 76 |

      Asterisk: \*

      77 | 78 |

      Underscore: \_

      79 | 80 |

      Left brace: \{

      81 | 82 |

      Right brace: \}

      83 | 84 |

      Left bracket: \[

      85 | 86 |

      Right bracket: \]

      87 | 88 |

      Left paren: \(

      89 | 90 |

      Right paren: \)

      91 | 92 |

      Greater-than: \>

      93 | 94 |

      Hash: \#

      95 | 96 |

      Period: \.

      97 | 98 |

      Bang: \!

      99 | 100 |

      Plus: \+

      101 | 102 |

      Minus: \-

      103 | 104 |

      These should get escaped, even though they're matching pairs for 105 | other Markdown constructs:

      106 | 107 |

      *asterisks*

      108 | 109 |

      _underscores_

      110 | 111 |

      `backticks`

      112 | 113 |

      This is a code span with a literal backslash-backtick sequence: \`

      114 | 115 |

      This is a tag with unescaped backticks bar.

      116 | 117 |

      This is a tag with backslashes bar.

      118 | -------------------------------------------------------------------------------- /tests/md1.0.3/Backslash escapes.mm: -------------------------------------------------------------------------------- 1 | .P 2 | These should all get escaped: 3 | .P 4 | Backslash: \e 5 | .P 6 | Backtick: ` 7 | .P 8 | Asterisk: * 9 | .P 10 | Underscore: _ 11 | .P 12 | Left brace: { 13 | .P 14 | Right brace: } 15 | .P 16 | Left bracket: [ 17 | .P 18 | Right bracket: ] 19 | .P 20 | Left paren: ( 21 | .P 22 | Right paren: ) 23 | .P 24 | Greater-than: > 25 | .P 26 | Hash: # 27 | .P 28 | Period: \[char46] 29 | .P 30 | Bang: ! 31 | .P 32 | Plus: + 33 | .P 34 | Minus: - 35 | .P 36 | These should not, because they occur within a code block: 37 | .VERBON 2 38 | Backslash: \e\e 39 | 40 | Backtick: \e` 41 | 42 | Asterisk: \e* 43 | 44 | Underscore: \e_ 45 | 46 | Left brace: \e{ 47 | 48 | Right brace: \e} 49 | 50 | Left bracket: \e[ 51 | 52 | Right bracket: \e] 53 | 54 | Left paren: \e( 55 | 56 | Right paren: \e) 57 | 58 | Greater-than: \e> 59 | 60 | Hash: \e# 61 | 62 | Period: \e. 63 | 64 | Bang: \e! 65 | 66 | Plus: \e+ 67 | 68 | Minus: \e- 69 | .VERBOFF 70 | .P 71 | Nor should these, which occur in code spans: 72 | .P 73 | Backslash: \fC\e\e\fR 74 | .P 75 | Backtick: \fC\e`\fR 76 | .P 77 | Asterisk: \fC\e*\fR 78 | .P 79 | Underscore: \fC\e_\fR 80 | .P 81 | Left brace: \fC\e{\fR 82 | .P 83 | Right brace: \fC\e}\fR 84 | .P 85 | Left bracket: \fC\e[\fR 86 | .P 87 | Right bracket: \fC\e]\fR 88 | .P 89 | Left paren: \fC\e(\fR 90 | .P 91 | Right paren: \fC\e)\fR 92 | .P 93 | Greater-than: \fC\e>\fR 94 | .P 95 | Hash: \fC\e#\fR 96 | .P 97 | Period: \fC\e.\fR 98 | .P 99 | Bang: \fC\e!\fR 100 | .P 101 | Plus: \fC\e+\fR 102 | .P 103 | Minus: \fC\e-\fR 104 | .P 105 | These should get escaped, even though they're matching pairs for 106 | other Markdown constructs: 107 | .P 108 | *asterisks* 109 | .P 110 | _underscores_ 111 | .P 112 | `backticks` 113 | .P 114 | This is a code span with a literal backslash-backtick sequence: \fC\e`\fR 115 | .P 116 | This is a tag with unescaped backticks bar\[char46] 117 | .P 118 | This is a tag with backslashes bar\[char46] 119 | -------------------------------------------------------------------------------- /tests/md1.0.3/Backslash escapes.text: -------------------------------------------------------------------------------- 1 | These should all get escaped: 2 | 3 | Backslash: \\ 4 | 5 | Backtick: \` 6 | 7 | Asterisk: \* 8 | 9 | Underscore: \_ 10 | 11 | Left brace: \{ 12 | 13 | Right brace: \} 14 | 15 | Left bracket: \[ 16 | 17 | Right bracket: \] 18 | 19 | Left paren: \( 20 | 21 | Right paren: \) 22 | 23 | Greater-than: \> 24 | 25 | Hash: \# 26 | 27 | Period: \. 28 | 29 | Bang: \! 30 | 31 | Plus: \+ 32 | 33 | Minus: \- 34 | 35 | 36 | 37 | These should not, because they occur within a code block: 38 | 39 | Backslash: \\ 40 | 41 | Backtick: \` 42 | 43 | Asterisk: \* 44 | 45 | Underscore: \_ 46 | 47 | Left brace: \{ 48 | 49 | Right brace: \} 50 | 51 | Left bracket: \[ 52 | 53 | Right bracket: \] 54 | 55 | Left paren: \( 56 | 57 | Right paren: \) 58 | 59 | Greater-than: \> 60 | 61 | Hash: \# 62 | 63 | Period: \. 64 | 65 | Bang: \! 66 | 67 | Plus: \+ 68 | 69 | Minus: \- 70 | 71 | 72 | Nor should these, which occur in code spans: 73 | 74 | Backslash: `\\` 75 | 76 | Backtick: `` \` `` 77 | 78 | Asterisk: `\*` 79 | 80 | Underscore: `\_` 81 | 82 | Left brace: `\{` 83 | 84 | Right brace: `\}` 85 | 86 | Left bracket: `\[` 87 | 88 | Right bracket: `\]` 89 | 90 | Left paren: `\(` 91 | 92 | Right paren: `\)` 93 | 94 | Greater-than: `\>` 95 | 96 | Hash: `\#` 97 | 98 | Period: `\.` 99 | 100 | Bang: `\!` 101 | 102 | Plus: `\+` 103 | 104 | Minus: `\-` 105 | 106 | 107 | These should get escaped, even though they're matching pairs for 108 | other Markdown constructs: 109 | 110 | \*asterisks\* 111 | 112 | \_underscores\_ 113 | 114 | \`backticks\` 115 | 116 | This is a code span with a literal backslash-backtick sequence: `` \` `` 117 | 118 | This is a tag with unescaped backticks bar. 119 | 120 | This is a tag with backslashes bar. 121 | -------------------------------------------------------------------------------- /tests/md1.0.3/Blockquotes with code blocks.html: -------------------------------------------------------------------------------- 1 |
      2 |

      Example:

      3 | 4 |
      sub status {
       5 |     print "working";
       6 | }
       7 | 
      8 | 9 |

      Or:

      10 | 11 |
      sub status {
      12 |     return "working";
      13 | }
      14 | 
      15 |
      16 | -------------------------------------------------------------------------------- /tests/md1.0.3/Blockquotes with code blocks.mm: -------------------------------------------------------------------------------- 1 | .DS I 2 | .P 3 | Example: 4 | .VERBON 2 5 | sub status { 6 | print "working"; 7 | } 8 | .VERBOFF 9 | .P 10 | Or: 11 | .VERBON 2 12 | sub status { 13 | return "working"; 14 | } 15 | .VERBOFF 16 | .DE 17 | -------------------------------------------------------------------------------- /tests/md1.0.3/Blockquotes with code blocks.text: -------------------------------------------------------------------------------- 1 | > Example: 2 | > 3 | > sub status { 4 | > print "working"; 5 | > } 6 | > 7 | > Or: 8 | > 9 | > sub status { 10 | > return "working"; 11 | > } 12 | -------------------------------------------------------------------------------- /tests/md1.0.3/Code Blocks.html: -------------------------------------------------------------------------------- 1 |
      code block on the first line
       2 | 
      3 | 4 |

      Regular text.

      5 | 6 |
      code block indented by spaces
       7 | 
      8 | 9 |

      Regular text.

      10 | 11 |
      the lines in this block  
      12 | all contain trailing spaces  
      13 | 
      14 | 15 |

      Regular Text.

      16 | 17 |
      code block on the last line
      18 | 
      19 | -------------------------------------------------------------------------------- /tests/md1.0.3/Code Blocks.mm: -------------------------------------------------------------------------------- 1 | .VERBON 2 2 | code block on the first line 3 | .VERBOFF 4 | .P 5 | Regular text. 6 | .VERBON 2 7 | code block indented by spaces 8 | .VERBOFF 9 | .P 10 | Regular text. 11 | .VERBON 2 12 | the lines in this block 13 | all contain trailing spaces 14 | .VERBOFF 15 | .P 16 | Regular Text. 17 | .VERBON 2 18 | code block on the last line 19 | .VERBOFF 20 | -------------------------------------------------------------------------------- /tests/md1.0.3/Code Blocks.text: -------------------------------------------------------------------------------- 1 | code block on the first line 2 | 3 | Regular text. 4 | 5 | code block indented by spaces 6 | 7 | Regular text. 8 | 9 | the lines in this block 10 | all contain trailing spaces 11 | 12 | Regular Text. 13 | 14 | code block on the last line -------------------------------------------------------------------------------- /tests/md1.0.3/Code Spans.html: -------------------------------------------------------------------------------- 1 |

      <test a=" content of attribute ">

      2 | 3 |

      Fix for backticks within HTML tag: like this

      4 | 5 |

      Here's how you put `backticks` in a code span.

      6 | -------------------------------------------------------------------------------- /tests/md1.0.3/Code Spans.mm: -------------------------------------------------------------------------------- 1 | .P 2 | \fC\fR 3 | .P 4 | Fix for backticks within HTML tag: like this 5 | .P 6 | Here's how you put \fC`backticks`\fR in a code span. 7 | -------------------------------------------------------------------------------- /tests/md1.0.3/Code Spans.text: -------------------------------------------------------------------------------- 1 | `` 2 | 3 | Fix for backticks within HTML tag: like this 4 | 5 | Here's how you put `` `backticks` `` in a code span. 6 | 7 | -------------------------------------------------------------------------------- /tests/md1.0.3/Hard-wrapped paragraphs with list-like lines.html: -------------------------------------------------------------------------------- 1 |

      In Markdown 1.0.0 and earlier. Version 2 | 8. This line turns into a list item. 3 | Because a hard-wrapped line in the 4 | middle of a paragraph looked like a 5 | list item.

      6 | 7 |

      Here's one with a bullet. 8 | * criminey.

      9 | -------------------------------------------------------------------------------- /tests/md1.0.3/Hard-wrapped paragraphs with list-like lines.mm: -------------------------------------------------------------------------------- 1 | .P 2 | In Markdown 1.0.0 and earlier. Version 3 | 8. This line turns into a list item. 4 | Because a hard-wrapped line in the 5 | middle of a paragraph looked like a 6 | list item. 7 | .P 8 | Here's one with a bullet. 9 | * criminey. 10 | -------------------------------------------------------------------------------- /tests/md1.0.3/Hard-wrapped paragraphs with list-like lines.text: -------------------------------------------------------------------------------- 1 | In Markdown 1.0.0 and earlier. Version 2 | 8. This line turns into a list item. 3 | Because a hard-wrapped line in the 4 | middle of a paragraph looked like a 5 | list item. 6 | 7 | Here's one with a bullet. 8 | * criminey. 9 | -------------------------------------------------------------------------------- /tests/md1.0.3/Horizontal rules.html: -------------------------------------------------------------------------------- 1 |

      Dashes:

      2 | 3 |
      4 | 5 |
      6 | 7 |
      8 | 9 |
      10 | 11 |
      ---
      12 | 
      13 | 14 |
      15 | 16 |
      17 | 18 |
      19 | 20 |
      21 | 22 |
      - - -
      23 | 
      24 | 25 |

      Asterisks:

      26 | 27 |
      28 | 29 |
      30 | 31 |
      32 | 33 |
      34 | 35 |
      ***
      36 | 
      37 | 38 |
      39 | 40 |
      41 | 42 |
      43 | 44 |
      45 | 46 |
      * * *
      47 | 
      48 | 49 |

      Underscores:

      50 | 51 |
      52 | 53 |
      54 | 55 |
      56 | 57 |
      58 | 59 |
      ___
      60 | 
      61 | 62 |
      63 | 64 |
      65 | 66 |
      67 | 68 |
      69 | 70 |
      _ _ _
      71 | 
      72 | -------------------------------------------------------------------------------- /tests/md1.0.3/Horizontal rules.mm: -------------------------------------------------------------------------------- 1 | .P 2 | Dashes: 3 | \l'\n(.lu*8u/10u' 4 | \l'\n(.lu*8u/10u' 5 | \l'\n(.lu*8u/10u' 6 | \l'\n(.lu*8u/10u' 7 | .VERBON 2 8 | --- 9 | .VERBOFF 10 | \l'\n(.lu*8u/10u' 11 | \l'\n(.lu*8u/10u' 12 | \l'\n(.lu*8u/10u' 13 | \l'\n(.lu*8u/10u' 14 | .VERBON 2 15 | - - - 16 | .VERBOFF 17 | .P 18 | Asterisks: 19 | \l'\n(.lu*8u/10u' 20 | \l'\n(.lu*8u/10u' 21 | \l'\n(.lu*8u/10u' 22 | \l'\n(.lu*8u/10u' 23 | .VERBON 2 24 | *** 25 | .VERBOFF 26 | \l'\n(.lu*8u/10u' 27 | \l'\n(.lu*8u/10u' 28 | \l'\n(.lu*8u/10u' 29 | \l'\n(.lu*8u/10u' 30 | .VERBON 2 31 | * * * 32 | .VERBOFF 33 | .P 34 | Underscores: 35 | \l'\n(.lu*8u/10u' 36 | \l'\n(.lu*8u/10u' 37 | \l'\n(.lu*8u/10u' 38 | \l'\n(.lu*8u/10u' 39 | .VERBON 2 40 | ___ 41 | .VERBOFF 42 | \l'\n(.lu*8u/10u' 43 | \l'\n(.lu*8u/10u' 44 | \l'\n(.lu*8u/10u' 45 | \l'\n(.lu*8u/10u' 46 | .VERBON 2 47 | _ _ _ 48 | .VERBOFF 49 | -------------------------------------------------------------------------------- /tests/md1.0.3/Horizontal rules.text: -------------------------------------------------------------------------------- 1 | Dashes: 2 | 3 | --- 4 | 5 | --- 6 | 7 | --- 8 | 9 | --- 10 | 11 | --- 12 | 13 | - - - 14 | 15 | - - - 16 | 17 | - - - 18 | 19 | - - - 20 | 21 | - - - 22 | 23 | 24 | Asterisks: 25 | 26 | *** 27 | 28 | *** 29 | 30 | *** 31 | 32 | *** 33 | 34 | *** 35 | 36 | * * * 37 | 38 | * * * 39 | 40 | * * * 41 | 42 | * * * 43 | 44 | * * * 45 | 46 | 47 | Underscores: 48 | 49 | ___ 50 | 51 | ___ 52 | 53 | ___ 54 | 55 | ___ 56 | 57 | ___ 58 | 59 | _ _ _ 60 | 61 | _ _ _ 62 | 63 | _ _ _ 64 | 65 | _ _ _ 66 | 67 | _ _ _ 68 | -------------------------------------------------------------------------------- /tests/md1.0.3/Inline HTML (Advanced).html: -------------------------------------------------------------------------------- 1 |

      Simple block on one line:

      2 | 3 |
      foo
      4 | 5 |

      And nested without indentation:

      6 | 7 |
      8 |
      9 |
      10 | foo 11 |
      12 |
      13 |
      14 |
      bar
      15 |
      16 | -------------------------------------------------------------------------------- /tests/md1.0.3/Inline HTML (Advanced).mm: -------------------------------------------------------------------------------- 1 | .P 2 | Simple block on one line: 3 | .P 4 | And nested without indentation: 5 | -------------------------------------------------------------------------------- /tests/md1.0.3/Inline HTML (Advanced).text: -------------------------------------------------------------------------------- 1 | Simple block on one line: 2 | 3 |
      foo
      4 | 5 | And nested without indentation: 6 | 7 |
      8 |
      9 |
      10 | foo 11 |
      12 |
      13 |
      14 |
      bar
      15 |
      16 | -------------------------------------------------------------------------------- /tests/md1.0.3/Inline HTML (Simple).html: -------------------------------------------------------------------------------- 1 |

      Here's a simple block:

      2 | 3 |
      4 | foo 5 |
      6 | 7 |

      This should be a code block, though:

      8 | 9 |
      <div>
      10 |     foo
      11 | </div>
      12 | 
      13 | 14 |

      As should this:

      15 | 16 |
      <div>foo</div>
      17 | 
      18 | 19 |

      Now, nested:

      20 | 21 |
      22 |
      23 |
      24 | foo 25 |
      26 |
      27 |
      28 | 29 |

      This should just be an HTML comment:

      30 | 31 | 32 | 33 |

      Multiline:

      34 | 35 | 39 | 40 |

      Code block:

      41 | 42 |
      <!-- Comment -->
      43 | 
      44 | 45 |

      Just plain comment, with trailing spaces on the line:

      46 | 47 | 48 | 49 |

      Code:

      50 | 51 |
      <hr />
      52 | 
      53 | 54 |

      Hr's:

      55 | 56 |


      57 | 58 |
      59 | 60 |
      61 | 62 |


      63 | 64 |
      65 | 66 |
      67 | 68 |
      69 | 70 |
      71 | 72 |


      73 | -------------------------------------------------------------------------------- /tests/md1.0.3/Inline HTML (Simple).mm: -------------------------------------------------------------------------------- 1 | .P 2 | Here's a simple block: 3 | .P 4 | This should be a code block, though: 5 | .VERBON 2 6 |
      7 | foo 8 |
      9 | .VERBOFF 10 | .P 11 | As should this: 12 | .VERBON 2 13 |
      foo
      14 | .VERBOFF 15 | .P 16 | Now, nested: 17 | .P 18 | This should just be an HTML comment: 19 | .P 20 | Multiline: 21 | .P 22 | Code block: 23 | .VERBON 2 24 | 25 | .VERBOFF 26 | .P 27 | Just plain comment, with trailing spaces on the line: 28 | .P 29 | Code: 30 | .VERBON 2 31 |
      32 | .VERBOFF 33 | .P 34 | Hr's: 35 | .P 36 | 37 | .P 38 | 39 | .P 40 | 41 | -------------------------------------------------------------------------------- /tests/md1.0.3/Inline HTML (Simple).text: -------------------------------------------------------------------------------- 1 | Here's a simple block: 2 | 3 |
      4 | foo 5 |
      6 | 7 | This should be a code block, though: 8 | 9 |
      10 | foo 11 |
      12 | 13 | As should this: 14 | 15 |
      foo
      16 | 17 | Now, nested: 18 | 19 |
      20 |
      21 |
      22 | foo 23 |
      24 |
      25 |
      26 | 27 | This should just be an HTML comment: 28 | 29 | 30 | 31 | Multiline: 32 | 33 | 37 | 38 | Code block: 39 | 40 | 41 | 42 | Just plain comment, with trailing spaces on the line: 43 | 44 | 45 | 46 | Code: 47 | 48 |
      49 | 50 | Hr's: 51 | 52 |
      53 | 54 |
      55 | 56 |
      57 | 58 |
      59 | 60 |
      61 | 62 |
      63 | 64 |
      65 | 66 |
      67 | 68 |
      69 | 70 | -------------------------------------------------------------------------------- /tests/md1.0.3/Inline HTML comments.html: -------------------------------------------------------------------------------- 1 |

      Paragraph one.

      2 | 3 | 4 | 5 | 8 | 9 |

      Paragraph two.

      10 | 11 | 12 | 13 |

      The end.

      14 | -------------------------------------------------------------------------------- /tests/md1.0.3/Inline HTML comments.mm: -------------------------------------------------------------------------------- 1 | .P 2 | Paragraph one. 3 | .P 4 | Paragraph two. 5 | .P 6 | The end. 7 | -------------------------------------------------------------------------------- /tests/md1.0.3/Inline HTML comments.text: -------------------------------------------------------------------------------- 1 | Paragraph one. 2 | 3 | 4 | 5 | 8 | 9 | Paragraph two. 10 | 11 | 12 | 13 | The end. 14 | -------------------------------------------------------------------------------- /tests/md1.0.3/Links, inline style.mm: -------------------------------------------------------------------------------- 1 | .P 2 | Just a URL (/url/)\[char46] 3 | .P 4 | URL and title (/url/)\[char46] 5 | .P 6 | URL and title (/url/)\[char46] 7 | .P 8 | URL and title (/url/)\[char46] 9 | .P 10 | URL and title (/url/)\[char46] 11 | .P 12 | Empty ()\[char46] 13 | -------------------------------------------------------------------------------- /tests/md1.0.3/Links, reference style.mm: -------------------------------------------------------------------------------- 1 | .P 2 | Foo bar (/url/)\[char46] 3 | .P 4 | Foo bar (/url/)\[char46] 5 | .P 6 | Foo bar (/url/)\[char46] 7 | .P 8 | With embedded [brackets] (/url/)\[char46] 9 | .P 10 | Indented once (/url)\[char46] 11 | .P 12 | Indented twice (/url)\[char46] 13 | .P 14 | Indented thrice (/url)\[char46] 15 | .P 16 | Indented [four][] times. 17 | .VERBON 2 18 | [four]: /url 19 | .VERBOFF 20 | \l'\n(.lu*8u/10u' 21 | .P 22 | this (foo) should work 23 | .P 24 | So should this (foo)\[char46] 25 | .P 26 | And this (foo)\[char46] 27 | .P 28 | And this (foo)\[char46] 29 | .P 30 | And this (foo)\[char46] 31 | .P 32 | But not [that] []\[char46] 33 | .P 34 | Nor [that][]\[char46] 35 | .P 36 | Nor [that]\[char46] 37 | .P 38 | [Something in brackets like this (foo) should work] 39 | .P 40 | [Same with this (foo)\[char46]] 41 | .P 42 | In this case, this (/somethingelse/) points to something else. 43 | .P 44 | Backslashing should suppress [this] and [this]\[char46] 45 | \l'\n(.lu*8u/10u' 46 | .P 47 | Here's one where the link 48 | breaks (/url/) across lines. 49 | .P 50 | Here's another where the link 51 | breaks (/url/) across lines, but with a line-ending space. 52 | -------------------------------------------------------------------------------- /tests/md1.0.3/Links, shortcut references.mm: -------------------------------------------------------------------------------- 1 | .P 2 | This is the simple case (/simple)\[char46] 3 | .P 4 | This one has a line 5 | break (/foo)\[char46] 6 | .P 7 | This one has a line 8 | break (/foo) with a line-ending space. 9 | .P 10 | this (/that) and the other (/other) 11 | -------------------------------------------------------------------------------- /tests/md1.0.3/Literal quotes in titles.html: -------------------------------------------------------------------------------- 1 |

      Foo bar.

      2 | 3 |

      Foo bar.

      4 | -------------------------------------------------------------------------------- /tests/md1.0.3/Literal quotes in titles.mm: -------------------------------------------------------------------------------- 1 | .P 2 | Foo bar (/url/)\[char46] 3 | .P 4 | Foo bar (/url/)\[char46] 5 | -------------------------------------------------------------------------------- /tests/md1.0.3/Literal quotes in titles.text: -------------------------------------------------------------------------------- 1 | Foo [bar][]. 2 | 3 | Foo [bar](/url/ "Title with "quotes" inside"). 4 | 5 | 6 | [bar]: /url/ "Title with "quotes" inside" 7 | 8 | -------------------------------------------------------------------------------- /tests/md1.0.3/Markdown Documentation - Basics.html: -------------------------------------------------------------------------------- 1 |

      Markdown: Basics

      2 | 3 | 10 | 11 |

      Getting the Gist of Markdown's Formatting Syntax

      12 | 13 |

      This page offers a brief overview of what it's like to use Markdown. 14 | The syntax page provides complete, detailed documentation for 15 | every feature, but Markdown should be very easy to pick up simply by 16 | looking at a few examples of it in action. The examples on this page 17 | are written in a before/after style, showing example syntax and the 18 | HTML output produced by Markdown.

      19 | 20 |

      It's also helpful to simply try Markdown out; the Dingus is a 21 | web application that allows you type your own Markdown-formatted text 22 | and translate it to XHTML.

      23 | 24 |

      Note: This document is itself written using Markdown; you 25 | can see the source for it by adding '.text' to the URL.

      26 | 27 |

      Paragraphs, Headers, Blockquotes

      28 | 29 |

      A paragraph is simply one or more consecutive lines of text, separated 30 | by one or more blank lines. (A blank line is any line that looks like a 31 | blank line -- a line containing nothing spaces or tabs is considered 32 | blank.) Normal paragraphs should not be intended with spaces or tabs.

      33 | 34 |

      Markdown offers two styles of headers: Setext and atx. 35 | Setext-style headers for <h1> and <h2> are created by 36 | "underlining" with equal signs (=) and hyphens (-), respectively. 37 | To create an atx-style header, you put 1-6 hash marks (#) at the 38 | beginning of the line -- the number of hashes equals the resulting 39 | HTML header level.

      40 | 41 |

      Blockquotes are indicated using email-style '>' angle brackets.

      42 | 43 |

      Markdown:

      44 | 45 |
      A First Level Header
       46 | ====================
       47 | 
       48 | A Second Level Header
       49 | ---------------------
       50 | 
       51 | Now is the time for all good men to come to
       52 | the aid of their country. This is just a
       53 | regular paragraph.
       54 | 
       55 | The quick brown fox jumped over the lazy
       56 | dog's back.
       57 | 
       58 | ### Header 3
       59 | 
       60 | > This is a blockquote.
       61 | > 
       62 | > This is the second paragraph in the blockquote.
       63 | >
       64 | > ## This is an H2 in a blockquote
       65 | 
      66 | 67 |

      Output:

      68 | 69 |
      <h1>A First Level Header</h1>
       70 | 
       71 | <h2>A Second Level Header</h2>
       72 | 
       73 | <p>Now is the time for all good men to come to
       74 | the aid of their country. This is just a
       75 | regular paragraph.</p>
       76 | 
       77 | <p>The quick brown fox jumped over the lazy
       78 | dog's back.</p>
       79 | 
       80 | <h3>Header 3</h3>
       81 | 
       82 | <blockquote>
       83 |     <p>This is a blockquote.</p>
       84 | 
       85 |     <p>This is the second paragraph in the blockquote.</p>
       86 | 
       87 |     <h2>This is an H2 in a blockquote</h2>
       88 | </blockquote>
       89 | 
      90 | 91 |

      Phrase Emphasis

      92 | 93 |

      Markdown uses asterisks and underscores to indicate spans of emphasis.

      94 | 95 |

      Markdown:

      96 | 97 |
      Some of these words *are emphasized*.
       98 | Some of these words _are emphasized also_.
       99 | 
      100 | Use two asterisks for **strong emphasis**.
      101 | Or, if you prefer, __use two underscores instead__.
      102 | 
      103 | 104 |

      Output:

      105 | 106 |
      <p>Some of these words <em>are emphasized</em>.
      107 | Some of these words <em>are emphasized also</em>.</p>
      108 | 
      109 | <p>Use two asterisks for <strong>strong emphasis</strong>.
      110 | Or, if you prefer, <strong>use two underscores instead</strong>.</p>
      111 | 
      112 | 113 |

      Lists

      114 | 115 |

      Unordered (bulleted) lists use asterisks, pluses, and hyphens (*, 116 | +, and -) as list markers. These three markers are 117 | interchangable; this:

      118 | 119 |
      *   Candy.
      120 | *   Gum.
      121 | *   Booze.
      122 | 
      123 | 124 |

      this:

      125 | 126 |
      +   Candy.
      127 | +   Gum.
      128 | +   Booze.
      129 | 
      130 | 131 |

      and this:

      132 | 133 |
      -   Candy.
      134 | -   Gum.
      135 | -   Booze.
      136 | 
      137 | 138 |

      all produce the same output:

      139 | 140 |
      <ul>
      141 | <li>Candy.</li>
      142 | <li>Gum.</li>
      143 | <li>Booze.</li>
      144 | </ul>
      145 | 
      146 | 147 |

      Ordered (numbered) lists use regular numbers, followed by periods, as 148 | list markers:

      149 | 150 |
      1.  Red
      151 | 2.  Green
      152 | 3.  Blue
      153 | 
      154 | 155 |

      Output:

      156 | 157 |
      <ol>
      158 | <li>Red</li>
      159 | <li>Green</li>
      160 | <li>Blue</li>
      161 | </ol>
      162 | 
      163 | 164 |

      If you put blank lines between items, you'll get <p> tags for the 165 | list item text. You can create multi-paragraph list items by indenting 166 | the paragraphs by 4 spaces or 1 tab:

      167 | 168 |
      *   A list item.
      169 | 
      170 |     With multiple paragraphs.
      171 | 
      172 | *   Another item in the list.
      173 | 
      174 | 175 |

      Output:

      176 | 177 |
      <ul>
      178 | <li><p>A list item.</p>
      179 | <p>With multiple paragraphs.</p></li>
      180 | <li><p>Another item in the list.</p></li>
      181 | </ul>
      182 | 
      183 | 184 |

      Links

      185 | 186 |

      Markdown supports two styles for creating links: inline and 187 | reference. With both styles, you use square brackets to delimit the 188 | text you want to turn into a link.

      189 | 190 |

      Inline-style links use parentheses immediately after the link text. 191 | For example:

      192 | 193 |
      This is an [example link](http://example.com/).
      194 | 
      195 | 196 |

      Output:

      197 | 198 |
      <p>This is an <a href="http://example.com/">
      199 | example link</a>.</p>
      200 | 
      201 | 202 |

      Optionally, you may include a title attribute in the parentheses:

      203 | 204 |
      This is an [example link](http://example.com/ "With a Title").
      205 | 
      206 | 207 |

      Output:

      208 | 209 |
      <p>This is an <a href="http://example.com/" title="With a Title">
      210 | example link</a>.</p>
      211 | 
      212 | 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 | 224 |

      Output:

      225 | 226 |
      <p>I get 10 times more traffic from <a href="http://google.com/"
      227 | title="Google">Google</a> than from <a href="http://search.yahoo.com/"
      228 | title="Yahoo Search">Yahoo</a> or <a href="http://search.msn.com/"
      229 | title="MSN Search">MSN</a>.</p>
      230 | 
      231 | 232 |

      The title attribute is optional. Link names may contain letters, 233 | numbers and spaces, but are not case sensitive:

      234 | 235 |
      I start my morning with a cup of coffee and
      236 | [The New York Times][NY Times].
      237 | 
      238 | [ny times]: http://www.nytimes.com/
      239 | 
      240 | 241 |

      Output:

      242 | 243 |
      <p>I start my morning with a cup of coffee and
      244 | <a href="http://www.nytimes.com/">The New York Times</a>.</p>
      245 | 
      246 | 247 |

      Images

      248 | 249 |

      Image syntax is very much like link syntax.

      250 | 251 |

      Inline (titles are optional):

      252 | 253 |
      ![alt text](/path/to/img.jpg "Title")
      254 | 
      255 | 256 |

      Reference-style:

      257 | 258 |
      ![alt text][id]
      259 | 
      260 | [id]: /path/to/img.jpg "Title"
      261 | 
      262 | 263 |

      Both of the above examples produce the same output:

      264 | 265 |
      <img src="/path/to/img.jpg" alt="alt text" title="Title" />
      266 | 
      267 | 268 |

      Code

      269 | 270 |

      In a regular paragraph, you can create code span by wrapping text in 271 | backtick quotes. Any ampersands (&) and angle brackets (< or 272 | >) will automatically be translated into HTML entities. This makes 273 | it easy to use Markdown to write about HTML example code:

      274 | 275 |
      I strongly recommend against using any `<blink>` tags.
      276 | 
      277 | I wish SmartyPants used named entities like `&mdash;`
      278 | instead of decimal-encoded entites like `&#8212;`.
      279 | 
      280 | 281 |

      Output:

      282 | 283 |
      <p>I strongly recommend against using any
      284 | <code>&lt;blink&gt;</code> tags.</p>
      285 | 
      286 | <p>I wish SmartyPants used named entities like
      287 | <code>&amp;mdash;</code> instead of decimal-encoded
      288 | entites like <code>&amp;#8212;</code>.</p>
      289 | 
      290 | 291 |

      To specify an entire block of pre-formatted code, indent every line of 292 | the block by 4 spaces or 1 tab. Just like with code spans, &, <, 293 | and > characters will be escaped automatically.

      294 | 295 |

      Markdown:

      296 | 297 |
      If you want your page to validate under XHTML 1.0 Strict,
      298 | you've got to put paragraph tags in your blockquotes:
      299 | 
      300 |     <blockquote>
      301 |         <p>For example.</p>
      302 |     </blockquote>
      303 | 
      304 | 305 |

      Output:

      306 | 307 |
      <p>If you want your page to validate under XHTML 1.0 Strict,
      308 | you've got to put paragraph tags in your blockquotes:</p>
      309 | 
      310 | <pre><code>&lt;blockquote&gt;
      311 |     &lt;p&gt;For example.&lt;/p&gt;
      312 | &lt;/blockquote&gt;
      313 | </code></pre>
      314 | 
      315 | -------------------------------------------------------------------------------- /tests/md1.0.3/Markdown Documentation - Basics.mm: -------------------------------------------------------------------------------- 1 | .H 1 "Markdown: Basics" 2 | .H 2 "Getting the Gist of Markdown's Formatting Syntax" 3 | .P 4 | This page offers a brief overview of what it's like to use Markdown. 5 | The syntax page (/projects/markdown/syntax) provides complete, detailed documentation for 6 | every feature, but Markdown should be very easy to pick up simply by 7 | looking at a few examples of it in action. The examples on this page 8 | are written in a before/after style, showing example syntax and the 9 | HTML output produced by Markdown. 10 | .P 11 | It's also helpful to simply try Markdown out; the Dingus (/projects/markdown/dingus) is a 12 | web application that allows you type your own Markdown-formatted text 13 | and translate it to XHTML. 14 | .P 15 | \fBNote:\fR This document is itself written using Markdown; you 16 | can see the source for it by adding '\[char46]text' to the URL (/projects/markdown/basics.text)\[char46] 17 | .H 2 "Paragraphs, Headers, Blockquotes" 18 | .P 19 | A paragraph is simply one or more consecutive lines of text, separated 20 | by one or more blank lines. (A blank line is any line that looks like a 21 | blank line -- a line containing nothing spaces or tabs is considered 22 | blank.) Normal paragraphs should not be intended with spaces or tabs. 23 | .P 24 | Markdown offers two styles of headers: \fISetext\fR and \fIatx\fR\[char46] 25 | Setext-style headers for \fC

      \fR and \fC

      \fR are created by 26 | "underlining" with equal signs (\fC=\fR) and hyphens (\fC-\fR), respectively. 27 | To create an atx-style header, you put 1-6 hash marks (\fC#\fR) at the 28 | beginning of the line -- the number of hashes equals the resulting 29 | HTML header level. 30 | .P 31 | Blockquotes are indicated using email-style '\fC>\fR' angle brackets. 32 | .P 33 | Markdown: 34 | .VERBON 2 35 | A First Level Header 36 | ==================== 37 | 38 | A Second Level Header 39 | --------------------- 40 | 41 | Now is the time for all good men to come to 42 | the aid of their country. This is just a 43 | regular paragraph. 44 | 45 | The quick brown fox jumped over the lazy 46 | dog's back. 47 | 48 | ### Header 3 49 | 50 | > This is a blockquote. 51 | > 52 | > This is the second paragraph in the blockquote. 53 | > 54 | > ## This is an H2 in a blockquote 55 | .VERBOFF 56 | .P 57 | Output: 58 | .VERBON 2 59 |

      A First Level Header

      60 | 61 |

      A Second Level Header

      62 | 63 |

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

      66 | 67 |

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

      69 | 70 |

      Header 3

      71 | 72 |
      73 |

      This is a blockquote.

      74 | 75 |

      This is the second paragraph in the blockquote.

      76 | 77 |

      This is an H2 in a blockquote

      78 |
      79 | .VERBOFF 80 | .H 3 "Phrase Emphasis" 81 | .P 82 | Markdown uses asterisks and underscores to indicate spans of emphasis. 83 | .P 84 | Markdown: 85 | .VERBON 2 86 | Some of these words *are emphasized*. 87 | Some of these words _are emphasized also_. 88 | 89 | Use two asterisks for **strong emphasis**. 90 | Or, if you prefer, __use two underscores instead__. 91 | .VERBOFF 92 | .P 93 | Output: 94 | .VERBON 2 95 |

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

      97 | 98 |

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

      100 | .VERBOFF 101 | .H 2 "Lists" 102 | .P 103 | Unordered (bulleted) lists use asterisks, pluses, and hyphens (\fC*\fR, 104 | \fC+\fR, and \fC-\fR) as list markers. These three markers are 105 | interchangable; this: 106 | .VERBON 2 107 | * Candy. 108 | * Gum. 109 | * Booze. 110 | .VERBOFF 111 | .P 112 | this: 113 | .VERBON 2 114 | + Candy. 115 | + Gum. 116 | + Booze. 117 | .VERBOFF 118 | .P 119 | and this: 120 | .VERBON 2 121 | - Candy. 122 | - Gum. 123 | - Booze. 124 | .VERBOFF 125 | .P 126 | all produce the same output: 127 | .VERBON 2 128 |
        129 |
      • Candy.
      • 130 |
      • Gum.
      • 131 |
      • Booze.
      • 132 |
      133 | .VERBOFF 134 | .P 135 | Ordered (numbered) lists use regular numbers, followed by periods, as 136 | list markers: 137 | .VERBON 2 138 | 1. Red 139 | 2. Green 140 | 3. Blue 141 | .VERBOFF 142 | .P 143 | Output: 144 | .VERBON 2 145 |
        146 |
      1. Red
      2. 147 |
      3. Green
      4. 148 |
      5. Blue
      6. 149 |
      150 | .VERBOFF 151 | .P 152 | If you put blank lines between items, you'll get \fC

      \fR tags for the 153 | list item text. You can create multi-paragraph list items by indenting 154 | the paragraphs by 4 spaces or 1 tab: 155 | .VERBON 2 156 | * A list item. 157 | 158 | With multiple paragraphs. 159 | 160 | * Another item in the list. 161 | .VERBOFF 162 | .P 163 | Output: 164 | .VERBON 2 165 |

        166 |
      • A list item.

        167 |

        With multiple paragraphs.

      • 168 |
      • Another item in the list.

      • 169 |
      170 | .VERBOFF 171 | .H 3 "Links" 172 | .P 173 | Markdown supports two styles for creating links: \fIinline\fR and 174 | \fIreference\fR\[char46] With both styles, you use square brackets to delimit the 175 | text you want to turn into a link. 176 | .P 177 | Inline-style links use parentheses immediately after the link text. 178 | For example: 179 | .VERBON 2 180 | This is an [example link](http://example.com/). 181 | .VERBOFF 182 | .P 183 | Output: 184 | .VERBON 2 185 |

      This is an 186 | example link.

      187 | .VERBOFF 188 | .P 189 | Optionally, you may include a title attribute in the parentheses: 190 | .VERBON 2 191 | This is an [example link](http://example.com/ "With a Title"). 192 | .VERBOFF 193 | .P 194 | Output: 195 | .VERBON 2 196 |

      This is an 197 | example link.

      198 | .VERBOFF 199 | .P 200 | Reference-style links allow you to refer to your links by names, which 201 | you define elsewhere in your document: 202 | .VERBON 2 203 | I get 10 times more traffic from [Google][1] than from 204 | [Yahoo][2] or [MSN][3]. 205 | 206 | [1]: http://google.com/ "Google" 207 | [2]: http://search.yahoo.com/ "Yahoo Search" 208 | [3]: http://search.msn.com/ "MSN Search" 209 | .VERBOFF 210 | .P 211 | Output: 212 | .VERBON 2 213 |

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

      217 | .VERBOFF 218 | .P 219 | The title attribute is optional. Link names may contain letters, 220 | numbers and spaces, but are \fInot\fR case sensitive: 221 | .VERBON 2 222 | I start my morning with a cup of coffee and 223 | [The New York Times][NY Times]. 224 | 225 | [ny times]: http://www.nytimes.com/ 226 | .VERBOFF 227 | .P 228 | Output: 229 | .VERBON 2 230 |

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

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

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

      270 | 271 |

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

      274 | .VERBOFF 275 | .P 276 | To specify an entire block of pre-formatted code, indent every line of 277 | the block by 4 spaces or 1 tab. Just like with code spans, \fC&\fR, \fC<\fR, 278 | and \fC>\fR characters will be escaped automatically. 279 | .P 280 | Markdown: 281 | .VERBON 2 282 | If you want your page to validate under XHTML 1.0 Strict, 283 | you've got to put paragraph tags in your blockquotes: 284 | 285 |
      286 |

      For example.

      287 |
      288 | .VERBOFF 289 | .P 290 | Output: 291 | .VERBON 2 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 |
      <blockquote>
      296 |     <p>For example.</p>
      297 | </blockquote>
      298 | 
      299 | .VERBOFF 300 | -------------------------------------------------------------------------------- /tests/md1.0.3/Markdown Documentation - 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 a 39 | blank line -- a line containing nothing spaces or tabs is considered 40 | blank.) Normal paragraphs should not be intended with spaces or tabs. 41 | 42 | Markdown offers two styles of headers: *Setext* and *atx*. 43 | Setext-style headers for `

      ` and `

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

      A First Level Header

      78 | 79 |

      A Second Level Header

      80 | 81 |

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

      84 | 85 |

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

      87 | 88 |

      Header 3

      89 | 90 |
      91 |

      This is a blockquote.

      92 | 93 |

      This is the second paragraph in the blockquote.

      94 | 95 |

      This is an H2 in a blockquote

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

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

      116 | 117 |

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

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

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

        180 |
      • A list item.

        181 |

        With multiple paragraphs.

      • 182 |
      • Another item in the list.

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

      This is an 201 | example link.

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

      This is an 210 | example link.

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

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

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

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

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

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

      279 | 280 |

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

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

      For example.

      296 |
      297 | 298 | Output: 299 | 300 |

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

      302 | 303 |
      <blockquote>
      304 |         <p>For example.</p>
      305 |     </blockquote>
      306 |     
      307 | -------------------------------------------------------------------------------- /tests/md1.0.3/Markdown Documentation - Syntax.html: -------------------------------------------------------------------------------- 1 |

      Markdown: Syntax

      2 | 3 | 10 | 11 | 44 | 45 |

      Note: This document is itself written using Markdown; you 46 | can see the source for it by adding '.text' to the URL.

      47 | 48 |
      49 | 50 |

      Overview

      51 | 52 |

      Philosophy

      53 | 54 |

      Markdown is intended to be as easy-to-read and easy-to-write as is feasible.

      55 | 56 |

      Readability, however, is emphasized above all else. A Markdown-formatted 57 | document should be publishable as-is, as plain text, without looking 58 | like it's been marked up with tags or formatting instructions. While 59 | Markdown's syntax has been influenced by several existing text-to-HTML 60 | filters -- including Setext, atx, Textile, reStructuredText, 61 | Grutatext, and EtText -- the single biggest source of 62 | inspiration for Markdown's syntax is the format of plain text email.

      63 | 64 |

      To this end, Markdown's syntax is comprised entirely of punctuation 65 | characters, which punctuation characters have been carefully chosen so 66 | as to look like what they mean. E.g., asterisks around a word actually 67 | look like *emphasis*. Markdown lists look like, well, lists. Even 68 | blockquotes look like quoted passages of text, assuming you've ever 69 | used email.

      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. <div>, 91 | <table>, <pre>, <p>, etc. -- must be separated from surrounding 92 | content by blank lines, and the start and end tags of the block should 93 | not be indented with tabs or spaces. Markdown is smart enough not 94 | to add extra (unwanted) <p> tags around HTML block-level tags.

      95 | 96 |

      For example, to add an HTML table to a Markdown article:

      97 | 98 |
      This is a regular paragraph.
       99 | 
      100 | <table>
      101 |     <tr>
      102 |         <td>Foo</td>
      103 |     </tr>
      104 | </table>
      105 | 
      106 | This is another regular paragraph.
      107 | 
      108 | 109 |

      Note that Markdown formatting syntax is not processed within block-level 110 | HTML tags. E.g., you can't use Markdown-style *emphasis* inside an 111 | HTML block.

      112 | 113 |

      Span-level HTML tags -- e.g. <span>, <cite>, or <del> -- can be 114 | used anywhere in a Markdown paragraph, list item, or header. If you 115 | want, you can even use HTML tags instead of Markdown formatting; e.g. if 116 | you'd prefer to use HTML <a> or <img> tags instead of Markdown's 117 | link or image syntax, go right ahead.

      118 | 119 |

      Unlike block-level HTML tags, Markdown syntax is processed within 120 | span-level tags.

      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. &lt;, and 128 | &amp;.

      129 | 130 |

      Ampersands in particular are bedeviling for web writers. If you want to 131 | write about 'AT&T', you need to write 'AT&amp;T'. You even need to 132 | escape ampersands within URLs. Thus, if you want to link to:

      133 | 134 |
      http://images.google.com/images?num=30&q=larry+bird
      135 | 
      136 | 137 |

      you need to encode the URL as:

      138 | 139 |
      http://images.google.com/images?num=30&amp;q=larry+bird
      140 | 
      141 | 142 |

      in your anchor tag href attribute. Needless to say, this is easy to 143 | forget, and is probably the single most common source of HTML validation 144 | errors in otherwise well-marked-up web sites.

      145 | 146 |

      Markdown allows you to use these characters naturally, taking care of 147 | all the necessary escaping for you. If you use an ampersand as part of 148 | an HTML entity, it remains unchanged; otherwise it will be translated 149 | into &amp;.

      150 | 151 |

      So, if you want to include a copyright symbol in your article, you can write:

      152 | 153 |
      &copy;
      154 | 
      155 | 156 |

      and Markdown will leave it alone. But if you write:

      157 | 158 |
      AT&T
      159 | 
      160 | 161 |

      Markdown will translate it to:

      162 | 163 |
      AT&amp;T
      164 | 
      165 | 166 |

      Similarly, because Markdown supports inline HTML, if you use 167 | angle brackets as delimiters for HTML tags, Markdown will treat them as 168 | such. But if you write:

      169 | 170 |
      4 < 5
      171 | 
      172 | 173 |

      Markdown will translate it to:

      174 | 175 |
      4 &lt; 5
      176 | 
      177 | 178 |

      However, inside Markdown code spans and blocks, angle brackets and 179 | ampersands are always encoded automatically. This makes it easy to use 180 | Markdown to write about HTML code. (As opposed to raw HTML, which is a 181 | terrible format for writing about HTML syntax, because every single < 182 | and & in your example code needs to be escaped.)

      183 | 184 |
      185 | 186 |

      Block Elements

      187 | 188 |

      Paragraphs and Line Breaks

      189 | 190 |

      A paragraph is simply one or more consecutive lines of text, separated 191 | by one or more blank lines. (A blank line is any line that looks like a 192 | blank line -- a line containing nothing but spaces or tabs is considered 193 | blank.) Normal paragraphs should not be intended with spaces or tabs.

      194 | 195 |

      The implication of the "one or more consecutive lines of text" rule is 196 | that Markdown supports "hard-wrapped" text paragraphs. This differs 197 | significantly from most other text-to-HTML formatters (including Movable 198 | Type's "Convert Line Breaks" option) which translate every line break 199 | character in a paragraph into a <br /> tag.

      200 | 201 |

      When you do want to insert a <br /> break tag using Markdown, you 202 | end a line with two or more spaces, then type return.

      203 | 204 |

      Yes, this takes a tad more effort to create a <br />, but a simplistic 205 | "every line break is a <br />" rule wouldn't work for Markdown. 206 | Markdown's email-style blockquoting and multi-paragraph list items 207 | work best -- and look better -- when you format them with hard breaks.

      208 | 209 | 210 | 211 |

      Markdown supports two styles of headers, Setext and atx.

      212 | 213 |

      Setext-style headers are "underlined" using equal signs (for first-level 214 | headers) and dashes (for second-level headers). For example:

      215 | 216 |
      This is an H1
      217 | =============
      218 | 
      219 | This is an H2
      220 | -------------
      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 | 235 |

      Optionally, you may "close" atx-style headers. This is purely 236 | cosmetic -- you can use this if you think it looks better. The 237 | closing hashes don't even need to match the number of hashes 238 | used to open the header. (The number of opening hashes 239 | determines the header level.) :

      240 | 241 |
      # This is an H1 #
      242 | 
      243 | ## This is an H2 ##
      244 | 
      245 | ### This is an H3 ######
      246 | 
      247 | 248 |

      Blockquotes

      249 | 250 |

      Markdown uses email-style > characters for blockquoting. If you're 251 | familiar with quoting passages of text in an email message, then you 252 | know how to create a blockquote in Markdown. It looks best if you hard 253 | wrap the text and put a > before every line:

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

      Markdown allows you to be lazy and only put the > before the first 264 | line of a hard-wrapped paragraph:

      265 | 266 |
      > This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
      267 | consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
      268 | Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
      269 | 
      270 | > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
      271 | id sem consectetuer libero luctus adipiscing.
      272 | 
      273 | 274 |

      Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by 275 | adding additional levels of >:

      276 | 277 |
      > This is the first level of quoting.
      278 | >
      279 | > > This is nested blockquote.
      280 | >
      281 | > Back to the first level.
      282 | 
      283 | 284 |

      Blockquotes can contain other Markdown elements, including headers, lists, 285 | and code blocks:

      286 | 287 |
      > ## This is a header.
      288 | > 
      289 | > 1.   This is the first list item.
      290 | > 2.   This is the second list item.
      291 | > 
      292 | > Here's some example code:
      293 | > 
      294 | >     return shell_exec("echo $input | $markdown_script");
      295 | 
      296 | 297 |

      Any decent text editor should make email-style quoting easy. For 298 | example, with BBEdit, you can make a selection and choose Increase 299 | Quote Level from the Text menu.

      300 | 301 |

      Lists

      302 | 303 |

      Markdown supports ordered (numbered) and unordered (bulleted) lists.

      304 | 305 |

      Unordered lists use asterisks, pluses, and hyphens -- interchangably 306 | -- as list markers:

      307 | 308 |
      *   Red
      309 | *   Green
      310 | *   Blue
      311 | 
      312 | 313 |

      is equivalent to:

      314 | 315 |
      +   Red
      316 | +   Green
      317 | +   Blue
      318 | 
      319 | 320 |

      and:

      321 | 322 |
      -   Red
      323 | -   Green
      324 | -   Blue
      325 | 
      326 | 327 |

      Ordered lists use numbers followed by periods:

      328 | 329 |
      1.  Bird
      330 | 2.  McHale
      331 | 3.  Parish
      332 | 
      333 | 334 |

      It's important to note that the actual numbers you use to mark the 335 | list have no effect on the HTML output Markdown produces. The HTML 336 | Markdown produces from the above list is:

      337 | 338 |
      <ol>
      339 | <li>Bird</li>
      340 | <li>McHale</li>
      341 | <li>Parish</li>
      342 | </ol>
      343 | 
      344 | 345 |

      If you instead wrote the list in Markdown like this:

      346 | 347 |
      1.  Bird
      348 | 1.  McHale
      349 | 1.  Parish
      350 | 
      351 | 352 |

      or even:

      353 | 354 |
      3. Bird
      355 | 1. McHale
      356 | 8. Parish
      357 | 
      358 | 359 |

      you'd get the exact same HTML output. The point is, if you want to, 360 | you can use ordinal numbers in your ordered Markdown lists, so that 361 | the numbers in your source match the numbers in your published HTML. 362 | But if you want to be lazy, you don't have to.

      363 | 364 |

      If you do use lazy list numbering, however, you should still start the 365 | list with the number 1. At some point in the future, Markdown may support 366 | starting ordered lists at an arbitrary number.

      367 | 368 |

      List markers typically start at the left margin, but may be indented by 369 | up to three spaces. List markers must be followed by one or more spaces 370 | or a tab.

      371 | 372 |

      To make lists look nice, you can wrap items with hanging indents:

      373 | 374 |
      *   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
      375 |     Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
      376 |     viverra nec, fringilla in, laoreet vitae, risus.
      377 | *   Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
      378 |     Suspendisse id sem consectetuer libero luctus adipiscing.
      379 | 
      380 | 381 |

      But if you want to be lazy, you don't have to:

      382 | 383 |
      *   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
      384 | Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
      385 | viverra nec, fringilla in, laoreet vitae, risus.
      386 | *   Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
      387 | Suspendisse id sem consectetuer libero luctus adipiscing.
      388 | 
      389 | 390 |

      If list items are separated by blank lines, Markdown will wrap the 391 | items in <p> tags in the HTML output. For example, this input:

      392 | 393 |
      *   Bird
      394 | *   Magic
      395 | 
      396 | 397 |

      will turn into:

      398 | 399 |
      <ul>
      400 | <li>Bird</li>
      401 | <li>Magic</li>
      402 | </ul>
      403 | 
      404 | 405 |

      But this:

      406 | 407 |
      *   Bird
      408 | 
      409 | *   Magic
      410 | 
      411 | 412 |

      will turn into:

      413 | 414 |
      <ul>
      415 | <li><p>Bird</p></li>
      416 | <li><p>Magic</p></li>
      417 | </ul>
      418 | 
      419 | 420 |

      List items may consist of multiple paragraphs. Each subsequent 421 | paragraph in a list item must be intended by either 4 spaces 422 | or one tab:

      423 | 424 |
      1.  This is a list item with two paragraphs. Lorem ipsum dolor
      425 |     sit amet, consectetuer adipiscing elit. Aliquam hendrerit
      426 |     mi posuere lectus.
      427 | 
      428 |     Vestibulum enim wisi, viverra nec, fringilla in, laoreet
      429 |     vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
      430 |     sit amet velit.
      431 | 
      432 | 2.  Suspendisse id sem consectetuer libero luctus adipiscing.
      433 | 
      434 | 435 |

      It looks nice if you indent every line of the subsequent 436 | paragraphs, but here again, Markdown will allow you to be 437 | lazy:

      438 | 439 |
      *   This is a list item with two paragraphs.
      440 | 
      441 |     This is the second paragraph in the list item. You're
      442 | only required to indent the first line. Lorem ipsum dolor
      443 | sit amet, consectetuer adipiscing elit.
      444 | 
      445 | *   Another item in the same list.
      446 | 
      447 | 448 |

      To put a blockquote within a list item, the blockquote's > 449 | delimiters need to be indented:

      450 | 451 |
      *   A list item with a blockquote:
      452 | 
      453 |     > This is a blockquote
      454 |     > inside a list item.
      455 | 
      456 | 457 |

      To put a code block within a list item, the code block needs 458 | to be indented twice -- 8 spaces or two tabs:

      459 | 460 |
      *   A list item with a code block:
      461 | 
      462 |         <code goes here>
      463 | 
      464 | 465 |

      It's worth noting that it's possible to trigger an ordered list by 466 | accident, by writing something like this:

      467 | 468 |
      1986. What a great season.
      469 | 
      470 | 471 |

      In other words, a number-period-space sequence at the beginning of a 472 | line. To avoid this, you can backslash-escape the period:

      473 | 474 |
      1986\. What a great season.
      475 | 
      476 | 477 |

      Code Blocks

      478 | 479 |

      Pre-formatted code blocks are used for writing about programming or 480 | markup source code. Rather than forming normal paragraphs, the lines 481 | of a code block are interpreted literally. Markdown wraps a code block 482 | in both <pre> and <code> tags.

      483 | 484 |

      To produce a code block in Markdown, simply indent every line of the 485 | block by at least 4 spaces or 1 tab. For example, given this input:

      486 | 487 |
      This is a normal paragraph:
      488 | 
      489 |     This is a code block.
      490 | 
      491 | 492 |

      Markdown will generate:

      493 | 494 |
      <p>This is a normal paragraph:</p>
      495 | 
      496 | <pre><code>This is a code block.
      497 | </code></pre>
      498 | 
      499 | 500 |

      One level of indentation -- 4 spaces or 1 tab -- is removed from each 501 | line of the code block. For example, this:

      502 | 503 |
      Here is an example of AppleScript:
      504 | 
      505 |     tell application "Foo"
      506 |         beep
      507 |     end tell
      508 | 
      509 | 510 |

      will turn into:

      511 | 512 |
      <p>Here is an example of AppleScript:</p>
      513 | 
      514 | <pre><code>tell application "Foo"
      515 |     beep
      516 | end tell
      517 | </code></pre>
      518 | 
      519 | 520 |

      A code block continues until it reaches a line that is not indented 521 | (or the end of the article).

      522 | 523 |

      Within a code block, ampersands (&) and angle brackets (< and >) 524 | are automatically converted into HTML entities. This makes it very 525 | easy to include example HTML source code using Markdown -- just paste 526 | it and indent it, and Markdown will handle the hassle of encoding the 527 | ampersands and angle brackets. For example, this:

      528 | 529 |
          <div class="footer">
      530 |         &copy; 2004 Foo Corporation
      531 |     </div>
      532 | 
      533 | 534 |

      will turn into:

      535 | 536 |
      <pre><code>&lt;div class="footer"&gt;
      537 |     &amp;copy; 2004 Foo Corporation
      538 | &lt;/div&gt;
      539 | </code></pre>
      540 | 
      541 | 542 |

      Regular Markdown syntax is not processed within code blocks. E.g., 543 | asterisks are just literal asterisks within a code block. This means 544 | it's also easy to use Markdown to write about Markdown's own syntax.

      545 | 546 |

      Horizontal Rules

      547 | 548 |

      You can produce a horizontal rule tag (<hr />) by placing three or 549 | more hyphens, asterisks, or underscores on a line by themselves. If you 550 | wish, you may use spaces between the hyphens or asterisks. Each of the 551 | following lines will produce a horizontal rule:

      552 | 553 |
      * * *
      554 | 
      555 | ***
      556 | 
      557 | *****
      558 | 
      559 | - - -
      560 | 
      561 | ---------------------------------------
      562 | 
      563 | _ _ _
      564 | 
      565 | 566 |
      567 | 568 |

      Span Elements

      569 | 570 | 571 | 572 |

      Markdown supports two style of links: inline and reference.

      573 | 574 |

      In both styles, the link text is delimited by [square brackets].

      575 | 576 |

      To create an inline link, use a set of regular parentheses immediately 577 | after the link text's closing square bracket. Inside the parentheses, 578 | put the URL where you want the link to point, along with an optional 579 | title for the link, surrounded in quotes. For example:

      580 | 581 |
      This is [an example](http://example.com/ "Title") inline link.
      582 | 
      583 | [This link](http://example.net/) has no title attribute.
      584 | 
      585 | 586 |

      Will produce:

      587 | 588 |
      <p>This is <a href="http://example.com/" title="Title">
      589 | an example</a> inline link.</p>
      590 | 
      591 | <p><a href="http://example.net/">This link</a> has no
      592 | title attribute.</p>
      593 | 
      594 | 595 |

      If you're referring to a local resource on the same server, you can 596 | use relative paths:

      597 | 598 |
      See my [About](/about/) page for details.
      599 | 
      600 | 601 |

      Reference-style links use a second set of square brackets, inside 602 | which you place a label of your choosing to identify the link:

      603 | 604 |
      This is [an example][id] reference-style link.
      605 | 
      606 | 607 |

      You can optionally use a space to separate the sets of brackets:

      608 | 609 |
      This is [an example] [id] reference-style link.
      610 | 
      611 | 612 |

      Then, anywhere in the document, you define your link label like this, 613 | on a line by itself:

      614 | 615 |
      [id]: http://example.com/  "Optional Title Here"
      616 | 
      617 | 618 |

      That is:

      619 | 620 |
        621 |
      • Square brackets containing the link identifier (optionally 622 | indented from the left margin using up to three spaces);
      • 623 |
      • followed by a colon;
      • 624 |
      • followed by one or more spaces (or tabs);
      • 625 |
      • followed by the URL for the link;
      • 626 |
      • optionally followed by a title attribute for the link, enclosed 627 | in double or single quotes.
      • 628 |
      629 | 630 |

      The link URL may, optionally, be surrounded by angle brackets:

      631 | 632 |
      [id]: <http://example.com/>  "Optional Title Here"
      633 | 
      634 | 635 |

      You can put the title attribute on the next line and use extra spaces 636 | or tabs for padding, which tends to look better with longer URLs:

      637 | 638 |
      [id]: http://example.com/longish/path/to/resource/here
      639 |     "Optional Title Here"
      640 | 
      641 | 642 |

      Link definitions are only used for creating links during Markdown 643 | processing, and are stripped from your document in the HTML output.

      644 | 645 |

      Link definition names may constist of letters, numbers, spaces, and punctuation -- but they are not case sensitive. E.g. these two links:

      646 | 647 |
      [link text][a]
      648 | [link text][A]
      649 | 
      650 | 651 |

      are equivalent.

      652 | 653 |

      The implicit link name shortcut allows you to omit the name of the 654 | link, in which case the link text itself is used as the name. 655 | Just use an empty set of square brackets -- e.g., to link the word 656 | "Google" to the google.com web site, you could simply write:

      657 | 658 |
      [Google][]
      659 | 
      660 | 661 |

      And then define the link:

      662 | 663 |
      [Google]: http://google.com/
      664 | 
      665 | 666 |

      Because link names may contain spaces, this shortcut even works for 667 | multiple words in the link text:

      668 | 669 |
      Visit [Daring Fireball][] for more information.
      670 | 
      671 | 672 |

      And then define the link:

      673 | 674 |
      [Daring Fireball]: http://daringfireball.net/
      675 | 
      676 | 677 |

      Link definitions can be placed anywhere in your Markdown document. I 678 | tend to put them immediately after each paragraph in which they're 679 | used, but if you want, you can put them all at the end of your 680 | document, sort of like footnotes.

      681 | 682 |

      Here's an example of reference links in action:

      683 | 684 |
      I get 10 times more traffic from [Google] [1] than from
      685 | [Yahoo] [2] or [MSN] [3].
      686 | 
      687 |   [1]: http://google.com/        "Google"
      688 |   [2]: http://search.yahoo.com/  "Yahoo Search"
      689 |   [3]: http://search.msn.com/    "MSN Search"
      690 | 
      691 | 692 |

      Using the implicit link name shortcut, you could instead write:

      693 | 694 |
      I get 10 times more traffic from [Google][] than from
      695 | [Yahoo][] or [MSN][].
      696 | 
      697 |   [google]: http://google.com/        "Google"
      698 |   [yahoo]:  http://search.yahoo.com/  "Yahoo Search"
      699 |   [msn]:    http://search.msn.com/    "MSN Search"
      700 | 
      701 | 702 |

      Both of the above examples will produce the following HTML output:

      703 | 704 |
      <p>I get 10 times more traffic from <a href="http://google.com/"
      705 | title="Google">Google</a> than from
      706 | <a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a>
      707 | or <a href="http://search.msn.com/" title="MSN Search">MSN</a>.</p>
      708 | 
      709 | 710 |

      For comparison, here is the same paragraph written using 711 | Markdown's inline link style:

      712 | 713 |
      I get 10 times more traffic from [Google](http://google.com/ "Google")
      714 | than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
      715 | [MSN](http://search.msn.com/ "MSN Search").
      716 | 
      717 | 718 |

      The point of reference-style links is not that they're easier to 719 | write. The point is that with reference-style links, your document 720 | source is vastly more readable. Compare the above examples: using 721 | reference-style links, the paragraph itself is only 81 characters 722 | long; with inline-style links, it's 176 characters; and as raw HTML, 723 | it's 234 characters. In the raw HTML, there's more markup than there 724 | is text.

      725 | 726 |

      With Markdown's reference-style links, a source document much more 727 | closely resembles the final output, as rendered in a browser. By 728 | allowing you to move the markup-related metadata out of the paragraph, 729 | you can add links without interrupting the narrative flow of your 730 | prose.

      731 | 732 |

      Emphasis

      733 | 734 |

      Markdown treats asterisks (*) and underscores (_) as indicators of 735 | emphasis. Text wrapped with one * or _ will be wrapped with an 736 | HTML <em> tag; double *'s or _'s will be wrapped with an HTML 737 | <strong> tag. E.g., this input:

      738 | 739 |
      *single asterisks*
      740 | 
      741 | _single underscores_
      742 | 
      743 | **double asterisks**
      744 | 
      745 | __double underscores__
      746 | 
      747 | 748 |

      will produce:

      749 | 750 |
      <em>single asterisks</em>
      751 | 
      752 | <em>single underscores</em>
      753 | 
      754 | <strong>double asterisks</strong>
      755 | 
      756 | <strong>double underscores</strong>
      757 | 
      758 | 759 |

      You can use whichever style you prefer; the lone restriction is that 760 | the same character must be used to open and close an emphasis span.

      761 | 762 |

      Emphasis can be used in the middle of a word:

      763 | 764 |
      un*fucking*believable
      765 | 
      766 | 767 |

      But if you surround an * or _ with spaces, it'll be treated as a 768 | literal asterisk or underscore.

      769 | 770 |

      To produce a literal asterisk or underscore at a position where it 771 | would otherwise be used as an emphasis delimiter, you can backslash 772 | escape it:

      773 | 774 |
      \*this text is surrounded by literal asterisks\*
      775 | 
      776 | 777 |

      Code

      778 | 779 |

      To indicate a span of code, wrap it with backtick quotes (`). 780 | Unlike a pre-formatted code block, a code span indicates code within a 781 | normal paragraph. For example:

      782 | 783 |
      Use the `printf()` function.
      784 | 
      785 | 786 |

      will produce:

      787 | 788 |
      <p>Use the <code>printf()</code> function.</p>
      789 | 
      790 | 791 |

      To include a literal backtick character within a code span, you can use 792 | multiple backticks as the opening and closing delimiters:

      793 | 794 |
      ``There is a literal backtick (`) here.``
      795 | 
      796 | 797 |

      which will produce this:

      798 | 799 |
      <p><code>There is a literal backtick (`) here.</code></p>
      800 | 
      801 | 802 |

      The backtick delimiters surrounding a code span may include spaces -- 803 | one after the opening, one before the closing. This allows you to place 804 | literal backtick characters at the beginning or end of a code span:

      805 | 806 |
      A single backtick in a code span: `` ` ``
      807 | 
      808 | A backtick-delimited string in a code span: `` `foo` ``
      809 | 
      810 | 811 |

      will produce:

      812 | 813 |
      <p>A single backtick in a code span: <code>`</code></p>
      814 | 
      815 | <p>A backtick-delimited string in a code span: <code>`foo`</code></p>
      816 | 
      817 | 818 |

      With a code span, ampersands and angle brackets are encoded as HTML 819 | entities automatically, which makes it easy to include example HTML 820 | tags. Markdown will turn this:

      821 | 822 |
      Please don't use any `<blink>` tags.
      823 | 
      824 | 825 |

      into:

      826 | 827 |
      <p>Please don't use any <code>&lt;blink&gt;</code> tags.</p>
      828 | 
      829 | 830 |

      You can write this:

      831 | 832 |
      `&#8212;` is the decimal-encoded equivalent of `&mdash;`.
      833 | 
      834 | 835 |

      to produce:

      836 | 837 |
      <p><code>&amp;#8212;</code> is the decimal-encoded
      838 | equivalent of <code>&amp;mdash;</code>.</p>
      839 | 
      840 | 841 |

      Images

      842 | 843 |

      Admittedly, it's fairly difficult to devise a "natural" syntax for 844 | placing images into a plain text document format.

      845 | 846 |

      Markdown uses an image syntax that is intended to resemble the syntax 847 | for links, allowing for two styles: inline and reference.

      848 | 849 |

      Inline image syntax looks like this:

      850 | 851 |
      ![Alt text](/path/to/img.jpg)
      852 | 
      853 | ![Alt text](/path/to/img.jpg "Optional title")
      854 | 
      855 | 856 |

      That is:

      857 | 858 |
        859 |
      • An exclamation mark: !;
      • 860 |
      • followed by a set of square brackets, containing the alt 861 | attribute text for the image;
      • 862 |
      • followed by a set of parentheses, containing the URL or path to 863 | the image, and an optional title attribute enclosed in double 864 | or single quotes.
      • 865 |
      866 | 867 |

      Reference-style image syntax looks like this:

      868 | 869 |
      ![Alt text][id]
      870 | 
      871 | 872 |

      Where "id" is the name of a defined image reference. Image references 873 | are defined using syntax identical to link references:

      874 | 875 |
      [id]: url/to/image  "Optional title attribute"
      876 | 
      877 | 878 |

      As of this writing, Markdown has no syntax for specifying the 879 | dimensions of an image; if this is important to you, you can simply 880 | use regular HTML <img> tags.

      881 | 882 |
      883 | 884 |

      Miscellaneous

      885 | 886 | 887 | 888 |

      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:

      889 | 890 |
      <http://example.com/>
      891 | 
      892 | 893 |

      Markdown will turn this into:

      894 | 895 |
      <a href="http://example.com/">http://example.com/</a>
      896 | 
      897 | 898 |

      Automatic links for email addresses work similarly, except that 899 | Markdown will also perform a bit of randomized decimal and hex 900 | entity-encoding to help obscure your address from address-harvesting 901 | spambots. For example, Markdown will turn this:

      902 | 903 |
      <address@example.com>
      904 | 
      905 | 906 |

      into something like this:

      907 | 908 |
      <a href="&#x6D;&#x61;i&#x6C;&#x74;&#x6F;:&#x61;&#x64;&#x64;&#x72;&#x65;
      909 | &#115;&#115;&#64;&#101;&#120;&#x61;&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;
      910 | &#109;">&#x61;&#x64;&#x64;&#x72;&#x65;&#115;&#115;&#64;&#101;&#120;&#x61;
      911 | &#109;&#x70;&#x6C;e&#x2E;&#99;&#111;&#109;</a>
      912 | 
      913 | 914 |

      which will render in a browser as a clickable link to "address@example.com".

      915 | 916 |

      (This sort of entity-encoding trick will indeed fool many, if not 917 | most, address-harvesting bots, but it definitely won't fool all of 918 | them. It's better than nothing, but an address published in this way 919 | will probably eventually start receiving spam.)

      920 | 921 |

      Backslash Escapes

      922 | 923 |

      Markdown allows you to use backslash escapes to generate literal 924 | characters which would otherwise have special meaning in Markdown's 925 | formatting syntax. For example, if you wanted to surround a word with 926 | literal asterisks (instead of an HTML <em> tag), you can backslashes 927 | before the asterisks, like this:

      928 | 929 |
      \*literal asterisks\*
      930 | 
      931 | 932 |

      Markdown provides backslash escapes for the following characters:

      933 | 934 |
      \   backslash
      935 | `   backtick
      936 | *   asterisk
      937 | _   underscore
      938 | {}  curly braces
      939 | []  square brackets
      940 | ()  parentheses
      941 | #   hash mark
      942 | +   plus sign
      943 | -   minus sign (hyphen)
      944 | .   dot
      945 | !   exclamation mark
      946 | 
      947 | -------------------------------------------------------------------------------- /tests/md1.0.3/Markdown Documentation - Syntax.mm: -------------------------------------------------------------------------------- 1 | .H 1 "Markdown: Syntax" 2 | .BL 3 | .LI 4 | Overview (#overview) 5 | .BL 6 | .LI 7 | Philosophy (#philosophy) 8 | .LI 9 | Inline HTML (#html) 10 | .LI 11 | Automatic Escaping for Special Characters (#autoescape) 12 | .LE 1 13 | .LI 14 | Block Elements (#block) 15 | .BL 16 | .LI 17 | Paragraphs and Line Breaks (#p) 18 | .LI 19 | Headers (#header) 20 | .LI 21 | Blockquotes (#blockquote) 22 | .LI 23 | Lists (#list) 24 | .LI 25 | Code Blocks (#precode) 26 | .LI 27 | Horizontal Rules (#hr) 28 | .LE 1 29 | .LI 30 | Span Elements (#span) 31 | .BL 32 | .LI 33 | Links (#link) 34 | .LI 35 | Emphasis (#em) 36 | .LI 37 | Code (#code) 38 | .LI 39 | Images (#img) 40 | .LE 1 41 | .LI 42 | Miscellaneous (#misc) 43 | .BL 44 | .LI 45 | Backslash Escapes (#backslash) 46 | .LI 47 | Automatic Links (#autolink) 48 | .LE 1 49 | .LE 1 50 | .P 51 | \fBNote:\fR This document is itself written using Markdown; you 52 | can see the source for it by adding '\[char46]text' to the URL (/projects/markdown/syntax.text)\[char46] 53 | \l'\n(.lu*8u/10u' 54 | .P 55 | Markdown is intended to be as easy-to-read and easy-to-write as is feasible. 56 | .P 57 | Readability, however, is emphasized above all else. A Markdown-formatted 58 | document should be publishable as-is, as plain text, without looking 59 | like it's been marked up with tags or formatting instructions. While 60 | Markdown's syntax has been influenced by several existing text-to-HTML 61 | filters -- including Setext (http://docutils.sourceforge.net/mirror/setext.html), atx (http://www.aaronsw.com/2002/atx/), Textile (http://textism.com/tools/textile/), reStructuredText (http://docutils.sourceforge.net/rst.html), 62 | Grutatext (http://www.triptico.com/software/grutatxt.html), and EtText (http://ettext.taint.org/doc/) -- the single biggest source of 63 | inspiration for Markdown's syntax is the format of plain text email. 64 | .P 65 | To this end, Markdown's syntax is comprised entirely of punctuation 66 | characters, which punctuation characters have been carefully chosen so 67 | as to look like what they mean. E.g., asterisks around a word actually 68 | look like *emphasis*\[char46] Markdown lists look like, well, lists. Even 69 | blockquotes look like quoted passages of text, assuming you've ever 70 | used email. 71 | .P 72 | Markdown's syntax is intended for one purpose: to be used as a 73 | format for \fIwriting\fR for the web. 74 | .P 75 | Markdown is not a replacement for HTML, or even close to it. Its 76 | syntax is very small, corresponding only to a very small subset of 77 | HTML tags. The idea is \fInot\fR to create a syntax that makes it easier 78 | to insert HTML tags. In my opinion, HTML tags are already easy to 79 | insert. The idea for Markdown is to make it easy to read, write, and 80 | edit prose. HTML is a \fIpublishing\fR format; Markdown is a \fIwriting\fR 81 | format. Thus, Markdown's formatting syntax only addresses issues that 82 | can be conveyed in plain text. 83 | .P 84 | For any markup that is not covered by Markdown's syntax, you simply 85 | use HTML itself. There's no need to preface it or delimit it to 86 | indicate that you're switching from Markdown to HTML; you just use 87 | the tags. 88 | .P 89 | The only restrictions are that block-level HTML elements -- e.g. \fC
      \fR, 90 | \fC\fR, \fC
      \fR, \fC

      \fR, etc. -- must be separated from surrounding 91 | content by blank lines, and the start and end tags of the block should 92 | not be indented with tabs or spaces. Markdown is smart enough not 93 | to add extra (unwanted) \fC

      \fR tags around HTML block-level tags. 94 | .P 95 | For example, to add an HTML table to a Markdown article: 96 | .VERBON 2 97 | This is a regular paragraph. 98 | 99 |

      100 | 101 | 102 | 103 |
      Foo
      104 | 105 | This is another regular paragraph. 106 | .VERBOFF 107 | .P 108 | Note that Markdown formatting syntax is not processed within block-level 109 | HTML tags. E.g., you can't use Markdown-style \fC*emphasis*\fR inside an 110 | HTML block. 111 | .P 112 | Span-level HTML tags -- e.g. \fC\fR, \fC\fR, or \fC\fR -- 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 \fC\fR or \fC\fR tags instead of Markdown's 116 | link or image syntax, go right ahead. 117 | .P 118 | Unlike block-level HTML tags, Markdown syntax \fIis\fR processed within 119 | span-level tags. 120 | .P 121 | In HTML, there are two characters that demand special treatment: \fC<\fR 122 | and \fC&\fR\[char46] Left angle brackets are used to start tags; ampersands are 123 | used to denote HTML entities. If you want to use them as literal 124 | characters, you must escape them as entities, e.g. \fC<\fR, and 125 | \fC&\fR\[char46] 126 | .P 127 | Ampersands in particular are bedeviling for web writers. If you want to 128 | write about 'AT&T', you need to write '\fCAT&T\fR'\[char46] You even need to 129 | escape ampersands within URLs. Thus, if you want to link to: 130 | .VERBON 2 131 | http://images.google.com/images?num=30&q=larry+bird 132 | .VERBOFF 133 | .P 134 | you need to encode the URL as: 135 | .VERBON 2 136 | http://images.google.com/images?num=30&q=larry+bird 137 | .VERBOFF 138 | .P 139 | in your anchor tag \fChref\fR attribute. Needless to say, this is easy to 140 | forget, and is probably the single most common source of HTML validation 141 | errors in otherwise well-marked-up web sites. 142 | .P 143 | Markdown allows you to use these characters naturally, taking care of 144 | all the necessary escaping for you. If you use an ampersand as part of 145 | an HTML entity, it remains unchanged; otherwise it will be translated 146 | into \fC&\fR\[char46] 147 | .P 148 | So, if you want to include a copyright symbol in your article, you can write: 149 | .VERBON 2 150 | © 151 | .VERBOFF 152 | .P 153 | and Markdown will leave it alone. But if you write: 154 | .VERBON 2 155 | AT&T 156 | .VERBOFF 157 | .P 158 | Markdown will translate it to: 159 | .VERBON 2 160 | AT&T 161 | .VERBOFF 162 | .P 163 | Similarly, because Markdown supports inline HTML (#html), if you use 164 | angle brackets as delimiters for HTML tags, Markdown will treat them as 165 | such. But if you write: 166 | .VERBON 2 167 | 4 < 5 168 | .VERBOFF 169 | .P 170 | Markdown will translate it to: 171 | .VERBON 2 172 | 4 < 5 173 | .VERBOFF 174 | .P 175 | However, inside Markdown code spans and blocks, angle brackets and 176 | ampersands are \fIalways\fR encoded automatically. This makes it easy to use 177 | Markdown to write about HTML code. (As opposed to raw HTML, which is a 178 | terrible format for writing about HTML syntax, because every single \fC<\fR 179 | and \fC&\fR in your example code needs to be escaped.) 180 | \l'\n(.lu*8u/10u' 181 | .P 182 | A paragraph is simply one or more consecutive lines of text, separated 183 | by one or more blank lines. (A blank line is any line that looks like a 184 | blank line -- a line containing nothing but spaces or tabs is considered 185 | blank.) Normal paragraphs should not be intended with spaces or tabs. 186 | .P 187 | The implication of the "one or more consecutive lines of text" rule is 188 | that Markdown supports "hard-wrapped" text paragraphs. This differs 189 | significantly from most other text-to-HTML formatters (including Movable 190 | Type's "Convert Line Breaks" option) which translate every line break 191 | character in a paragraph into a \fC
      \fR tag. 192 | .P 193 | When you \fIdo\fR want to insert a \fC
      \fR break tag using Markdown, you 194 | end a line with two or more spaces, then type return. 195 | .P 196 | Yes, this takes a tad more effort to create a \fC
      \fR, but a simplistic 197 | "every line break is a \fC
      \fR" rule wouldn't work for Markdown. 198 | Markdown's email-style blockquoting (#blockquote) and multi-paragraph list items (#list) 199 | work best -- and look better -- when you format them with hard breaks. 200 | .P 201 | Markdown supports two styles of headers, Setext (http://docutils.sourceforge.net/mirror/setext.html) and atx (http://www.aaronsw.com/2002/atx/)\[char46] 202 | .P 203 | Setext-style headers are "underlined" using equal signs (for first-level 204 | headers) and dashes (for second-level headers)\[char46] For example: 205 | .VERBON 2 206 | This is an H1 207 | ============= 208 | 209 | This is an H2 210 | ------------- 211 | .VERBOFF 212 | .P 213 | Any number of underlining \fC=\fR's or \fC-\fR's will work. 214 | .P 215 | Atx-style headers use 1-6 hash characters at the start of the line, 216 | corresponding to header levels 1-6. For example: 217 | .VERBON 2 218 | # This is an H1 219 | 220 | ## This is an H2 221 | 222 | ###### This is an H6 223 | .VERBOFF 224 | .P 225 | Optionally, you may "close" atx-style headers. This is purely 226 | cosmetic -- you can use this if you think it looks better. The 227 | closing hashes don't even need to match the number of hashes 228 | used to open the header. (The number of opening hashes 229 | determines the header level.) : 230 | .VERBON 2 231 | # This is an H1 # 232 | 233 | ## This is an H2 ## 234 | 235 | ### This is an H3 ###### 236 | .VERBOFF 237 | .P 238 | Markdown uses email-style \fC>\fR characters for blockquoting. If you're 239 | familiar with quoting passages of text in an email message, then you 240 | know how to create a blockquote in Markdown. It looks best if you hard 241 | wrap the text and put a \fC>\fR before every line: 242 | .VERBON 2 243 | > This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, 244 | > consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. 245 | > Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus. 246 | > 247 | > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse 248 | > id sem consectetuer libero luctus adipiscing. 249 | .VERBOFF 250 | .P 251 | Markdown allows you to be lazy and only put the \fC>\fR before the first 252 | line of a hard-wrapped paragraph: 253 | .VERBON 2 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 | .VERBOFF 261 | .P 262 | Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by 263 | adding additional levels of \fC>\fR: 264 | .VERBON 2 265 | > This is the first level of quoting. 266 | > 267 | > > This is nested blockquote. 268 | > 269 | > Back to the first level. 270 | .VERBOFF 271 | .P 272 | Blockquotes can contain other Markdown elements, including headers, lists, 273 | and code blocks: 274 | .VERBON 2 275 | > ## This is a header. 276 | > 277 | > 1. This is the first list item. 278 | > 2. This is the second list item. 279 | > 280 | > Here's some example code: 281 | > 282 | > return shell_exec("echo $input | $markdown_script"); 283 | .VERBOFF 284 | .P 285 | Any decent text editor should make email-style quoting easy. For 286 | example, with BBEdit, you can make a selection and choose Increase 287 | Quote Level from the Text menu. 288 | .P 289 | Markdown supports ordered (numbered) and unordered (bulleted) lists. 290 | .P 291 | Unordered lists use asterisks, pluses, and hyphens -- interchangably 292 | -- as list markers: 293 | .VERBON 2 294 | * Red 295 | * Green 296 | * Blue 297 | .VERBOFF 298 | .P 299 | is equivalent to: 300 | .VERBON 2 301 | + Red 302 | + Green 303 | + Blue 304 | .VERBOFF 305 | .P 306 | and: 307 | .VERBON 2 308 | - Red 309 | - Green 310 | - Blue 311 | .VERBOFF 312 | .P 313 | Ordered lists use numbers followed by periods: 314 | .VERBON 2 315 | 1. Bird 316 | 2. McHale 317 | 3. Parish 318 | .VERBOFF 319 | .P 320 | It's important to note that the actual numbers you use to mark the 321 | list have no effect on the HTML output Markdown produces. The HTML 322 | Markdown produces from the above list is: 323 | .VERBON 2 324 |
        325 |
      1. Bird
      2. 326 |
      3. McHale
      4. 327 |
      5. Parish
      6. 328 |
      329 | .VERBOFF 330 | .P 331 | If you instead wrote the list in Markdown like this: 332 | .VERBON 2 333 | 1. Bird 334 | 1. McHale 335 | 1. Parish 336 | .VERBOFF 337 | .P 338 | or even: 339 | .VERBON 2 340 | 3. Bird 341 | 1. McHale 342 | 8. Parish 343 | .VERBOFF 344 | .P 345 | you'd get the exact same HTML output. The point is, if you want to, 346 | you can use ordinal numbers in your ordered Markdown lists, so that 347 | the numbers in your source match the numbers in your published HTML. 348 | But if you want to be lazy, you don't have to. 349 | .P 350 | If you do use lazy list numbering, however, you should still start the 351 | list with the number 1. At some point in the future, Markdown may support 352 | starting ordered lists at an arbitrary number. 353 | .P 354 | List markers typically start at the left margin, but may be indented by 355 | up to three spaces. List markers must be followed by one or more spaces 356 | or a tab. 357 | .P 358 | To make lists look nice, you can wrap items with hanging indents: 359 | .VERBON 2 360 | * Lorem ipsum dolor sit amet, consectetuer adipiscing elit. 361 | Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, 362 | viverra nec, fringilla in, laoreet vitae, risus. 363 | * Donec sit amet nisl. Aliquam semper ipsum sit amet velit. 364 | Suspendisse id sem consectetuer libero luctus adipiscing. 365 | .VERBOFF 366 | .P 367 | But if you want to be lazy, you don't have to: 368 | .VERBON 2 369 | * Lorem ipsum dolor sit amet, consectetuer adipiscing elit. 370 | Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, 371 | viverra nec, fringilla in, laoreet vitae, risus. 372 | * Donec sit amet nisl. Aliquam semper ipsum sit amet velit. 373 | Suspendisse id sem consectetuer libero luctus adipiscing. 374 | .VERBOFF 375 | .P 376 | If list items are separated by blank lines, Markdown will wrap the 377 | items in \fC

      \fR tags in the HTML output. For example, this input: 378 | .VERBON 2 379 | * Bird 380 | * Magic 381 | .VERBOFF 382 | .P 383 | will turn into: 384 | .VERBON 2 385 |

        386 |
      • Bird
      • 387 |
      • Magic
      • 388 |
      389 | .VERBOFF 390 | .P 391 | But this: 392 | .VERBON 2 393 | * Bird 394 | 395 | * Magic 396 | .VERBOFF 397 | .P 398 | will turn into: 399 | .VERBON 2 400 |
        401 |
      • Bird

      • 402 |
      • Magic

      • 403 |
      404 | .VERBOFF 405 | .P 406 | List items may consist of multiple paragraphs. Each subsequent 407 | paragraph in a list item must be intended by either 4 spaces 408 | or one tab: 409 | .VERBON 2 410 | 1. This is a list item with two paragraphs. Lorem ipsum dolor 411 | sit amet, consectetuer adipiscing elit. Aliquam hendrerit 412 | mi posuere lectus. 413 | 414 | Vestibulum enim wisi, viverra nec, fringilla in, laoreet 415 | vitae, risus. Donec sit amet nisl. Aliquam semper ipsum 416 | sit amet velit. 417 | 418 | 2. Suspendisse id sem consectetuer libero luctus adipiscing. 419 | .VERBOFF 420 | .P 421 | It looks nice if you indent every line of the subsequent 422 | paragraphs, but here again, Markdown will allow you to be 423 | lazy: 424 | .VERBON 2 425 | * This is a list item with two paragraphs. 426 | 427 | This is the second paragraph in the list item. You're 428 | only required to indent the first line. Lorem ipsum dolor 429 | sit amet, consectetuer adipiscing elit. 430 | 431 | * Another item in the same list. 432 | .VERBOFF 433 | .P 434 | To put a blockquote within a list item, the blockquote's \fC>\fR 435 | delimiters need to be indented: 436 | .VERBON 2 437 | * A list item with a blockquote: 438 | 439 | > This is a blockquote 440 | > inside a list item. 441 | .VERBOFF 442 | .P 443 | To put a code block within a list item, the code block needs 444 | to be indented \fItwice\fR -- 8 spaces or two tabs: 445 | .VERBON 2 446 | * A list item with a code block: 447 | 448 | 449 | .VERBOFF 450 | .P 451 | It's worth noting that it's possible to trigger an ordered list by 452 | accident, by writing something like this: 453 | .VERBON 2 454 | 1986. What a great season. 455 | .VERBOFF 456 | .P 457 | In other words, a \fInumber-period-space\fR sequence at the beginning of a 458 | line. To avoid this, you can backslash-escape the period: 459 | .VERBON 2 460 | 1986\e. What a great season. 461 | .VERBOFF 462 | .P 463 | Pre-formatted code blocks are used for writing about programming or 464 | markup source code. Rather than forming normal paragraphs, the lines 465 | of a code block are interpreted literally. Markdown wraps a code block 466 | in both \fC
      \fR and \fC\fR tags.
      467 | .P
      468 | To produce a code block in Markdown, simply indent every line of the
      469 | block by at least 4 spaces or 1 tab. For example, given this input:
      470 | .VERBON 2
      471 | This is a normal paragraph:
      472 | 
      473 |     This is a code block.
      474 | .VERBOFF
      475 | .P
      476 | Markdown will generate:
      477 | .VERBON 2
      478 | 

      This is a normal paragraph:

      479 | 480 |
      This is a code block.
      481 | 
      482 | .VERBOFF 483 | .P 484 | One level of indentation -- 4 spaces or 1 tab -- is removed from each 485 | line of the code block. For example, this: 486 | .VERBON 2 487 | Here is an example of AppleScript: 488 | 489 | tell application "Foo" 490 | beep 491 | end tell 492 | .VERBOFF 493 | .P 494 | will turn into: 495 | .VERBON 2 496 |

      Here is an example of AppleScript:

      497 | 498 |
      tell application "Foo"
      499 |     beep
      500 | end tell
      501 | 
      502 | .VERBOFF 503 | .P 504 | A code block continues until it reaches a line that is not indented 505 | (or the end of the article)\[char46] 506 | .P 507 | Within a code block, ampersands (\fC&\fR) and angle brackets (\fC<\fR and \fC>\fR) 508 | are automatically converted into HTML entities. This makes it very 509 | easy to include example HTML source code using Markdown -- just paste 510 | it and indent it, and Markdown will handle the hassle of encoding the 511 | ampersands and angle brackets. For example, this: 512 | .VERBON 2 513 | 516 | .VERBOFF 517 | .P 518 | will turn into: 519 | .VERBON 2 520 |
      <div class="footer">
      521 |     &copy; 2004 Foo Corporation
      522 | </div>
      523 | 
      524 | .VERBOFF 525 | .P 526 | Regular Markdown syntax is not processed within code blocks. E.g., 527 | asterisks are just literal asterisks within a code block. This means 528 | it's also easy to use Markdown to write about Markdown's own syntax. 529 | .P 530 | You can produce a horizontal rule tag (\fC
      \fR) by placing three or 531 | more hyphens, asterisks, or underscores on a line by themselves. If you 532 | wish, you may use spaces between the hyphens or asterisks. Each of the 533 | following lines will produce a horizontal rule: 534 | .VERBON 2 535 | * * * 536 | 537 | *** 538 | 539 | ***** 540 | 541 | - - - 542 | 543 | --------------------------------------- 544 | 545 | _ _ _ 546 | .VERBOFF 547 | \l'\n(.lu*8u/10u' 548 | .P 549 | Markdown supports two style of links: \fIinline\fR and \fIreference\fR\[char46] 550 | .P 551 | In both styles, the link text is delimited by [square brackets]\[char46] 552 | .P 553 | To create an inline link, use a set of regular parentheses immediately 554 | after the link text's closing square bracket. Inside the parentheses, 555 | put the URL where you want the link to point, along with an \fIoptional\fR 556 | title for the link, surrounded in quotes. For example: 557 | .VERBON 2 558 | This is [an example](http://example.com/ "Title") inline link. 559 | 560 | [This link](http://example.net/) has no title attribute. 561 | .VERBOFF 562 | .P 563 | Will produce: 564 | .VERBON 2 565 |

      This is 566 | an example inline link.

      567 | 568 |

      This link has no 569 | title attribute.

      570 | .VERBOFF 571 | .P 572 | If you're referring to a local resource on the same server, you can 573 | use relative paths: 574 | .VERBON 2 575 | See my [About](/about/) page for details. 576 | .VERBOFF 577 | .P 578 | Reference-style links use a second set of square brackets, inside 579 | which you place a label of your choosing to identify the link: 580 | .VERBON 2 581 | This is [an example][id] reference-style link. 582 | .VERBOFF 583 | .P 584 | You can optionally use a space to separate the sets of brackets: 585 | .VERBON 2 586 | This is [an example] [id] reference-style link. 587 | .VERBOFF 588 | .P 589 | Then, anywhere in the document, you define your link label like this, 590 | on a line by itself: 591 | .VERBON 2 592 | [id]: http://example.com/ "Optional Title Here" 593 | .VERBOFF 594 | .P 595 | That is: 596 | .BL 597 | .LI 598 | Square brackets containing the link identifier (optionally 599 | indented from the left margin using up to three spaces); 600 | .LI 601 | followed by a colon; 602 | .LI 603 | followed by one or more spaces (or tabs); 604 | .LI 605 | followed by the URL for the link; 606 | .LI 607 | optionally followed by a title attribute for the link, enclosed 608 | in double or single quotes. 609 | .LE 1 610 | .P 611 | The link URL may, optionally, be surrounded by angle brackets: 612 | .VERBON 2 613 | [id]: "Optional Title Here" 614 | .VERBOFF 615 | .P 616 | You can put the title attribute on the next line and use extra spaces 617 | or tabs for padding, which tends to look better with longer URLs: 618 | .VERBON 2 619 | [id]: http://example.com/longish/path/to/resource/here 620 | "Optional Title Here" 621 | .VERBOFF 622 | .P 623 | Link definitions are only used for creating links during Markdown 624 | processing, and are stripped from your document in the HTML output. 625 | .P 626 | Link definition names may constist of letters, numbers, spaces, and punctuation -- but they are \fInot\fR case sensitive. E.g. these two links: 627 | .VERBON 2 628 | [link text][a] 629 | [link text][A] 630 | .VERBOFF 631 | .P 632 | are equivalent. 633 | .P 634 | The \fIimplicit link name\fR shortcut allows you to omit the name of the 635 | link, in which case the link text itself is used as the name. 636 | Just use an empty set of square brackets -- e.g., to link the word 637 | "Google" to the google.com web site, you could simply write: 638 | .VERBON 2 639 | [Google][] 640 | .VERBOFF 641 | .P 642 | And then define the link: 643 | .VERBON 2 644 | [Google]: http://google.com/ 645 | .VERBOFF 646 | .P 647 | Because link names may contain spaces, this shortcut even works for 648 | multiple words in the link text: 649 | .VERBON 2 650 | Visit [Daring Fireball][] for more information. 651 | .VERBOFF 652 | .P 653 | And then define the link: 654 | .VERBON 2 655 | [Daring Fireball]: http://daringfireball.net/ 656 | .VERBOFF 657 | .P 658 | Link definitions can be placed anywhere in your Markdown document. I 659 | tend to put them immediately after each paragraph in which they're 660 | used, but if you want, you can put them all at the end of your 661 | document, sort of like footnotes. 662 | .P 663 | Here's an example of reference links in action: 664 | .VERBON 2 665 | I get 10 times more traffic from [Google] [1] than from 666 | [Yahoo] [2] or [MSN] [3]. 667 | 668 | [1]: http://google.com/ "Google" 669 | [2]: http://search.yahoo.com/ "Yahoo Search" 670 | [3]: http://search.msn.com/ "MSN Search" 671 | .VERBOFF 672 | .P 673 | Using the implicit link name shortcut, you could instead write: 674 | .VERBON 2 675 | I get 10 times more traffic from [Google][] than from 676 | [Yahoo][] or [MSN][]. 677 | 678 | [google]: http://google.com/ "Google" 679 | [yahoo]: http://search.yahoo.com/ "Yahoo Search" 680 | [msn]: http://search.msn.com/ "MSN Search" 681 | .VERBOFF 682 | .P 683 | Both of the above examples will produce the following HTML output: 684 | .VERBON 2 685 |

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

      689 | .VERBOFF 690 | .P 691 | For comparison, here is the same paragraph written using 692 | Markdown's inline link style: 693 | .VERBON 2 694 | I get 10 times more traffic from [Google](http://google.com/ "Google") 695 | than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or 696 | [MSN](http://search.msn.com/ "MSN Search"). 697 | .VERBOFF 698 | .P 699 | The point of reference-style links is not that they're easier to 700 | write. The point is that with reference-style links, your document 701 | source is vastly more readable. Compare the above examples: using 702 | reference-style links, the paragraph itself is only 81 characters 703 | long; with inline-style links, it's 176 characters; and as raw HTML, 704 | it's 234 characters. In the raw HTML, there's more markup than there 705 | is text. 706 | .P 707 | With Markdown's reference-style links, a source document much more 708 | closely resembles the final output, as rendered in a browser. By 709 | allowing you to move the markup-related metadata out of the paragraph, 710 | you can add links without interrupting the narrative flow of your 711 | prose. 712 | .P 713 | Markdown treats asterisks (\fC*\fR) and underscores (\fC_\fR) as indicators of 714 | emphasis. Text wrapped with one \fC*\fR or \fC_\fR will be wrapped with an 715 | HTML \fC\fR tag; double \fC*\fR's or \fC_\fR's will be wrapped with an HTML 716 | \fC\fR tag. E.g., this input: 717 | .VERBON 2 718 | *single asterisks* 719 | 720 | _single underscores_ 721 | 722 | **double asterisks** 723 | 724 | __double underscores__ 725 | .VERBOFF 726 | .P 727 | will produce: 728 | .VERBON 2 729 | single asterisks 730 | 731 | single underscores 732 | 733 | double asterisks 734 | 735 | double underscores 736 | .VERBOFF 737 | .P 738 | You can use whichever style you prefer; the lone restriction is that 739 | the same character must be used to open and close an emphasis span. 740 | .P 741 | Emphasis can be used in the middle of a word: 742 | .VERBON 2 743 | un*fucking*believable 744 | .VERBOFF 745 | .P 746 | But if you surround an \fC*\fR or \fC_\fR with spaces, it'll be treated as a 747 | literal asterisk or underscore. 748 | .P 749 | To produce a literal asterisk or underscore at a position where it 750 | would otherwise be used as an emphasis delimiter, you can backslash 751 | escape it: 752 | .VERBON 2 753 | \e*this text is surrounded by literal asterisks\e* 754 | .VERBOFF 755 | .P 756 | To indicate a span of code, wrap it with backtick quotes (\fC`\fR)\[char46] 757 | Unlike a pre-formatted code block, a code span indicates code within a 758 | normal paragraph. For example: 759 | .VERBON 2 760 | Use the `printf()` function. 761 | .VERBOFF 762 | .P 763 | will produce: 764 | .VERBON 2 765 |

      Use the printf() function.

      766 | .VERBOFF 767 | .P 768 | To include a literal backtick character within a code span, you can use 769 | multiple backticks as the opening and closing delimiters: 770 | .VERBON 2 771 | ``There is a literal backtick (`) here.`` 772 | .VERBOFF 773 | .P 774 | which will produce this: 775 | .VERBON 2 776 |

      There is a literal backtick (`) here.

      777 | .VERBOFF 778 | .P 779 | The backtick delimiters surrounding a code span may include spaces -- 780 | one after the opening, one before the closing. This allows you to place 781 | literal backtick characters at the beginning or end of a code span: 782 | .VERBON 2 783 | A single backtick in a code span: `` ` `` 784 | 785 | A backtick-delimited string in a code span: `` `foo` `` 786 | .VERBOFF 787 | .P 788 | will produce: 789 | .VERBON 2 790 |

      A single backtick in a code span: `

      791 | 792 |

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

      793 | .VERBOFF 794 | .P 795 | With a code span, ampersands and angle brackets are encoded as HTML 796 | entities automatically, which makes it easy to include example HTML 797 | tags. Markdown will turn this: 798 | .VERBON 2 799 | Please don't use any `` tags. 800 | .VERBOFF 801 | .P 802 | into: 803 | .VERBON 2 804 |

      Please don't use any <blink> tags.

      805 | .VERBOFF 806 | .P 807 | You can write this: 808 | .VERBON 2 809 | `—` is the decimal-encoded equivalent of `—`. 810 | .VERBOFF 811 | .P 812 | to produce: 813 | .VERBON 2 814 |

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

      816 | .VERBOFF 817 | .P 818 | Admittedly, it's fairly difficult to devise a "natural" syntax for 819 | placing images into a plain text document format. 820 | .P 821 | Markdown uses an image syntax that is intended to resemble the syntax 822 | for links, allowing for two styles: \fIinline\fR and \fIreference\fR\[char46] 823 | .P 824 | Inline image syntax looks like this: 825 | .VERBON 2 826 | ![Alt text](/path/to/img.jpg) 827 | 828 | ![Alt text](/path/to/img.jpg "Optional title") 829 | .VERBOFF 830 | .P 831 | That is: 832 | .BL 833 | .LI 834 | An exclamation mark: \fC!\fR; 835 | .LI 836 | followed by a set of square brackets, containing the \fCalt\fR 837 | attribute text for the image; 838 | .LI 839 | followed by a set of parentheses, containing the URL or path to 840 | the image, and an optional \fCtitle\fR attribute enclosed in double 841 | or single quotes. 842 | .LE 1 843 | .P 844 | Reference-style image syntax looks like this: 845 | .VERBON 2 846 | ![Alt text][id] 847 | .VERBOFF 848 | .P 849 | Where "id" is the name of a defined image reference. Image references 850 | are defined using syntax identical to link references: 851 | .VERBON 2 852 | [id]: url/to/image "Optional title attribute" 853 | .VERBOFF 854 | .P 855 | As of this writing, Markdown has no syntax for specifying the 856 | dimensions of an image; if this is important to you, you can simply 857 | use regular HTML \fC\fR tags. 858 | \l'\n(.lu*8u/10u' 859 | .P 860 | 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: 861 | .VERBON 2 862 | 863 | .VERBOFF 864 | .P 865 | Markdown will turn this into: 866 | .VERBON 2 867 | http://example.com/ 868 | .VERBOFF 869 | .P 870 | Automatic links for email addresses work similarly, except that 871 | Markdown will also perform a bit of randomized decimal and hex 872 | entity-encoding to help obscure your address from address-harvesting 873 | spambots. For example, Markdown will turn this: 874 | .VERBON 2 875 | 876 | .VERBOFF 877 | .P 878 | into something like this: 879 | .VERBON 2 880 | address@exa 883 | mple.com 884 | .VERBOFF 885 | .P 886 | which will render in a browser as a clickable link to "address@example.com"\[char46] 887 | .P 888 | (This sort of entity-encoding trick will indeed fool many, if not 889 | most, address-harvesting bots, but it definitely won't fool all of 890 | them. It's better than nothing, but an address published in this way 891 | will probably eventually start receiving spam.) 892 | .P 893 | Markdown allows you to use backslash escapes to generate literal 894 | characters which would otherwise have special meaning in Markdown's 895 | formatting syntax. For example, if you wanted to surround a word with 896 | literal asterisks (instead of an HTML \fC\fR tag), you can backslashes 897 | before the asterisks, like this: 898 | .VERBON 2 899 | \e*literal asterisks\e* 900 | .VERBOFF 901 | .P 902 | Markdown provides backslash escapes for the following characters: 903 | .VERBON 2 904 | \e backslash 905 | ` backtick 906 | * asterisk 907 | _ underscore 908 | {} curly braces 909 | [] square brackets 910 | () parentheses 911 | # hash mark 912 | + plus sign 913 | - minus sign (hyphen) 914 | . dot 915 | ! exclamation mark 916 | .VERBOFF 917 | -------------------------------------------------------------------------------- /tests/md1.0.3/Markdown Documentation - 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 intended with spaces or tabs. 190 | 191 | The implication of the "one or more consecutive lines of text" rule is 192 | that Markdown supports "hard-wrapped" text paragraphs. This differs 193 | significantly from most other text-to-HTML formatters (including Movable 194 | Type's "Convert Line Breaks" option) which translate every line break 195 | character in a paragraph into a `
      ` 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 intended by either 4 spaces 405 | or one tab: 406 | 407 | 1. This is a list item with two paragraphs. Lorem ipsum dolor 408 | sit amet, consectetuer adipiscing elit. Aliquam hendrerit 409 | mi posuere lectus. 410 | 411 | Vestibulum enim wisi, viverra nec, fringilla in, laoreet 412 | vitae, risus. Donec sit amet nisl. Aliquam semper ipsum 413 | sit amet velit. 414 | 415 | 2. Suspendisse id sem consectetuer libero luctus adipiscing. 416 | 417 | It looks nice if you indent every line of the subsequent 418 | paragraphs, but here again, Markdown will allow you to be 419 | lazy: 420 | 421 | * This is a list item with two paragraphs. 422 | 423 | This is the second paragraph in the list item. You're 424 | only required to indent the first line. Lorem ipsum dolor 425 | sit amet, consectetuer adipiscing elit. 426 | 427 | * Another item in the same list. 428 | 429 | To put a blockquote within a list item, the blockquote's `>` 430 | delimiters need to be indented: 431 | 432 | * A list item with a blockquote: 433 | 434 | > This is a blockquote 435 | > inside a list item. 436 | 437 | To put a code block within a list item, the code block needs 438 | to be indented *twice* -- 8 spaces or two tabs: 439 | 440 | * A list item with a code block: 441 | 442 | 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 | * * * 543 | 544 |

      Span Elements

      545 | 546 | 547 | 548 | Markdown supports two style of links: *inline* and *reference*. 549 | 550 | In both styles, the link text is delimited by [square brackets]. 551 | 552 | To create an inline link, use a set of regular parentheses immediately 553 | after the link text's closing square bracket. Inside the parentheses, 554 | put the URL where you want the link to point, along with an *optional* 555 | title for the link, surrounded in quotes. For example: 556 | 557 | This is [an example](http://example.com/ "Title") inline link. 558 | 559 | [This link](http://example.net/) has no title attribute. 560 | 561 | Will produce: 562 | 563 |

      This is 564 | an example inline link.

      565 | 566 |

      This link has no 567 | title attribute.

      568 | 569 | If you're referring to a local resource on the same server, you can 570 | use relative paths: 571 | 572 | See my [About](/about/) page for details. 573 | 574 | Reference-style links use a second set of square brackets, inside 575 | which you place a label of your choosing to identify the link: 576 | 577 | This is [an example][id] reference-style link. 578 | 579 | You can optionally use a space to separate the sets of brackets: 580 | 581 | This is [an example] [id] reference-style link. 582 | 583 | Then, anywhere in the document, you define your link label like this, 584 | on a line by itself: 585 | 586 | [id]: http://example.com/ "Optional Title Here" 587 | 588 | That is: 589 | 590 | * Square brackets containing the link identifier (optionally 591 | indented from the left margin using up to three spaces); 592 | * followed by a colon; 593 | * followed by one or more spaces (or tabs); 594 | * followed by the URL for the link; 595 | * optionally followed by a title attribute for the link, enclosed 596 | in double or single quotes. 597 | 598 | The link URL may, optionally, be surrounded by angle brackets: 599 | 600 | [id]: "Optional Title Here" 601 | 602 | You can put the title attribute on the next line and use extra spaces 603 | or tabs for padding, which tends to look better with longer URLs: 604 | 605 | [id]: http://example.com/longish/path/to/resource/here 606 | "Optional Title Here" 607 | 608 | Link definitions are only used for creating links during Markdown 609 | processing, and are stripped from your document in the HTML output. 610 | 611 | Link definition names may constist of letters, numbers, spaces, and punctuation -- but they are *not* case sensitive. E.g. these two links: 612 | 613 | [link text][a] 614 | [link text][A] 615 | 616 | are equivalent. 617 | 618 | The *implicit link name* shortcut allows you to omit the name of the 619 | link, in which case the link text itself is used as the name. 620 | Just use an empty set of square brackets -- e.g., to link the word 621 | "Google" to the google.com web site, you could simply write: 622 | 623 | [Google][] 624 | 625 | And then define the link: 626 | 627 | [Google]: http://google.com/ 628 | 629 | Because link names may contain spaces, this shortcut even works for 630 | multiple words in the link text: 631 | 632 | Visit [Daring Fireball][] for more information. 633 | 634 | And then define the link: 635 | 636 | [Daring Fireball]: http://daringfireball.net/ 637 | 638 | Link definitions can be placed anywhere in your Markdown document. I 639 | tend to put them immediately after each paragraph in which they're 640 | used, but if you want, you can put them all at the end of your 641 | document, sort of like footnotes. 642 | 643 | Here's an example of reference links in action: 644 | 645 | I get 10 times more traffic from [Google] [1] than from 646 | [Yahoo] [2] or [MSN] [3]. 647 | 648 | [1]: http://google.com/ "Google" 649 | [2]: http://search.yahoo.com/ "Yahoo Search" 650 | [3]: http://search.msn.com/ "MSN Search" 651 | 652 | Using the implicit link name shortcut, you could instead write: 653 | 654 | I get 10 times more traffic from [Google][] than from 655 | [Yahoo][] or [MSN][]. 656 | 657 | [google]: http://google.com/ "Google" 658 | [yahoo]: http://search.yahoo.com/ "Yahoo Search" 659 | [msn]: http://search.msn.com/ "MSN Search" 660 | 661 | Both of the above examples will produce the following HTML output: 662 | 663 |

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

      667 | 668 | For comparison, here is the same paragraph written using 669 | Markdown's inline link style: 670 | 671 | I get 10 times more traffic from [Google](http://google.com/ "Google") 672 | than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or 673 | [MSN](http://search.msn.com/ "MSN Search"). 674 | 675 | The point of reference-style links is not that they're easier to 676 | write. The point is that with reference-style links, your document 677 | source is vastly more readable. Compare the above examples: using 678 | reference-style links, the paragraph itself is only 81 characters 679 | long; with inline-style links, it's 176 characters; and as raw HTML, 680 | it's 234 characters. In the raw HTML, there's more markup than there 681 | is text. 682 | 683 | With Markdown's reference-style links, a source document much more 684 | closely resembles the final output, as rendered in a browser. By 685 | allowing you to move the markup-related metadata out of the paragraph, 686 | you can add links without interrupting the narrative flow of your 687 | prose. 688 | 689 | 690 |

      Emphasis

      691 | 692 | Markdown treats asterisks (`*`) and underscores (`_`) as indicators of 693 | emphasis. Text wrapped with one `*` or `_` will be wrapped with an 694 | HTML `` tag; double `*`'s or `_`'s will be wrapped with an HTML 695 | `` tag. E.g., this input: 696 | 697 | *single asterisks* 698 | 699 | _single underscores_ 700 | 701 | **double asterisks** 702 | 703 | __double underscores__ 704 | 705 | will produce: 706 | 707 | single asterisks 708 | 709 | single underscores 710 | 711 | double asterisks 712 | 713 | double underscores 714 | 715 | You can use whichever style you prefer; the lone restriction is that 716 | the same character must be used to open and close an emphasis span. 717 | 718 | Emphasis can be used in the middle of a word: 719 | 720 | un*fucking*believable 721 | 722 | But if you surround an `*` or `_` with spaces, it'll be treated as a 723 | literal asterisk or underscore. 724 | 725 | To produce a literal asterisk or underscore at a position where it 726 | would otherwise be used as an emphasis delimiter, you can backslash 727 | escape it: 728 | 729 | \*this text is surrounded by literal asterisks\* 730 | 731 | 732 | 733 |

      Code

      734 | 735 | To indicate a span of code, wrap it with backtick quotes (`` ` ``). 736 | Unlike a pre-formatted code block, a code span indicates code within a 737 | normal paragraph. For example: 738 | 739 | Use the `printf()` function. 740 | 741 | will produce: 742 | 743 |

      Use the printf() function.

      744 | 745 | To include a literal backtick character within a code span, you can use 746 | multiple backticks as the opening and closing delimiters: 747 | 748 | ``There is a literal backtick (`) here.`` 749 | 750 | which will produce this: 751 | 752 |

      There is a literal backtick (`) here.

      753 | 754 | The backtick delimiters surrounding a code span may include spaces -- 755 | one after the opening, one before the closing. This allows you to place 756 | literal backtick characters at the beginning or end of a code span: 757 | 758 | A single backtick in a code span: `` ` `` 759 | 760 | A backtick-delimited string in a code span: `` `foo` `` 761 | 762 | will produce: 763 | 764 |

      A single backtick in a code span: `

      765 | 766 |

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

      767 | 768 | With a code span, ampersands and angle brackets are encoded as HTML 769 | entities automatically, which makes it easy to include example HTML 770 | tags. Markdown will turn this: 771 | 772 | Please don't use any `` tags. 773 | 774 | into: 775 | 776 |

      Please don't use any <blink> tags.

      777 | 778 | You can write this: 779 | 780 | `—` is the decimal-encoded equivalent of `—`. 781 | 782 | to produce: 783 | 784 |

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

      786 | 787 | 788 | 789 |

      Images

      790 | 791 | Admittedly, it's fairly difficult to devise a "natural" syntax for 792 | placing images into a plain text document format. 793 | 794 | Markdown uses an image syntax that is intended to resemble the syntax 795 | for links, allowing for two styles: *inline* and *reference*. 796 | 797 | Inline image syntax looks like this: 798 | 799 | ![Alt text](/path/to/img.jpg) 800 | 801 | ![Alt text](/path/to/img.jpg "Optional title") 802 | 803 | That is: 804 | 805 | * An exclamation mark: `!`; 806 | * followed by a set of square brackets, containing the `alt` 807 | attribute text for the image; 808 | * followed by a set of parentheses, containing the URL or path to 809 | the image, and an optional `title` attribute enclosed in double 810 | or single quotes. 811 | 812 | Reference-style image syntax looks like this: 813 | 814 | ![Alt text][id] 815 | 816 | Where "id" is the name of a defined image reference. Image references 817 | are defined using syntax identical to link references: 818 | 819 | [id]: url/to/image "Optional title attribute" 820 | 821 | As of this writing, Markdown has no syntax for specifying the 822 | dimensions of an image; if this is important to you, you can simply 823 | use regular HTML `` tags. 824 | 825 | 826 | * * * 827 | 828 | 829 |

      Miscellaneous

      830 | 831 | 832 | 833 | Markdown supports a shortcut style for creating "automatic" links for URLs and email addresses: simply surround the URL or email address with angle brackets. What this means is that if you want to show the actual text of a URL or email address, and also have it be a clickable link, you can do this: 834 | 835 | 836 | 837 | Markdown will turn this into: 838 | 839 | http://example.com/ 840 | 841 | Automatic links for email addresses work similarly, except that 842 | Markdown will also perform a bit of randomized decimal and hex 843 | entity-encoding to help obscure your address from address-harvesting 844 | spambots. For example, Markdown will turn this: 845 | 846 | 847 | 848 | into something like this: 849 | 850 | address@exa 853 | mple.com 854 | 855 | which will render in a browser as a clickable link to "address@example.com". 856 | 857 | (This sort of entity-encoding trick will indeed fool many, if not 858 | most, address-harvesting bots, but it definitely won't fool all of 859 | them. It's better than nothing, but an address published in this way 860 | will probably eventually start receiving spam.) 861 | 862 | 863 | 864 |

      Backslash Escapes

      865 | 866 | Markdown allows you to use backslash escapes to generate literal 867 | characters which would otherwise have special meaning in Markdown's 868 | formatting syntax. For example, if you wanted to surround a word with 869 | literal asterisks (instead of an HTML `` tag), you can backslashes 870 | before the asterisks, like this: 871 | 872 | \*literal asterisks\* 873 | 874 | Markdown provides backslash escapes for the following characters: 875 | 876 | \ backslash 877 | ` backtick 878 | * asterisk 879 | _ underscore 880 | {} curly braces 881 | [] square brackets 882 | () parentheses 883 | # hash mark 884 | + plus sign 885 | - minus sign (hyphen) 886 | . dot 887 | ! exclamation mark 888 | 889 | -------------------------------------------------------------------------------- /tests/md1.0.3/Nested blockquotes.html: -------------------------------------------------------------------------------- 1 |
      2 |

      foo

      3 | 4 |
      5 |

      bar

      6 |
      7 | 8 |

      foo

      9 |
      10 | -------------------------------------------------------------------------------- /tests/md1.0.3/Nested blockquotes.mm: -------------------------------------------------------------------------------- 1 | .DS I 2 | .P 3 | foo 4 | .DS I 5 | .P 6 | bar 7 | .DE 8 | .P 9 | foo 10 | .DE 11 | -------------------------------------------------------------------------------- /tests/md1.0.3/Nested blockquotes.text: -------------------------------------------------------------------------------- 1 | > foo 2 | > 3 | > > bar 4 | > 5 | > foo 6 | -------------------------------------------------------------------------------- /tests/md1.0.3/Ordered and unordered lists.html: -------------------------------------------------------------------------------- 1 |

      Unordered

      2 | 3 |

      Asterisks tight:

      4 | 5 |
        6 |
      • asterisk 1
      • 7 |
      • asterisk 2
      • 8 |
      • asterisk 3
      • 9 |
      10 | 11 |

      Asterisks loose:

      12 | 13 |
        14 |
      • asterisk 1

      • 15 |
      • asterisk 2

      • 16 |
      • asterisk 3

      • 17 |
      18 | 19 |
      20 | 21 |

      Pluses tight:

      22 | 23 |
        24 |
      • Plus 1
      • 25 |
      • Plus 2
      • 26 |
      • Plus 3
      • 27 |
      28 | 29 |

      Pluses loose:

      30 | 31 |
        32 |
      • Plus 1

      • 33 |
      • Plus 2

      • 34 |
      • Plus 3

      • 35 |
      36 | 37 |
      38 | 39 |

      Minuses tight:

      40 | 41 |
        42 |
      • Minus 1
      • 43 |
      • Minus 2
      • 44 |
      • Minus 3
      • 45 |
      46 | 47 |

      Minuses loose:

      48 | 49 |
        50 |
      • Minus 1

      • 51 |
      • Minus 2

      • 52 |
      • Minus 3

      • 53 |
      54 | 55 |

      Ordered

      56 | 57 |

      Tight:

      58 | 59 |
        60 |
      1. First
      2. 61 |
      3. Second
      4. 62 |
      5. Third
      6. 63 |
      64 | 65 |

      and:

      66 | 67 |
        68 |
      1. One
      2. 69 |
      3. Two
      4. 70 |
      5. Three
      6. 71 |
      72 | 73 |

      Loose using tabs:

      74 | 75 |
        76 |
      1. First

      2. 77 |
      3. Second

      4. 78 |
      5. Third

      6. 79 |
      80 | 81 |

      and using spaces:

      82 | 83 |
        84 |
      1. One

      2. 85 |
      3. Two

      4. 86 |
      5. Three

      6. 87 |
      88 | 89 |

      Multiple paragraphs:

      90 | 91 |
        92 |
      1. Item 1, graf one.

        93 | 94 |

        Item 2. graf two. The quick brown fox jumped over the lazy dog's 95 | back.

      2. 96 |
      3. Item 2.

      4. 97 |
      5. Item 3.

      6. 98 |
      99 | 100 |

      Nested

      101 | 102 |
        103 |
      • Tab 104 | 105 |
          106 |
        • Tab 107 | 108 |
            109 |
          • Tab
          • 110 |
        • 111 |
      • 112 |
      113 | 114 |

      Here's another:

      115 | 116 |
        117 |
      1. First
      2. 118 |
      3. Second: 119 | 120 |
          121 |
        • Fee
        • 122 |
        • Fie
        • 123 |
        • Foe
        • 124 |
      4. 125 |
      5. Third
      6. 126 |
      127 | 128 |

      Same thing but with paragraphs:

      129 | 130 |
        131 |
      1. First

      2. 132 |
      3. Second: 133 | 134 |
          135 |
        • Fee
        • 136 |
        • Fie
        • 137 |
        • Foe
        • 138 |
      4. 139 |
      5. Third

      6. 140 |
      141 | 142 |

      This was an error in Markdown 1.0.1:

      143 | 144 |
        145 |
      • this

        146 | 147 |
          148 |
        • sub
        • 149 |
        150 | 151 |

        that

      • 152 |
      153 | -------------------------------------------------------------------------------- /tests/md1.0.3/Ordered and unordered lists.mm: -------------------------------------------------------------------------------- 1 | .H 2 "Unordered" 2 | .P 3 | Asterisks tight: 4 | .BL 5 | .LI 6 | asterisk 1 7 | .LI 8 | asterisk 2 9 | .LI 10 | asterisk 3 11 | .LE 1 12 | .P 13 | Asterisks loose: 14 | .BL 15 | .LI 16 | asterisk 1 17 | .LI 18 | asterisk 2 19 | .LI 20 | asterisk 3 21 | .LE 1 22 | \l'\n(.lu*8u/10u' 23 | .P 24 | Pluses tight: 25 | .BL 26 | .LI 27 | Plus 1 28 | .LI 29 | Plus 2 30 | .LI 31 | Plus 3 32 | .LE 1 33 | .P 34 | Pluses loose: 35 | .BL 36 | .LI 37 | Plus 1 38 | .LI 39 | Plus 2 40 | .LI 41 | Plus 3 42 | .LE 1 43 | \l'\n(.lu*8u/10u' 44 | .P 45 | Minuses tight: 46 | .BL 47 | .LI 48 | Minus 1 49 | .LI 50 | Minus 2 51 | .LI 52 | Minus 3 53 | .LE 1 54 | .P 55 | Minuses loose: 56 | .BL 57 | .LI 58 | Minus 1 59 | .LI 60 | Minus 2 61 | .LI 62 | Minus 3 63 | .LE 1 64 | .H 2 "Ordered" 65 | .P 66 | Tight: 67 | .AL 68 | .LI 69 | First 70 | .LI 71 | Second 72 | .LI 73 | Third 74 | .LE 1 75 | .P 76 | and: 77 | .AL 78 | .LI 79 | One 80 | .LI 81 | Two 82 | .LI 83 | Three 84 | .LE 1 85 | .P 86 | Loose using tabs: 87 | .AL 88 | .LI 89 | First 90 | .LI 91 | Second 92 | .LI 93 | Third 94 | .LE 1 95 | .P 96 | and using spaces: 97 | .AL 98 | .LI 99 | One 100 | .LI 101 | Two 102 | .LI 103 | Three 104 | .LE 1 105 | .P 106 | Multiple paragraphs: 107 | .AL 108 | .LI 109 | Item 1, graf one. 110 | .P 111 | Item 2. graf two. The quick brown fox jumped over the lazy dog's 112 | back. 113 | .LI 114 | Item 2. 115 | .LI 116 | Item 3. 117 | .LE 1 118 | .H 2 "Nested" 119 | .BL 120 | .LI 121 | Tab 122 | .BL 123 | .LI 124 | Tab 125 | .BL 126 | .LI 127 | Tab 128 | .LE 1 129 | .LE 1 130 | .LE 1 131 | .P 132 | Here's another: 133 | .AL 134 | .LI 135 | First 136 | .LI 137 | Second: 138 | .BL 139 | .LI 140 | Fee 141 | .LI 142 | Fie 143 | .LI 144 | Foe 145 | .LE 1 146 | .LI 147 | Third 148 | .LE 1 149 | .P 150 | Same thing but with paragraphs: 151 | .AL 152 | .LI 153 | First 154 | .LI 155 | Second: 156 | .BL 157 | .LI 158 | Fee 159 | .LI 160 | Fie 161 | .LI 162 | Foe 163 | .LE 1 164 | .LI 165 | Third 166 | .LE 1 167 | .P 168 | This was an error in Markdown 1.0.1: 169 | .BL 170 | .LI 171 | this 172 | .BL 173 | .LI 174 | sub 175 | .LE 1 176 | .P 177 | that 178 | .LE 1 179 | -------------------------------------------------------------------------------- /tests/md1.0.3/Ordered and unordered lists.text: -------------------------------------------------------------------------------- 1 | ## Unordered 2 | 3 | Asterisks tight: 4 | 5 | * asterisk 1 6 | * asterisk 2 7 | * asterisk 3 8 | 9 | 10 | Asterisks loose: 11 | 12 | * asterisk 1 13 | 14 | * asterisk 2 15 | 16 | * asterisk 3 17 | 18 | * * * 19 | 20 | Pluses tight: 21 | 22 | + Plus 1 23 | + Plus 2 24 | + Plus 3 25 | 26 | 27 | Pluses loose: 28 | 29 | + Plus 1 30 | 31 | + Plus 2 32 | 33 | + Plus 3 34 | 35 | * * * 36 | 37 | 38 | Minuses tight: 39 | 40 | - Minus 1 41 | - Minus 2 42 | - Minus 3 43 | 44 | 45 | Minuses loose: 46 | 47 | - Minus 1 48 | 49 | - Minus 2 50 | 51 | - Minus 3 52 | 53 | 54 | ## Ordered 55 | 56 | Tight: 57 | 58 | 1. First 59 | 2. Second 60 | 3. Third 61 | 62 | and: 63 | 64 | 1. One 65 | 2. Two 66 | 3. Three 67 | 68 | 69 | Loose using tabs: 70 | 71 | 1. First 72 | 73 | 2. Second 74 | 75 | 3. Third 76 | 77 | and using spaces: 78 | 79 | 1. One 80 | 81 | 2. Two 82 | 83 | 3. Three 84 | 85 | Multiple paragraphs: 86 | 87 | 1. Item 1, graf one. 88 | 89 | Item 2. graf two. The quick brown fox jumped over the lazy dog's 90 | back. 91 | 92 | 2. Item 2. 93 | 94 | 3. Item 3. 95 | 96 | 97 | 98 | ## Nested 99 | 100 | * Tab 101 | * Tab 102 | * Tab 103 | 104 | Here's another: 105 | 106 | 1. First 107 | 2. Second: 108 | * Fee 109 | * Fie 110 | * Foe 111 | 3. Third 112 | 113 | Same thing but with paragraphs: 114 | 115 | 1. First 116 | 117 | 2. Second: 118 | * Fee 119 | * Fie 120 | * Foe 121 | 122 | 3. Third 123 | 124 | 125 | This was an error in Markdown 1.0.1: 126 | 127 | * this 128 | 129 | * sub 130 | 131 | that 132 | -------------------------------------------------------------------------------- /tests/md1.0.3/Strong and em together.html: -------------------------------------------------------------------------------- 1 |

      This is strong and em.

      2 | 3 |

      So is this word.

      4 | 5 |

      This is strong and em.

      6 | 7 |

      So is this word.

      8 | -------------------------------------------------------------------------------- /tests/md1.0.3/Strong and em together.mm: -------------------------------------------------------------------------------- 1 | .P 2 | \fB\fIThis is strong and em.\fR\fR 3 | .P 4 | So is \fB\fIthis\fR\fR word. 5 | .P 6 | \fB\fIThis is strong and em.\fR\fR 7 | .P 8 | So is \fB\fIthis\fR\fR word. 9 | -------------------------------------------------------------------------------- /tests/md1.0.3/Strong and em together.text: -------------------------------------------------------------------------------- 1 | ***This is strong and em.*** 2 | 3 | So is ***this*** word. 4 | 5 | ___This is strong and em.___ 6 | 7 | So is ___this___ word. 8 | -------------------------------------------------------------------------------- /tests/md1.0.3/Tabs.html: -------------------------------------------------------------------------------- 1 |
        2 |
      • this is a list item 3 | indented with tabs

      • 4 |
      • this is a list item 5 | indented with spaces

      • 6 |
      7 | 8 |

      Code:

      9 | 10 |
      this code block is indented by one tab
      11 | 
      12 | 13 |

      And:

      14 | 15 |
          this code block is indented by two tabs
      16 | 
      17 | 18 |

      And:

      19 | 20 |
      +   this is an example list item
      21 |     indented with tabs
      22 | 
      23 | +   this is an example list item
      24 |     indented with spaces
      25 | 
      26 | -------------------------------------------------------------------------------- /tests/md1.0.3/Tabs.mm: -------------------------------------------------------------------------------- 1 | .BL 2 | .LI 3 | this is a list item 4 | indented with tabs 5 | .LI 6 | this is a list item 7 | indented with spaces 8 | .LE 1 9 | .P 10 | Code: 11 | .VERBON 2 12 | this code block is indented by one tab 13 | .VERBOFF 14 | .P 15 | And: 16 | .VERBON 2 17 | this code block is indented by two tabs 18 | .VERBOFF 19 | .P 20 | And: 21 | .VERBON 2 22 | + this is an example list item 23 | indented with tabs 24 | 25 | + this is an example list item 26 | indented with spaces 27 | .VERBOFF 28 | -------------------------------------------------------------------------------- /tests/md1.0.3/Tabs.text: -------------------------------------------------------------------------------- 1 | + this is a list item 2 | indented with tabs 3 | 4 | + this is a list item 5 | indented with spaces 6 | 7 | Code: 8 | 9 | this code block is indented by one tab 10 | 11 | And: 12 | 13 | this code block is indented by two tabs 14 | 15 | And: 16 | 17 | + this is an example list item 18 | indented with tabs 19 | 20 | + this is an example list item 21 | indented with spaces 22 | -------------------------------------------------------------------------------- /tests/md1.0.3/Tidyness.html: -------------------------------------------------------------------------------- 1 |
      2 |

      A list within a blockquote:

      3 | 4 |
        5 |
      • asterisk 1
      • 6 |
      • asterisk 2
      • 7 |
      • asterisk 3
      • 8 |
      9 |
      10 | -------------------------------------------------------------------------------- /tests/md1.0.3/Tidyness.mm: -------------------------------------------------------------------------------- 1 | .DS I 2 | .P 3 | A list within a blockquote: 4 | .BL 5 | .LI 6 | asterisk 1 7 | .LI 8 | asterisk 2 9 | .LI 10 | asterisk 3 11 | .LE 1 12 | .DE 13 | -------------------------------------------------------------------------------- /tests/md1.0.3/Tidyness.text: -------------------------------------------------------------------------------- 1 | > A list within a blockquote: 2 | > 3 | > * asterisk 1 4 | > * asterisk 2 5 | > * asterisk 3 6 | --------------------------------------------------------------------------------