diff --git a/README.md b/README.md index 7057a96..6dffa2c 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,6 @@ # Ocean markdown-it -[Ocean markdown-it] library is a wrapper for [markdown-it] built to render Ocean-flavored markdown (OFM). - -[Ocean markdown-it]: https://github.com/dnotes/ocean-markdown-it -[commonmark specification]: https://spec.commonmark.org/0.29/ -[markdown-it]: https://github.com/markdown-it/markdown-it +[Ocean markdown-it] is a wrapper for [markdown-it] built to render Ocean-flavored Markdown ([OFM]). ## Installation @@ -13,7 +9,7 @@ ## Usage -Ocean Markdown IT can be used as an inline replacement for [markdown-it]. The module exports an instance of markdown-it that has been created with all of the configuration and plugins necessary for supporting OFM. +Ocean markdown-it can be used as an inline replacement for [markdown-it]. The module exports an instance of markdown-it that has been created with all of the configuration and plugins necessary for properly rendering OFM. ``` javascript const md = require('ocean-markdown-it') @@ -21,6 +17,13 @@ html = md.render('# This is Ocean-flavored markdown {.title}') console.log(html) //

This is Ocean-flavored markdown

``` -# Ocean-flavored Markdown +# Ocean-flavored Markdown (OFM) -Ocean-flavored markdown is an expanded subset of the [commonmark specification] optimized for literary texts. In the few conditions under which [markdown-it] diverges from commonmark, OFM follows the markdown-it implementation. \ No newline at end of file +Markdown is a widely-used convention for writing for the web, useful because it is easy and quick to write and creates a readable text document that converts well to HTML. The [Markdown] website has a good introduction for people who may find it unfamiliar. Ocean-flavored Markdown is an extension of this syntax designed to support literature. The specification is detailed at [spec.md]. + +[Ocean markdown-it]: https://github.com/dnotes/ocean-markdown-it +[Commonmark spec]: https://spec.commonmark.org/0.29/ +[markdown-it]: https://github.com/markdown-it/markdown-it +[Markdown]: https://daringfireball.net/markdown +[OFM]: #ocean-flavored-markdown-ofm +[spec.md]: https://github.com/dnotes/ocean-markdown-it/blob/master/spec.md \ No newline at end of file diff --git a/spec.md b/spec.md index f9e9095..815a430 100644 --- a/spec.md +++ b/spec.md @@ -1,16 +1,173 @@ # Introduction -## Ocean Markdown specification +## Ocean-flavored Markdown (OFM) spec + +Ocean-flavored Markdown (OFM) is an extended subset of the [Commonmark spec] optimized for literary texts. Ocean Markdown is defined in relation to the [Commonmark spec], meaning that Commonmark definitions are theoretically maintained as in the original unless otherwise specified in this document. In the few conditions under which [markdown-it] diverges from Commonmark in implementation, OFM follows the markdown-it implementation. + +[Commonmark]: https://commonmark.org +[Commonmark spec]: https://spec.commonmark.org/v0.29/ +[markdown-it]: https://github.com/markdown-it/markdown-it + +## OFM Principles -The Ocean Markdown specification is an extended subset of the Commonmark specification optimized for literature instead of modern internet communication. Ocean Markdown is defined in relation to the Commonmark specification, meaning that Commonmark definitions are maintained as in the original unless otherwise specified in this document. +Development of the OFM specification is guided by four principles: support [literature], maintain [existing functionality], prefer a [flat structure], and follow [existing implementation]. -# Divergence from Commonmark +### Support literature +[literature]: #support-literature -# Additions to Commonmark +The primary purpose of OFM is to support literature. Literary texts have different structures and writing conventions from the modern style of writing for the Internet that Markdown and Commonmark were created to support. -## Footnotes +### Maintain existing functionality +[existing functionality]: #maintain-existing-functionality -Ocean Markdown defines footnotes or endnotes exactly as supported by the [markdown-it-footnote plugin](//github.com/markdown-it/markdown-it-footnote). +Altering or removing features supported by Commonmark should only be done with justification based on the OFM principles. Removal of features should only be done when a convention is insufficient to achieve the purpose. + +### Prefer flat structure +[flat structure]: #prefer-flat-structure + +In contrast to modern writing styles which often employ a semantic and nested structure that can be easily parsed by machines, literature uses a relatively flat structure of titles and paragraphs, relying on human understanding to distinguish elements like chapters and lists. This flat structure affords several benefits for parsing, rendering and understanding literature, including: + +- easier referencing of numbered paragraphs +- more faithful rendering of ordered list items +- lazy loading of blocks within large documents +- better support for audio mapping + +### Follow existing implementation +[existing implementation]: #follow-existing-implementation + +For ease of developing tools, the OFM spec may follow implementations of Markdown parsers that differ from Commonmark spec in the following cases: + +- the parser adds features not in Commonmark +- the parser incorrectly implements an edge case that does not affect literature + + + +# Relation to the Commonmark spec + +The sections below follow the [Commonmark spec], detailing any ways in which OFM diverges from and adds to Commonmark requirements. The following features are maintained exactly as in Commonmark: + +- [Leaf blocks] + - [Thematic breaks] + - [ATX headings] + - [Setext headings] + - [Fenced code blocks] + - [HTML blocks] [1] + - [Link reference definitions] [2] + - [Paragraphs] + - [Blank lines] +- [Container blocks] + - [Block quotes] [1] +- [Inlines] + - [Entity and numeric character references] + - [Emphasis and strong emphasis] + - [Links] [2] + - [Images] [2] + - [Autolinks] + - [Raw HTML] [1] + - [Hard line breaks] + - [Soft line breaks] + - [Textual content] + +1\. Discouraged. See notes below. + +2\. See notes below about right-to-left language support. + +[leaf blocks]: https://spec.commonmark.org/0.29/#leaf-blocks +[Leaf blocks]: https://spec.commonmark.org/0.29/#leaf-blocks +[container blocks]: https://spec.commonmark.org/0.29/#container-blocks +[Container blocks]: https://spec.commonmark.org/0.29/#container-blocks +[inline elements]: https://spec.commonmark.org/0.29/#inlines +[Inline elements]: https://spec.commonmark.org/0.29/#inlines +[Inlines]: https://spec.commonmark.org/0.29/#inlines + +[Thematic breaks]: https://spec.commonmark.org/0.29/#thematic-breaks +[ATX headings]: https://spec.commonmark.org/0.29/#atx-headings +[Setext headings]: https://spec.commonmark.org/0.29/#setext-headings +[Indented code blocks]: https://spec.commonmark.org/0.29/#indented-code-blocks +[Fenced code blocks]: https://spec.commonmark.org/0.29/#fenced-code-blocks +[HTML blocks]: https://spec.commonmark.org/0.29/#html-blocks +[Link reference definitions]: https://spec.commonmark.org/0.29/#link-reference-definitions +[Paragraphs]: https://spec.commonmark.org/0.29/#paragraphs +[Blank lines]: https://spec.commonmark.org/0.29/#blank-lines +[Block quotes]: https://spec.commonmark.org/0.29/#block-quotes +[List items]: https://spec.commonmark.org/0.29/#list-items +[Lists]: https://spec.commonmark.org/0.29/#lists +[Backslash escapes]: https://spec.commonmark.org/0.29/#backslash-escapes +[Entity and numeric character references]: https://spec.commonmark.org/0.29/#entity-and-numeric-character-references +[Code spans]: https://spec.commonmark.org/0.29/#code-spans +[Emphasis and strong emphasis]: https://spec.commonmark.org/0.29/#emphasis-and-strong-emphasis +[Links]: https://spec.commonmark.org/0.29/#links +[Images]: https://spec.commonmark.org/0.29/#images +[Autolinks]: https://spec.commonmark.org/0.29/#autolinks +[Raw HTML]: https://spec.commonmark.org/0.29/#raw-html +[Hard line breaks]: https://spec.commonmark.org/0.29/#hard-line-breaks +[Soft line breaks]: https://spec.commonmark.org/0.29/#soft-line-breaks +[Textual content]: https://spec.commonmark.org/0.29/#textual-content + +[1]: #divergence-from-commonmark +[2]: #right-to-left-language-support + + + +## Divergence from Commonmark + +The following elements in Ocean-flavored Markdown differ from their counterparts in Commonmark: + + +### [Indented code blocks] + +Indented blocks in OFM are to be treated as block quotes, not as code. + +**Justification**: In [literature] it is a standard convention that long quotations are written as indented free-standing text blocks, and such quotations are common while code is almost nonexistent. + +### [HTML blocks] + +The use of HTML blocks is discouraged in OFM, and may be limited or deprecated in future. + + +### [Block quotes] + +Block quotes in OFM are indicated by indentation; however, the Commonmark block quote syntax is also supported. + +While OFM continues to support block quotes as [container blocks] that may hold multiple other block elements, this use is discouraged and may be deprecated in the future. + +**Justification**: Commonmark block quotes use a syntax that is never used in [literature], so it does no harm to [maintain functionality]. Commonmark block quotes also allow a nested structure, but a [flat structure] can be encouraged by convention in this case. + +### [List items] and [Lists] + +List items in OFM are rendered as regular paragraphs with a class of "list-item". Lists and list items are thus treated as [leaf blocks] instead of [container blocks]. + +Nested list items, beyond the first level, are indicated by a level class, e.g. `

