@soldair/marky-markdown
v6.0.0
Published
The thing npm uses to clean up READMEs and other markdown files
Downloads
7
Maintainers
Readme
marky-markdown
The thing npmjs.com uses to clean up READMEs and other markdown files.
What it does
- Parses markdown with markdown-it, a fast and commonmark-compliant parser.
- Removes broken and malicious user input with sanitize-html
- Applies syntax highlighting to GitHub-flavored code blocks using the highlights library from Atom.
- Uses cheerio to perform various feats of DOM manipulation.
- Converts headings (h1, h2, etc) into anchored hyperlinks.
- Converts relative GitHub links to their absolute equivalents.
- Converts relative GitHub images sources to their GitHub raw equivalents.
- Converts insecure Gravatar URLs to HTTPS.
- Wraps embedded YouTube videos so they can be styled.
- Parses and sanitizes
package.description
as markdown. - Applies CSS classes to redundant content that closely matches npm package name and description.
- Applies CSS classes to badge images, so we can do something interesting with them one day.
Installation
npm install marky-markdown --save
Programmatic Usage
marky-markdown exports a single function. For basic use, that function takes a single argument: a string to convert.
var marky = require("marky-markdown")
marky("# hello, I'm markdown").html()
Options
The exported function takes an optional options object as its second argument:
marky("some trusted string", {sanitize: false}).html()
The default options are as follows:
{
sanitize: true, // remove script tags and stuff
highlightSyntax: true, // run highlights on fenced code blocks
prefixHeadingIds: true, // prevent DOM id collisions
serveImagesWithCDN: false, // use npm's CDN to proxy images over HTTPS
debug: false, // console.log() all the things
package: null, // npm package metadata
}
cheerio "middleware"
marky-markdown always returns the generated HTML document as a cheerio DOM object that can be queried using a familiar jQuery syntax:
var $ = marky("![cat](cat.png)")
$("img").length
// => 1
$("img").attr("src")
// => "cat.png"
npm packages
Pass in an npm package
object to do stuff like rewriting relative URLs
to their absolute equivalent on GitHub, normalizing package metadata
with redundant readme content, etc
var package = {
name: "foo"
name: "foo is a thing"
repository: {
type: "git",
url: "https://github.com/kung/foo"
}
}
marky(
"# hello, I am the foo readme",
{package: package}
).html()
Command-line Usage
You can use marky-markdown to parse markdown files in the shell. The easiest way to do this is to install globally:
npm i -g marky-markdown
marky-markdown some.md > some.html
Tests
npm install
npm test
Dependencies
- cheerio: Tiny, fast, and elegant implementation of core jQuery designed specifically for the server
- escape-html: Escape HTML entities
- github-url-to-object: Extract user, repo, and other interesting properties from GitHub URLs
- highlights: Syntax highlighter
- highlights-tokens: A list of the language tokens used by the Atom.app highlights syntax highlighter
- html-frontmatter: Extract key-value metadata from HTML comments
- js-beautify: jsbeautifier.org for node
- lodash: A utility library delivering consistency, customization, performance, & extras.
- markdown-it: Markdown-it - modern pluggable markdown parser.
- sanitize-html: Clean up user-submitted HTML, preserving whitelisted elements and whitelisted attributes on a per-element basis
- similarity: How similar are these two strings?
- string: string contains methods that aren't included in the vanilla JavaScript string such as escaping html, decoding html entities, stripping tags, etc.
License
ISC