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

html-frontmatter

v1.6.1

Published

Extract key-value metadata from HTML comments

Downloads

272

Readme

HTML Frontmatter

Extract key-value metadata from HTML comments

In the world of printed books, front matter is the stuff at the beginning of the book like the title page, foreword, preface, table of contents, etc. In the world of computer programming, frontmatter is metadata at the top of a file. The term was (probably) popularized by the Jekyll static site generator.

Unlike YAML frontmatter though, HTML frontmatter lives inside plain old HTML comments, so it will be quietly ignored by tools/browsers that don't know about it.

Installation

Download node at nodejs.org and install it, if you haven't already.

npm install html-frontmatter --save

Usage

Given an HTML or Markdown file that looks like this:

<!--
title: GitHub Integration
keywords: github, git, npm, enterprise
published: 2014-10-02
description: npmE works with GitHub!
-->

<h1>Hello World</h1>

And code like this:

var fm = require('html-frontmatter')
var frontmatter = fm(fs.readFileSync('github.md', 'utf-8'))

Here's what you'll get:

{
  title: "GitHub Integration",
  keywords: "github, git, npm, enterprise",
  published: "Wed Oct 01 2014 17:00:00 GMT-0700 (PDT)",
  description: "npmE works with GitHub!"
}

Multiline Values

If you have a long string (like a description) and want it to span multiple lines, simply indent each subsequent line with 2 or more spaces:

<!--
description: This is a long string that
  wraps and goes on forever
  and wraps some more
-->

Colons in Values

Your values can contain colons. No worries.

<!--
title: How I roll: or, the life of a wheel
-->

Array Values

Your values can include shallow arrays

<!--
title: This post has tags
tags: [100, this is a string, true]
-->

Is equivalent to:

<!--
title: This post has tags
tags: [
  100,
  this is a string,
  true
  ]
# note: the closing bracket of an array must be indented by 2 spaces or more
-->

And will return:

{
  title: "This post has tags",
  tags: [100, 'this is a string', true]
}

Coercion

  • Boolean "true" and "false" strings are converted to Boolean.
  • Numeric strings are converted to Number.
  • Strings in YMD-ish format are converted to Date objects.

Under the Hood

html-frontmatter exposes the regular expression it uses to detect presence of frontmatter as a property named pattern. You can use it to conditionally parse frontmatter:

var fm = require('html-frontmatter')
var content = "A string that doesn't have frontmatter in it"
if (content.match(fm.pattern)) {
  // nope
}

Tests

npm install
npm test

# ✓ extracts metadata from colon-delimited comments at the top of an HTML string
# ✓ returns null if frontmatter is not found
# ✓ handles values that contain colons
# ✓ handles line-wrapped values
# ✓ cleans up excess whitespace
# ✓ ignores comments that are not at the top of the file
# ✓ allows newlines before comments
# ✓ ignores comment lines starting with hashes (#)
# ✓ allows single-line comments
# ✓ does not include additional comments
# ✓ coerces boolean strings into Booleans
# ✓ coerces numeric strings into Numbers
# ✓ coerces YMD-ish date strings into Dates
# ✓ exposes its regex pattern as `pattern`
# ✓ handles missing right-hand-value
# ✓ handles shallow arrays