diff --git a/website/docs/blog.mdx b/website/docs/blog.mdx index 035732b7ed..4c689b5c6f 100644 --- a/website/docs/blog.mdx +++ b/website/docs/blog.mdx @@ -328,7 +328,7 @@ authors: The configuration file can be localized, just create a localized copy of it at: ```bash -website/i18n//docusaurus-plugin-content-blog/authors.yml +website/i18n/{{locale}}/docusaurus-plugin-content-blog/authors.yml ``` @@ -522,19 +522,21 @@ https://example.com/blog/feed.json ### Blog-only mode {#blog-only-mode} -You can run your Docusaurus 2 site without a landing page and instead have your blog's post list page as the index page. Set the `routeBasePath` to be `'/'` to indicate it's the root path. +You can run your Docusaurus 2 site without a dedicated landing page and instead have your blog's post list page as the index page. Set the `routeBasePath` to be `'/'` to serve the blog through the root route `example.com/` instead of the subroute `example.com/blog/`. -```js {10} title="docusaurus.config.js" +```js title="docusaurus.config.js" module.exports = { // ... presets: [ [ '@docusaurus/preset-classic', { - docs: false, + // highlight-next-line + docs: false, // Optional: disable the docs plugin blog: { - path: './blog', - routeBasePath: '/', // Set this value to '/'. + // highlight-next-line + routeBasePath: '/', // Serve the blog at the site's root + /* other blog options */ }, }, ], @@ -548,6 +550,12 @@ Don't forget to delete the existing homepage at `./src/pages/index.js` or else t ::: +:::tip + +There's also a "Docs-only mode" for those who only want to use the docs. Read [Docs-only mode](./guides/docs/docs-introduction.md) for detailed instructions or a more elaborated explanation of `routeBasePath`. + +::: + ### Multiple blogs {#multiple-blogs} By default, the classic theme assumes only one blog per website and hence includes only one instance of the blog plugin. If you would like to have multiple blogs on a single website, it's possible too! You can add another blog by specifying another blog plugin in the `plugins` option for `docusaurus.config.js`. diff --git a/website/docs/guides/docs/docs-introduction.md b/website/docs/guides/docs/docs-introduction.md index 0612e7b089..793c5468f7 100644 --- a/website/docs/guides/docs/docs-introduction.md +++ b/website/docs/guides/docs/docs-introduction.md @@ -22,7 +22,7 @@ For example, `greeting.md` id is `greeting` and `guide/hello.md` id is `guide/he ```bash website # Root directory of your site └── docs -   ├── greeting.md + ├── greeting.md └── guide └── hello.md ``` @@ -69,16 +69,89 @@ Lorem ipsum ## Docs-only mode {#docs-only-mode} -If you only want the documentation feature, you can run your Docusaurus 2 site without a landing page and display your documentation page as the index page instead. +A freshly initialized Docusaurus site has the following structure: -To enable docs-only mode, set the docs plugin `routeBasePath: '/'`, and use the frontmatter `slug: /` on the document that should be the index page ([more info](#home-page-docs)). +``` +example.com/ -> generated from `src/pages/index.js` + +example.com/docs/intro -> generated from `docs/intro.md` +example.com/docs/tutorial-basics/... -> generated from `docs/tutorial-basics/...` +... + +example.com/blog/2021/08/26/welcome -> generated from `blog/2021-08-26-welcome/index.md` +example.com/blog/2021/08/01/mdx-blog-post -> generated from `blog/2021-08-01-mdx-blog-post.mdx` +... +``` + +All docs will be served under the subroute `docs/`. But what if **your site only has docs**, or you want to prioritize your docs by putting it at the root? + +Assume that you have the following in your configuration: + +```js title="docusaurus.config.js" +module.exports = { + // ... + presets: [ + '@docusaurus/preset-classic', + { + docs: { + /* docs plugin options */ + }, + blog: { + /* blog plugin options */ + }, + // ... + }, + ], +}; +``` + +To enter docs-only mode, change it to like this: + +```js title="docusaurus.config.js" +module.exports = { + // ... + presets: [ + '@docusaurus/preset-classic', + { + docs: { + // highlight-next-line + routeBasePath: '/', // Serve the docs at the site's root + /* other docs plugin options */ + }, + // highlight-next-line + blog: false, // Optional: disable the blog plugin + // ... + }, + ], +}; +``` + +Note that you **don't necessarily have to give up on using blog** or other plugins; all that `routeBasePath: '/'` does is that instead of serving the docs through `https://example.com/docs/some-doc`, they are now at the site root: `https://example.com/some-doc`. The blog, if enabled, can still be accessed through the `blog/` subroute. + +Don't forget to put some page at the root (`https://example.com/`) through adding the front matter: + +```yml title="docs/intro.md" +--- +# highlight-next-line +slug: / +--- +This page will be the home page when users visit https://example.com/. +``` :::caution -You should delete the existing homepage at `./src/pages/index.js`, or else there will be two files mapping to the same route! +If you added `slug: /` to a doc to make it the homepage, you should delete the existing homepage at `./src/pages/index.js`, or else there will be two files mapping to the same route! ::: +Now, the site's structure will be like the following: + +``` +example.com/ -> generated from `docs/intro.md` +example.com/tutorial-basics/... -> generated from `docs/tutorial-basics/...` +... +``` + :::tip There's also a "blog-only mode" for those who only want to use the blog feature of Docusaurus 2. You can use the same method detailed above. Follow the setup instructions on [Blog-only mode](../../blog.mdx#blog-only-mode).