|
2 months ago | |
---|---|---|
bin | 5 months ago | |
example | 3 months ago | |
spec | 2 months ago | |
src | 2 months ago | |
tools | 5 months ago | |
.ameba.yml | 5 months ago | |
.editorconfig | 3 years ago | |
.gitignore | 3 years ago | |
CHANGELOG.md | 2 months ago | |
LICENSE | 3 months ago | |
README.md | 3 months ago | |
shard.yml | 3 months ago |
Luce is a CommonMark compliant parser and renderer which supports a few common extensions.
Luce is a port of the Dart markdown package.
shard.yml
: dependencies:
luce:
git: https://codeberg.org/supercell/luce
version: ~> 0.5.0
shards install
require "luce"
puts Luce.to_html("Hello *Markdown*") # => <p>Hello <em>Markdown</em></p>
A few Markdown extensions, beyond what was specified in the original
Perl Markdown implementation, are supported. By default, the ones
supported in CommonMark are enabled. Any individual extension can
be enabled by specifying an Array of extension syntax in the
block_syntaxes
or inline_syntaxes
argument of Luce.to_html
.
The currently supported inline extension syntax are:
InlineHTMLSyntax.new()
- approximately CommonMark's
definition of "Raw HTML".The currently supported block extension syntax are:
FencedCodeBlockSyntax
- Code blocks familiar to Pandoc and PHP
Markdown Extra users.HeaderWithIdSyntax
- ATX-style headers have generated IDs, for link
anchors (akin to Pandoc's auto_identifiers).SetextHeaderWithIdSyntax
- Setext-style headers have generated IDs
for link anchors (akin to Pandoc's auto_identifiers).TableSyntax
- Table syntax familiar to GitHub, PHP Markdown Extra,
and Pandoc users.For example:
html = Luce.to_html(%(Hello <span class="green">Markdown</span>),
inline_syntaxes: [Luce::InlineHTMLSyntax.new])
puts html # => <p>Hello <span class="green">Markdown</span></p>\n
To make extension management easy, you can also just specify an
extension set. Both Luce.to_html
and Document.new
accept an
extension_set
named parameter. Currently, there are four pre-defined
extension sets.
Luce::ExtensionSet::NONE
includes no extensions. With no
extensions, Markdown documents will be parsed with a default set of
block and inline syntax parsers that closely match how the document
might be parsed by the original Perl Markdown implementation.
Luce::ExtensionSet::COMMON_MARK
includes two extensions in addition
to the default parsers to bring the parsed output closer to the
CommonMark specification:
Block Syntax Parser
FencedCodeBlockSyntax
Inline Syntax Parser
InlineHTMLSyntax
Luce::ExtensionSet::GITHUB_FLAVOURED
includes five extensions in
addition to the default parsers to bring the parsed output close to the
GitHub Flavoured Markdown specification:
Block Syntax Parser
FencedCodeBlockSyntax
TableSyntax
Inline Syntax Parser
InlineHTMLSyntax
StrikethroughSyntax
AutolinkExtensionSyntax
Luce::ExtensionSet::GITHUB_WEB
includes eight extensions. The same
set of parsers used int he GITHUB_FLAVOURED
extension set with the
addition of the block syntax parsers, HeaderWithIdSyntax and
SetextHeaderWithIdSyntax, which add id
attributes to headers and
inline syntax parser, EmojiSyntax, for parsing GitHub style emoji
characters:
Block Syntax Parser
FencedCodeBlockSyntax
HeaderWithIdSyntax
, which adds id
attributes to ATX-style
headers, for easy intra-document linking.
SetextHeaderWithIdSyntax
, which adds id
attributes to
Setext-style headers, for easy intra-document linking.
TableSyntax
Inline Syntax Parser
InlineHTMLSyntax
StrikethroguhSyntax
EmojiSyntax
AutolinkExtension
You can create and use your own syntax.
require "luce"
syntaxes = [Luce::TextSyntax.new("nyan", sub: "~=[,,_,,]:3")]
puts Luce.to_html("nyan", inline_syntaxes: syntaxes)
# => <p>~=[,,_,,]:3</p>
This shard offers no features in the way of HTML sanitization. Read Estevão Soares dos Santos' great article, "Markdown's XSS Vulnerability (and how to mitigate it)", to learn more.
The authors recommend that you perform any necessary sanitization on the
resulting HTML, for example via the sanitize
shard.
git checkout -b my-new-feature
)git commit -am 'Add some feature'
)git push origin my-new-feature
)This shard contains a number of files in the tools
directory for tracking
compliance with CommonMark.
crystal tools/stats.cr --update-files
to update the per-test
results tools/common_mark_stats.json
and the test summary
tools/common_mark_stats.txt
. > cd /path/to/commonmark-spec
> python3 test/spec_tests.py --dump-tests > \
/path/to/luce/tools/common_mark_tests.json
https://spec.commonmark.org/0.30
in the repository. (Including this one.)
Verify the updated links are still valid.CHANGELOG.md
.