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

feat(core): support TypeScript + ESM configuration (#9317)

Browse source 
Co-authored-by: Joshua Chen <sidachen2003@gmail.com>
Co-authored-by: sebastienlorber <lorber.sebastien@gmail.com>
This commit is contained in:
Chongyi Zheng 2023-10-13 20:46:03 -04:00 • committed by GitHub
parent 336a44f3ea
commit 45f1a669b5
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
126 changed files with 2054 additions and 914 deletions
Download patch file Download diff file Expand all files Collapse all files

4
website/docs/guides/docs/docs-introduction.mdx
View file

@ -44,7 +44,7 @@ All docs will be served under the subroute `docs/`. But what if **your site only
Assume that you have the following in your configuration:
```js title="docusaurus.config.js"
module.exports = {
export default {
// ...
presets: [
[
@ -66,7 +66,7 @@ module.exports = {
To enter docs-only mode, change it to like this:
```js title="docusaurus.config.js"
module.exports = {
export default {
// ...
presets: [
[

14
website/docs/guides/docs/docs-multi-instance.mdx
View file

@ -64,7 +64,7 @@ In this case, you should use the same plugin twice in your site configuration.
When using the preset:
```js title="docusaurus.config.js"
module.exports = {
export default {
presets: [
[
'@docusaurus/preset-classic',
@ -75,7 +75,7 @@ module.exports = {
// highlight-end
path: 'product',
routeBasePath: 'product',
sidebarPath: require.resolve('./sidebarsProduct.js'),
sidebarPath: './sidebarsProduct.js',
// ... other options
},
},
@ -90,7 +90,7 @@ module.exports = {
// highlight-end
path: 'community',
routeBasePath: 'community',
sidebarPath: require.resolve('./sidebarsCommunity.js'),
sidebarPath: './sidebarsCommunity.js',
// ... other options
},
],
@ -101,7 +101,7 @@ module.exports = {
When not using the preset:
```js title="docusaurus.config.js"
module.exports = {
export default {
plugins: [
[
'@docusaurus/plugin-content-docs',
@ -111,7 +111,7 @@ module.exports = {
// highlight-end
path: 'product',
routeBasePath: 'product',
sidebarPath: require.resolve('./sidebarsProduct.js'),
sidebarPath: './sidebarsProduct.js',
// ... other options
},
],
@ -123,7 +123,7 @@ module.exports = {
// highlight-end
path: 'community',
routeBasePath: 'community',
sidebarPath: require.resolve('./sidebarsCommunity.js'),
sidebarPath: './sidebarsCommunity.js',
// ... other options
},
],
@ -190,7 +190,7 @@ Each docs-related [theme navbar items](../../api/themes/theme-configuration.mdx#
For example, if you want to have one version dropdown for each mobile SDK (iOS and Android), you could do:
```js title="docusaurus.config.js"
module.exports = {
export default {
themeConfig: {
navbar: {
items: [

16
website/docs/guides/docs/sidebar/autogenerated.mdx
View file

@ -21,7 +21,7 @@ type SidebarItemAutogenerated = {
Docusaurus can generate a full sidebar from your docs folder:
```js title="sidebars.js"
module.exports = {
export default {
myAutogeneratedSidebar: [
// highlight-start
{
@ -67,7 +67,7 @@ docs
And assume every doc's ID is just its file name. If you define an autogenerated sidebar like this:
```js title="sidebars.js"
module.exports = {
export default {
mySidebar: [
'intro',
{
@ -109,7 +109,7 @@ module.exports = {
It would be resolved as:
```js title="sidebars.js"
module.exports = {
export default {
mySidebar: [
'intro',
{
@ -175,7 +175,7 @@ A category index document is a document following one of those filename conventi
This is equivalent to using a category with a [doc link](items.mdx#category-doc-link):
```js title="sidebars.js"
module.exports = {
export default {
docs: [
// highlight-start
{
@ -215,7 +215,7 @@ some-doc
It is possible to opt out any of the category index conventions, or define even more conventions. You can inject your own `isCategoryIndex` matcher through the [`sidebarItemsGenerator`](#customize-the-sidebar-items-generator) callback. For example, you can also pick `intro` as another file name eligible for automatically becoming the category index.
```js title="docusaurus.config.js"
module.exports = {
export default {
plugins: [
[
'@docusaurus/plugin-content-docs',
@ -247,7 +247,7 @@ module.exports = {
Or choose to not have any category index convention.
```js title="docusaurus.config.js"
module.exports = {
export default {
plugins: [
[
'@docusaurus/plugin-content-docs',
@ -426,7 +426,7 @@ Updating a number prefix can be annoying, as it can require **updating multiple
You can provide a custom `sidebarItemsGenerator` function in the docs plugin (or preset) config:
```js title="docusaurus.config.js"
module.exports = {
export default {
plugins: [
[
'@docusaurus/plugin-content-docs',
@ -477,7 +477,7 @@ function reverseSidebarItems(items) {
}
// highlight-end
module.exports = {
export default {
plugins: [
[
'@docusaurus/plugin-content-docs',

16
website/docs/guides/docs/sidebar/index.mdx
View file

@ -16,14 +16,14 @@ To use sidebars on your Docusaurus site:
2. Pass this object into the `@docusaurus/plugin-docs` plugin directly or via `@docusaurus/preset-classic`.
```js title="docusaurus.config.js"
module.exports = {
export default {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
// highlight-next-line
sidebarPath: require.resolve('./sidebars.js'),
sidebarPath: './sidebars.js',
},
},
],
@ -44,7 +44,7 @@ import DocCardList from '@theme/DocCardList';
If the `sidebarPath` is unspecified, Docusaurus [automatically generates a sidebar](autogenerated.mdx) for you, by using the filesystem structure of the `docs` folder:
```js title="sidebars.js"
module.exports = {
export default {
mySidebar: [
{
type: 'autogenerated',
@ -71,7 +71,7 @@ type Sidebar =
For example:
```js title="sidebars.js"
module.exports = {
export default {
mySidebar: [
{
type: 'category',
@ -123,7 +123,7 @@ type SidebarsFile = {
By enabling the `themeConfig.docs.sidebar.hideable` option, you can make the entire sidebar hideable, allowing users to better focus on the content. This is especially useful when content is consumed on medium-sized screens (e.g. tablets).
```js title="docusaurus.config.js"
module.exports = {
export default {
themeConfig: {
// highlight-start
docs: {
@ -141,7 +141,7 @@ module.exports = {
The `themeConfig.docs.sidebar.autoCollapseCategories` 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.
```js title="docusaurus.config.js"
module.exports = {
export default {
themeConfig: {
// highlight-start
docs: {
@ -178,7 +178,7 @@ By default, breadcrumbs are rendered at the top, using the "sidebar path" of the
This behavior can be disabled with plugin options:
```js title="docusaurus.config.js"
module.exports = {
export default {
presets: [
[
'@docusaurus/preset-classic',
@ -201,7 +201,7 @@ A real-world example from the Docusaurus site:
import CodeBlock from '@theme/CodeBlock';
<CodeBlock language="js" title="sidebars.js">
{require('!!raw-loader!@site/sidebars.js')
{require('!!raw-loader!@site/sidebars.ts')
.default
.split('\n')
// remove comments

42
website/docs/guides/docs/sidebar/items.mdx
View file

@ -42,7 +42,7 @@ type SidebarItemDoc =
Example:
```js title="sidebars.js"
module.exports = {
export default {
mySidebar: [
// Normal syntax:
// highlight-start
@ -92,7 +92,7 @@ type SidebarItemLink = {
Example:
```js title="sidebars.js"
module.exports = {
export default {
myLinksSidebar: [
// highlight-start
// External link
@ -133,7 +133,7 @@ type SidebarItemHtml = {
Example:
```js title="sidebars.js"
module.exports = {
export default {
myHtmlSidebar: [
// highlight-start
{
@ -151,7 +151,7 @@ module.exports = {
The menu item is already wrapped in an `<li>` tag, so if your custom item is simple, such as a title, just supply a string as the value and use the `className` property to style it:
```js title="sidebars.js"
module.exports = {
export default {
myHtmlSidebar: [
{
type: 'html',
@ -186,7 +186,7 @@ type SidebarItemCategory = {
Example:
```js title="sidebars.js"
module.exports = {
export default {
docs: [
{
type: 'category',
@ -211,7 +211,7 @@ module.exports = {
Use the [**shorthand syntax**](#category-shorthand) when you don't need customizations:
```js title="sidebars.js"
module.exports = {
export default {
docs: {
Guides: [
'creating-pages',
@ -242,7 +242,7 @@ Autogenerated categories can use the [`_category_.yml`](./autogenerated.mdx#cate
You can auto-generate an index page that displays all the direct children of this category. The `slug` allows you to customize the generated page's route, which defaults to `/category/[categoryName]`.
```js title="sidebars.js"
module.exports = {
export default {
docs: [
{
type: 'category',
@ -276,7 +276,7 @@ Use `generated-index` links as a quick way to get an introductory document.
A category can link to an existing document.
```js title="sidebars.js"
module.exports = {
export default {
docs: [
{
type: 'category',
@ -317,7 +317,7 @@ import DocCardList from '@theme/DocCardList';
We support the option to expand/collapse categories. Categories are collapsible by default, but you can disable collapsing with `collapsible: false`.
```js title="sidebars.js"
module.exports = {
export default {
docs: [
{
type: 'category',
@ -340,7 +340,7 @@ module.exports = {
To make all categories non-collapsible by default, set the `sidebarCollapsible` option in `plugin-content-docs` to `false`:
```js title="docusaurus.config.js"
module.exports = {
export default {
presets: [
[
'@docusaurus/preset-classic',
@ -366,7 +366,7 @@ The option in `sidebars.js` takes precedence over plugin configuration, so it is
Collapsible categories are collapsed by default. If you want them to be expanded on the first render, you can set `collapsed` to `false`:
```js title="sidebars.js"
module.exports = {
export default {
docs: {
Guides: [
'creating-pages',
@ -385,7 +385,7 @@ module.exports = {
Similar to `collapsible`, you can also set the global configuration `options.sidebarCollapsed` to `false`. Individual `collapsed` options in `sidebars.js` will still take precedence over this configuration.
```js title="docusaurus.config.js"
module.exports = {
export default {
presets: [
[
'@docusaurus/preset-classic',
@ -420,7 +420,7 @@ An item with type `doc` can be simply a string representing its ID:
```
```js title="sidebars.js"
module.exports = {
export default {
sidebar: [
// highlight-start
{
@ -438,7 +438,7 @@ module.exports = {
```
```js title="sidebars.js"
module.exports = {
export default {
sidebar: [
// highlight-start
'myDoc',
@ -455,7 +455,7 @@ module.exports = {
So it's possible to simplify the example above to:
```js title="sidebars.js"
module.exports = {
export default {
mySidebar: [
{
type: 'category',
@ -494,7 +494,7 @@ A category item can be represented by an object whose key is its label, and the
```
```js title="sidebars.js"
module.exports = {
export default {
sidebar: [
// highlight-start
{
@ -513,7 +513,7 @@ module.exports = {
```
```js title="sidebars.js"
module.exports = {
export default {
sidebar: [
// highlight-start
{
@ -532,7 +532,7 @@ module.exports = {
This permits us to simplify that example to:
```js title="sidebars.js"
module.exports = {
export default {
mySidebar: [
// highlight-start
{
@ -554,7 +554,7 @@ module.exports = {
Each shorthand object after this transformation will contain exactly one entry. Now consider the further simplified example below:
```js title="sidebars.js"
module.exports = {
export default {
mySidebar: [
// highlight-start
{
@ -581,7 +581,7 @@ Wherever you have an array of items that is reduced to one category shorthand, y
```
```js title="sidebars.js"
module.exports = {
export default {
sidebar: [
{
'Getting started': ['doc1'],
@ -602,7 +602,7 @@ module.exports = {
```
```js title="sidebars.js"
module.exports = {
export default {
sidebar: {
'Getting started': ['doc1'],
Docusaurus: {

11
website/docs/guides/docs/sidebar/multiple-sidebars.mdx
View file

@ -18,7 +18,7 @@ The Docusaurus site is a good example of using multiple sidebars:
Consider this example:
```js title="sidebars.js"
module.exports = {
export default {
tutorialSidebar: {
'Category A': ['doc1', 'doc2'],
},
@ -33,7 +33,7 @@ When browsing `doc1` or `doc2`, the `tutorialSidebar` will be displayed; when br
Following the example above, if a `commonDoc` is included in both sidebars:
```js title="sidebars.js"
module.exports = {
export default {
tutorialSidebar: {
'Category A': ['doc1', 'doc2', 'commonDoc'],
},
@ -51,7 +51,7 @@ When you add doc Y to sidebar X, it creates a two-way binding: sidebar X contain
Front matter option `displayed_sidebar` will forcibly set the sidebar association. For the same example, you can still use doc shorthands without any special configuration:
```js title="sidebars.js"
module.exports = {
export default {
tutorialSidebar: {
'Category A': ['doc1', 'doc2'],
},
@ -88,7 +88,7 @@ If a sidebar is displayed by setting `displayed_sidebar` front matter, and this
You can customize pagination with front matter `pagination_next` and `pagination_prev`. Consider this sidebar:
```js title="sidebars.js"
module.exports = {
export default {
tutorial: [
'introduction',
{
@ -123,7 +123,7 @@ It is particularly useful where you wish to link to the same document from multi
Consider this example:
```js title="sidebars.js"
module.exports = {
export default {
tutorialSidebar: {
'Category A': [
'doc1',
@ -135,7 +135,6 @@ module.exports = {
},
apiSidebar: ['doc3', 'doc4', 'commonDoc'],
};
}
```
You can think of the `ref` type as the equivalent to doing the following:

2
website/docs/guides/docs/versioning.mdx
View file

@ -187,7 +187,7 @@ Docusaurus defaults work great for the first use case. We will label the current
**For the 2nd use case**: if you release v1 and don't plan to work on v2 anytime soon, instead of versioning v1 and having to maintain the docs in 2 folders (`./docs` + `./versioned_docs/version-1.0.0`), you may consider "pretending" that the current version is a cut version by giving it a path and a label:
```js title="docusaurus.config.js"
module.exports = {
export default {
presets: [
'@docusaurus/preset-classic',
docs: {