Skip to content

Latest commit

 

History

History
84 lines (56 loc) · 3.1 KB

README.md

File metadata and controls

84 lines (56 loc) · 3.1 KB
Raw

docs.npmjs.com

The place where all things npm will one day be documented.

Editing Content

All the markdown files can be found in the content directory. Some of these files live here in this repository, others live in other repositories and are imported during the build process. These imported files are ignored by git to prevent people from accidentally editing the wrong files.

HTML Frontmatter for Page Metadata

This site uses html-frontmatter to add metadata to pages.

title

If a 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.

order

Pages are sorted alphabetically by default, but the page order per section can be overridden by using a numerical order frontmatter property. It is not necessary to order all pages in a section: Any pages in a section that don't have an order property will be relegated to the end of that section.

Redirects

If you rename or remove a file, add it to lib/redirects.js too keep things from breaking.

Development

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

To run the app locally:

npm install
npm run dev

Now you have a server running nodemon at localhost:5000.

The Build Process

The build is run automatically after every npm install and before npm start. Here's an overview of what it does.

  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 HTML content of each file included.

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

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

git push origin +master:deploy-staging
git push origin +master:deploy-production

If you get dissed with an "Everything up-to-date" message, make an empty commit and push again:

git commit -avm "emptiness" --allow-empty