mirror of
https://github.com/facebook/docusaurus.git
synced 2025-08-03 16:59:06 +02:00
refactor: rename Git master branch to main (#5345)
* Prepare to renaming master branch to main * Update CONTRIBUTING.md * Update packages/docusaurus-migrate/src/__tests__/__fixtures__/missing_version_website/website/package.json * Update packages/docusaurus-migrate/src/__tests__/__fixtures__/complex_website/website/package.json * Update packages/docusaurus-migrate/src/__tests__/__fixtures__/simple_website/website/package.json * missing master -> main replaces * useless char * For GH Pages org deploy, DEPLOYMENT_BRANCH env is now required * fix versioning page * fix vercel links * update deployment.mdx Co-authored-by: Sébastien Lorber <slorber@users.noreply.github.com> Co-authored-by: slorber <lorber.sebastien@gmail.com>
This commit is contained in:
Paul O’Shannessy
GitHub
parent
33a85c71aa
commit
8341527fc9
77 changed files with 230 additions and 206 deletions
|
|
@ -34,12 +34,12 @@ module.exports = {
|
|||
* Base url to edit your site.
|
||||
* Docusaurus will compute the final editUrl with "editUrl + relativeDocPath"
|
||||
*/
|
||||
editUrl: 'https://github.com/facebook/docusaurus/edit/master/website/',
|
||||
editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
|
||||
/**
|
||||
* For advanced cases, compute the edit url for each Markdown file yourself.
|
||||
*/
|
||||
editUrl: ({locale, blogDirPath, blogPath, permalink}) => {
|
||||
return `https://github.com/facebook/docusaurus/edit/master/website/${blogDirPath}/${blogPath}`;
|
||||
return `https://github.com/facebook/docusaurus/edit/main/website/${blogDirPath}/${blogPath}`;
|
||||
},
|
||||
/**
|
||||
* Useful if you commit localized files to git.
|
||||
|
|
|
|||
|
|
@ -35,7 +35,7 @@ module.exports = {
|
|||
* Docusaurus will compute the final editUrl with "editUrl + relativeDocPath"
|
||||
* Omitting this variable entirely will disable edit links.
|
||||
*/
|
||||
editUrl: 'https://github.com/facebook/docusaurus/edit/master/website/',
|
||||
editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
|
||||
/**
|
||||
* For advanced cases, compute the edit url for each Markdown file yourself.
|
||||
*/
|
||||
|
|
@ -46,7 +46,7 @@ module.exports = {
|
|||
docPath,
|
||||
permalink,
|
||||
}) {
|
||||
return `https://github.com/facebook/docusaurus/edit/master/website/${versionDocsDirPath}/${docPath}`;
|
||||
return `https://github.com/facebook/docusaurus/edit/main/website/${versionDocsDirPath}/${docPath}`;
|
||||
},
|
||||
/**
|
||||
* Useful if you commit localized files to git.
|
||||
|
|
@ -191,7 +191,7 @@ module.exports = {
|
|||
*/
|
||||
versions: {
|
||||
/*
|
||||
Example configuration:
|
||||
Example configuration:
|
||||
current: {
|
||||
label: 'Android SDK v2.0.0 (WIP)',
|
||||
path: 'android-2.0.0',
|
||||
|
|
@ -244,7 +244,7 @@ hide_table_of_contents: false
|
|||
sidebar_label: Markdown
|
||||
sidebar_position: 3
|
||||
pagination_label: Markdown features
|
||||
custom_edit_url: https://github.com/facebook/docusaurus/edit/master/docs/api-doc-markdown.md
|
||||
custom_edit_url: https://github.com/facebook/docusaurus/edit/main/docs/api-doc-markdown.md
|
||||
description: How do I find you when I cannot solve this problem
|
||||
keywords:
|
||||
- docs
|
||||
|
|
|
|||
|
|
@ -127,8 +127,8 @@ Optional parameters, also set as environment variables:
|
|||
| Name | Description |
|
||||
| --- | --- |
|
||||
| `USE_SSH` | Set to `true` to use SSH instead of the default HTTPS for the connection to the GitHub repo. |
|
||||
| `DEPLOYMENT_BRANCH` | The branch that the website will be deployed to, defaults to `gh-pages` for normal repos and `master` for repository names ending in `github.io`. |
|
||||
| `CURRENT_BRANCH` | The branch that contains the latest docs changes that will be deployed. Usually, the branch will be `master`, but it could be any branch (default or otherwise) except for `gh-pages`. If nothing is set for this variable, then the current branch will be used. |
|
||||
| `DEPLOYMENT_BRANCH` | The branch that the website will be deployed to, defaults to `gh-pages`. For GitHub Pages Organization repos (`config.projectName` ending in `github.io`), this env variable is required. |
|
||||
| `CURRENT_BRANCH` | The branch that contains the latest docs changes that will be deployed. Usually, the branch will be `main`, but it could be any branch (default or otherwise) except for `gh-pages`. If nothing is set for this variable, then the current branch will be used. |
|
||||
| `GIT_PASS` | Password (or token) of the `git` user (specified by `GIT_USER`). For example, to facilitate non-interactive deployment (e.g. continuous deployment) |
|
||||
|
||||
GitHub enterprise installations should work in the same manner as github.com; you only need to set the organization's GitHub Enterprise host as an environment variable:
|
||||
|
|
@ -269,7 +269,7 @@ node_js:
|
|||
- '10'
|
||||
branches:
|
||||
only:
|
||||
- master
|
||||
- main
|
||||
cache:
|
||||
yarn: true
|
||||
script:
|
||||
|
|
@ -279,7 +279,7 @@ script:
|
|||
- yarn && GIT_USER="${GH_NAME}" yarn deploy
|
||||
```
|
||||
|
||||
Now, whenever a new commit lands in `master`, Travis CI will run your suite of tests and if everything passes, your website will be deployed via the `yarn deploy` script.
|
||||
Now, whenever a new commit lands in `main`, Travis CI will run your suite of tests and if everything passes, your website will be deployed via the `yarn deploy` script.
|
||||
|
||||
### Triggering deployment with Buddy {#triggering-deployment-with-buddy}
|
||||
|
||||
|
|
@ -312,7 +312,7 @@ After creating this simple pipeline, each new commit pushed to the branch you se
|
|||
|
||||
```yaml title="azure-pipelines.yml"
|
||||
trigger:
|
||||
- master
|
||||
- main
|
||||
|
||||
pool:
|
||||
vmImage: 'ubuntu-latest'
|
||||
|
|
@ -329,7 +329,7 @@ steps:
|
|||
- script: |
|
||||
git config --global user.name "${GH_NAME}"
|
||||
git config --global user.email "${GH_EMAIL}"
|
||||
git checkout -b master
|
||||
git checkout -b main
|
||||
echo "machine github.com login ${GH_NAME} password ${GH_TOKEN}" > ~/.netrc
|
||||
yarn && GIT_USER="${GH_NAME}" yarn deploy
|
||||
env:
|
||||
|
|
@ -394,7 +394,7 @@ While you set up the site, specify the build commands and directories as follows
|
|||
|
||||
If you did not configure these build options, you may still go to "Site settings" -> "Build and deploy" after your site is created.
|
||||
|
||||
Once properly configured with the above options, your site should deploy and automatically redeploy upon merging to your deploy branch, which defaults to `master`.
|
||||
Once properly configured with the above options, your site should deploy and automatically redeploy upon merging to your deploy branch, which defaults to `main`.
|
||||
|
||||
:::warning
|
||||
|
||||
|
|
|
|||
|
|
@ -20,8 +20,8 @@ To better understand how versioning works and see if it suits your needs, you ca
|
|||
|
||||
```shell
|
||||
website
|
||||
├── sidebars.json # sidebar for master (next) version
|
||||
├── docs # docs directory for master (next) version
|
||||
├── sidebars.json # sidebar for the current docs version
|
||||
├── docs # docs directory for the current docs version
|
||||
│ ├── foo
|
||||
│ │ └── bar.md # https://mysite.com/docs/next/foo/bar
|
||||
│ └── hello.md # https://mysite.com/docs/next/hello
|
||||
|
|
@ -48,11 +48,19 @@ The table below explains how a versioned file maps to its version and the genera
|
|||
| --------------------------------------- | -------------- | ----------------- |
|
||||
| `versioned_docs/version-1.0.0/hello.md` | 1.0.0 | /docs/1.0.0/hello |
|
||||
| `versioned_docs/version-1.1.0/hello.md` | 1.1.0 (latest) | /docs/hello |
|
||||
| `docs/hello.md` | next | /docs/next/hello |
|
||||
| `docs/hello.md` | current | /docs/next/hello |
|
||||
|
||||
:::tip
|
||||
|
||||
The files in the `docs` directory belong to the `current` docs version.
|
||||
|
||||
By default, the `current` docs version is labelled as `Next` and hosted under `/docs/next/*`, but is entirely configurable to fit your project's release lifecycle.
|
||||
|
||||
:::
|
||||
|
||||
### Tagging a new version {#tagging-a-new-version}
|
||||
|
||||
1. First, make sure your content in the `docs` directory is ready to be frozen as a version. A version always should be based from master.
|
||||
1. First, make sure the current docs version (the `docs` directory) is ready to be frozen.
|
||||
1. Enter a new version number.
|
||||
|
||||
```bash npm2yarn
|
||||
|
|
@ -72,7 +80,7 @@ When tagging a new version, the document versioning mechanism will:
|
|||
1. Place the new file into the corresponding version folder.
|
||||
1. Include the reference for the new file into the corresponding sidebar file, according to version number.
|
||||
|
||||
**Master docs**
|
||||
**Current version docs**
|
||||
|
||||
```shell
|
||||
# The new file.
|
||||
|
|
@ -82,7 +90,7 @@ docs/new.md
|
|||
sidebar.js
|
||||
```
|
||||
|
||||
**Older docs**
|
||||
**Older version docs**
|
||||
|
||||
```shell
|
||||
# The new file.
|
||||
|
|
|
|||
|
|
@ -484,7 +484,7 @@ module.exports = {
|
|||
return `https://crowdin.com/project/docusaurus-v2/${locale}`;
|
||||
}
|
||||
// Link to Github for English docs
|
||||
return `https://github.com/facebook/docusaurus/edit/master/website/${versionDocsDirPath}/${docPath}`;
|
||||
return `https://github.com/facebook/docusaurus/edit/main/website/${versionDocsDirPath}/${docPath}`;
|
||||
},
|
||||
// highlight-end
|
||||
},
|
||||
|
|
@ -494,7 +494,7 @@ module.exports = {
|
|||
if (locale !== DefaultLocale) {
|
||||
return `https://crowdin.com/project/docusaurus-v2/${locale}`;
|
||||
}
|
||||
return `https://github.com/facebook/docusaurus/edit/master/website/${blogDirPath}/${blogPath}`;
|
||||
return `https://github.com/facebook/docusaurus/edit/main/website/${blogDirPath}/${blogPath}`;
|
||||
},
|
||||
// highlight-start
|
||||
},
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ The goals of the Docusaurus i18n system are:
|
|||
- **Easy to use with [Crowdin](https://crowdin.com/)**: multiple Docusaurus v1 sites use Crowdin, and should be able to migrate to v2
|
||||
- **Good SEO defaults**: we set useful SEO headers like [`hreflang`](https://developers.google.com/search/docs/advanced/crawling/localized-versions) for you
|
||||
- **RTL support**: locales reading right-to-left (Arabic, Hebrew, etc.) are supported and easy to implement
|
||||
- **Default translations**: classic theme labels are translated for you in [many languages](https://github.com/facebook/docusaurus/tree/master/packages/docusaurus-theme-classic/codeTranslations)
|
||||
- **Default translations**: classic theme labels are translated for you in [many languages](https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-theme-classic/codeTranslations)
|
||||
|
||||
### i18n non-goals {#i18n-non-goals}
|
||||
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ This tutorial will walk you through the basis of the **Docusaurus i18n system**.
|
|||
|
||||
We will add **French** translations to a **newly initialized English Docusaurus website**.
|
||||
|
||||
Initialize a new site with `npx @docusaurus/init@latest init website classic` (like [this one](https://github.com/facebook/docusaurus/tree/master/examples/classic)).
|
||||
Initialize a new site with `npx @docusaurus/init@latest init website classic` (like [this one](https://github.com/facebook/docusaurus/tree/main/examples/classic)).
|
||||
|
||||
## Configure your site {#configure-your-site}
|
||||
|
||||
|
|
@ -64,7 +64,7 @@ We haven't provided any translation, and the site is **mostly untranslated**.
|
|||
|
||||
Docusaurus provides **default translations** for generic theme labels, such as "Next" and "Previous" for the pagination.
|
||||
|
||||
Please help us complete those **[default translations](https://github.com/facebook/docusaurus/tree/master/packages/docusaurus-theme-classic/codeTranslations)**.
|
||||
Please help us complete those **[default translations](https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-theme-classic/codeTranslations)**.
|
||||
|
||||
:::
|
||||
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ id: installation
|
|||
title: Installation
|
||||
---
|
||||
|
||||
Docusaurus is essentially a set of npm [packages](https://github.com/facebook/docusaurus/tree/master/packages).
|
||||
Docusaurus is essentially a set of npm [packages](https://github.com/facebook/docusaurus/tree/main/packages).
|
||||
|
||||
:::tip
|
||||
|
||||
|
|
|
|||
|
|
@ -122,7 +122,7 @@ yarn-error.log*
|
|||
|
||||
### `README` {#readme}
|
||||
|
||||
The D1 website may have an existing README file. You can modify it to reflect the D2 changes, or copy the default [Docusaurus v2 README](https://github.com/facebook/docusaurus/blob/master/packages/docusaurus-init/templates/classic/README.md).
|
||||
The D1 website may have an existing README file. You can modify it to reflect the D2 changes, or copy the default [Docusaurus v2 README](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-init/templates/classic/README.md).
|
||||
|
||||
## Site configurations {#site-configurations}
|
||||
|
||||
|
|
@ -154,7 +154,7 @@ module.exports = {
|
|||
};
|
||||
```
|
||||
|
||||
We recommend moving the `docs` folder into the `website` folder and that is also the default directory structure in v2. [Now](https://zeit.co/now) supports [Docusaurus project deployments out-of-the-box](https://github.com/zeit/now-examples/tree/master/docusaurus) if the `docs` directory is within the `website`. It is also generally better for the docs to be within the website so that the docs and the rest of the website code are co-located within one `website` directory.
|
||||
We recommend moving the `docs` folder into the `website` folder and that is also the default directory structure in v2. [Vercel](https://vercel.com) supports [Docusaurus project deployments out-of-the-box](https://github.com/vercel/vercel/tree/main/examples/docusaurus) if the `docs` directory is within the `website`. It is also generally better for the docs to be within the website so that the docs and the rest of the website code are co-located within one `website` directory.
|
||||
|
||||
If you are migrating your Docusaurus v1 website, and there are pending documentation pull requests, you can temporarily keep the `/docs` folder to its original place, to avoid producing conflicts.
|
||||
|
||||
|
|
@ -342,7 +342,7 @@ module.exports = {
|
|||
// Equivalent to `customDocsPath`.
|
||||
path: 'docs',
|
||||
// Equivalent to `editUrl` but should point to `website` dir instead of `website/docs`.
|
||||
editUrl: 'https://github.com/facebook/docusaurus/edit/master/website',
|
||||
editUrl: 'https://github.com/facebook/docusaurus/edit/main/website',
|
||||
// Equivalent to `docsUrl`.
|
||||
routeBasePath: 'docs',
|
||||
// Remark and Rehype plugins passed to MDX. Replaces `markdownOptions` and `markdownPlugins`.
|
||||
|
|
@ -551,8 +551,8 @@ export default MyPage;
|
|||
|
||||
The following code could be helpful for migration of various pages:
|
||||
|
||||
- Index page - [Flux](https://github.com/facebook/flux/blob/master/website/src/pages/index.js/) (recommended), [Docusaurus 2](https://github.com/facebook/docusaurus/blob/master/website/src/pages/index.js/), [Hermes](https://github.com/facebook/hermes/blob/master/website/src/pages/index.js/)
|
||||
- Help/Support page - [Docusaurus 2](https://github.com/facebook/docusaurus/blob/master/website/src/pages/help.js/), [Flux](http://facebook.github.io/flux/support)
|
||||
- Index page - [Flux](https://github.com/facebook/flux/blob/master/website/src/pages/index.js/) (recommended), [Docusaurus 2](https://github.com/facebook/docusaurus/blob/main/website/src/pages/index.js/), [Hermes](https://github.com/facebook/hermes/blob/main/website/src/pages/index.js/)
|
||||
- Help/Support page - [Docusaurus 2](https://github.com/facebook/docusaurus/blob/main/website/src/pages/help.js/), [Flux](http://facebook.github.io/flux/support)
|
||||
|
||||
## Content {#content}
|
||||
|
||||
|
|
|
|||
|
|
@ -158,7 +158,7 @@ This workflow has not been tested in practice, please report us how good it is.
|
|||
|
||||
This way, you wouldn't need to create a new Crowdin project, transfer the translation memory, apply pre-translations, and try to fix the pre-translations errors.
|
||||
|
||||
You could create a Crowdin branch for Docusaurus v2, where you upload the v2 sources, and merge the Crowdin branch to master once ready.
|
||||
You could create a Crowdin branch for Docusaurus v2, where you upload the v2 sources, and merge the Crowdin branch to main once ready.
|
||||
|
||||
### Use Git instead of Crowdin {#use-git-instead-of-crowdin}
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue