3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-08-02 16:29:47 +02:00
Code Issues Projects Releases Packages Wiki Activity

feat(v2): add trailingSlash config option (#4908)

Browse source 
* POC: add trailingSlash option

* integrate the preferFoldersOutput option of fork @slorber/static-site-generator-webpack-plugin

* Fix broken links when using trailing slash => using md links is more reliable

* fix TS issue

* minor polish

* fix doc page being sensitive to trailing slashes

* Add tests for applyTrailingSlash

* rename test files

* extract and test applyRouteTrailingSlash

* update snapshot

* add trailing slash config to serve command

* fix getSidebar() => still sensitive to trailing slash setting

* never apply trailing slash to an anchor link

* Add documentation for trailingSlash setting
This commit is contained in:
Sébastien Lorber 2021-06-09 19:59:39 +02:00 • committed by GitHub
parent 77264f1eb0
commit df8a900f9c
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
28 changed files with 469 additions and 67 deletions
Download patch file Download diff file Expand all files Collapse all files

65
website/docs/deployment.mdx
View file

@ -9,32 +9,60 @@ To build the static files of your website for production, run:
npm run build
```
Once it finishes, the static files will be generated within the `build/` directory.
Once it finishes, the static files will be generated within the `build` directory.
You can deploy your site to static site hosting services such as [Vercel](https://vercel.com/), [GitHub Pages](https://pages.github.com/), [Netlify](https://www.netlify.com/), [Render](https://render.com/docs/static-sites), and [Surge](https://surge.sh/help/getting-started-with-surge). Docusaurus sites are statically rendered so they work without JavaScript too!
:::note
## Testing Build Local {#testing-build-local}
The only responsibility of Docusaurus is to build your site and emit static files in `build`.
It is important to test build before deploying to a production. Docusaurus includes a [`docusaurus serve`](cli.md#docusaurus-serve) command to test build locally.
It is now up to you to choose how to host those static files.
:::
You can deploy your site to static site hosting services such as [Vercel](https://vercel.com/), [GitHub Pages](https://pages.github.com/), [Netlify](https://www.netlify.com/), [Render](https://render.com/docs/static-sites), [Surge](https://surge.sh/help/getting-started-with-surge)...
A Docusaurus site is statically rendered, and it can generally work without JavaScript!
## Testing your Build Locally {#testing-build-locally}
It is important to test your build locally before deploying to production.
Docusaurus includes a [`docusaurus serve`](cli.md#docusaurus-serve) command for that:
```bash npm2yarn
npm run serve
```
## Self Hosting {#self-hosting}
## Trailing slash configuration {#trailing-slashes}
:::warning
Docusaurus has a [`trailingSlash` config](./api/docusaurus.config.js.md#trailing-slash), to allow customizing URLs/links and emitted filename patterns.
It is not the most performant solution
The default value generally works fine.
Unfortunately, each static hosting provider has a **different behavior**, and deploying the exact same site to various hosts can lead to distinct results.
Depending on your host, it can be useful to change this config.
:::tip
Use [slorber/trailing-slash-guide](https://github.com/slorber/trailing-slash-guide) to understand better the behavior of your host and configure `trailingSlash` appropriately.
:::
Docusaurus can be self hosted using [`docusaurus serve`](cli.md#docusaurus-serve). Change port using `--port` and `--host` to change host.
## Self-Hosting {#self-hosting}
Docusaurus can be self-hosted using [`docusaurus serve`](cli.md#docusaurus-serve). Change port using `--port` and `--host` to change host.
```bash npm2yarn
npm run serve -- --build --port 80 --host 0.0.0.0
```
:::warning
It is not the best option, compared to a static hosting provider / CDN.
:::
## Deploying to GitHub Pages {#deploying-to-github-pages}
Docusaurus provides an easy way to publish to [GitHub Pages](https://pages.github.com/). Which is hosting that comes for free with every GitHub repository.
@ -54,10 +82,18 @@ First, modify your `docusaurus.config.js` and add the required params:
In case you want to use your custom domain for GitHub Pages, create a `CNAME` file in the `static` directory. Anything within the `static` directory will be copied to the root of the `build` directory for deployment.
When using a custom domain, you should be able to move back from `baseUrl: '/projectName/'` to `baseUrl: '/'`
You may refer to GitHub Pages' documentation [User, Organization, and Project Pages](https://help.github.com/en/articles/user-organization-and-project-pages) for more details.
:::
:::caution
GitHub Pages adds a trailing slash to Docusaurus URLs by default. Adjusting the `trailingSlash` setting can be useful.
:::
Example:
```jsx {3-6} title="docusaurus.config.js"
@ -67,6 +103,7 @@ module.exports = {
baseUrl: '/',
projectName: 'endiliey.github.io',
organizationName: 'endiliey',
trailingSlash: false,
// ...
};
```
@ -337,9 +374,17 @@ If you did not configure these build options, you may still go to "Site settings
Once properly configured with the above options, your site should deploy and automatically redeploy upon merging to your deploy branch, which defaults to `master`.
:::important
:::warning
Make sure to disable Netlify setting `Pretty URLs` to prevent lowercased URLs, unnecessary redirects and 404 errors.
By default, Netlify adds trailing slashes to Docusaurus URLs.
It is recommended to disable the Netlify setting `Post Processing > Asset Optimization > Pretty Urls` to prevent lowercased URLs, unnecessary redirects and 404 errors.
**Be very careful**: the `Disable asset optimization` global checkbox is broken and does not really disable the `Pretty URLs` setting in practice. Please make sure to **uncheck it independently**.
If you want to keep the `Pretty Urls` Netlify setting on, adjust the `trailingSlash` Docusaurus config appropriately.
Refer to [slorber/trailing-slash-guide](https://github.com/slorber/trailing-slash-guide) for more information.
:::