Skip to content

Latest commit

 

History

History
79 lines (56 loc) · 2.42 KB

README.md

File metadata and controls

79 lines (56 loc) · 2.42 KB

docs.npmjs.com

The place where all things npm will one day be documented

Development

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

To run the app locally:

npm install
npm start

Now you have a server running at at localhost:5000

The Build Process

The prepublish task is run automatically after npm install. This triggers npm run build, which does the following:

  1. Copies npm documentation from ./node_modules/npm/doc to ./content
  2. Walks the content directory collecting markdown files.
  3. Reads the contents of each markdown file.
  4. Parses HTML Frontmatter from the markdown files
  5. Converts markdown to HTML
  6. Writes content.json with Base64-encoded markdown contents AND HTML contents
  7. Writes views/partials/nav.hbs

The copied and generated files are ignored for two reasons:

  1. Keeps the git history uncluttered.
  2. Prevents humans from accidentally editing auto-generated files

HTML Frontmatter

When the build process runs, it looks for metadata in markdown files in the following format:

<!--
title: GitHub integration
keywords: github, git, enterprise
description: If your organization uses GitHub or GitHub Enterprise, npmE can be configured
  to automatically use them for login and access control.
-->

See an example in content/enterprise/github.md.

This metadata is then added to content.json, and looks like this:

{
  "title": "GitHub integration",
  "keywords": "github, git, enterprise",
  "description": "If your organization...etc"
}

If the file has a title property in its frontmatter, it will be used for the <title> of the rendered HTML page. If title is absent from the frontmatter, the filename (without the .md extension) is used.

Frontmatter values can span multiple lines for longer strings like description text. To make a value multiline, simply indent it with two or more spaces on subsequent lines.

Webservice

The content.json file is served publicly at /content.json with CORS support, allowing browsers on other domains to fetch all the npm documentation and accompanying metadata with a single HTTP call.

Deployment

export NODE_ENV=production