`. + +Lists are not supported. + +**Justification**: While [literature] does contain lists, the item identifiers--bullets, numbers, or letters--are considered part of the content, and support a much wider range of values than html bullets or automated numbering. In almost no case is there any advantage in maintaining the semantic nature of an html list, and collapsing list items into regular paragraphs affords a [flat structure]. + + +### [Backslash escapes] + +In Ocean-flavored markdown, backslash escapes work as usual inside indented blocks. + +**Justification**: This is a consequence of rendering indented text blocks as block quotes instead of code. In this instance backslash escapes are still needed. + +### [Code spans] + +Inline code spans are not supported in Ocean-flavored Markdown. Markdown that would ordinarily be rendered as code spans should be rendered as plain text. + +**Justification**: The backtick character occasionally occurs in [literature], but code is rare; if code is needed it must be fenced by three backticks. + +### [Raw HTML] + +The use of raw HTML is discouraged in OFM, and may be limited or deprecated in future. + + + +## Additions to Commonmark + +### Footnotes +[markdown-it-footnote]: https://github.com/markdown-it/markdown-it-footnote + +Ocean Markdown defines footnotes exactly as supported by the [markdown-it-footnote] plugin. Footnote labels are [inline elements], while footnote definitions function like [container blocks], although they are rendered at the end of the document instead of where they occur. Footnote definitions are created in the same format as link and image definitions. They may be placed anywhere in the document. Footnotes can be defined immediately following the paragraph: @@ -158,3 +315,40 @@ Paragraph with footnote reference[^1]. ```````````````````````````````` + +### Block attributes +[markdown-it-attrs]: https://github.com/markdown-it/markdown-it-attrs + +Block attributes are an extension to block elements classes and html attributes, and are defined exactly as implemented by the [markdown-it-attrs] plugin. + + +### Page numbers +[markdown-it-pagenumbers]: https://github.com/markdown-it/markdown-it-pagenumbers + +Page numbers are [inline elements] defined exactly as implemented by the [markdown-it-pagenumbers] plugin. + +### Typographic elements +[markdown-it-replacements]: https://github.com/edemaine/markdown-it-replacements + +A limited list of typographic replacements are required by OFM, and these are obtained using the [markdown-it-replacements] plugin. The following typographic replacements are required: + +- Copyright +- Trademark +- Registered trademark +- Em-dashes + +Automated conversion of quotation marks to smart quotes, e.g. as implemented by markdown-it smart quotes, are not part of the OFM spec, but may be used provided that they do not change smart quotes that are explicitly written in the Markdown. + +### Underlined characters +[markdown-it-macron-underline]: https://github.com/dnotes/markdown-it-macron-underlines + +Unicode combining macron below characters should be rendered as underline tags. In the examples below, the combining character has been replaced with an underline to show its relative position: + +- Double macron (U+035F): `s_h` should be rendered as `sh` +- Single macron (U+0331): `h_` should be rendered as `h` + + + +## Right-To-Left Language Support + +OFM is committed to supporting markdown written in right-to-left scripts, which is not well supported by Markdown or Commonmark. The nature of this support is still under discussion, but it may entail ensuring that any markdown syntax that relies on direction-specific delimiters, such as brackets or parentheses, work just as well in the opposite direction, such that `]link[)url(` is equivalent to `[link](url)`. This could be done either by altering the parsers to recognize the delimiters in reverse, or possibly by using a preprocessor to replace RTL syntax delimiters with standard ones. diff --git a/test/fixtures/definitions.txt b/test/fixtures/definitions.txt index edc2061..e59169d 100644 --- a/test/fixtures/definitions.txt +++ b/test/fixtures/definitions.txt @@ -1268,7 +1268,7 @@ aaa . -Fenced code blocks: Commonmark #108 (1885), markdown-it #1 (13) +Fenced code blocks: Commonmark #108 (1885), markdown-it #1 (14) . ``` ``` aaa @@ -1370,7 +1370,7 @@ foo

. -Fenced code blocks: Commonmark #116 (1996), markdown-it #2 (27) +Fenced code blocks: Commonmark #116 (1996), markdown-it #2 (28) . ~~~ aa ``` ~~~ foo @@ -2030,7 +2030,7 @@ Link reference definitions: Commonmark #163 (2836) . -Link reference definitions: Commonmark #164 (2845), markdown-it #3 (50) +Link reference definitions: Commonmark #164 (2845), markdown-it #3 (51) . [Foo bar]: @@ -2298,7 +2298,7 @@ Link reference definitions: Commonmark #186 (3116) . -Link reference definitions: Commonmark #187 (3137), markdown-it #4 (72) +Link reference definitions: Commonmark #187 (3137), markdown-it #4 (73) . [foo] @@ -2567,7 +2567,7 @@ Block quotes: Commonmark #208 (3511) . -Block quotes: Commonmark #209 (3535), markdown-it #5 (90) +Block quotes: Commonmark #209 (3535), markdown-it #5 (91) . > . @@ -2575,7 +2575,7 @@ Block quotes: Commonmark #209 (3535), markdown-it #5 (90) . -Block quotes: Commonmark #210 (3543), markdown-it #6 (96) +Block quotes: Commonmark #210 (3543), markdown-it #6 (97) . > > @@ -3741,7 +3741,7 @@ Lists: Commonmark #281 (5153) . -Lists: Commonmark #282 (5177), markdown-it #7 (115) +Lists: Commonmark #282 (5177), markdown-it #7 (116) . - a - b @@ -3759,7 +3759,7 @@ Lists: Commonmark #282 (5177), markdown-it #7 (115) . -Lists: Commonmark #283 (5197), markdown-it #8 (139) +Lists: Commonmark #283 (5197), markdown-it #8 (140) . 1. a @@ -4366,7 +4366,7 @@ Code spans: Commonmark #330 (5891) . -Code spans: Commonmark #331 (5899), markdown-it #9 (167) +Code spans: Commonmark #331 (5899), markdown-it #9 (168) . ` `` ` . @@ -4374,7 +4374,7 @@ Code spans: Commonmark #331 (5899), markdown-it #9 (167) . -Code spans: Commonmark #332 (5908), markdown-it #10 (178) +Code spans: Commonmark #332 (5908), markdown-it #10 (179) . ` a` . @@ -4382,7 +4382,7 @@ Code spans: Commonmark #332 (5908), markdown-it #10 (178) . -Code spans: Commonmark #333 (5917), markdown-it #11 (189) +Code spans: Commonmark #333 (5917), markdown-it #11 (190) . ` b ` . @@ -4390,7 +4390,7 @@ Code spans: Commonmark #333 (5917), markdown-it #11 (189) . -Code spans: Commonmark #334 (5925), markdown-it #12 (199) +Code spans: Commonmark #334 (5925), markdown-it #12 (200) . ` ` ` ` @@ -4400,7 +4400,7 @@ Code spans: Commonmark #334 (5925), markdown-it #12 (199) . -Code spans: Commonmark #335 (5936), markdown-it #13 (211) +Code spans: Commonmark #335 (5936), markdown-it #13 (212) . `` foo @@ -4412,7 +4412,7 @@ baz . -Code spans: Commonmark #336 (5946), markdown-it #14 (221) +Code spans: Commonmark #336 (5946), markdown-it #14 (222) . `` foo @@ -4422,7 +4422,7 @@ foo . -Code spans: Commonmark #337 (5957), markdown-it #15 (233) +Code spans: Commonmark #337 (5957), markdown-it #15 (234) . `foo bar baz` @@ -5055,7 +5055,7 @@ Emphasis and strong emphasis: Commonmark #414 (6902) . -Emphasis and strong emphasis: Commonmark #415 (6913), markdown-it #16 (250) +Emphasis and strong emphasis: Commonmark #415 (6913), markdown-it #16 (251) . foo***bar***baz . @@ -5063,7 +5063,7 @@ foo***bar***baz . -Emphasis and strong emphasis: Commonmark #416 (6919), markdown-it #17 (258) +Emphasis and strong emphasis: Commonmark #416 (6919), markdown-it #17 (259) . foo******bar*********baz . @@ -5627,7 +5627,7 @@ Links: Commonmark #485 (7537) . -Links: Commonmark #486 (7543), markdown-it #18 (273) +Links: Commonmark #486 (7543), markdown-it #18 (274) . [link]() . @@ -7025,7 +7025,7 @@ bar

. -Hard line breaks: Commonmark #637 (9241), markdown-it #19 (287) +Hard line breaks: Commonmark #637 (9241), markdown-it #19 (288) . `code span` @@ -7139,7 +7139,7 @@ Multiple spaces . -Footnotes: Ocean #1 (17) +Footnotes: Ocean #1 (180) . Paragraph with footnote reference[^1]. @@ -7156,7 +7156,7 @@ Paragraph with footnote reference[^1]. . -Footnotes: Ocean #2 (34) +Footnotes: Ocean #2 (197) . Paragraph with footnote reference[^1]. @@ -7176,7 +7176,7 @@ Intermediate paragraph. . -Footnotes: Ocean #3 (54) +Footnotes: Ocean #3 (217) . [^1]: Footnote text. @@ -7193,7 +7193,7 @@ Paragraph with footnote reference[^1]. . -Footnotes: Ocean #4 (71) +Footnotes: Ocean #4 (234) . [^2]: Footnote text. @@ -7210,7 +7210,7 @@ Paragraph with footnote reference[^2]. . -Footnotes: Ocean #5 (89) +Footnotes: Ocean #5 (252) . [^fn_2-aáж§:]: Footnote text. @@ -7227,7 +7227,7 @@ Paragraph with footnote reference[^fn_2-aáж§:]. . -Footnotes: Ocean #6 (106) +Footnotes: Ocean #6 (269) . [^howdy doody]: Footnote text. @@ -7238,7 +7238,7 @@ Paragraph with footnote reference[^howdy doody]. . -Footnotes: Ocean #7 (117) +Footnotes: Ocean #7 (280) . [^]: Footnote text @@ -7249,7 +7249,7 @@ Paragraph with footnote reference[^]. . -Footnotes: Ocean #8 (129) +Footnotes: Ocean #8 (292) . Paragraph with footnote reference^[Footnote text.]. . @@ -7264,7 +7264,7 @@ Paragraph with footnote reference^[Footnote text.]. . -Footnotes: Ocean #9 (144) +Footnotes: Ocean #9 (307) . Paragraph with footnote reference[^1].