docusaurus/admin/publish.md

Publishing Instructions

Docusaurus is published as an npm package that can be installed via npm or yarn. Get access from the Docusaurus npm admins (@yangshun/@JoelMarcey).

Log in to npm

Publishing will only work if you are logged into npm with an account with publishing rights to the package.

If you are not currently logged into npm on your CLI, do the following:

1. npm login
2. Enter username, password and associated email address
3. Make sure you have 2FA enabled on your account (preferably just for authorization)

Docusaurus 2

If you're publishing new v2 versions, 2FA might get in the way as the pin might expire during the publishing as there are over 10 packages to publish. You're encouraged not to use the "Authorization and Publishing" 2FA option.

0. Build skeleton website with new version (Docker required)

To make sure that all packages will work correctly when they are published, you can build them locally and use them to run the skeleton website:

yarn test:build:v2

This command will build all the packages that it will publish to the running private npm proxy registry, and then initialize a new website in the test-website directory. Now you can start the dev server and/or make a production built.

cd test-website
yarn start
yarn build # after manual testing in browser

If there are no errors, you can start preparing for the new release.

1. Update the v2 changelog

Generate a GitHub auth token by going to https://github.com/settings/tokens. Save the token somewhere for future reference.

Before running the command below, get all tags from the original repository by running git fetch --tags.

GITHUB_AUTH=<Your GitHub auth token> yarn changelog

Copy the generated contents and paste them in CHANGELOG-2.x.md.

2. Cut a new version of the docs

cd website
yarn run docusaurus docs:version 2.0.0-alpha.41

Test running the website with the new version locally.

3. Create a Pull Request

Make a commit and create a pull request with the changes and get it merged. An example PR would be #2287. Make sure the preview loads fine and is showing the new version.

4. Publish to npm

As we have a monorepo structure, we use lerna publish to publish the new version of packages to npm in one shot.

First, be sure to run the command below to verify that you have access to all the necessary repositories.

npm access ls-packages

The list of packages which need access (as of April 2020)

{
  "@docusaurus/plugin-sitemap": "read-write",
  "@docusaurus/mdx-loader": "read-write",
  "@docusaurus/utils": "read-write",
  "@docusaurus/core": "read-write",
  "@docusaurus/plugin-content-blog": "read-write",
  "@docusaurus/plugin-content-docs": "read-write",
  "@docusaurus/plugin-content-pages": "read-write",
  "@docusaurus/preset-classic": "read-write",
  "@docusaurus/theme-search-algolia": "read-write",
  "@docusaurus/theme-classic": "read-write",
  "@docusaurus/theme-live-codeblock": "read-write",
  "@docusaurus/plugin-google-analytics": "read-write",
  "@docusaurus/plugin-google-gtag": "read-write",
  "@docusaurus/init": "read-write",
  "@docusaurus/plugin-content-docs-legacy": "read-write",
  "@docusaurus/plugin-ideal-image": "read-write",
  "@docusaurus/types": "read-write",
  "docusaurus": "read-write",
  "docusaurus-init": "read-write",
  "stylelint-copyright": "read-write"
}

If all accesses are available, build all the necessary packages with yarn tsc, and then you can run the command to release a new version:

yarn lerna publish 2.0.0-alpha.41 --dist-tag next

Note: The v1 packages will also be modified because it's part of the monorepo. It is not ideal but we will live with it for now.

This command does a few things:

• Modifies the versions of all the package.json in the repository to be 2.0.0-alpha.41 and creates a commit
• Creates a new Git tag v2.0.0-alpha.41
• Pushes the new commit and Git tag to master

You should receive many emails notifying you that a new version of the packages has been published.

5. Create a release on GitHub

• Go to https://github.com/facebook/docusaurus/releases/new
• Under the "Tag version" field, look for the newly-created tag, which is v2.0.0-alpha.41 in this case
• Paste the CHANGELOG changes in the textarea below
• Hit the green "Publish release" button
• Profit! 💰

6. Notify people about new release (optional but desirable)

After new release, it was cool to notify our users about this in the Dicsord chat (docusaurus-users channel) and write summaries in Twiiter using the following templates.

For Discord:

A new version %VER% is available now! 🎉
See release notes at the following link https://github.com/facebook/docusaurus/releases/tag/%VER%

For Twitter:

💥 A new version %VER% is available now! 💥

###
LIST HERE MAJOR FEATURES, SEE EXAMPLES BELOW

- Dropdown nav 🔗
- New code blocks features 🖥️
- Draft blog posts ✏️
- Announcement bar 📢

..

NOTE: most likely this last item will be relevant for each new release, so do not forget include it
- Many documentation improvements and bug fixes! 🐛
###

https://github.com/facebook/docusaurus/releases/tag/%VER%

Docusaurus 1

1. Bump version number in package.json.
2. Update the changelog, including at the reference links at the bottom.
3. Do this always, but particularly important if there were any package.json changes in this release:
   1. If there is no node_modules directory in you local Docusaurus version, run yarn install and npm install.
   2. Run yarn upgrade to update yarn.lock and npm update to update package-lock.json.
4. From the website-1.x directory, run npm run docusaurus-version x.x.x, where x.x.x is the same version number you updated to in package.json.
5. Test your PR locally on a project that was created via these instructions.
6. Submit your PR
7. When your PR is merged, rebase to get the PR commit locally
8. Run npm publish
9. Tag the commit with the new version prefixed with a v (e.g. v1.19.0) and push the tag to master
10. Go to https://github.com/facebook/docusaurus/releases/new
11. Under the "Tag version" field, look for the newly-created tag
12. Paste the CHANGELOG changes in the textarea below
13. Hit the green "Publish release" button
14. Profit! 💰

What version should you use?

The version number should generally increase by some factor than the current one. You can check current version by looking in package.json.

{
  "name": "docusaurus",
  "version": "1.0.0-alpha.41",
  "repository": {
    "type": "git",
    "url": "https://github.com/facebook/docusaurus.git"
  }
  ...
}

For the above example, you may want to bump the version to 1.0.0-alpha.42 or 1.0.0-beta.1 or 1.0.1.

You can also see the full list of all published versions with npm show docusaurus versions --json.