npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@soldair/marky-markdown

v6.0.0

Published

The thing npm uses to clean up READMEs and other markdown files

Downloads

7

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