This library provides markdown parser.
The library consists with 3 parts, first one is the parser, second one is the converter which converts markdown node to HTML. And the last one is the extensions and its APIs.
A simple example of how to generate HTML snippet from Markdown document
(import (rnrs)
(text markdown)
(text sxml serializer))
(define markdown-doc "
Hello markdown
==============
- list
- list2
")
(srl:sxml->html-noindent
(convert-markdown
(parse-markdown markdown-parser (open-string-input-port markdown-doc))
default-markdown-converter 'html))
Returns #t if the given obj is a Markdown parser, otherwise #f.
Returns #t if the given obj is a Markdown node, otherwise #f.
parser must be a Markdown parser.
If the second form is used, then input-port must be a textual input port.
If the first form is used, then (current-input-port) will be used.
Parse Markdown document retrieved from the given textual port and returns
Markdown node.
Alias of the parse-markdown for better naming matching.
Sagittarius default Markdown parser, this parser supports the following Markdown syntax:
Definition lists: see Supported syntax
Footnote: see Supported syntax
Strictly complying commonmark specification parser. This parser only supports Commonmark syntax.
For those well-known syntax, please refer the appropriate links listed
on the markdown-parser.
Definition lists can be written like this:
definition
: description
can also be multiple lines
definition2
: description of definition2
Footnote can be written like this:
Lorem ipsum[^lorem]
^[lorem]: dolor sit amet
Returns #t if the given obj is a Markdown converter, otherwise #f.
A default converter. This converter supports the below converters and most of the extensions.
A markdown converter which converts Markdown node to HTML (SXML).
The result SXML can be converted to string by using srl:sxml->html-noindent
defined in (text sxml serializer) library.
NOTE: this converter only supports commonmark nodes. So if you want to use
GFM or other extensions, use default-markdown-converter or create a custom
converter.
A markdown converter which converts Markdown node to XML (SXML).
The result XML is mostly complies the commonmark DTD.
Converts given node to type by using given converter.
If the second form is used then options must be a Markdown conversion
options object.
Alias of the convert-markdown with different argument order for better
name match.
Merge given converters to one newly allocated converter.
Returns #t if the given obj is a Markdown conversion options,
otherwise #f.
A record builder macro. The field can be specified on this macro is below
unknown-node-handler
A procedure must accept one argument, which is a markdown node.
This is called when the converter doesn't know how to handle the
given node.
context-date
A context data for the converter. The value depends on the type of converter.
Markdown parser and converter can be extended by using extensions. The below example creates a parser which supports only Commonmark syntax and strikethrough.
(define (rnrs)
(text markdown parser)
(text markdown extensions gfm))
(define strikethrough-parser
(markdown-parser-builder:build
(markdown-parser-builder (externsions (list gfm-strikethrough-extension)))))
Markdown parser library which provides parser builder and other utility procedures.
Returns #t if the given obj is a Markdown parser builder, otherwise #f.
A Markdown parser builder has the following fields
block-parsers
A list of thunks to provide supporting block parsers.
inline-parser-producer
A thunk to provide inline content parser.
post-processors
A list of post processors
extensions
A list of extensions
A macro to build a Markdown parser builder generated by (record builder).
Builder must be a Markdown parser builder.
Creates a Markdown parser from the given builder.
Here is the list of extension libraries and supporting extensions.
(text markdown extensions gfm)
Partial support of GFM extensions.
gfm-strikethrough-extension
GFM strikethough extension. GFM strikethrough can be written like this:
~~example~~
gfm-table-extension
GFM table extension. The below is an example of GFM table:
| head1 | head2 |
| ----- | ----- |
| col1 | col2 |
gfm-task-list-extension
GFM task list extension. The below is an example of GFM task list:
- [] to be done
- [ ] the same as above
- [X] done
- [x] also done
gfm-extensions
This extension provides all the supporting GFM extensions described above.
(text markdown extensions footnotes)
Footnotes extension. This extension is still an experimental state, as there's no HTML footnotes tag.
footnotes-extension
Footnotes extension. A footnote can be written like this:
This is a paragraph[^note]
^[note]: this is a footnote
(text markdown extensions definition-lists)
Definition lists extension. This extension provides definition lists syntax.
definition-lists-extension
Definition lists extension. A definition list can be written like this:
define
: description
(text markdown extensions heading-anchor)
Heading anchor extension. This extension provides auto heading anchor and
named heading anchor. The auto heading anchor will generates an anchor
from the heading text. And named heading anchor reads the special syntax
as a heading anchor.
This extension is not in the default parser, if you need this, you need
to create a custom parser.
heading-anchor-extension
Heading anchor extension. A named heading anchor can be written like this:
# Heading anchor example {#head1}
This section will be removed in the future release.
Below APIs are supported for backward compatibility. New application shouldn't use these APIs.
Reads markdown from given input port in.
The keyword argument as specifies the return value. Following 3 are supported:
sxml
Returns SHTML. The procedure uses
markdown-sexp->sxml to convert raw markdown S-expression.
html
Returns HTML string. The procedure uses
markdown-sexp->string to convert raw markdown S-expression.
sexp
Returns S-expression representation of markdown.
Parsing markdown is done by parse-markdown. The rest argument _opt_is
passed to both parse-markdown and underlying conversion procedure.
So if you want to read a markdown document as an HTML string without
indentation, then the procedure should be called like the following:
(markdown-read in :as 'html :no-indent #t)
Reads markdown from given string.
This procedure is thin wrapper of markdown-read. It opens string
input port of string and call the markdown-read.
The rest argument opt is passed to markdown-read.
Converts given markdown S-expression sexp to SXML.
The keyword arguments no-reference and no-notes control the result SXML to have reference section and note section. If the values are true values, then returning SXML doesn't have reference or note section.
Converts given markdown S-expression sexp to HTML string.
The procedure first calls markdown-sexp->sxml passing sexp and
opts then converts the returned value to HTML string.
The keyword argument no-indent controls if the returning string has indentation or not. If the value is true value, then returning string doesn't have indentation.
Returns #t if the given object is a markdown parser error condition, otherwise #f.
Returns position and expexted slot of the given
markdown parser error condition, respectively.
Parses given input port in and returns markdown S-expression.
The returning value is S-expression represented AST of markdown. The structure is not specified in this document yet, thus it might be changed in future.