@cryptotaxi247 / documentation
Code Commits Issues Pulls Sessions CI/CD
@reggi/path-to-regexp
@reggi/path-to-regexp dependabot/npm_and_yarn/main/copy-to-clipboard-4.0.2 dependabot/npm_and_yarn/main/eslint-10.4.0 dependabot/npm_and_yarn/main/npmcli/eslint-config-7.0.0 dependabot/npm_and_yarn/main/proc-log-7.0.0 dependabot/npm_and_yarn/npm_and_yarn-826852524d dependabot/npm_and_yarn/npm_and_yarn-ab9a7f4bc2 deprecate-totp-2fa dhei/classic-tokens gat-bypass-2fa-docs jpg619/fix-accessibility-content-flow jpg619/version-bump-tar-2 kartykp/gat-bypass-2fa-docs kartykp/upgrade-path-to-regex main maitxn/version-bump-tar patch-1 reggi/cache-based-on-version reggi/dev-engines reggi/fix-transform-prettier reggi/overrides update-search-sensitivity
md 171 lines 9.8 KB
Rendered Raw
1 # Contributing to the npm Documentation
2
3 This is the documentation for [https://docs.npmjs.com/](https://docs.npmjs.com/). Do you want to contribute a change? Great!
4
5 ### Table of Contents
6
7 - [Quick start](#quick-start)
8 - [Running locally](#running-locally)
9 - [Updating content](#updating-content)
10 - [Navigation](#navigation)
11 - [CLI](#cli)
12 - [Deploying changes](#deploying-changes)
13
14 ## Quick start
15
16 1. `npm install` to download Gatsby and all the dependencies
17 2. `npm run develop`: starts the test server at `http://localhost:8000`.
18 3. Update the content - it's MDX, which is like Markdown - in the `content` directory.
19 4. Review your content at `http://localhost:8000`. (Gatsby watches the filesystem and will reload your content changes immediately.)
20 5. Once you're happy, commit it and open a pull request at https://github.com/npm/documentation.
21 6. A CI workflow run will publish your PR to a GitHub Preview Page.
22 7. Once the content is reviewed, merge the pull request. That will [deploy the site](https://github.com/npm/documentation/actions/workflows/publish.yml).
23
24 ## Running locally
25
26 First, `npm install` the dependencies. This will install Gatsby, et al.
27
28 Next, `npm run develop` to start the test server to view your changes. The Gatsby server will be started on port 8000. You can navigate to `http://localhost:8000` to view the site live. This npm script doesn't work on Windows terminals, run it manually using appropriate syntax for your terminal. The syntax for command prompt is `set PARCEL_WORKERS=0 & npm run gatsby develop`.
29
30 In order to cut down on the time it takes `npm run develop` to complete, you can use the environment variables `GATSBY_CONTENT_ALLOW` and `GATSBY_CONTENT_IGNORE` to only build some pages.
31
32 For example, if the only pages you need to test locally are in `/cli/v10/commands`, then you can run the the following to build the `cli/v10/commands` pages:
33
34 ```sh
35 GATSBY_CONTENT_ALLOW=cli/v10/commands npm run develop
36 ```
37
38 The `content/cli` directory has the most pages so it tends to be most helpful to ignore older CLI versions unless you need to explicitly test those pages:
39
40 ```sh
41 GATSBY_CONTENT_IGNORE=cli/v6,cli/v7,cli/v8,cli/v9 npm run develop
42 ```
43
44 **For best results use The latest versions of Node.js and npm**
45
46 **Gatsby will watch your filesystem looking for updates.** Any content changes you make should be reflected in the site immediately.
47
48 ## Updating content
49
50 ### Commits
51
52 We use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
53
54 When opening a pull request please be sure that either the pull request title, or each commit in the pull request, has one of the following prefixes:
55
56 - `feat`: For when introducing a new feature.
57 - `fix`: For bug fixes.
58 - `docs`: For documentation updates. This specifically means the documentation in and this repo, NOT the contents of the documentation site itself.
59 - `chore`: For changes that do not affect the published site. Often these are changes to tests. The result will be _no_ change to the website when it is next published.
60
61 ### Documentation content
62
63 The documentation content lives in the `content` directory, and is Markdown. (Actually, [MDX](https://mdxjs.com/), a sort of reactive Markdown.)
64
65 ### Static content (images)
66
67 Static content lives in the `static` directory. Since most of the static content is screenshots, you can use the `Screenshot` component to reference them, which is an extension of the `Img` component that is configured for the docs site. For example, an image living as `static/organizations/managing-teams/team-members.png` would be referenced as:
68
69 ```
70 <Screenshot src="/organizations/managing-teams/team-members.png" alt="Screenshot of the team members button" />
71 ```
72
73 (Note the `alt` tag, it is mandatory.)
74
75 ### "Shared" content
76
77 There are various places where we want to share content between pages, to prevent copy-pasta. For example, we display a screenshot of the user login dialog repeatedly. Therefore this shared content is defined in `src/shared.js`, and includes a literal MDX snippet.
78
79 For example, `user-login` is defined with `text` and `image` properties:
80
81 ```js
82 'user-login': {
83 'text': (<><Link href="https://www.npmjs.com/login">Log in</Link> to npm
84 with your user account.</>),
85 'image': (<Screenshot src="/shared/user-login.png" alt="Screenshot of np
86 m login dialog" />)
87 },
88 ```
89
90 Since MDX is reactive, you can import the shared data at the top of the file, just beneath your frontmatter. It uses the special path `~/shared.js` so it can be imported the same way from any nested file without needing to figure out the appropriate relative path:
91
92 ```
93 ---
94 title: Using shared content
95 ---
96 import shared form '~/shared.js'
97 ```
98
99 And then reference the shared content within `<>`:
100
101 ```
102 To login, <>{shared['user-login'].text}</>
103 ```
104
105 ### URLs
106
107 Note that for backward compatibility reasons, the on-disk paths are not precisely identical to the URLs for the documentation. To keep URLs expressive but still short, intermediate directories are removed from a page's URL.
108
109 You can see this navigating through the documentation hierarchy: if you visit the "Packages and modules" page, you'll navigate to `https://docs.npmjs.com/packages-and-modules`.
110
111 There's then a folder beneath that, "Contributing packages to the registry", which is (sensibly) at `https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry`.
112
113 You might (understandably) expect the page "Creating Node.js modules" to be URL-wise beneath `contributing-packages-to-the-registry`, but unfortunately, you would be wrong. To keep URLs short, the intermediate folder paths are removed from pages, so "Creating Node.js modules" becomes `https://docs.npmjs.com/creating-node-js-modules`.
114
115 If you have only a URL and want to find where it lives on disk, you can consult the left-hand navigation on the site.
116
117 <img width="353" alt="Screen Shot 2021-03-02 at 10 06 19" src="https://user-images.githubusercontent.com/1130014/109632522-04494980-7b3f-11eb-8b07-9e7bb992872f.png">
118
119 You can also use `find` from within the `content` directory. For example:
120
121 ```
122 find . -iname creating-node-js-modules\* -print
123 ```
124
125 ### Frontmatter
126
127 The content pages should include [frontmatter](https://jekyllrb.com/docs/front-matter/).
128
129 - `title`: the page's title (string); required
130 - `redirect_from`: any URLs on the site that will be redirected to this page (array of strings)
131
132 ## Navigation
133
134 The site's navigation (on the left-hand sidebar of the site) is controlled by `content/nav.yml`. If you add or remove a page from the site, you'll also want to add or remove it from the navigation configuration.
135
136 ## CLI
137
138 The documentation for the [npm cli](https://github.com/npm/cli) is not modified in this repository. Instead, the canonical location for it is in the [npm/cli](https://github.com/npm/cli) repository. Modifications to those files are automatically included here for completeness.
139
140 **Pull requests to CLI documentation in this repository will be closed.**
141
142 ### Updating CLI Content
143
144 Since the CLI documentation content lives in the [npm/cli repo](https://github.com/npm/cli), there is a [GitHub Actions workflow](https://github.com/npm/documentation/actions/workflows/update-cli.yml) that pulls documentation updates from the CLI into this repository. This is done nightly.
145
146 This process can, of course, be done manually. This may be useful for editing its behavior or debugging, and it _should_ be done when you're adding a new major version to the site.
147
148 1. Review the configuration
149 The `cli/releases.json` configures how the CLI documentation is included. It is an array of documentation versions, each having the following configuration:
150
151 - `id`: A short identifier for the documentation version, eg `v6` or `v7`. This corresponds to a directory containing a version of the CLI repository (using a submodule). This will also be used as the output folder in the content.
152 - `branch`: The branch name for the version. This will be used to fetch the latest version of the documentation from GitHub.
153 - `spec`: The registry spec for the version. This will be used to fetch the latest version in that range from the registry.
154 - `resolved`: This should not be edited manually. This is a reference to the last fetched version of the content for this release. If a future fetch is done and this field matches what is returned from the registry, then no updates will be made. To force an update (which can be useful when making changes to the `bin/build.js` script) it can be run with the argument `--force`.
155
156 2. Fetch and import the latest content for each CLI release
157 Run `npm run build -w cli` to download the latest version for each release and import its content into the `content` directory. This will take the content in each submodule's `docs/content` directory, perform any necessary translations (like adding historical redirects) and putting it in this repository's `content` directory. In addition, it will take the `docs/nav.yml` and include it in this repository's navigation.
158
159 ## Reviewing changes
160
161 When a pull request is opened or updated the [GitHub Actions workflow](https://github.com/npm/documentation/actions/workflows/publish.yml) will deploy a preview to the [`github-pages` environment](https://github.com/npm/documentation/deployments/activity_log?environment=github-pages). The URL will be reported to the pull request and the status can be checked by looking at the workflows for the [`pull_request_target` event](https://github.com/npm/documentation/actions/workflows/publish.yml?query=event%3Apull_request_target).
162
163 ## Deploying changes
164
165 The docs site (https://docs.npmjs.com/) is published from a [GitHub Actions workflow](https://github.com/npm/documentation/actions/workflows/publish.yml) on any push into the main branch. That means that the workflow for updating the site is:
166
167 1. Make your changes locally, review them, commit them.
168 2. Open a pull request for review
169 3. Merge that pull request
170
171 On step three, your changes will be published live! 🎉