From 940d9d05cea912c9698a74777705425a9e12eeb5 Mon Sep 17 00:00:00 2001 From: Luke Karrys Date: Sun, 15 Oct 2023 10:52:54 -0700 Subject: [PATCH] chore: prettier --- .eslintrc.js | 47 ++--- .prettierIgnore | 3 - CODE_OF_CONDUCT.md | 25 ++- CONTENT-MODEL.md | 85 ++++---- CONTRIBUTING.md | 167 ++++----------- README.md | 24 +-- gatsby-node.js | 6 +- package-lock.json | 24 +-- package.json | 15 +- scripts/template-oss/index.js | 6 +- src/pages/404.js | 4 +- src/shared.js | 386 +++++++++++++++++++++++++--------- theme/.gitignore | 1 + theme/package.json | 1 - 14 files changed, 446 insertions(+), 348 deletions(-) diff --git a/.eslintrc.js b/.eslintrc.js index e6e582cb67d..80f7f33438e 100644 --- a/.eslintrc.js +++ b/.eslintrc.js @@ -1,11 +1,7 @@ module.exports = { root: true, - ignorePatterns: [ - 'cli/', - 'theme/', - ], + ignorePatterns: ['cli/', '.cache/', 'public/'], extends: [ - '@npmcli', 'eslint:recommended', 'plugin:react/recommended', 'plugin:github/react', @@ -17,26 +13,29 @@ module.exports = { version: 'detect', }, }, - overrides: [{ - files: ['src/**'], - parserOptions: { - ecmaFeatures: { - jsx: true, + overrides: [ + { + files: ['src/**'], + parserOptions: { + ecmaFeatures: { + jsx: true, + }, + }, + env: { + commonjs: true, + es2022: true, + browser: true, + node: false, + }, + rules: { + 'max-len': 'off', }, }, - env: { - commonjs: true, - es2022: true, - browser: true, - node: false, - }, - rules: { - 'max-len': 'off', - }, - }, { - files: ['src/shared.js'], - rules: { - 'react/no-unescaped-entities': 'off', + { + files: ['src/shared.js'], + rules: { + 'react/no-unescaped-entities': 'off', + }, }, - }], + ], } diff --git a/.prettierIgnore b/.prettierIgnore index 20d36b1f1bc..211b3a7e6ac 100644 --- a/.prettierIgnore +++ b/.prettierIgnore @@ -1,10 +1,7 @@ **/template-oss/*.json **/template-oss/*.yml content/ -content-debug/ cli/ .github/ package-lock.json -CODE_OF_CONDUCT.md -CONTENT-MODEL.md SECURITY.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index e38a947239a..057b269445a 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -10,20 +10,20 @@ We pledge to act and interact in ways that contribute to an open, welcoming, div Examples of behavior that contributes to a positive environment for our community include: -* Demonstrating empathy and kindness toward other people -* Being respectful of differing opinions, viewpoints, and experiences -* Giving and gracefully accepting constructive feedback -* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience -* Focusing on what is best not just for us as individuals, but for the overall community +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints, and experiences +- Giving and gracefully accepting constructive feedback +- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience +- Focusing on what is best not just for us as individuals, but for the overall community Examples of unacceptable behavior include: -* The use of sexualized language or imagery, and sexual attention or advances of any kind -* Trolling, insulting or derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or email address, without their explicit permission -* Contacting individual members, contributors, or leaders privately, outside designated community mechanisms, without their explicit permission -* Other conduct which could reasonably be considered inappropriate in a professional setting +- The use of sexualized language or imagery, and sexual attention or advances of any kind +- Trolling, insulting or derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or email address, without their explicit permission +- Contacting individual members, contributors, or leaders privately, outside designated community mechanisms, without their explicit permission +- Other conduct which could reasonably be considered inappropriate in a professional setting ## Enforcement Responsibilities @@ -65,7 +65,7 @@ Community leaders will follow these Community Impact Guidelines in determining t ### 4. Permanent Ban -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals. +**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals. **Consequence**: A permanent ban from any sort of public interaction within the community. @@ -78,4 +78,3 @@ Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcem [homepage]: https://www.contributor-covenant.org For answers to common questions about this code of conduct, see the FAQ at . Translations are available at . - diff --git a/CONTENT-MODEL.md b/CONTENT-MODEL.md index cd4c1334faa..165eb7e1b61 100644 --- a/CONTENT-MODEL.md +++ b/CONTENT-MODEL.md @@ -1,32 +1,38 @@ # Content model + ## Introduction -This content model explains the goals of content in the npm docs, and what to include when you're writing or updating an article. We use a model to ensure that our content consistently, clearly, and comprehensively communicates what people need to achieve their goals with npm. -Following a content model creates consistency that helps users and maintainers of the docs. + +This content model explains the goals of content in the npm docs, and what to include when you're writing or updating an article. We use a model to ensure that our content consistently, clearly, and comprehensively communicates what people need to achieve their goals with npm. Following a content model creates consistency that helps users and maintainers of the docs. For style questions, default to https://github.com/github/docs-internal/blob/main/contributing/content-style-guide.md ## Content structure + Docs are grouped by topic. -* Top-level doc set (Example: https://docs.npmjs.com/packages-and-modules) - * Categories (Example: https://docs.npmjs.com/packages-and-modules/introduction-to-packages-and-modules) - * Articles (Example: https://docs.npmjs.com/about-packages-and-modules) + +- Top-level doc set (Example: https://docs.npmjs.com/packages-and-modules) + - Categories (Example: https://docs.npmjs.com/packages-and-modules/introduction-to-packages-and-modules) + - Articles (Example: https://docs.npmjs.com/about-packages-and-modules) ### Categories + Categories are organized around a feature or a discrete set of tasks. Use titles that are task-based and describe the purpose or goal of the category. ### Articles + Articles are the basic unit of content for the docs. Use titles that are clear, descriptive, and specific, with the same terminology as the product itself. All articles follow the same content order. #### Content order + Introduce content from the broadest applicability to the most specific, following this order: -* Conceptual content -* Procedural content for enabling a feature or setting -* Procedural content on using a feature -* Procedural content on managing a feature or setting -* Procedural content on disabling a feature or setting -* Procedural content on destructive actions (e.g. deletion) -* Troubleshooting information +- Conceptual content +- Procedural content for enabling a feature or setting +- Procedural content on using a feature +- Procedural content on managing a feature or setting +- Procedural content on disabling a feature or setting +- Procedural content on destructive actions (e.g. deletion) +- Troubleshooting information Articles answer, “What is it? Why do it?” and then “How does someone do it?” @@ -34,57 +40,64 @@ Articles answer, “What is it? Why do it?” and then “How does someone do it **Conceptual** -Conceptual content helps people understand a feature or topic by providing a clear, high-level overview, explanation of how the feature or topic can help them on their journey, and context like use cases or examples. Conceptual content is clear enough for a novice audience but also includes relevant information for advanced users. People most often use conceptual content when they're learning. -If people need certain permissions to do a task described in the article, include a permissions statement describing who can do the task in the conceptual information. +Conceptual content helps people understand a feature or topic by providing a clear, high-level overview, explanation of how the feature or topic can help them on their journey, and context like use cases or examples. Conceptual content is clear enough for a novice audience but also includes relevant information for advanced users. People most often use conceptual content when they're learning. If people need certain permissions to do a task described in the article, include a permissions statement describing who can do the task in the conceptual information. How to write conceptual content -* If people need specific permissions to do what is described in the article, list those required permissions -* Describe in plain language what the feature, setting, or topic is -* Describe its purpose and why it’s useful to the reader -* Share use cases or examples -* If relevant, describe how the feature or topic works -* Highlight any details the reader needs to know to use the feature -* Include next steps for getting started with the feature (whether through further reading links or content within the article itself) + +- If people need specific permissions to do what is described in the article, list those required permissions +- Describe in plain language what the feature, setting, or topic is +- Describe its purpose and why it’s useful to the reader +- Share use cases or examples +- If relevant, describe how the feature or topic works +- Highlight any details the reader needs to know to use the feature +- Include next steps for getting started with the feature (whether through further reading links or content within the article itself) **Procedural** Procedural content helps people complete a task from start to finish while they're using npm. Procedural content gives context on how the task fits into someone's larger journey. If a procedure has prerequisites, include them before the procedural content. How to write procedural content -* Group multiple related procedures into a single article unless there's a reason not to -* Use ordered lists for procedural steps -* If a step is optional, indicate that first -* Tell readers the expected outcome of any procedures -* Include troubleshooting tips as frequently as possible + +- Group multiple related procedures into a single article unless there's a reason not to +- Use ordered lists for procedural steps +- If a step is optional, indicate that first +- Tell readers the expected outcome of any procedures +- Include troubleshooting tips as frequently as possible How to write prerequisites -* Put the prerequisites immediately before the procedure that they are relevant to. If the prerequisites are relevant to all the procedures in an article, put them after the conceptual content and before the first procedure -* You can use a list, a sentence, or a paragraph to explain prerequisites -* You can also use a separate prerequisites section when: - * The prerequisite information is very important and should not be missed - * There is more than one prerequisite + +- Put the prerequisites immediately before the procedure that they are relevant to. If the prerequisites are relevant to all the procedures in an article, put them after the conceptual content and before the first procedure +- You can use a list, a sentence, or a paragraph to explain prerequisites +- You can also use a separate prerequisites section when: + - The prerequisite information is very important and should not be missed + - There is more than one prerequisite #### Contents of an article -* Title -* Conceptual content -* Prerequisites (if applicable) -* Procedural content -* Troubleshooting (if applicable) + +- Title +- Conceptual content +- Prerequisites (if applicable) +- Procedural content +- Troubleshooting (if applicable) ## User and job stories + When planning content, you can create user and job stories to define acceptance criteria that help determine if an article is helping users accomplish their goals. ### User stories + Create user stories to better understand each audience when a feature affects more than one audience. As a [person in a particular role], I want to [perform an action or find something out], so that I can [achieve my goal of...]. ### Job stories + Job stories are narrow, granular, and useful for targeted actions or specific tasks that a single audience wants to achieve. When [there's a particular situation], I want to [perform an action or find something out], so that I can [achieve my goal of...]. ### Acceptance criteria + Acceptance criteria explain the specific ways we'll know when a user or job story is considered complete. To define acceptance criteria, identify what an article has to offer someone for them to complete their desired task and feel satisfied. ## Article template diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index af98f7f9167..4a0b7c1372d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,67 +1,48 @@ # Contributing to the npm Documentation -This is the documentation for -[https://docs.npmjs.com/](https://docs.npmjs.com/). Do you want to -contribute a change? Great! +This is the documentation for [https://docs.npmjs.com/](https://docs.npmjs.com/). Do you want to contribute a change? Great! ### Table of Contents -* [Quick start](#quick-start) -* [Running locally](#running-locally) -* [Updating content](#updating-content) -* [Navigation](#navigation) -* [CLI](#cli) -* [Deploying changes](#deploying-changes) -* [Theme](#theme) +- [Quick start](#quick-start) +- [Running locally](#running-locally) +- [Updating content](#updating-content) +- [Navigation](#navigation) +- [CLI](#cli) +- [Deploying changes](#deploying-changes) +- [Theme](#theme) ## Quick start 1. `npm install` to download Gatsby, our theme, and the dependencies 2. `npm run develop`: starts the test server at `http://localhost:8000`. -3. Update the content - it's MDX, which is like Markdown - in the `content` - directory. -4. Review your content at `http://localhost:8000`. (Gatsby watches the - filesystem and will reload your content changes immediately.) -5. Once you're happy, commit it and open a pull request at - https://github.com/npm/documentation. +3. Update the content - it's MDX, which is like Markdown - in the `content` directory. +4. Review your content at `http://localhost:8000`. (Gatsby watches the filesystem and will reload your content changes immediately.) +5. Once you're happy, commit it and open a pull request at https://github.com/npm/documentation. 6. A CI workflow run will publish your PR to a GitHub Preview Page. -7. Once the content is reviewed, merge the pull request. That will - [deploy the site](https://github.com/npm/documentation/actions/workflows/publish.yml). +7. Once the content is reviewed, merge the pull request. That will [deploy the site](https://github.com/npm/documentation/actions/workflows/publish.yml). ## Running locally -First, `npm install` the dependencies. This will install Gatsby, et al. +First, `npm install` the dependencies. This will install Gatsby, et al. -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. +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. -In order to cut down on the time it takes `npm run develop` to complete, you can -use the environment variable `GATSBY_PARTIAL_CONTENT` to only build some pages. -For example, if the only pages you need to test locally are in `/cli/v10/commands`, -then you can run the site locally with `GATSBY_PARTIAL_CONTENT=cli/v10/commands npm run develop`. +In order to cut down on the time it takes `npm run develop` to complete, you can use the environment variable `GATSBY_PARTIAL_CONTENT` to only build some pages. For example, if the only pages you need to test locally are in `/cli/v10/commands`, then you can run the site locally with `GATSBY_PARTIAL_CONTENT=cli/v10/commands npm run develop`. **For best results use Node 18 and npm 9+** -**Gatsby will watch your filesystem looking for updates.** Any content -changes you make should be reflected in the site immediately. +**Gatsby will watch your filesystem looking for updates.** Any content changes you make should be reflected in the site immediately. ## Updating content ### Documentation content -The documentation content lives in the `content` directory, and is -Markdown. (Actually, [MDX](https://mdxjs.com/), a sort of reactive -Markdown.) +The documentation content lives in the `content` directory, and is Markdown. (Actually, [MDX](https://mdxjs.com/), a sort of reactive Markdown.) ### Static content (images) -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: +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: ``` @@ -71,13 +52,9 @@ referenced as: ### "Shared" content -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. +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. -For example, `user-login` is defined with `text` and `image` -properties: +For example, `user-login` is defined with `text` and `image` properties: ```js 'user-login': { @@ -88,10 +65,7 @@ m login dialog" />) }, ``` -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: +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: ``` --- @@ -108,31 +82,19 @@ To login, <>{shared['user-login'].text} ### URLs -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. +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. -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`. +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`. -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`. +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`. -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`. +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`. -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. +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. Screen Shot 2021-03-02 at 10 06 19 -You can also use `find` from within the `content` directory. For example: +You can also use `find` from within the `content` directory. For example: ``` find . -iname creating-node-js-modules\* -print @@ -140,91 +102,52 @@ find . -iname creating-node-js-modules\* -print ### Frontmatter -The content pages should include -[frontmatter](https://jekyllrb.com/docs/front-matter/). +The content pages should include [frontmatter](https://jekyllrb.com/docs/front-matter/). -* `title`: the page's title (string); required -* `redirect_from`: any URLs on the site that will be redirected to this page (array of strings) +- `title`: the page's title (string); required +- `redirect_from`: any URLs on the site that will be redirected to this page (array of strings) ## Navigation -The site's navigation (on the left-hand sidebar of the site) is controlled -by `src/theme/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. +The site's navigation (on the left-hand sidebar of the site) is controlled by `src/theme/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. ## CLI -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. +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. **Pull requests to CLI documentation in this repository will be closed.** ### Updating CLI Content -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. +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. -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. +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. 1. Review the configuration - The `cli/releases.json` configures how the CLI documentation is - included. It is an array of documentation versions, each having - the following configuration: - - * `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. - * `branch`: The branch name for the version. This will be used to - fetch the latest version of the documentation from GitHub. - * `spec`: The registry spec for the version. This will be used - to fetch the latest version in that range from the registry. - * `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`. + The `cli/releases.json` configures how the CLI documentation is included. It is an array of documentation versions, each having the following configuration: + + - `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. + - `branch`: The branch name for the version. This will be used to fetch the latest version of the documentation from GitHub. + - `spec`: The registry spec for the version. This will be used to fetch the latest version in that range from the registry. + - `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`. 2. Fetch and import the latest content for each CLI release - 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. + 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. ## Reviewing changes -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). +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). ## Deploying changes -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: +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: 1. Make your changes locally, review them, commit them. 2. Open a pull request for review 3. Merge that pull request -On step three, your changes will be published live! 🎉 +On step three, your changes will be published live! 🎉 ## Theme -The Gatsby theme used here is located in the [`theme/`](./theme) directory. It is a variation of -[doctocat](https://github.com/primer/doctocat) with some theme changes -for npm's design language and additional components to support multiple -versions of the CLI documentation. +The Gatsby theme used here is located in the [`theme/`](./theme) directory. It is a variation of [doctocat](https://github.com/primer/doctocat) with some theme changes for npm's design language and additional components to support multiple versions of the CLI documentation. diff --git a/README.md b/README.md index bdd21df3afc..de38e2c6f09 100644 --- a/README.md +++ b/README.md @@ -2,35 +2,25 @@ [![Publish](https://github.com/npm/documentation/actions/workflows/publish.yml/badge.svg)](https://github.com/npm/documentation/actions/workflows/publish.yml) -This is the documentation for -[https://docs.npmjs.com/](https://docs.npmjs.com/). +This is the documentation for [https://docs.npmjs.com/](https://docs.npmjs.com/). -[This repository](https://github.com/npm/documentation) contains the -content for our documentation site, and the GitHub Actions workflows -that generate the site itself. +[This repository](https://github.com/npm/documentation) contains the content for our documentation site, and the GitHub Actions workflows that generate the site itself. ## Quick start 1. `npm install` to download gatsby, our theme, and the dependencies 2. `npm run develop`: starts the test server at `http://localhost:8000`. -3. Update the content - it's Mdx, which is like markdown - in the `content` - directory. -4. Review your content at `http://localhost:8000`. (Gatsby watches the - filesystem and will reload your content changes immediately.) -5. Once you're happy, commit it and open a pull request at - https://github.com/npm/documentation. +3. Update the content - it's Mdx, which is like markdown - in the `content` directory. +4. Review your content at `http://localhost:8000`. (Gatsby watches the filesystem and will reload your content changes immediately.) +5. Once you're happy, commit it and open a pull request at https://github.com/npm/documentation. 6. A CI workflow run will publish your PR to a GitHub Preview Page. -7. Once the content is reviewed, merge the pull request. That will - [deploy the site](https://github.com/npm/documentation/actions/workflows/publish.yml). +7. Once the content is reviewed, merge the pull request. That will [deploy the site](https://github.com/npm/documentation/actions/workflows/publish.yml). Do you want to know more? Check out our [contributing guide](CONTRIBUTING.md). ## Theme -The gatsby theme used here is located in the [`theme/`](./theme) directory. It is a variation of -[doctocat](https://github.com/primer/doctocat) with some theme changes -for npm's design language and additional components to support multiple -versions of the CLI documentation. +The gatsby theme used here is located in the [`theme/`](./theme) directory. It is a variation of [doctocat](https://github.com/primer/doctocat) with some theme changes for npm's design language and additional components to support multiple versions of the CLI documentation. ## License diff --git a/gatsby-node.js b/gatsby-node.js index 5a6f547cf00..244b1129bbd 100644 --- a/gatsby-node.js +++ b/gatsby-node.js @@ -1,8 +1,8 @@ const path = require('path') -exports.onCreateNode = ({ node, actions, getNode }) => { +exports.onCreateNode = ({node, actions, getNode}) => { if (node.internal.type === 'Mdx') { - const { name, relativeDirectory: dir } = getNode(node.parent) + const {name, relativeDirectory: dir} = getNode(node.parent) // These paths are unchanged: // - directory indexes @@ -21,7 +21,7 @@ exports.onCreateNode = ({ node, actions, getNode }) => { } } -exports.onCreateWebpackConfig = ({ stage, actions }) => { +exports.onCreateWebpackConfig = ({stage, actions}) => { actions.setWebpackConfig({ resolve: { alias: { diff --git a/package-lock.json b/package-lock.json index 17bb996458f..89da67fa624 100644 --- a/package-lock.json +++ b/package-lock.json @@ -19,15 +19,20 @@ "theme": "^1.0.0" }, "devDependencies": { - "@npmcli/eslint-config": "^4.0.2", + "@github/prettier-config": "^0.0.6", "@npmcli/template-oss": "4.19.0", + "@testing-library/jest-dom": "^6.1.4", + "@testing-library/react": "^9.5.0", + "babel-jest": "^29.7.0", "eslint": "^8.51.0", "eslint-plugin-github": "^4.10.1", "eslint-plugin-jsx-a11y": "^6.7.1", "eslint-plugin-primer-react": "^4.0.3", "eslint-plugin-react": "^7.33.2", "eslint-plugin-react-hooks": "^4.6.0", - "tap": "^16.3.9" + "jest": "^29.7.0", + "jest-environment-jsdom": "^29.7.0", + "prettier": "^3.0.3" }, "engines": { "node": ">=18.0.0" @@ -33702,20 +33707,7 @@ "styled-components": "^5.3.11" }, "devDependencies": { - "@github/prettier-config": "^0.0.6", - "@npmcli/template-oss": "4.19.0", - "@testing-library/jest-dom": "^6.1.4", - "@testing-library/react": "^9.5.0", - "babel-jest": "^29.7.0", - "eslint": "^8.51.0", - "eslint-plugin-github": "^4.10.1", - "eslint-plugin-jsx-a11y": "^6.7.1", - "eslint-plugin-primer-react": "^4.0.3", - "eslint-plugin-react": "^7.33.2", - "eslint-plugin-react-hooks": "^4.6.0", - "jest": "^29.7.0", - "jest-environment-jsdom": "^29.7.0", - "prettier": "^3.0.3" + "@npmcli/template-oss": "4.19.0" }, "engines": { "node": ">=18.0.0" diff --git a/package.json b/package.json index 623175bf5e7..a40f993d157 100644 --- a/package.json +++ b/package.json @@ -35,15 +35,20 @@ "theme": "^1.0.0" }, "devDependencies": { - "@npmcli/eslint-config": "^4.0.2", + "@github/prettier-config": "^0.0.6", "@npmcli/template-oss": "4.19.0", + "@testing-library/jest-dom": "^6.1.4", + "@testing-library/react": "^9.5.0", + "babel-jest": "^29.7.0", "eslint": "^8.51.0", "eslint-plugin-github": "^4.10.1", "eslint-plugin-jsx-a11y": "^6.7.1", "eslint-plugin-primer-react": "^4.0.3", "eslint-plugin-react": "^7.33.2", "eslint-plugin-react-hooks": "^4.6.0", - "tap": "^16.3.9" + "jest": "^29.7.0", + "jest-environment-jsdom": "^29.7.0", + "prettier": "^3.0.3" }, "author": "GitHub Inc.", "engines": { @@ -53,9 +58,5 @@ "//@npmcli/template-oss": "This file is partially managed by @npmcli/template-oss. Edits may be overwritten.", "version": "4.19.0", "content": "./scripts/template-oss" - }, - "eslintIgnore": [ - ".cache/", - "public/" - ] + } } diff --git a/scripts/template-oss/index.js b/scripts/template-oss/index.js index c255603456b..5e1cdbec821 100644 --- a/scripts/template-oss/index.js +++ b/scripts/template-oss/index.js @@ -11,7 +11,7 @@ module.exports = { }, rootModule: { add: { - 'package.json': { file: 'pkg.json', overwrite: false }, + 'package.json': {file: 'pkg.json', overwrite: false}, '.eslintrc.js': false, 'CODE_OF_CONDUCT.md': false, 'CONTRIBUTING.md': false, @@ -24,7 +24,7 @@ module.exports = { }, workspaceModule: { add: { - 'package.json': { file: 'pkg.json', overwrite: false }, + 'package.json': {file: 'pkg.json', overwrite: false}, '.eslintrc.js': false, }, }, @@ -35,7 +35,7 @@ module.exports = { lockfile: true, allowedPackages: ['eslint'], requiredPackages: { - devDependencies: [] + devDependencies: [], }, allowPaths: [ '/.reuse/', diff --git a/src/pages/404.js b/src/pages/404.js index ce26afdd713..501498fb24c 100644 --- a/src/pages/404.js +++ b/src/pages/404.js @@ -1,9 +1,7 @@ import React from 'react' const Page404 = () => { - return ( -

404 page

- ) + return

404 page

} export default Page404 diff --git a/src/shared.js b/src/shared.js index 234a8cffe37..e8700bfa2d3 100644 --- a/src/shared.js +++ b/src/shared.js @@ -1,215 +1,401 @@ import React from 'react' -import { Link } from '@primer/react' +import {Link} from '@primer/react' import Screenshot from 'theme/src/mdx/screenshot' import Note from 'theme/src/mdx/note' export default { /* User login */ 'user-login': { - text: (<>On the npm "Sign In" page, enter your account details and click Sign In.), - image: (), + text: ( + <> + On the npm "Sign In" page, enter your account details and click{' '} + Sign In. + + ), + image: , }, 'contact-support': { - text: (contact npm Support), + text: contact npm Support, }, 'contact-enterprise-support': { - text: (contact Enterprise Support), + text: contact Enterprise Support, }, 'profile-settings': { - text: (<>In the upper right corner of the page, click your profile picture, then click Profile Settings.), - image: (), + text: ( + <> + In the upper right corner of the page, click your profile picture, then click Profile Settings. + + ), + image: ( + + ), }, 'account-settings': { - text: (<>In the upper right corner of the page, click your profile picture, then click Account.), - image: (), + text: ( + <> + In the upper right corner of the page, click your profile picture, then click Account. + + ), + image: ( + + ), }, 'start-account-recovery': { - text: (<>On the "Request an Account Recovery" page, click Start Account Recovery.), - image: (), + text: ( + <> + On the "Request an Account Recovery" page, click Start Account Recovery. + + ), + image: ( + + ), }, 'use-recovery-code': { - text: (<>On the "Two-Factor Authentication" page, click Use a recovery code or request a reset.), - image: (), + text: ( + <> + On the "Two-Factor Authentication" page, click Use a recovery code or request a reset. + + ), + image: ( + + ), }, 'support-ticket-form': { - text: (<>In the "Open a Support Ticket" form, enter the following information:), + text: <>In the "Open a Support Ticket" form, enter the following information:, }, 'enter-email-address': { - text: (<>In the Email field, enter an email address where our support team can contact you.), + text: ( + <> + In the Email field, enter an email address where our support team can contact you. + + ), }, 'support-ticket-other': { - text: (<>If you need help with anything else, in the How can we help? section, select Other and enter more information in the Additional Details field.), + text: ( + <> + If you need help with anything else, in the How can we help? section, select{' '} + Other and enter more information in the Additional Details field. + + ), }, 'connect-to-accounts': { - text: (<> -
    -
  • If you have previously linked a GitHub account to your npm account, select Connect to GitHub. This will help our support team verify your account.
    • -
  • If you have previously linked a Twitter account to your npm account, select Connect to Twitter. This will help our support team verify your account.
    • -
- + text: ( + <> +
    +
  • + If you have previously linked a GitHub account to your npm account, select{' '} + Connect to GitHub. This will help our support team verify your account. +
    • +
  • + If you have previously linked a Twitter account to your npm account, select{' '} + Connect to Twitter. This will help our support team verify your account. +
    • +
+ ), }, 'submit-support-ticket': { - text: (<>At the bottom of the form, click Submit Support Ticket.), + text: ( + <> + At the bottom of the form, click Submit Support Ticket. + + ), }, /* Billing */ 'billing-creditcard-form': { - text: (<> - In the credit card information dialog box, enter your credit card information: - -
    -
  • Card number
    • -
  • MM / YY: the month and year of the card expiration date
    • -
  • CVC: the three-digit code on the credit card
    • -
- + text: ( + <> + In the credit card information dialog box, enter your credit card information: +
    +
  • Card number
    • +
  • MM / YY: the month and year of the card expiration date
    • +
  • CVC: the three-digit code on the credit card
    • +
+ ), - image: (), + image: , }, 'billing-downgrade-selection': { - text: (<>Under "change plan", click Downgrade Plan.), - image: (), + text: ( + <> + Under "change plan", click Downgrade Plan. + + ), + image: , }, 'billing-downgrade-confirm': { - text: (<>Under "Are you sure?", click Downgrade to a free account.), - image: (), + text: ( + <> + Under "Are you sure?", click Downgrade to a free account. + + ), + image: ( + + ), }, 'billing-download': { - text: (<>To download a single receipt, find the row of the receipt you want to download, then click the PDF icon on the right side of the row.), - image: (), + text: ( + <> + To download a single receipt, find the row of the receipt you want to download, then click the PDF icon on the + right side of the row. + + ), + image: , }, 'billing-download-checked': { - text: (<>To download multiple receipts, first select the receipts that you wish to download by selecting the box next to the date. To select all receipts, select the checkbox next to the "Date" header. Then click Download Checked.), - image: (), + text: ( + <> + To download multiple receipts, first select the receipts that you wish to download by selecting the box next to + the date. To select all receipts, select the checkbox next to the "Date" header. Then click{' '} + Download Checked. + + ), + image: , }, 'billing-email': { - text: (<>To email a single receipt, find the row of the receipt you want to download, then, on the right side of the row, click the email icon.), - image: (), + text: ( + <> + To email a single receipt, find the row of the receipt you want to download, then, on the right side of the row, + click the email icon. + + ), + image: , }, 'billing-email-checked': { - text: (<>To email multiple receipts, first select the receipts that you wish to download by selecting the box next to the date. To select all receipts, select the checkbox next to the "Date" header. Then click Email Checked.), - image: (), + text: ( + <> + To email multiple receipts, first select the receipts that you wish to download by selecting the box next to the + date. To select all receipts, select the checkbox next to the "Date" header. Then click{' '} + Email Checked. + + ), + image: , }, 'billing-email-receipt': { - text: (<>In the Email Receipt dialog box, fill in the "From", "To", and "Message" fields.), - image: (), + text: <>In the Email Receipt dialog box, fill in the "From", "To", and "Message" fields., + image: , }, 'billing-extra-info': { - text: (<>To add a business name, VAT number, address of record, or other information to your receipts, in the "Extra Billing Information" text box, type the information.), - image: (), + text: ( + <> + To add a business name, VAT number, address of record, or other information to your receipts, in the "Extra + Billing Information" text box, type the information. + + ), + image: , }, 'billing-extra-receipt-email': { - text: (<>To update the email address used for receipts, beside "Send my receipts", select the checkbox and type the email address that should receive billing receipts.), - image: (), + text: ( + <> + To update the email address used for receipts, beside "Send my receipts", select the checkbox and type the email + address that should receive billing receipts. + + ), + image: ( + + ), }, 'billing-extra-save': { - text: (<>Click Save.), - image: (), + text: ( + <> + Click Save. + + ), + image: , }, 'billing-form': { - text: (<> - In the billing information dialog box, enter your billing information: - -
    -
  • Email: the email address used for the billing contact
    • -
  • Name: the name on the credit card used to pay
    • -
  • Street, City, ZIP Code, Country: the billing address associated with the credit card
    • -
- + text: ( + <> + In the billing information dialog box, enter your billing information: +
    +
  • Email: the email address used for the billing contact
    • +
  • Name: the name on the credit card used to pay
    • +
  • Street, City, ZIP Code, Country: the billing address associated with the credit card
    • +
+ ), - image: (), + image: , }, 'billing-history': { - text: (<>On the Billing Information page, under "monthly bill", select View Billing History.), - image: (), + text: ( + <> + On the Billing Information page, under "monthly bill", select View Billing History. + + ), + image: , }, 'billing-info': { - text: (<>In the upper right corner of the page, click your profile picture, then select Billing Info.), - image: (), + text: ( + <> + In the upper right corner of the page, click your profile picture, then select Billing Info. + + ), + image: , }, 'billing-receipt-settings': { - text: (<>At the bottom of the Billing History dialog box, click "Receipt Settings".), - image: (), + text: <>At the bottom of the Billing History dialog box, click "Receipt Settings"., + image: , }, 'billing-update-card': { - text: (<>Click Update Card.), - image: (), + text: ( + <> + Click Update Card. + + ), + image: ( + + ), }, 'billing-view': { - text: (<>To view a single receipt, find the row of the receipt you want to view, then, on the right side of the row, click the view icon.), - image: (), + text: ( + <> + To view a single receipt, find the row of the receipt you want to view, then, on the right side of the row, + click the view icon. + + ), + image: , }, 'grace-period': { text: 'nine days', }, 'payment-info-button': { - text: (<>Click Payment Info.), - image: (), + text: ( + <> + Click Payment Info. + + ), + image: , }, 'payment-remember-me': { - text: (<>To save your credit card information for other payments on npm, select "Remember me".), - image: (), + text: <>To save your credit card information for other payments on npm, select "Remember me"., + image: , }, 'payment-info': { - text: (<>Under "monthly bill", click Edit Payment Info.), - image: (), + text: ( + <> + Under "monthly bill", click Edit Payment Info. + + ), + image: , }, 'billing-price-teams': { - text: (<>$7 per member per month), + text: <>$7 per member per month, }, 'billing-organization-plans': { - image: (), + image: ( + + ), }, /* Package management */ 'organization-package-public': { - image: (), + image: , }, 'organization-package-private': { - image: (), + image: ( + + ), }, /* Organizations */ 'organization-create': { - text: (<>In the upper right corner of the page, click your profile picture, then click Add an Organization.), - image: (), + text: ( + <> + In the upper right corner of the page, click your profile picture, then click{' '} + Add an Organization. + + ), + image: ( + + ), }, 'organization-selection': { - text: (<>In the left sidebar, click the name of your organization.), - image: (), + text: <>In the left sidebar, click the name of your organization., + image: , }, 'organization-billing-tab': { - text: (<>On the organization settings page, click Billing.), - image: (), + text: ( + <> + On the organization settings page, click Billing. + + ), + image: , }, 'organization-members-tab': { - text: (<>On the organization settings page, click Members.), - image: (), + text: ( + <> + On the organization settings page, click Members. + + ), + image: , }, 'organization-teams-tab': { - text: (<>On the organization settings page, click Teams.), - image: (), + text: ( + <> + On the organization settings page, click Teams. + + ), + image: , }, /* Enterprise */ 'enterprise-admin-panel': { - text: (<>In the upper right corner of the page, click your profile picture, then click Site Administration.), - image: (), + text: ( + <> + In the upper right corner of the page, click your profile picture, then click{' '} + Site Administration. + + ), + image: , }, 'enterprise-admin-panel-settings': { - image: (), + image: ( + + ), }, 'enterprise-choose-security-policy': { - image: (), + image: ( + + ), }, 'enterprise-custom-blocking-message': { - image: (), + image: ( + + ), }, 'enterprise-instance-login': { - text: (<>Log in to your Enterprise instance.), + text: <>Log in to your Enterprise instance., }, 'enterprise-migration-requirements': { - text: (<>Note: Using pneumatic-tubes for migration requires
  • Node 8+
  • npm 5+ (to install or upgrade, run npm install npm@latest -g)
), + text: ( + + <> + Note: Using{' '} + + pneumatic-tubes + {' '} + for migration requires{' '} +
    +
  • Node 8+
    • +
  • + npm 5+ (to install or upgrade, run npm install npm@latest -g) +
    • +
+ + + ), }, } diff --git a/theme/.gitignore b/theme/.gitignore index 6954e80d139..921c7946a40 100644 --- a/theme/.gitignore +++ b/theme/.gitignore @@ -8,6 +8,7 @@ !/.eslintrc.js !/.eslintrc.local.* !/.gitignore +!/.prettierIgnore !/bin/ !/CHANGELOG* !/docs/ diff --git a/theme/package.json b/theme/package.json index 443a151a9ff..c5d05f56e75 100644 --- a/theme/package.json +++ b/theme/package.json @@ -9,7 +9,6 @@ "private": true, "main": "index.js", "license": "MIT", - "prettier": "@github/prettier-config", "scripts": { "test": "jest", "lint": "eslint \"**/*.js\"",