mirror of
https://github.com/facebook/docusaurus.git
synced 2025-08-02 08:19:07 +02:00
feat(v2): add trailingSlash config option (#4908)
* 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
GitHub
parent
77264f1eb0
commit
df8a900f9c
28 changed files with 469 additions and 67 deletions
|
|
@ -81,6 +81,24 @@ module.exports = {
|
|||
|
||||
## Optional fields {#optional-fields}
|
||||
|
||||
### `trailingSlash` {#trailing-slash}
|
||||
|
||||
- Type: `boolean | undefined`
|
||||
|
||||
Allow to customize the presence/absence of a trailing slash at the end of URLs/links, and how static HTML files are generated:
|
||||
|
||||
- `undefined` (default): keeps URLs untouched, and emit `/docs/myDoc/index.html` for `/docs/myDoc.md`
|
||||
- `true`: add trailing slashes to URLs/links, and emit `/docs/myDoc/index.html` for `/docs/myDoc.md`
|
||||
- `false`: remove trailing slashes from URLs/links, and emit `/docs/myDoc.html` for `/docs/myDoc.md`
|
||||
|
||||
:::tip
|
||||
|
||||
Each static hosting provider serve static files differently (this behavior may even change over time).
|
||||
|
||||
Refer to the [deployment guide](../deployment.mdx) and [slorber/trailing-slash-guide](https://github.com/slorber/trailing-slash-guide) to choose the appropriate setting.
|
||||
|
||||
:::
|
||||
|
||||
### `i18n` {#i18n}
|
||||
|
||||
- Type: `Object`
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ title: '📦 plugin-google-analytics'
|
|||
slug: '/api/plugins/@docusaurus/plugin-google-analytics'
|
||||
---
|
||||
|
||||
The default [Google Analytics](https://developers.google.com/analytics/devguides/collection/analyticsjs/) plugin. It is a JavaScript library for measuring how users interact with your website **in the production build**. If you are using Google Analytics 4 you might need to consider using [plugin-google-gtag](./plugin-google-gtag) instead.
|
||||
The default [Google Analytics](https://developers.google.com/analytics/devguides/collection/analyticsjs/) plugin. It is a JavaScript library for measuring how users interact with your website **in the production build**. If you are using Google Analytics 4 you might need to consider using [plugin-google-gtag](./plugin-google-gtag.md) instead.
|
||||
|
||||
## Installation {#installation}
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
:::
|
||||
|
||||
|
|
|
|||
|
|
@ -13,16 +13,27 @@ Markdown docs have their own [Markdown frontmatter](../../api/plugins/plugin-con
|
|||
|
||||
## Referencing other documents {#referencing-other-documents}
|
||||
|
||||
If you want to reference another document file, you could use the name of the document you want to reference. Docusaurus will convert the file path to be the final website path (and remove the `.md`).
|
||||
If you want to reference another document file, you could use the relative path of the document you want to link to.
|
||||
|
||||
For example, if you are in `doc2.md` and you want to reference `doc1.md` and `folder/doc3.md`:
|
||||
Docusaurus will convert the file path to be the final document url path (and remove the `.md` extension).
|
||||
|
||||
For example, if you are in `folder/doc1.md` and you want to reference `folder/doc2.md`, `folder/subfolder/doc3.md` and `otherFolder/doc4.md`:
|
||||
|
||||
```md
|
||||
I am referencing a [document](doc1.md). Reference to another [document in a folder](folder/doc3.md).
|
||||
I am referencing a [document](doc2.md).
|
||||
|
||||
[Relative document](../doc2.md) referencing works as well.
|
||||
Reference to another [document in a subfolder](subfolder/doc3.md).
|
||||
|
||||
[Relative document](../otherFolder/doc4.md) referencing works as well.
|
||||
```
|
||||
|
||||
One benefit of this approach is that the links to external files will still work if you are viewing the file on GitHub.
|
||||
:::tip
|
||||
|
||||
Another benefit, for versioned docs, is that one versioned doc will link to another doc of the exact same version.
|
||||
It is better to use relative file paths links instead of relative links:
|
||||
|
||||
- links will keep working on the GitHub interface
|
||||
- you can customize the document slugs without having to update all the links
|
||||
- a versioned doc will link to another doc of the exact same version
|
||||
- relative links are very likely to break if you update the [`trailingSlash` config](../../api/docusaurus.config.js.md#trailing-slash)
|
||||
|
||||
:::
|
||||
|
|
|
|||
|
|
@ -105,7 +105,7 @@ module.exports = {
|
|||
|
||||
By default, DocSearch comes with a fine-tuned theme that was designed for accessibility, making sure that colors and contrasts respect standards.
|
||||
|
||||
Still, you can reuse the [Infima CSS variables](styling-layout#styling-your-site-with-infima) from Docusaurus to style DocSearch by editing the `/src/css/custom.css` file.
|
||||
Still, you can reuse the [Infima CSS variables](styling-layout.md#styling-your-site-with-infima) from Docusaurus to style DocSearch by editing the `/src/css/custom.css` file.
|
||||
|
||||
```css title="/src/css/custom.css"
|
||||
html[data-theme='light'] .DocSearch {
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue