string \| EditUrlFunction | `undefined` | Base URL to edit your site. The final URL is computed by `editUrl + relativeDocPath`. Using a function allows more nuanced control for each file. Omitting this variable entirely will disable edit links. |
| `editLocalizedFiles` | `boolean` | `false` | The edit URL will target the localized file, instead of the original unlocalized file. Ignored when `editUrl` is a function. |
| `editCurrentVersion` | `boolean` | `false` | The edit URL will always target the current version doc instead of older versions. Ignored when `editUrl` is a function. |
@@ -94,6 +95,7 @@ type SidebarGenerator = (generatorArgs: {
sidebarPosition?: number | undefined;
}>; // all the docs of that version (unfiltered)
numberPrefixParser: PrefixParser; // numberPrefixParser configured for this plugin
+ categoriesMetadata: Record'light' \| 'dark' | `'light'` | The color mode when user first visits the site. |
| `disableSwitch` | `boolean` | `false` | Hides the switch in the navbar. Useful if you want to support a single color mode. |
| `respectPrefersColorScheme` | `boolean` | `false` | Whether to use the `prefers-color-scheme` media-query, using user system preferences, instead of the hardcoded `defaultMode`. |
-| `switchConfig` | _See below_ | _See below_ | Dark/light switch icon options. |
-| `switchConfig.darkIcon` | `string` | `'🌜'` | Icon for the switch while in dark mode. |
-| `switchConfig.darkIconStyle` | JSX style object (see [documentation](https://reactjs.org/docs/dom-elements.html#style)) | `{}` | CSS to apply to dark icon. |
-| `switchConfig.lightIcon` | `string` | `'🌞'` | Icon for the switch while in light mode. |
-| `switchConfig.lightIconStyle` | JSX style object | `{}` | CSS to apply to light icon. |
@@ -46,18 +41,6 @@ module.exports = {
defaultMode: 'light',
disableSwitch: false,
respectPrefersColorScheme: false,
- switchConfig: {
- darkIcon: '🌙',
- darkIconStyle: {
- marginLeft: '2px',
- },
- // Unicode icons such as '\u2600' will work
- // Unicode with 5 chars require brackets: '\u{1F602}'
- lightIcon: '\u{1F602}',
- lightIconStyle: {
- marginLeft: '1px',
- },
- },
},
// highlight-end
},
diff --git a/website/versioned_docs/version-2.0.0-beta.15/api/themes/theme-live-codeblock.md b/website/versioned_docs/version-2.0.0-beta.17/api/themes/theme-live-codeblock.md
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/api/themes/theme-live-codeblock.md
rename to website/versioned_docs/version-2.0.0-beta.17/api/themes/theme-live-codeblock.md
diff --git a/website/versioned_docs/version-2.0.0-beta.15/api/themes/theme-search-algolia.md b/website/versioned_docs/version-2.0.0-beta.17/api/themes/theme-search-algolia.md
similarity index 79%
rename from website/versioned_docs/version-2.0.0-beta.15/api/themes/theme-search-algolia.md
rename to website/versioned_docs/version-2.0.0-beta.17/api/themes/theme-search-algolia.md
index 077a4ab13b..05e2f767fe 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/api/themes/theme-search-algolia.md
+++ b/website/versioned_docs/version-2.0.0-beta.17/api/themes/theme-search-algolia.md
@@ -11,7 +11,7 @@ This theme provides a `@theme/SearchBar` component that integrates with Algolia
npm install --save @docusaurus/theme-search-algolia
```
-This theme also adds search page available at `/search` (as swizzlable `SearchPage` component) path with OpenSearch support.
+This theme also adds search page available at `/search` (as swizzlable `SearchPage` component) path with OpenSearch support. You can this default path via `themeConfig.algolia.searchPagePath`. Use `false` to disable search page.
:::tip
diff --git a/website/versioned_docs/version-2.0.0-beta.15/assets/docusaurus-asset-example-banner.png b/website/versioned_docs/version-2.0.0-beta.17/assets/docusaurus-asset-example-banner.png
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/assets/docusaurus-asset-example-banner.png
rename to website/versioned_docs/version-2.0.0-beta.17/assets/docusaurus-asset-example-banner.png
diff --git a/website/versioned_docs/version-2.0.0-beta.15/assets/docusaurus-asset-example.docx b/website/versioned_docs/version-2.0.0-beta.17/assets/docusaurus-asset-example.docx
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/assets/docusaurus-asset-example.docx
rename to website/versioned_docs/version-2.0.0-beta.17/assets/docusaurus-asset-example.docx
diff --git a/website/versioned_docs/version-2.0.0-beta.15/assets/docusaurus-asset-example.xyz b/website/versioned_docs/version-2.0.0-beta.17/assets/docusaurus-asset-example.xyz
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/assets/docusaurus-asset-example.xyz
rename to website/versioned_docs/version-2.0.0-beta.17/assets/docusaurus-asset-example.xyz
diff --git a/website/versioned_docs/version-2.0.0-beta.15/blog.mdx b/website/versioned_docs/version-2.0.0-beta.17/blog.mdx
similarity index 92%
rename from website/versioned_docs/version-2.0.0-beta.15/blog.mdx
rename to website/versioned_docs/version-2.0.0-beta.17/blog.mdx
index 06777ff89e..3e0173879a 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/blog.mdx
+++ b/website/versioned_docs/version-2.0.0-beta.17/blog.mdx
@@ -69,39 +69,7 @@ This is my first post on Docusaurus 2.
A whole bunch of exploration to follow.
```
-:::note
-
-Docusaurus will extract a `YYYY-MM-DD` date from a file/folder name such as `YYYY-MM-DD-my-blog-post-title.md`.
-
-This naming convention is optional, and you can provide the date as front matter.
-
-
-
-
-:::
-
-:::tip
-
-Using a folder can be convenient to co-locate blog post images alongside the Markdown file.
-
-:::
-
-The only required field in the front matter is `title`; however, we provide options to add more metadata to your blog post, for example, author information. For all possible fields, see [the API documentation](api/plugins/plugin-content-blog.md#markdown-front-matter).
+The front matter is useful to add more metadata to your blog post, for example, author information, but Docusaurus will be able to infer all necessary metadata without the front matter. For all possible fields, see [the API documentation](api/plugins/plugin-content-blog.md#markdown-front-matter).
## Blog list {#blog-list}
@@ -173,9 +141,51 @@ module.exports = {
};
```
+## Blog post date {#blog-post-date}
+
+Docusaurus will extract a `YYYY-MM-DD` date from a file/folder name such as `YYYY-MM-DD-my-blog-post-title.md`.
+
+Example supported patterns
- -| Pattern | Example | -| --- | --- | -| Single file | `2021-05-28-my-blog-post-title.md` | -| MDX file | `2021-05-28-my-blog-post-title.mdx` | -| Single folder + `index.md` | `2021-05-28-my-blog-post-title/index.md` | -| Folder named by date | `2021-05-28/my-blog-post-title.md` | -| Nested folders by date | `2021/05/28/my-blog-post-title.md` | -| Partially nested folders by date | `2021/05-28-my-blog-post-title.md` | -| Nested folders + `index.md` | `2021/05/28/my-blog-post-title/index.md` | -| Date in the middle of path | `category/2021/05-28-my-blog-post-title.md` | - -The date will be excised from the path and appended to the beginning of the URL slug. - -
+
+
+:::tip
+
+Using a folder can be convenient to co-locate blog post images alongside the Markdown file.
+
+:::
+
+This naming convention is optional, and you can also provide the date as front matter. Since the front matter follows YAML syntax where the datetime notation is supported, you can use front matter if you need more fine-grained publish dates. For example, if you have multiple posts published on the same day, you can order them according to the time of the day:
+
+```md title="earlier-post.md"
+---
+date: 2021-09-13T10:00
+---
+```
+
+```md title="later-post.md"
+---
+date: 2021-09-13T18:00
+---
+```
+
## Blog post authors {#blog-post-authors}
-Use the `authors` front matter field to declare blog post authors.
+Use the `authors` front matter field to declare blog post authors. An author should have at least a `name` or an `image_url`. Docusaurus uses information like `url`, `email`, and `title`, but any other information is allowed.
### Inline authors {#inline-authors}
@@ -192,6 +202,7 @@ authors:
title: Co-creator of Docusaurus 1
url: https://github.com/JoelMarcey
image_url: https://github.com/JoelMarcey.png
+ email: jimarcey@gmail.com
---
```
@@ -205,6 +216,7 @@ authors:
title: Co-creator of Docusaurus 1
url: https://github.com/JoelMarcey
image_url: https://github.com/JoelMarcey.png
+ email: jimarcey@gmail.com
- name: Sébastien Lorber
title: Docusaurus maintainer
url: https://sebastienlorber.com
@@ -249,6 +261,7 @@ jmarcey:
title: Co-creator of Docusaurus 1
url: https://github.com/JoelMarcey
image_url: https://github.com/JoelMarcey.png
+ email: jimarcey@gmail.com
slorber:
name: Sébastien Lorber
@@ -343,6 +356,12 @@ website/i18n/[locale]/docusaurus-plugin-content-blog/authors.yml
An author, either declared through front matter or through the authors map, needs to have a name or an avatar, or both. If all authors of a post don't have names, Docusaurus will display their avatars compactly. See [this test post](/tests/blog/2022/01/20/image-only-authors) for the effect.
+:::caution Feed generation
+
+[RSS feeds](#feed) require the author's email to be set for the author to appear in the feed.
+
+:::
+
## Reading time {#reading-time}
Docusaurus generates a reading time estimation for each blog post based on word count. We provide an option to customize this.
diff --git a/website/versioned_docs/version-2.0.0-beta.15/browser-support.md b/website/versioned_docs/version-2.0.0-beta.17/browser-support.md
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/browser-support.md
rename to website/versioned_docs/version-2.0.0-beta.17/browser-support.md
diff --git a/website/versioned_docs/version-2.0.0-beta.15/cli.md b/website/versioned_docs/version-2.0.0-beta.17/cli.md
similarity index 81%
rename from website/versioned_docs/version-2.0.0-beta.15/cli.md
rename to website/versioned_docs/version-2.0.0-beta.17/cli.md
index b2593ca4b0..f300d26abe 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/cli.md
+++ b/website/versioned_docs/version-2.0.0-beta.17/cli.md
@@ -85,55 +85,37 @@ For advanced minification of CSS bundle, we use the [advanced cssnano preset](ht
:::
-### `docusaurus swizzle [siteDir]` {#docusaurus-swizzle-sitedir}
+### `docusaurus swizzle [themeName] [componentName] [siteDir]` {#docusaurus-swizzle}
-```mdx-code-block
-import SwizzleWarning from "./_partials/swizzleWarning.mdx"
-
-Example supported patterns
+ +| Pattern | Example | +| --- | --- | +| Single file | `2021-05-28-my-blog-post-title.md` | +| MDX file | `2021-05-28-my-blog-post-title.mdx` | +| Single folder + `index.md` | `2021-05-28-my-blog-post-title/index.md` | +| Folder named by date | `2021-05-28/my-blog-post-title.md` | +| Nested folders by date | `2021/05/28/my-blog-post-title.md` | +| Partially nested folders by date | `2021/05-28-my-blog-post-title.md` | +| Nested folders + `index.md` | `2021/05/28/my-blog-post-title/index.md` | +| Date in the middle of path | `category/2021/05-28-my-blog-post-title.md` | + +The date will be excised from the path and appended to the beginning of the URL slug. + +Contact us through {customFields.teamEmail}!
;
+}
+```
+
+## Choosing a hosting provider {#choosing-a-hosting-provider}
There are a few common hosting options:
@@ -182,7 +213,7 @@ Refer to [slorber/trailing-slash-guide](https://github.com/slorber/trailing-slas
Deploying your Docusaurus project to [Vercel](https://vercel.com/) will provide you with [various benefits](https://vercel.com/) in the areas of performance and ease of use.
-To deploy your Docusaurus project with a [Vercel for Git Integration](https://vercel.com/docs/git-integrations), make sure it has been pushed to a Git repository.
+To deploy your Docusaurus project with a [Vercel for Git Integration](https://vercel.com/docs/concepts/git), make sure it has been pushed to a Git repository.
Import the project into Vercel using the [Import Flow](https://vercel.com/import/git). During the import, you will find all relevant options preconfigured for you; however, you can choose to change any of these options, a list of which can be found [here](https://vercel.com/docs/build-step#build-&-development-settings).
@@ -308,12 +339,12 @@ Alternatively, you can use SSH (`USE_SSH=true`) to log in.
[GitHub Actions](https://help.github.com/en/actions) allow you to automate, customize, and execute your software development workflows right in your repository.
-The workflow examples below assume your website source resides in the `main` branch of your repository (the _source branch_ is `main`), under a folder called `website/`, and your [publishing source](https://help.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site) is configured for the `gh-pages` branch (the _deployment branch_ is `gh-pages`).
+The workflow examples below assume your website source resides in the `main` branch of your repository (the _source branch_ is `main`), and your [publishing source](https://help.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site) is configured for the `gh-pages` branch (the _deployment branch_ is `gh-pages`).
Our goal is that:
-1. When a new pull request is made to `main` and updates `website/`, there's an action that ensures the site builds successfully, without actually deploying. This job will be called `test-deploy`.
-2. When a pull request is merged to the `main` branch or someone pushes to the `main` branch directly and `website/` is updated, it will be built and deployed to the `gh-pages` branch. After that, the new build output will be served on the GitHub Pages site. This job will be called `deploy`.
+1. When a new pull request is made to `main`, there's an action that ensures the site builds successfully, without actually deploying. This job will be called `test-deploy`.
+2. When a pull request is merged to the `main` branch or someone pushes to the `main` branch directly, it will be built and deployed to the `gh-pages` branch. After that, the new build output will be served on the GitHub Pages site. This job will be called `deploy`.
Here are two approaches to deploying your docs with GitHub Actions. Based on the location of your deployment branch (`gh-pages`), choose the relevant tab below:
@@ -324,7 +355,7 @@ Here are two approaches to deploying your docs with GitHub Actions. Based on the
Customizing category index matching
@@ -292,9 +305,9 @@ function isCategoryIndex({fileName, directories}) { ## Autogenerated sidebar metadata {#autogenerated-sidebar-metadata} -For hand-written sidebar definitions, you would provide metadata to sidebar items through `sidebars.js`; for autogenerated, Docusaurus would read them from the item's respective file. In addition, you may want to adjust the relative position of each item, because, by default, items within a sidebar slice will be generated in **alphabetical order** (using files and folders names). +For handwritten sidebar definitions, you would provide metadata to sidebar items through `sidebars.js`; for autogenerated, Docusaurus would read them from the item's respective file. In addition, you may want to adjust the relative position of each item because, by default, items within a sidebar slice will be generated in **alphabetical order** (using file and folder names). -**For docs**: use additional front matter. The `label` and `className` attributes now become `sidebar_label` and `sidebar_class_name`, while there's an additional `sidebar_position` front matter. +**For docs**: use additional front matter. The `label`, `className`, and `customProps` attributes are declared in front matter as `sidebar_label`, `sidebar_class_name`, and `sidebar_custom_props`, respectively. Position can be specified in the same way, via `sidebar_position` front matter. ```md title="docs/tutorials/tutorial-easy.md" --- @@ -352,6 +365,8 @@ If the `link` is explicitly specified, Docusaurus will not apply any [default co The doc links can be specified relatively, e.g. if the category is generated with the `guides` directory, `"link": {"type": "doc", "id": "intro"}` will be resolved to the ID `guides/intro`, only falling back to `intro` if a doc with the former ID doesn't exist. +You can also use `link: null` to opt out of default conventions and not generate any category index page. + ::: :::info @@ -360,7 +375,7 @@ The position metadata is only used **within a sidebar slice**: Docusaurus does n ::: -## Using number prefixes +## Using number prefixes {#using-number-prefixes} A simple way to order an autogenerated sidebar is to prefix docs and folders by number prefixes, which also makes them appear in the file system in the same order when sorted by file name: @@ -396,7 +411,7 @@ Updating a number prefix can be annoying, as it can require **updating multiple ::: -## Customize the sidebar items generator +## Customize the sidebar items generator {#customize-the-sidebar-items-generator} You can provide a custom `sidebarItemsGenerator` function in the docs plugin (or preset) config: @@ -413,6 +428,7 @@ module.exports = { item, version, docs, + categoriesMetadata, isCategoryIndex, }) { // Example: return an hardcoded list of static sidebar items diff --git a/website/versioned_docs/version-2.0.0-beta.15/guides/docs/sidebar/index.md b/website/versioned_docs/version-2.0.0-beta.17/guides/docs/sidebar/index.md similarity index 88% rename from website/versioned_docs/version-2.0.0-beta.15/guides/docs/sidebar/index.md rename to website/versioned_docs/version-2.0.0-beta.17/guides/docs/sidebar/index.md index a839f6ba8e..9634f4853c 100644 --- a/website/versioned_docs/version-2.0.0-beta.15/guides/docs/sidebar/index.md +++ b/website/versioned_docs/version-2.0.0-beta.17/guides/docs/sidebar/index.md @@ -117,7 +117,7 @@ type SidebarsFile = { }; ``` -## Theme configuration +## Theme configuration {#theme-configuration} ### Hideable sidebar {#hideable-sidebar} @@ -133,7 +133,7 @@ module.exports = { }; ``` -### Auto-collapse sidebar categories +### Auto-collapse sidebar categories {#auto-collapse-sidebar-categories} The `themeConfig.autoCollapseSidebarCategories` option would collapse all sibling categories when expanding one category. This saves the user from having too many categories open and helps them focus on the selected section. @@ -160,6 +160,28 @@ To pass in custom props to a swizzled sidebar item, add the optional `customProp }; ``` +## Sidebar Breadcrumbs {#sidebar-breadcrumbs} + +By default, breadcrumbs are rendered at the top, using the "sidebar path" of the current page. + +This behavior can be disabled with plugin options: + +```js title="docusaurus.config.js" +module.exports = { + presets: [ + [ + '@docusaurus/preset-classic', + { + docs: { + // highlight-next-line + breadcrumbs: false, + }, + }, + ], + ], +}; +``` + ## Complex sidebars example {#complex-sidebars-example} A real-world example from the Docusaurus site: diff --git a/website/versioned_docs/version-2.0.0-beta.15/guides/docs/sidebar/items.md b/website/versioned_docs/version-2.0.0-beta.17/guides/docs/sidebar/items.md similarity index 75% rename from website/versioned_docs/version-2.0.0-beta.15/guides/docs/sidebar/items.md rename to website/versioned_docs/version-2.0.0-beta.17/guides/docs/sidebar/items.md index 30e9471204..04faf577a7 100644 --- a/website/versioned_docs/version-2.0.0-beta.15/guides/docs/sidebar/items.md +++ b/website/versioned_docs/version-2.0.0-beta.17/guides/docs/sidebar/items.md @@ -5,12 +5,18 @@ slug: /sidebar/items # Sidebar items +```mdx-code-block +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +``` + We have introduced three types of item types in the example in the previous section: `doc`, `category`, and `link`, whose usages are fairly intuitive. We will formally introduce their APIs. There's also a fourth type: `autogenerated`, which we will explain in detail later. - **[Doc](#sidebar-item-doc)**: link to a doc page, associating it with the sidebar - **[Link](#sidebar-item-link)**: link to any internal or external page - **[Category](#sidebar-item-category)**: creates a dropdown of sidebar items - **[Autogenerated](autogenerated.md)**: generate a sidebar slice automatically +- **[HTML](#sidebar-item-html)**: renders pure HTML in the item's position - **[\*Ref](multiple-sidebars.md#sidebar-item-ref)**: link to a doc page, without making the item take part in navigation generation ## Doc: link to a doc {#sidebar-item-doc} @@ -25,6 +31,7 @@ type SidebarItemDoc = id: string; label: string; // Sidebar label text className?: string; // Class name for sidebar label + customProps?: Record
', // The HTML to be rendered
+ defaultStyle: true, // Use the default menu item styling
+ },
+ // highlight-end
+ ],
+};
+```
+
+:::tip
+
+The menu item is already wrapped in an `
`, without any processing or file existence checking.
diff --git a/website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-code-blocks.mdx b/website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-code-blocks.mdx
similarity index 99%
rename from website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-code-blocks.mdx
rename to website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-code-blocks.mdx
index b57c25dcdd..7934b6ebaa 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-code-blocks.mdx
+++ b/website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-code-blocks.mdx
@@ -197,13 +197,13 @@ To accomplish this, Docusaurus adds the `docusaurus-highlight-code-line` class t
}
/* If you have a different syntax highlighting theme for dark mode. */
-html[data-theme='dark'] .docusaurus-highlight-code-line {
+[data-theme='dark'] .docusaurus-highlight-code-line {
/* Color which works with dark mode syntax highlighting theme */
background-color: rgb(100, 100, 100);
}
```
-### Highlighting with metadata string
+### Highlighting with metadata string {#highlighting-with-metadata-string}
You can also specify highlighted line ranges within the language meta string (leave a space after the language). To highlight multiple lines, separate the line numbers by commas or use the range syntax to select a chunk of lines. This feature uses the `parse-number-range` library and you can find [more syntax](https://www.npmjs.com/package/parse-numeric-range) on their project details.
diff --git a/website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-head-metadata.mdx b/website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-head-metadata.mdx
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-head-metadata.mdx
rename to website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-head-metadata.mdx
diff --git a/website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-headings.mdx b/website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-headings.mdx
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-headings.mdx
rename to website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-headings.mdx
diff --git a/website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-inline-toc.mdx b/website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-inline-toc.mdx
similarity index 59%
rename from website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-inline-toc.mdx
rename to website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-inline-toc.mdx
index bfdc6c1a6d..4a48251ac4 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-inline-toc.mdx
+++ b/website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-inline-toc.mdx
@@ -35,30 +35,33 @@ import TOCInline from '@theme/TOCInline';
## Custom table of contents {#custom-table-of-contents}
-The `toc` props is just a list of table of contents items:
+The `toc` prop is just a list of heading items:
```ts
type TOCItem = {
value: string;
id: string;
- children: TOCItem[];
level: number;
};
```
-You can create this TOC tree manually, or derive a new TOC tree from the `toc` variable:
+Note that the `toc` global is a flat array, so you can easily cut out unwanted nodes or insert extra nodes, and create a new TOC tree.
```jsx
import TOCInline from '@theme/TOCInline';
+
+
+
+```bash
+npm init docusaurus website classic
+```
+
+
+
+
+```bash
+yarn create docusaurus website classic
+```
+
+
+
+
+```bash
+pnpm create docusaurus website classic
+```
+
+
+
+````
+
+
+
+Docusaurus makes best efforts to select a package manager to install dependencies for you, based on the command you are using and the project you are in. You can override this behavior by using `--package-manager [npm/yarn/pnpm]`.
+
+```bash
+# Use Yarn to install dependencies even when the command is npx
+npx create-docusaurus@latest my-website classic --package-manager yarn
+```
+
+If you want to skip installing dependencies, use the `--skip-install` option.
```bash
npx create-docusaurus@latest my-website classic --skip-install
```
-You can also use the template's TypeScript variant by passing the `--typescript` flag.
-
-```bash
-npx create-docusaurus@latest my-website classic --typescript
-```
-
## Project structure {#project-structure}
Assuming you chose the classic template and named your site `my-website`, you will see the following files generated under a new directory `my-website/`:
@@ -100,7 +146,7 @@ my-website
- `/package.json` - A Docusaurus website is a React app. You can install and use any npm packages you like in them
- `/sidebar.js` - Used by the documentation to specify the order of documents in the sidebar
-### Monorepos
+### Monorepos {#monorepos}
If you are using Docusaurus for documentation of an existing project, a monorepo may be the solution for you. Monorepos allow you to share dependencies between similar projects. For example, your website may use your local packages to showcase the latest features, instead of depending on a released version; your contributors can also conveniently update the docs as they implement features. An example monorepo folder structure is below:
diff --git a/website/versioned_docs/version-2.0.0-beta.15/introduction.md b/website/versioned_docs/version-2.0.0-beta.17/introduction.md
similarity index 94%
rename from website/versioned_docs/version-2.0.0-beta.15/introduction.md
rename to website/versioned_docs/version-2.0.0-beta.17/introduction.md
index 32c98c3f83..36c26cfe15 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/introduction.md
+++ b/website/versioned_docs/version-2.0.0-beta.17/introduction.md
@@ -46,6 +46,22 @@ Or read the **[5-minute tutorial](https://tutorial.docusaurus.io)** online.
:::
+## Docusaurus: Documentation Made Easy
+
+In this presentation at [Algolia Community Event](https://www.algolia.com/), [Meta Open Source team](https://opensource.facebook.com/) shared a brief walk-through of Docusaurus. They covered how to get started with the project, enable plugins, and set up functionalities like documentation and blogging.
+
+Alternative installation commands
+ +You can also initialize a new project using your preferred project manager: + +````mdx-code-block +
+
+
+
## Disclaimer {#disclaimer}
Docusaurus v2 is **beta** but already quite stable and widely used.
diff --git a/website/versioned_docs/version-2.0.0-beta.15/migration/migration-automated.md b/website/versioned_docs/version-2.0.0-beta.17/migration/migration-automated.md
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/migration/migration-automated.md
rename to website/versioned_docs/version-2.0.0-beta.17/migration/migration-automated.md
diff --git a/website/versioned_docs/version-2.0.0-beta.15/migration/migration-manual.md b/website/versioned_docs/version-2.0.0-beta.17/migration/migration-manual.md
similarity index 99%
rename from website/versioned_docs/version-2.0.0-beta.15/migration/migration-manual.md
rename to website/versioned_docs/version-2.0.0-beta.17/migration/migration-manual.md
index 71d880ae62..4f2a53cddf 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/migration/migration-manual.md
+++ b/website/versioned_docs/version-2.0.0-beta.17/migration/migration-manual.md
@@ -492,7 +492,7 @@ You'll have to migrate your sidebar if it contains category type. Rename `subcat
### Footer {#footer}
-`website/core/Footer.js` is no longer needed. If you want to modify the default footer provided by Docusaurus, [swizzle](../advanced/swizzling.md#swizzling) it:
+`website/core/Footer.js` is no longer needed. If you want to modify the default footer provided by Docusaurus, [swizzle](../swizzling.md) it:
```bash npm2yarn
npm run swizzle @docusaurus/theme-classic Footer
diff --git a/website/versioned_docs/version-2.0.0-beta.15/migration/migration-overview.md b/website/versioned_docs/version-2.0.0-beta.17/migration/migration-overview.md
similarity index 98%
rename from website/versioned_docs/version-2.0.0-beta.15/migration/migration-overview.md
rename to website/versioned_docs/version-2.0.0-beta.17/migration/migration-overview.md
index f65d3ae724..14e9b96769 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/migration/migration-overview.md
+++ b/website/versioned_docs/version-2.0.0-beta.17/migration/migration-overview.md
@@ -8,7 +8,7 @@ This doc guides you through migrating an existing Docusaurus 1 site to Docusauru
We try to make this as easy as possible, and provide a migration cli.
-## Main differences
+## Main differences {#main-differences}
Docusaurus 1 is a pure documentation site generator, using React as a server-side template engine, but not loading React on the browser.
diff --git a/website/versioned_docs/version-2.0.0-beta.15/migration/migration-translated-sites.md b/website/versioned_docs/version-2.0.0-beta.17/migration/migration-translated-sites.md
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/migration/migration-translated-sites.md
rename to website/versioned_docs/version-2.0.0-beta.17/migration/migration-translated-sites.md
diff --git a/website/versioned_docs/version-2.0.0-beta.15/migration/migration-versioned-sites.md b/website/versioned_docs/version-2.0.0-beta.17/migration/migration-versioned-sites.md
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/migration/migration-versioned-sites.md
rename to website/versioned_docs/version-2.0.0-beta.17/migration/migration-versioned-sites.md
diff --git a/website/versioned_docs/version-2.0.0-beta.15/playground.mdx b/website/versioned_docs/version-2.0.0-beta.17/playground.mdx
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/playground.mdx
rename to website/versioned_docs/version-2.0.0-beta.17/playground.mdx
diff --git a/website/versioned_docs/version-2.0.0-beta.15/search.md b/website/versioned_docs/version-2.0.0-beta.17/search.md
similarity index 95%
rename from website/versioned_docs/version-2.0.0-beta.15/search.md
rename to website/versioned_docs/version-2.0.0-beta.17/search.md
index f7632e8785..d3b27ec96c 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/search.md
+++ b/website/versioned_docs/version-2.0.0-beta.17/search.md
@@ -107,6 +107,9 @@ module.exports = {
// Optional: Algolia search parameters
searchParameters: {},
+ // Optional: path for search page that enabled by default (`false` to disable it)
+ searchPagePath: 'search',
+
//... other Algolia params
},
// highlight-end
@@ -118,13 +121,15 @@ module.exports = {
The `searchParameters` option used to be named `algoliaOptions` in Docusaurus v1.
+Refer to its [official DocSearch documentation](https://docsearch.algolia.com/docs/api#searchparameters) for possible values.
+
:::
:::caution
-The search feature will not work reliably until Algolia crawls your site with the **search plugin enabled**.
+The search feature will not work reliably until Algolia crawls your site.
-If you are installing the Algolia plugin for the first time and want to ensure the search feature works before deploying it to production, you can ask the DocSearch team to trigger a crawl on a staging environment url or deploy preview.
+If search doesn't work after any significant change, please use the Algolia dashboard to **trigger a new crawl**.
:::
@@ -173,7 +178,9 @@ module.exports = {
// highlight-start
algolia: {
contextualSearch: false,
- facetFilters: ['language:en', ['filter1', 'filter2'], 'filter3'],
+ searchParameters: {
+ facetFilters: ['language:en', ['filter1', 'filter2'], 'filter3'],
+ },
},
// highlight-end
},
@@ -191,7 +198,7 @@ By default, DocSearch comes with a fine-tuned theme that was designed for access
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 {
+[data-theme='light'] .DocSearch {
/* --docsearch-primary-color: var(--ifm-color-primary); */
/* --docsearch-text-color: var(--ifm-font-color-base); */
--docsearch-muted-color: var(--ifm-color-secondary-darkest);
@@ -209,7 +216,7 @@ html[data-theme='light'] .DocSearch {
--docsearch-footer-background: var(--ifm-color-white);
}
-html[data-theme='dark'] .DocSearch {
+[data-theme='dark'] .DocSearch {
--docsearch-text-color: var(--ifm-font-color-base);
--docsearch-muted-color: var(--ifm-color-secondary-darkest);
--docsearch-container-background: rgba(47, 55, 69, 0.7);
diff --git a/website/versioned_docs/version-2.0.0-beta.15/seo.md b/website/versioned_docs/version-2.0.0-beta.17/seo.md
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/seo.md
rename to website/versioned_docs/version-2.0.0-beta.17/seo.md
diff --git a/website/versioned_docs/version-2.0.0-beta.15/static-assets.md b/website/versioned_docs/version-2.0.0-beta.17/static-assets.md
similarity index 97%
rename from website/versioned_docs/version-2.0.0-beta.15/static-assets.md
rename to website/versioned_docs/version-2.0.0-beta.17/static-assets.md
index b666fddc79..ec2660c42d 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/static-assets.md
+++ b/website/versioned_docs/version-2.0.0-beta.17/static-assets.md
@@ -24,9 +24,9 @@ module.exports = {
Now, all files in `public` as well as `static` will be copied to the build output.
-## Referencing your static asset
+## Referencing your static asset {#referencing-your-static-asset}
-### In JSX
+### In JSX {#in-jsx}
In JSX, you can reference assets from the `static` folder in your code using absolute URLs, but this is not ideal because changing the site `baseUrl` will **break those links**. For the image `
` served at `https://example.com/test`, the browser will try to resolve it from the URL root, i.e. as `https://example.com/img/docusaurus.png`, which will fail because it's actually served at `https://example.com/test/img/docusaurus.png`.
@@ -58,7 +58,7 @@ import DocusaurusLogoWithKeytar from '@site/static/img/docusaurus_keytar.svg';
@@ -112,25 +118,25 @@ In light mode, the `` element has a `data-theme="light"` attribute; and in
```css
/* Overriding root Infima variables */
-html[data-theme='dark'] {
+[data-theme='dark'] {
--ifm-color-primary: #4e89e8;
}
/* Styling one class specially in dark mode */
-html[data-theme='dark'] .purple-text {
+[data-theme='dark'] .purple-text {
color: plum;
}
```
### Mobile View {#mobile-view}
-Docusaurus uses `966px` as the cutoff between mobile screen width and desktop. If you want your layout to be different in the mobile view, you can use media queries.
+Docusaurus uses `996px` as the cutoff between mobile screen width and desktop. If you want your layout to be different in the mobile view, you can use media queries.
```css
.banner {
padding: 4rem;
}
/** In mobile view, reduce the padding */
-@media screen and (max-width: 966px) {
+@media screen and (max-width: 996px) {
.heroBanner {
padding: 2rem;
}
diff --git a/website/versioned_docs/version-2.0.0-beta.17/swizzling.md b/website/versioned_docs/version-2.0.0-beta.17/swizzling.md
new file mode 100644
index 0000000000..d1cf3347a6
--- /dev/null
+++ b/website/versioned_docs/version-2.0.0-beta.17/swizzling.md
@@ -0,0 +1,324 @@
+---
+description: Customize your site's appearance through creating your own theme components
+---
+
+# Swizzling
+
+In this section, we will introduce how customization of layout is done in Docusaurus.
+
+> Déja vu...?
+
+This section is similar to [Styling and Layout](./styling-layout.md), but this time, we will write actual React code instead of playing with stylesheets. We will talk about a central concept in Docusaurus: **swizzling**, which allows **deeper site customizations**.
+
+In practice, swizzling permits to **swap a theme component with your own implementation**, and it comes in 2 patterns:
+
+- [**Ejecting**](#ejecting): creates a **copy** of the original theme component, which you can fully **customize**
+- [**Wrapping**](#wrapping): creates a **wrapper** around the original theme component, which you can **enhance**
+
+
+
+
+```jsx title="src/theme/SomeComponent.js"
+import React from 'react';
+
+export default function SomeComponent(props) {
+ // You can fully customize this implementation
+ // including changing the JSX, CSS and React hooks
+ return (
+
+
+
+```jsx title="src/theme/SomeComponent.js"
+import React from 'react';
+import SomeComponent from '@theme-original/SomeComponent';
+
+export default function SomeComponentWrapper(props) {
+ // You can enhance the original component,
+ // including adding extra props or JSX elements around it
+ return (
+ <>
+
+
+````
+
+To get an overview of all the themes and components available to swizzle, run:
+
+```bash npm2yarn
+npm run swizzle -- --list
+```
+
+Use `--help` to see all available CLI options, or refer to the reference [swizzle CLI documentation](./cli.md#docusaurus-swizzle).
+
+:::note
+
+After swizzling a component, **restart your dev server** in order for Docusaurus to know about the new component.
+
+:::
+
+:::warning Prefer staying on the safe side
+
+Be sure to understand [which components are **safe to swizzle**](#what-is-safe-to-swizzle). Some components are **internal implementation details** of a theme.
+
+:::
+
+:::info
+
+`docusaurus swizzle` is only an automated way to help you swizzle the component. You can also create the `src/theme/SomeComponent.js` file manually, and Docusaurus will [resolve it](./advanced/client.md#theme-aliases). There's no internal magic behind this command!
+
+:::
+
+### Ejecting {#ejecting}
+
+Ejecting a theme component is the process of **creating a copy** of the original theme component, which you can **fully customize and override**.
+
+To eject a theme component, use the swizzle CLI interactively, or with the `--eject` option:
+
+```bash npm2yarn
+npm run swizzle [theme name] [component name] -- --eject
+```
+
+An example:
+
+```bash npm2yarn
+npm run swizzle @docusaurus/theme-classic Footer -- --eject
+```
+
+This will copy the current `` component's implementation to your site's `src/theme` directory. Docusaurus will now use this `
+
+
+
+## Swizzling Process
+
+### Overview
+
+Docusaurus provides an convenient **interactive CLI** to swizzle components. You generally only need to remember the following command:
+
+```bash npm2yarn
+npm run swizzle
+```
+
+It will generate a new component your `src/theme` directory, which should look like this example:
+
+````mdx-code-block
+Why is it called swizzling?
+ +**The name comes from Objective-C and Swift-UI**: [method swizzling](https://pspdfkit.com/blog/2019/swizzling-in-swift/) is the process of changing the implementation of an existing selector (method). + +**For Docusaurus, component swizzling means providing an alternative component that takes precedence over the component provided by the theme.** + +You can think of it as [Monkey Patching](https://en.wikipedia.org/wiki/Monkey_patch) for React components, enabling you to override the default implementation. Gatsby has a similar concept called [theme shadowing](https://www.gatsbyjs.com/docs/how-to/plugins-and-themes/shadowing/). + +To gain a deeper understanding of this, you have to understand [how theme components are resolved](./advanced/client.md#theme-aliases). + +
+
+ );
+}
+```
+
+Some Component
+Some component implementation details
+