126 lines
4.0 KiB
Markdown
126 lines
4.0 KiB
Markdown
This is an implementation of John Gruber's [markdown][] in
|
||
[Go][]. It is a translation of [peg-markdown][], written by
|
||
John MacFarlane in C, into Go. It is using a modified version
|
||
of Andrew J Snodgrass' PEG parser [peg][] -- now supporting
|
||
LEG grammars --, which itself is based on the parser used
|
||
by peg-markdown.
|
||
|
||
[markdown]: http://daringfireball.net/projects/markdown/
|
||
[peg-markdown]: https://github.com/jgm/peg-markdown
|
||
[peg]: https://github.com/pointlander/peg
|
||
[Go]: http://golang.org/
|
||
|
||
Support for HTML output is implemented, but Groff and LaTeX
|
||
output have not been ported. The output is identical
|
||
to that of peg-markdown.
|
||
|
||
I try to keep the grammar in sync with the C version, by
|
||
cherry-picking relevant changes. In the commit history the
|
||
corresponding revisions have a suffix *[jgm/peg-markdown].*
|
||
|
||
A simple benchmark has been done by comparing the
|
||
execution times of the Go binary (cmd/main.go) and the
|
||
original C implementation's binary needed for processing
|
||
a Markdown document, which had been created by
|
||
concatenating ten [Markdown syntax descriptions][syntax].
|
||
|
||
[syntax]: http://daringfireball.net/projects/markdown/syntax.text
|
||
|
||
The C version is still around 1.3x faster than the Go version.
|
||
|
||
|
||
## Installation
|
||
|
||
Provided you have a copy of Go 1, and git is available,
|
||
|
||
go get github.com/knieriem/markdown
|
||
|
||
should download and install the package according to
|
||
your GOPATH settings.
|
||
|
||
See doc.go for an example how to use the package. There has
|
||
been an API change recently: Where you previously wrote
|
||
|
||
buf, err := ioutil.ReadAll(os.Stdin)
|
||
...
|
||
doc := markdown.Parse(string(buf), markdown.Extensions{Smart: true})
|
||
doc.WriteHtml(w)
|
||
|
||
you would now write:
|
||
|
||
p := markdown.NewParser(&markdown.Extensions{Smart: true})
|
||
|
||
w := bufio.NewWriter(os.Stdout)
|
||
p.Markdown(os.Stdin, markdown.ToHTML(w))
|
||
w.Flush()
|
||
|
||
One purpose of the change is to have a Parser that can be
|
||
reused between invocations of the converter.
|
||
|
||
---
|
||
|
||
To create the command line program *markdown,* run
|
||
|
||
go build github.com/knieriem/markdown/cmd/markdown
|
||
|
||
the binary should then be available in the current directory.
|
||
|
||
To run tests, type
|
||
|
||
go test github.com/knieriem/markdown
|
||
|
||
At the moment, tests are based on the .text files from the
|
||
Markdown 1.0.3 test suite created by John Gruber, [imported from
|
||
peg-markdown][testsuite]. The output of the conversion of these
|
||
.text files to html is compared to the output of peg-markdown.
|
||
|
||
[testsuite]: https://github.com/jgm/peg-markdown/tree/master/MarkdownTest_1.0.3
|
||
|
||
## Development
|
||
|
||
There is not yet a way to create a Go source file like
|
||
`parser.leg.go` automatically from another file, `parser.leg`,
|
||
when building packages and commands using the Go tool. To make
|
||
*markdown* installable using `go get`, `parser.leg.go` has
|
||
been added to the VCS.
|
||
|
||
`Make parser` will update `parser.leg.go` using `leg` – which
|
||
is part of [knieriem/peg][] at github –, if parser.leg has
|
||
been changed, or if the Go file is missing. If a copy of *peg*
|
||
is not yet present on your system, run
|
||
|
||
go get github.com/knieriem/peg
|
||
|
||
Then `make parser` should succeed.
|
||
|
||
[knieriem/peg]: https://github.com/knieriem/peg
|
||
|
||
|
||
## Extensions
|
||
|
||
In addition to the extensions already present in peg-markdown,
|
||
this package also supports definition lists (option `-dlists`)
|
||
similar to the way they are described in the documentation of
|
||
[PHP Markdown Extra][].
|
||
|
||
Definitions (`<dd>...</dd>`) are implemented using [`ListTight`][ListTight]
|
||
and `ListLoose`, on which bullet lists and ordered lists are based
|
||
already. If there is an empty line between the definition title and
|
||
the first definition, a loose list is expected, a tight list otherwise.
|
||
|
||
As definition item markers both `:` and `~` can be used.
|
||
|
||
[PHP Markdown Extra]: http://michelf.com/projects/php-markdown/extra/#def-list
|
||
[ListTight]: https://github.com/knieriem/markdown/blob/master/parser.leg#L191
|
||
|
||
|
||
## Todo
|
||
|
||
* Port tables and perhaps other extensions from [fletcher/peg-multimarkdown][mmd].
|
||
|
||
## Subdirectory Index
|
||
|
||
* cmd/markdown – command line program `markdown`
|
||
|
||
[mmd]: https://github.com/fletcher/peg-multimarkdown
|