markdown-it-do-co-pack

Markdown-it DigitalOcean Community Plugin (Unofficial)

Unofficial Markdown-it plugin, to apply the same rules and Markdown conversion features as the Markdown Preview Tool.

Abbreviations / Acronyms

Throughout documentation and source-code, there are a few terminology shortcuts used:

• MDIT = Markdown-it
• MD = Markdown
• DO = DigitalOcean
  • DOCO = DigitalOcean Community

Usage

For how to use the DO Community flavor of Markdown, you can refer to:

• The Markdown Preview Tool
• The DO Article Templates
• The DO Formatting and Style Guide

For using this package, there are a few different ways you can use it to transform Markdown:

Usage - As a Plugin (Recommended)

The recommended way to use this package is as a Markdown-it plugin, which loads the entire pack of rules in one shot, or selectively based on the input options. This is recommended because:

• Some of the rules rely on precise loading order, and the plugin automatically observes correct rule ordering
• This automatically runs applyLowLevelDefaults for you, which makes sure MDIT options align with what is needed to produce DO output
• The plugin loader will avoid duplicating rules

The plugin is exported as DoAuthoringMdItPlugin, as well as the default export from index. You can use it like so:

Example Code - JS, ESM - All Rules

import {DoAuthoringMdItPlugin} from 'markdown-it-do-co-pack';
import MarkdownIt from 'markdown-it';

const mdItInstance = new MarkdownIt();

mdItInstance.use(DoAuthoringMdItPlugin, {
	rules: 'all', // This can also be `default`, or an array of rule names
});

let input =
`
# Example

<$>[note]
**Note:** This is a special note!
<$>

Here is a <^>variable highlight<^>.
`


const output = mdItInstance.render(input);
console.log(output);

/**
 * Output:

<h1 id="example">Example</h1>

<p><span class='note'><strong>Note:</strong> This is a special note!<br></span></p>

<p>Here is a <span class="highlight">variable highlight</span>.</p>

 */

Usage - Individual Rules

Although not recommended (see above), technically you can use each rule contained in this pack individually, if you so desire.

Example: Individual Rule - With Plugin Loader

const mdItInstance = new MarkdownIt();
mdItInstance.use(DoAuthoringMdItPlugin, {
	rules: ['do_notes']
});

Example: Individual Rule - Without Plugin Loader

import {RulesByName} from 'markdown-it-do-co-pack';
import MarkdownIt from 'markdown-it';

const mdItInstance = new MarkdownIt();

const {name: ruleName, ruleFn} = RulesByName.do_variable_highlights;

mdItInstance.core.ruler.push(ruleName, ruleFn);

let input =
`
In this sentence, <^>this<^> is a variable.
`


const output = mdItInstance.render(input);
console.log(output);
// <p>In this sentence, <span class="highlight">this</span> is a variable.</p>

TypeScript Support

TypeScript definitions are included in this package.

The most important one for most users will be the DoPluginOptions interface, which helps avoid mistakes when loading the main plugin with .use().

Because of how .use() takes generics, there are two ways I can recommend using the options type:

With Generic Slot

This definitely requires that you have installed @types/markdown-it.

import {DoAuthoringMdItPlugin, DoPluginOptions} from 'markdown-it-do-co-pack';
import MarkdownIt from 'markdown-it';

const mdItInstance = new MarkdownIt();

mdItInstance.use<DoPluginOptions>(DoAuthoringMdItPlugin, {
	rules: 'all'
});

Declaring options separately

You can also create options separately and explicitly type them:

import {DoAuthoringMdItPlugin, DoPluginOptions} from 'markdown-it-do-co-pack';
import MarkdownIt from 'markdown-it';

const mdItInstance = new MarkdownIt();

const options: DoPluginOptions = {
	rules: 'all'
}

mdItInstance.use(DoAuthoringMdItPlugin, options);

Known Issues

Certain rules from other plugins can conflict with the rules contained within this pack. Furthermore, there is no way for me to predict which ones are going to conflict, nor can I audit them all manually, given the number of 3rd party plugins and rules for Markdown-it.

An example of a conflict is the math-inline rule provided by the Markdown All in One VSCode extension - it conflicts with DO's variable highlighting rule.

Development

Tests

The expected value for each render test is whatever the official DigitalOcean Markdown preview tool spits out (or, more specifically, whatever the API returns)

• Per rule tests
  • Isolated rule tests are in rules.spec.ts, and (try) to test each rule without consideration of the others
  • To make the strings easier to paste into JavaScript / TypeScript, I used this CyberChef rule, and some manual escaping when applicable.
• Plugin tests
  • Plugin tests use text fixtures to make large tests easier to add
  • Test fixtures follow the pattern of {name}-input.md for the test input, and {name}-expected.txt for the expected (rendered) value generated by Markdown-it, when the plugin is used.

Coverage

Coverage reports are generated by NYC / Istanbul. Use test to test with coverage, or test:nocov to test without it.

🚨 Warning: Coverage uploading is currently broken with CodeCov. I'm looking for a fix / alternative.

Change Notes

Version	Date	Notes
1.0.0	6/28/2021	Initial Release 🚀

About Me:

More About Me (Joshua Tzucker):

• 🔗joshuatz.com
• 👨‍💻dev.to/joshuatz
• 💬@1joshuatz
• 💾github.com/joshuatz