Skip to content

Commit 8bfa05f

Browse files
ethomsonwraithgar
ethomson
authored and
wraithgar
committed
chore(docs): add navigation configuration
The documentation in this repository is added to the overall npm documentation at https://docs.npmjs.com/, which includes both the documentation for the public registry and the CLI. The documentation site itself also has a navigational hierarchy; since the content is included from the CLI, we also want to ensure that the navigation for that content lives in this repository. This means that this repository is the source of truth for all of the CLI documentation, and we do not need to update two places when we add, edit, or remove CLI documentation. It all lives here. This also teaches the documentation rendering script to identify when the navigation configuration (nav.yml) is missing new pages that were recently added or retains old pages that have recently been deleted. PR-URL: #2775 Credit: @ethomson Close: #2775 Reviewed-by: @wraithgar
1 parent ba1adef commit 8bfa05f

File tree

3 files changed

+341
-6
lines changed

3 files changed

+341
-6
lines changed

‎.npmignore

+1
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ node_modules/npm-registry-mock
1616

1717
# don't need these in the npm package.
1818
html/*.png
19+
docs/nav.yml
1920

2021
# don't ignore .npmignore files
2122
# these are used in some tests.

‎docs/dockhand.js

+91-6
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,12 @@ const template = fs.readFileSync('template.html').toString();
1919

2020
const run = async function() {
2121
try {
22-
await walk(inputRoot);
22+
const navPaths = await getNavigationPaths();
23+
const fsPaths = await renderFilesystemPaths();
24+
25+
if (!ensureNavigationComplete(navPaths, fsPaths)) {
26+
process.exit(1);
27+
}
2328
}
2429
catch (error) {
2530
console.error(error);
@@ -28,7 +33,85 @@ const run = async function() {
2833

2934
run();
3035

31-
async function walk(root, dirRelative) {
36+
function ensureNavigationComplete(navPaths, fsPaths) {
37+
const unmatchedNav = { }, unmatchedFs = { };
38+
39+
for (const navPath of navPaths) {
40+
unmatchedNav[navPath] = true;
41+
}
42+
43+
for (let fsPath of fsPaths) {
44+
fsPath = '/' + fsPath.replace(/\.md$/, "");
45+
46+
if (unmatchedNav[fsPath]) {
47+
delete unmatchedNav[fsPath];
48+
}
49+
else {
50+
unmatchedFs[fsPath] = true;
51+
}
52+
}
53+
54+
const missingNav = Object.keys(unmatchedNav).sort();
55+
const missingFs = Object.keys(unmatchedFs).sort()
56+
57+
if (missingNav.length > 0 || missingFs.length > 0) {
58+
let message = "Error: documentation navigation (nav.yml) does not match filesystem.\n";
59+
60+
if (missingNav.length > 0) {
61+
message += "\nThe following path(s) exist on disk but are not present in nav.yml:\n\n";
62+
63+
for (const nav of missingNav) {
64+
message += ` ${nav}\n`;
65+
}
66+
}
67+
68+
if (missingNav.length > 0 && missingFs.length > 0) {
69+
message += "\nThe following path(s) exist in nav.yml but are not present on disk:\n\n";
70+
71+
for (const fs of missingFs) {
72+
message += ` ${fs}\n`;
73+
}
74+
}
75+
76+
message += "\nUpdate nav.yml to ensure that all files are listed in the appropriate place.";
77+
78+
console.error(message);
79+
80+
return false;
81+
}
82+
83+
return true;
84+
}
85+
86+
function getNavigationPaths() {
87+
const navFilename = path.join(docsRoot, 'nav.yml');
88+
const nav = yaml.parse(fs.readFileSync(navFilename).toString(), 'utf8');
89+
90+
return walkNavigation(nav);
91+
}
92+
93+
function walkNavigation(entries) {
94+
const paths = [ ]
95+
96+
for (const entry of entries) {
97+
if (entry.children) {
98+
paths.push(... walkNavigation(entry.children));
99+
}
100+
else {
101+
paths.push(entry.url);
102+
}
103+
}
104+
105+
return paths;
106+
}
107+
108+
async function renderFilesystemPaths() {
109+
return await walkFilesystem(inputRoot);
110+
}
111+
112+
async function walkFilesystem(root, dirRelative) {
113+
const paths = [ ]
114+
32115
const dirPath = dirRelative ? path.join(root, dirRelative) : root;
33116
const children = fs.readdirSync(dirPath);
34117

@@ -37,15 +120,18 @@ async function walk(root, dirRelative) {
37120
const childPath = path.join(root, childRelative);
38121

39122
if (fs.lstatSync(childPath).isDirectory()) {
40-
await walk(root, childRelative);
123+
paths.push(... await walkFilesystem(root, childRelative));
41124
}
42125
else {
43-
await translate(childRelative);
126+
await renderFile(childRelative);
127+
paths.push(childRelative);
44128
}
45129
}
130+
131+
return paths;
46132
}
47133

48-
async function translate(childPath) {
134+
async function renderFile(childPath) {
49135
const inputPath = path.join(inputRoot, childPath);
50136

51137
if (!inputPath.match(/\.md$/)) {
@@ -119,7 +205,6 @@ async function translate(childPath) {
119205
console.log(`warning: unknown token '${token}' in ${inputPath}`);
120206
return '';
121207
}
122-
console.log(key);
123208
return key;
124209
});
125210

‎docs/nav.yml

+249
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,249 @@
1+
# This is the navigation for the documentation pages; it is not used
2+
# directly within the CLI documentation. Instead, it will be used
3+
# for the https://docs.npmjs.com/ site.
4+
5+
- title: CLI Commands
6+
shortName: Commands
7+
url: /commands
8+
children:
9+
- title: npm
10+
url: /commands/npm
11+
description: JavaScript package manager
12+
- title: npm access
13+
url: /commands/npm-access
14+
description: Set access level on published packages
15+
- title: npm adduser
16+
url: /commands/npm-adduser
17+
description: Add a registry user account
18+
- title: npm audit
19+
url: /commands/npm-audit
20+
description: Run a security audit
21+
- title: npm bin
22+
url: /commands/npm-bin
23+
description: Display npm bin folder
24+
- title: npm bugs
25+
url: /commands/npm-bugs
26+
description: Bugs for a package in a web browser maybe
27+
- title: npm cache
28+
url: /commands/npm-cache
29+
description: Manipulates packages cache
30+
- title: npm ci
31+
url: /commands/npm-ci
32+
description: Install a project with a clean slate
33+
- title: npm completion
34+
url: /commands/npm-completion
35+
description: Tab completion for npm
36+
- title: npm config
37+
url: /commands/npm-config
38+
description: Manage the npm configuration files
39+
- title: npm dedupe
40+
url: /commands/npm-dedupe
41+
description: Reduce duplication
42+
- title: npm deprecate
43+
url: /commands/npm-deprecate
44+
description: Deprecate a version of a package
45+
- title: npm diff
46+
url: /commands/npm-diff
47+
description: The registry diff command
48+
- title: npm dist-tag
49+
url: /commands/npm-dist-tag
50+
description: Modify package distribution tags
51+
- title: npm docs
52+
url: /commands/npm-docs
53+
description: Docs for a package in a web browser maybe
54+
- title: npm doctor
55+
url: /commands/npm-doctor
56+
description: Check your environments
57+
- title: npm edit
58+
url: /commands/npm-edit
59+
description: Edit an installed package
60+
- title: npm exec
61+
url: /commands/npm-exec
62+
description: Run a command from an npm package
63+
- title: npm explain
64+
url: /commands/npm-explain
65+
description: Explain installed packages
66+
- title: npm explore
67+
url: /commands/npm-explore
68+
description: Browse an installed package
69+
- title: npm fund
70+
url: /commands/npm-fund
71+
description: Retrieve funding information
72+
- title: npm help
73+
url: /commands/npm-help
74+
description: Search npm help documentation
75+
- title: npm help-search
76+
url: /commands/npm-help-search
77+
description: Get help on npm
78+
- title: npm hook
79+
url: /commands/npm-hook
80+
description: Manage registry hooks
81+
- title: npm init
82+
url: /commands/npm-init
83+
description: Create a package.json file
84+
- title: npm install
85+
url: /commands/npm-install
86+
description: Install a package
87+
- title: npm install-ci-test
88+
url: /commands/npm-install-ci-test
89+
description: Install a project with a clean slate and run tests
90+
- title: npm install-test
91+
url: /commands/npm-install-test
92+
description: Install package(s) and run tests
93+
- title: npm link
94+
url: /commands/npm-link
95+
description: Symlink a package folder
96+
- title: npm logout
97+
url: /commands/npm-logout
98+
description: Log out of the registry
99+
- title: npm ls
100+
url: /commands/npm-ls
101+
description: List installed packages
102+
- title: npm org
103+
url: /commands/npm-org
104+
description: Manage orgs
105+
- title: npm outdated
106+
url: /commands/npm-outdated
107+
description: Check for outdated packages
108+
- title: npm owner
109+
url: /commands/npm-owner
110+
description: Manage package owners
111+
- title: npm pack
112+
url: /commands/npm-pack
113+
description: Create a tarball from a package
114+
- title: npm ping
115+
url: /commands/npm-ping
116+
description: Ping npm registry
117+
- title: npm prefix
118+
url: /commands/npm-prefix
119+
description: Display prefix
120+
- title: npm profile
121+
url: /commands/npm-profile
122+
description: Change settings on your registry profile
123+
- title: npm prune
124+
url: /commands/npm-prune
125+
description: Remove extraneous packages
126+
- title: npm publish
127+
url: /commands/npm-publish
128+
description: Publish a package
129+
- title: npm rebuild
130+
url: /commands/npm-rebuild
131+
description: Rebuild a package
132+
- title: npm repo
133+
url: /commands/npm-repo
134+
description: Open package repository page in the browser
135+
- title: npm restart
136+
url: /commands/npm-restart
137+
description: Restart a package
138+
- title: npm root
139+
url: /commands/npm-root
140+
description: Display npm root
141+
- title: npm run-script
142+
url: /commands/npm-run-script
143+
description: Run arbitrary package scripts
144+
- title: npm search
145+
url: /commands/npm-search
146+
description: Search for packages
147+
- title: npm set-script
148+
url: /commands/npm-set-script
149+
description: Set tasks in the scripts section of package.json
150+
- title: npm shrinkwrap
151+
url: /commands/npm-shrinkwrap
152+
description: Lock down dependency versions for publication
153+
- title: npm star
154+
url: /commands/npm-star
155+
description: Mark your favorite packages
156+
- title: npm stars
157+
url: /commands/npm-stars
158+
description: View packages marked as favorites
159+
- title: npm start
160+
url: /commands/npm-start
161+
description: Start a package
162+
- title: npm stop
163+
url: /commands/npm-stop
164+
description: Stop a package
165+
- title: npm team
166+
url: /commands/npm-team
167+
description: Manage organization teams and team memberships
168+
- title: npm test
169+
url: /commands/npm-test
170+
description: Test a package
171+
- title: npm token
172+
url: /commands/npm-token
173+
description: Manage your authentication tokens
174+
- title: npm uninstall
175+
url: /commands/npm-uninstall
176+
description: Remove a package
177+
- title: npm unpublish
178+
url: /commands/npm-unpublish
179+
description: Remove a package from the registry
180+
- title: npm unstar
181+
url: /commands/npm-unstar
182+
description: Remove an item from your favorite packages
183+
- title: npm update
184+
url: /commands/npm-update
185+
description: Update a package
186+
- title: npm version
187+
url: /commands/npm-version
188+
description: Bump a package version
189+
- title: npm view
190+
url: /commands/npm-view
191+
description: View registry info
192+
- title: npm whoami
193+
url: /commands/npm-whoami
194+
description: Display npm username
195+
- title: npx
196+
url: /commands/npx
197+
description: Run a command from an npm package
198+
199+
- title: Configuring npm
200+
shortName: Configuring
201+
url: /configuring-npm
202+
children:
203+
- title: Install
204+
url: /configuring-npm/install
205+
description: Download and install node and npm
206+
- title: Folders
207+
url: /configuring-npm/folders
208+
description: Folder structures used by npm
209+
- title: .npmrc
210+
url: /configuring-npm/npmrc
211+
description: The npm config files
212+
- title: npm-shrinkwrap.json
213+
url: /configuring-npm/npm-shrinkwrap-json
214+
description: A publishable lockfile
215+
- title: package.json
216+
url: /configuring-npm/package-json
217+
description: Specifics of npm's package.json handling
218+
- title: package-lock.json
219+
url: /configuring-npm/package-lock-json
220+
description: A manifestation of the manifest
221+
222+
- title: Using npm
223+
shortName: Using
224+
url: /using-npm
225+
children:
226+
- title: Registry
227+
url: /using-npm/registry
228+
description: The JavaScript Package Registry
229+
- title: Config
230+
url: /using-npm/config
231+
description: About npm configuration
232+
- title: Scope
233+
url: /using-npm/scope
234+
description: Scoped packages
235+
- title: Scripts
236+
url: /using-npm/scripts
237+
description: How npm handles the "scripts" field
238+
- title: Workspaces
239+
url: /using-npm/workspaces
240+
description: Working with workspaces
241+
- title: Organizations
242+
url: /using-npm/orgs
243+
description: Working with teams & organizations
244+
- title: Developers
245+
url: /using-npm/developers
246+
description: Developer guide
247+
- title: Removal
248+
url: /using-npm/removal
249+
description: Cleaning the slate

0 commit comments

Comments
 (0)