A JS library to convert linguistics-flavored markdown to HTML.
npm install @digitallinguistics/ling-mdA JS library to convert [linguistics-flavored markdown][spec] to HTML.
This library uses [markdown-it] for converting markdown, with a few custom extensions specific to the ling-md format (see Notes below for details). It also enables several commonly-used markdown extensions that are also relevant to linguistics (such as footnotes).
After conversion, you'll probably still want to apply additional CSS styles to the HTML. For example, grammatical glosses like ^^fut^^ are converted to abbreviation tags such as fut, but abbreviation tags are not styled in smallcaps by default.
Install the library:
``cmd`
npm i @digitallinguistics/ling-md
Create a new parser instance and parse the linguistics-flavored markdown:
`js
import Parser from '@digitallinguistics/ling-md'
const markdown = The word perro in Spanish means ''dog''.
const parser = new Parser({ / options / })
const html = parser.parse(markdown)
console.log(html) //
The word perro in Spanish means dog
.
Features
The library enables the following features by default:
$3
| Feature | Markdown | HTML |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------ |
| grammatical glosses |
| fut |
| inline examples | The word perro is Spanish. | The word perro is Spanish.
|
| inline translations | The word perro means ''dog''. | The word perro means dog
.
|
| interlinear glosses | \`igl
ninakupenda
ni-na-ku-pend-a
1sg.SUBJ-PRES-2sg.OBJ-love-IND
I love you
`
| [See documentation here.][dlx2html] |$3
| Feature | Markdown | HTML |
| ---------------------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
| alerts |
> [!note]
> Note Text
| [See documentation here.][alert] |
| block attributes | # Heading {#intro} | |
| bracketed spans | [/lɪŋˈɡwɪstɪks/]{.phon} | /lɪŋˈɡwɪstɪks/ |
| checklists | [See documentation here.][checklists] | |
| definition lists | [See documentation here.][def-lists] | |
| fenced code attributes | \`js {.code-example}
console.log('Hello world!')
`
| console.log('Hello world!') |
| footnotes | Here is a footnote reference,[^1] and some more text.\n\n[^1]: Here is the footnote.
| [See example here.][fn] |
| header anchors | # Header Title | |
| HTML | bold | bold |
| inline attributes | perro{.example lang=spa} | | | inserted text |
| marked text | ==marked text== | marked text |
| math (LaTeX) | Euler’s identity $e^{i\pi}+1=0$ is a beautiful formula in $\mathbb{R}^2$. | (Outputs an image.) |
| smart quotes | "Hello world!" | “Hello world!” |
| tables | [See documentation here.][tables] | |
| strikethrough | ~~This was mistaken text.~~ | |
| subscript | ~subscript~ | subscript |
| summary + details | [See documentation here.][summary-details] | |
| superscript | ^superscript^ | superscript |
| table captions | [See documentation here][table-captions] | |
| table of contents | [[toc]] | [See documentation here.][toc] |
| typography | -- --- ... 1st 2nd 3rd 4th 1/3 3/4 | – — … 1st 2nd 3rd 4th ⅓ ¾ |Usage Notes
- Most markdown libraries convert single asterisks (
perro) to emphasis (perro), but ling-md converts them to [idiomatic text][i] (perro). Use double asterisks for bold instead. (See ["you're using <em> wrong"][em-article] by Facundo Corradini for more information.)
- Attributes may be added in a variety of formats. See the [attributes-parser][attrs-parser] library for a complete list. The most common ones are:
- .className > class="className"
- > id="name"
- > attr="val" (data-* attributes also work)
- There is no markdown shortcut for underlining. Use the tag instead.
- You can enter interlinear glossed examples in [Scription] format, using fenced code blocks, like so:
``
igl
ninakupenda
ni-na-ku-pend-a
1sg.SUBJ-PRES-2sg.OBJ-love-IND
I love you
`
Note that you can enter multiple examples in a single code block, separated by a blank line.
You can also pass options to both the
and dlx2html libraries by including those options in the YAML header of the interlinear, like so:
``
igl
---
dlx2html:
glosses: true
scription2dlx:
emphasis: false
--- ninakupenda
ni-na-ku-pend-a
1sg.SUBJ-PRES-2sg.OBJ-love-IND
I love you
`
API
$3
Provides access to the
instance for further customization.$3
Parse a markdown string using the current options and return HTML.
$3
| Option | Type | Default | Description |
| --------------- | --------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
dlx2html | Object | [See documentation here.][dlx2html] | Options to pass to dlx2html (the library that converts interlinear examples to HTML). If options are provided in a YAML header within fenced code blocks, those options override these ones. |
| markdown | Object | {
html: true,
typographer: true
}
| Options to pass to markdown-it. typographer and html are enabled by default. |
| plugins | Object | {} | Options to pass to any of the markdown-it plugins. Each key should be the name of the plugin, and the value is the options to pass to it. Example: { '@mdit/plugin-alert': { / options / } } You can see a complete list of the markdown-it plugins that are used in this library in the source code [here][source]. |
| translations | span\|q | span | Whether to use or a element for translations.s will wrap the inner text in single quotes. |scription2dlx
|| Object | [See documentation here.][scription2html] | Options to pass toscription2html` (the library that parses interlinear examples). If options are provided in a YAML header within fenced code blocks, those options override these ones. |
[alert]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts
[attrs-parser]: https://www.npmjs.com/package/attributes-parser
[checklists]: https://www.markdownguide.org/extended-syntax/#task-lists
[def-lists]: https://pandoc.org/MANUAL.html#definition-lists
[dlx2html]: https://github.com/digitallinguistics/dlx2html
[em-article]: https://blog.logrocket.com/youre-using-em-wrong/
[fn]: https://mdit-plugins.github.io/footnote.html
[i]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/i
[markdown-it]: https://github.com/markdown-it/markdown-it#readme
[Scription]: https://scription.digitallinguistics.io/
[scription2html]: https://github.com/digitallinguistics/scription2html
[spec]: https://github.com/digitallinguistics/ling-markdown-spec
[source]: https://github.com/digitallinguistics/ling-md/blob/main/index.js
[summary-details]: https://www.npmjs.com/package/markdown-it-collapsible
[table-captions]: https://github.com/martinring/markdown-it-table-captions
[tables]: https://www.markdownguide.org/extended-syntax/#tables
[toc]: https://www.npmjs.com/package/markdown-it-table-of-contents