npm/docs.npmjs.com — pull request #45 by zeke (2014-11-19 07:51:47+00:00)
Title: All the Docs!

[docs.npmjs.com](https://docs.npmjs.com) currently processes our [enterprise content](https://github.com/npm/docs.npmjs.com/tree/master/content/enterprise) and the [docs within the npm client](https://github.com/npm/npm/tree/master/doc), but I think it should be the tool that collects, transforms, and distributes **all of our markdown content**, whether it's getting started guides, API reference, product info, policies, static company pages, etc. Because docs.npmjs.com [is a cors-friendly JSON webservice](https://docs.npmjs.com/content.json), we can consume and display this content wherever we want: on the docs site, on newww, from the command line, in Dash.app...

There are many transformations that need to be applied to all of our markdown files, so it makes sense to do that work in one place:

- Run all HTML through the Caja sanitizer (as newww is currently doing for package READMEs), to remove malicious and/or erroneous HTML content.
- Apply syntax highlighting HTML and CSS to code blocks. Currently this is done browser-side on newww, which leads to an occasional flash-of-unstyled-code and adds 35K to the js bundle. Currently this syntax highlighting is not applied anywhere on docs.npmjs.com.
- Automatically add anchors to headings for deep linking within pages. This is not yet happening anywhere.

That's all looking ahead, though.

Here are some proposed changes that bring us closer to that goal:

## Policies

@isaacs has expressed an interest in keeping the existing [policies repo](https://github.com/npm/policies) intact, so rather than moving content out of that repo, let's just `npm install` it in this one!

- Added a [package.json](https://github.com/npm/policies/blob/master/package.json) file to the policies repo, with a registry-2 style package name: `@npm/policies`
- Installed policies package from GitHub: `npm install npm/policies` because registry 2 is not ready
- Updated build script to copy markdown files from `./node_modules/@npm/policies/` to `./content/`

## Static Pages

There's a [static-pages repo](https://github.com/npm/static-pages) with one file in it: `jobs.md`. My proposal is to kill that repo in favor of `/content/company` in this repo.

## Sections

I created a file called `sections.json` that allows the sections to be named and ordered. It looks like this:

```json
[{
"id": "misc",
"title": "Using npm"
}, {
"id": "enterprise",
"title": "npm Enterprise"
}, {
"id": "cli",
"title": "CLI Commands"
}, {
"id": "files",
"title": "Configuring npm"
}, {
"id": "api",
"title": "Using npm programmatically"
}, {
"id": "policies",
"title": "npm policy documents"
}, {
"id": "company",
"title": "About npm inc"
}]
```

If there are sections that we wish to disable on docs.npmjs.com (such as `company`), we can easily do so by including an additional property above and checking for it in the template.

@seldo, @linclark, @rockbot please tell me your thoughts.