diff --git a/website/docs/blog.md b/website/docs/blog.md index ea2dec558e..9c0d868b70 100644 --- a/website/docs/blog.md +++ b/website/docs/blog.md @@ -9,12 +9,19 @@ To setup your site's blog, start by creating a `blog` directory. Then, add a navbar link to your blog within `docusaurus.config.js`: -```js -links: [ - ... - {to: 'blog', label: 'Blog', position: 'left'}, // or position: 'right' - ... -] +```js title="docusaurus.config.js" +module.exports = { + themeConfig: { + // ... + navbar: { + links: [ + // ... + // highlight-next-line + {to: 'blog', label: 'Blog', position: 'left'}, // or position: 'right' + ], + }, + }, +}; ``` ## Adding posts @@ -128,7 +135,7 @@ https://{your-domain}/blog/atom.xml ### 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 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. **Note:** Make sure there's no `index.js` page in `src/pages` or else there will be two files mapping to the same route! @@ -141,7 +148,7 @@ module.exports = { { blog: { path: './blog', - routeBasePath: '/', // Set this value to '/'. + routeBasePath: '', // Set this value to ''. }, }, ], diff --git a/website/docs/configuration.md b/website/docs/configuration.md index ea06d73174..b99c625f02 100644 --- a/website/docs/configuration.md +++ b/website/docs/configuration.md @@ -109,14 +109,16 @@ Docusaurus guards `docusaurus.config.js` from unknown fields. To add a custom fi Example: -```js {3-6} title="docusaurus.config.js" +```js title="docusaurus.config.js" module.exports = { - ... + // ... + // highlight-start customFields: { image: '', keywords: [], }, - ... + // highlight-end + // ... }; ``` @@ -126,13 +128,16 @@ Your configuration object will be made available to all the components of your s Basic Example: -```jsx {2,5-6} +```jsx import React from 'react'; +// highlight-next-line import useDocusaurusContext from '@docusaurus/useDocusaurusContext'; const Hello = () => { + // highlight-start const context = useDocusaurusContext(); const {siteConfig = {}} = context; + // highlight-end const {title, tagline} = siteConfig; return
{`${title} · ${tagline}`}
; diff --git a/website/docs/creating-pages.md b/website/docs/creating-pages.md index 887060f722..fb61af8280 100644 --- a/website/docs/creating-pages.md +++ b/website/docs/creating-pages.md @@ -13,7 +13,7 @@ The functionality of pages is powered by `@docusaurus/plugin-content-pages`. In the `/src/pages/` directory, create a file called `hello.js` with the following contents: -```jsx +```jsx title="/src/pages/hello.js" import React from 'react'; import Layout from '@theme/Layout'; diff --git a/website/docs/deployment.md b/website/docs/deployment.md index e31bcd399a..3dac6d4232 100644 --- a/website/docs/deployment.md +++ b/website/docs/deployment.md @@ -36,13 +36,13 @@ Example: ```jsx {3-6} title="docusaurus.config.js" module.exports = { - ... + // ... url: 'https://endiliey.github.io', // Your website URL baseUrl: '/', projectName: 'endiliey.github.io', - organizationName: 'endiliey' - ... -} + organizationName: 'endiliey', + // ... +}; ``` :::tip @@ -119,7 +119,7 @@ To deploy your Docusaurus 2 sites to [Netlify](https://www.netlify.com/), first module.exports = { url: 'https://docusaurus-2.netlify.com', // url to your site with no trailing slash baseUrl: '/', // base directory of your site relative to your repo - ... + // ... }; ``` diff --git a/website/docs/docs.md b/website/docs/docs.md index fed1dbb8d0..d44c89ebed 100644 --- a/website/docs/docs.md +++ b/website/docs/docs.md @@ -44,7 +44,7 @@ module.exports = { // Sidebars filepath relative to the site dir. sidebarPath: require.resolve('./sidebars.js'), }, - ... + // ... }, ], ], @@ -248,12 +248,12 @@ For sites with a sizable amount of content, we support the option to expand/coll ```js {4} title="docusaurus.config.js" module.exports = { - ... + // ... themeConfig: { sidebarCollapsible: false, - ... + // ... }, -} +}; ``` ## Docs-only mode @@ -271,7 +271,7 @@ module.exports = { { docs: { routeBasePath: '', // Set to empty string. - ... + // ... }, }, ], @@ -280,7 +280,7 @@ module.exports = { }; ``` -2. Set up a redirect to the initial document on the home page in `src/pages/index.js`, e.g. for the document `getting-started`. This is needed because by default there's no page created for the root of the docs. +2. Set up a redirect to the initial document on the home page in `/src/pages/index.js`, e.g. for the document `getting-started`. This is needed because by default there's no page created for the root of the docs. ```jsx title="src/pages/index.js" import React from 'react'; @@ -299,6 +299,6 @@ Now, when visiting your site, it will show your initial document instead of a la :::tip -There's also a "blog-only mode", for those who only want to use the blog component of Docusaurus 2. You can use the same method detailed above, except that you need to delete the `src/pages/index.js` file. Follow the setup instructions on [Blog-only mode](blog.md#blog-only-mode). +There's also a "blog-only mode", for those who only want to use the blog component of Docusaurus 2. You can use the same method detailed above, except that you need to delete the `/src/pages/index.js` file. Follow the setup instructions on [Blog-only mode](blog.md#blog-only-mode). ::: diff --git a/website/docs/installation.md b/website/docs/installation.md index 2b62088520..c092aa4972 100644 --- a/website/docs/installation.md +++ b/website/docs/installation.md @@ -107,12 +107,12 @@ Please update to the latest Docusaurus 2 version shown at the top of the page, n ::: -```json - "dependencies": { - "@docusaurus/core": "^2.0.0-alpha.49", - "@docusaurus/preset-classic": "^2.0.0-alpha.49", - ... - } +```json title="package.json" +"dependencies": { + "@docusaurus/core": "^2.0.0-alpha.49", + "@docusaurus/preset-classic": "^2.0.0-alpha.49", + // ... +} ``` Then, in the directory containing `package.json`, run your package manager's install command: @@ -131,7 +131,7 @@ You should see the correct version as output. Alternatively, if you are using Yarn, you can do: -``` +```bash yarn upgrade @docusaurus/core@2.0.0-alpha.49 @docusaurus/preset-classic@2.0.0-alpha.49 ``` diff --git a/website/docs/markdown-features.mdx b/website/docs/markdown-features.mdx index a4623cd860..6af41a403e 100644 --- a/website/docs/markdown-features.mdx +++ b/website/docs/markdown-features.mdx @@ -469,13 +469,13 @@ Code blocks within documentation are super-powered 💪. You can add a title to the code block by adding `title` key after the language (leave a space between them). - ```jsx title="src/components/HelloCodeTitle.js" + ```jsx title="/src/components/HelloCodeTitle.js" function HelloCodeTitle(props) { return

Hello, {props.name}

; } ``` -```jsx title="src/components/HelloCodeTitle.js" +```jsx title="/src/components/HelloCodeTitle.js" function HelloCodeTitle(props) { return

Hello, {props.name}

; } @@ -520,12 +520,12 @@ For example, if you want to add highlighting for the `powershell` language: ```js {5} title="docusaurus.config.js" module.exports = { - ... + // ... themeConfig: { prism: { additionalLanguages: ['powershell'], }, - ... + // ... }, }; ``` @@ -672,9 +672,9 @@ You will also need to add the plugin to your `docusaurus.config.js`. ```js {3} module.exports = { - ... + // ... themes: ['@docusaurus/theme-live-codeblock'], - ... + // ... } ``` diff --git a/website/docs/migrating-from-v1-to-v2.md b/website/docs/migrating-from-v1-to-v2.md index 652b737130..98b1b9cf66 100644 --- a/website/docs/migrating-from-v1-to-v2.md +++ b/website/docs/migrating-from-v1-to-v2.md @@ -62,21 +62,21 @@ Meanwhile, CLI commands are renamed to `docusaurus ` (instead of `docus The `"scripts"` section of your `package.json` should be updated as follows: -```json {3-6} +```json {3-6} title="package.json" { "scripts": { "start": "docusaurus start", "build": "docusaurus build", "swizzle": "docusaurus swizzle", "deploy": "docusaurus deploy" - ... + // ... } } ``` A typical Docusaurus 2 `package.json` may look like this: -```json +```json title="package.json" { "scripts": { "start": "docusaurus start", @@ -112,7 +112,7 @@ If you are deploying to GitHub pages, make sure to run `yarn deploy` instead of The `.gitignore` in your `website` should contain: -``` +```bash title=".gitignore" # dependencies /node_modules @@ -156,7 +156,7 @@ module.exports = { // sidebars file relative to website dir. sidebarPath: require.resolve('./sidebars.json'), }, - ... + // ... }, ], ], @@ -245,7 +245,7 @@ module.exports = { In Docusaurus 1, header icon and header links were root fields in `siteConfig`: -```js +```js title="siteConfig.js" headerIcon: 'img/docusaurus.svg', headerLinks: [ { doc: "doc1", label: "Getting Started" }, @@ -428,7 +428,7 @@ In previous version, nested sidebar category is not allowed and sidebar category You'll have to migrate your sidebar if it contains category type. Rename `subcategory` to `category` and `ids` to `items`. -```js +```js title="sidebars.json" { - type: 'subcategory', + type: 'category', @@ -615,7 +615,7 @@ So v1 users need to migrate their versioned_sidebars file Example `versioned_sidebars/version-1.0.0-sidebars.json`: -```json {2-3,5-6,9-10} +```json {2-3,5-6,9-10} title="versioned_sidebars/version-1.0.0-sidebars.json" { + "version-1.0.0/docs": { - "version-1.0.0-docs": { diff --git a/website/docs/presets.md b/website/docs/presets.md index a0116928af..fd1372cf61 100644 --- a/website/docs/presets.md +++ b/website/docs/presets.md @@ -72,14 +72,14 @@ This is especially useful when some plugins and themes are intended to be used t The classic preset that is usually shipped by default to new docusaurus website. It is a set of plugins and themes. -| Themes | Plugins | -| -------------------------------- | ----------------------------------- | -| @docusaurus/theme-classic | @docusaurus/plugin-content-docs | -| @docusaurus/theme-search-algolia | @docusaurus/plugin-content-blog | -| | @docusaurus/plugin-content-pages | -| | @docusaurus/plugin-google-analytics | -| | @docusaurus/plugin-google-gtag | -| | @docusaurus/plugin-sitemap | +| Themes | Plugins | +| ---------------------------------- | ------------------------------------- | +| `@docusaurus/theme-classic` | `@docusaurus/plugin-content-docs` | +| `@docusaurus/theme-search-algolia` | `@docusaurus/plugin-content-blog` | +| | `@docusaurus/plugin-content-pages` | +| | `@docusaurus/plugin-google-analytics` | +| | `@docusaurus/plugin-google-gtag` | +| | `@docusaurus/plugin-sitemap` | To specify plugin options individually, you can provide the necessary fields to certain plugins, i.e. `customCss` for `@docusaurus/theme-classic`, pass them in the preset field, like this: diff --git a/website/docs/search.md b/website/docs/search.md index 0805afe0e9..76a9225b05 100644 --- a/website/docs/search.md +++ b/website/docs/search.md @@ -18,16 +18,21 @@ Algolia DocSearch works by crawling the content of your website every 24 hours a To connect your docs with Algolia, add an `algolia` field in your `themeConfig`. Note that you will need algolia API key and algolia index. You can [apply for DocSearch here](https://community.algolia.com/docsearch/). -```jsx {3-8} title="docusaurus.config.js" -themeConfig: { +```jsx title="docusaurus.config.js" +module.exports = { + // ... + themeConfig: { // ... + // highlight-start algolia: { appId: 'app-id', apiKey: 'api-key', indexName: 'index-name', algoliaOptions: {}, // Optional, if provided by Algolia }, + // highlight-end }, +}; ``` ### Customizing the Algolia search bar diff --git a/website/docs/styling-layout.md b/website/docs/styling-layout.md index bf29f96ff6..e7b26aa627 100644 --- a/website/docs/styling-layout.md +++ b/website/docs/styling-layout.md @@ -10,16 +10,18 @@ import ColorGenerator from '@site/src/components/ColorGenerator'; If you're using `@docusaurus/preset-classic`, you can create your own CSS files (e.g. `/src/css/custom.css`) and import them globally by passing it as an option into the preset. -```js {7-9} title="docusaurus.config.js" +```js title="docusaurus.config.js" module.exports = { // ... presets: [ [ '@docusaurus/preset-classic', { + // highlight-start theme: { customCss: require.resolve('./src/css/custom.css'), }, + // highlight-end }, ], ], @@ -32,7 +34,7 @@ Any CSS you write within that file will be available globally and can be referen `@docusaurus/preset-classic` uses [Infima](https://facebookincubator.github.io/infima/) as the underlying styling framework. Infima provides flexible layout and common UI components styling suitable for content-centric websites (blogs, documentation, landing pages). For more details, check out the [Infima website](https://facebookincubator.github.io/infima/). -When you `init` your Docusaurus 2 project, the website will be generated with basic Infima stylesheets and default styling. You may customize the styling by editing the `src/css/custom.css` file. +When you `init` your Docusaurus 2 project, the website will be generated with basic Infima stylesheets and default styling. You may customize the styling by editing the `/src/css/custom.css` file. ```css title="/src/css/custom.css" /** @@ -53,7 +55,7 @@ When you `init` your Docusaurus 2 project, the website will be generated with ba Infima uses 7 shades of each color. We recommend using [ColorBox](https://www.colorbox.io/) to find the different shades of colors for your chosen primary color. -Alternatively, use the following tool to generate the different shades for your website and copy the variables into `src/css/custom.css`. +Alternatively, use the following tool to generate the different shades for your website and copy the variables into `/src/css/custom.css`. @@ -142,10 +144,10 @@ npm install --save docusaurus-plugin-sass ```jsx {3} title="docusaurus.config.js" module.exports = { - ... + // ... plugins: ['docusaurus-plugin-sass'], - ... -} + // ... +}; ``` 3. Write and import your stylesheets in Sass/SCSS as normal. @@ -160,11 +162,11 @@ module.exports = { [ '@docusaurus/preset-classic', { - ... + // ... theme: { customCss: require.resolve('./src/css/custom.scss'), }, - ... + // ... }, ], ], diff --git a/website/docs/theme-classic.md b/website/docs/theme-classic.md index 01868ed5a3..c36e90b823 100644 --- a/website/docs/theme-classic.md +++ b/website/docs/theme-classic.md @@ -17,10 +17,10 @@ To remove the ability to switch on dark mode, there is an option `themeConfig.di ```js {4} title="docusaurus.config.js" module.exports = { - ... + // ... themeConfig: { disableDarkMode: false, - ... + // ... }, }; ``` @@ -31,14 +31,14 @@ You can configure a default image that will be used for your meta tag, in partic ```js {4-6} title="docusaurus.config.js" module.exports = { - ... + // ... themeConfig: { // Relative to your site's "static" directory. // Cannot be SVGs. Can be external URLs too. image: 'img/docusaurus.png', - ... + // ... }, -} +}; ``` ### Announcement bar @@ -47,17 +47,18 @@ Sometimes you want to announce something in your website. Just for such a case, ```js {4-9} title="docusaurus.config.js" module.exports = { - ... + // ... themeConfig: { announcementBar: { id: 'support_us', // Any value that will identify this message - content: 'We are looking to revamp our docs, please fill this survey', + content: + 'We are looking to revamp our docs, please fill this survey', backgroundColor: '#fafbfc', // Defaults to `#fff` textColor: '#091E42', // Defaults to `#000` }, - ... + // ... }, -} +}; ``` ## Hooks @@ -91,7 +92,7 @@ To improve dark mode support, you can also set a different logo for this mode. ```js {5-11} title="docusaurus.config.js" module.exports = { - ... + // ... themeConfig: { navbar: { title: 'Site Title', @@ -103,9 +104,9 @@ module.exports = { target: '_self', // by default, this value is calculated based on the `href` attribute (the external link will open in a new tab, all others in the current one) }, }, - ... + // ... }, -} +}; ``` ### Navbar Links @@ -114,7 +115,7 @@ You can add links to the navbar via `themeConfig.navbar.links`: ```js {5-15} title="docusaurus.config.js" module.exports = { - ... + // ... themeConfig: { navbar: { links: [ @@ -129,9 +130,9 @@ module.exports = { // ... other links ], }, - ... + // ... }, -} +}; ``` Outbound links automatically get `target="_blank" rel="noopener noreferrer"` attributes. @@ -142,7 +143,7 @@ Navbar items can also be dropdown items by specifying the `items`, an inner arra ```js {9-19} title="docusaurus.config.js" module.exports = { - ... + // ... themeConfig: { navbar: { links: [ @@ -163,9 +164,9 @@ module.exports = { }, ], }, - ... + // ... }, -} +}; ``` ### Auto-hide sticky navbar @@ -174,14 +175,14 @@ You can enable this cool UI feature that automatically hides the navbar when a u ```js {5} title="docusaurus.config.js" module.exports = { - ... + // ... themeConfig: { navbar: { hideOnScroll: true, }, - ... + // ... }, -} +}; ``` ## Footer @@ -194,13 +195,15 @@ Docusaurus uses [Prism React Renderer](https://github.com/FormidableLabs/prism-r By default, we use [Palenight](https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/themes/palenight.js) as syntax highlighting theme. You can specify a custom theme from the [list of available themes](https://github.com/FormidableLabs/prism-react-renderer/tree/master/src/themes). If you want to use a different syntax highlighting theme when the site is in dark mode, you may also do so. -```js {4-5} title="docusaurus.config.js" +```js {5-6} title="docusaurus.config.js" module.exports = { + // ... themeConfig: { prism: { theme: require('prism-react-renderer/themes/github'), darkTheme: require('prism-react-renderer/themes/dracula'), }, + // ... }, }; ``` @@ -213,12 +216,12 @@ You can set a default language for code blocks if no language is added after the ```js {5} title="docusaurus.config.js" module.exports = { - ... + // ... themeConfig: { prism: { defaultLanguage: 'javascript', }, - ... + // ... }, }; ``` diff --git a/website/docs/using-plugins.md b/website/docs/using-plugins.md index bce6ff9e89..dd697a2e13 100644 --- a/website/docs/using-plugins.md +++ b/website/docs/using-plugins.md @@ -400,12 +400,13 @@ npm install --save @docusaurus/plugin-ideal-image Modify your `docusaurus.config.js` -```diff +```js title="docusaurus.config.js" module.exports = { - ... -+ plugins: ['@docusaurus/plugin-ideal-image'], - ... -} + // ... + // highlight-next-line + plugins: ['@docusaurus/plugin-ideal-image'], + // ... +}; ``` #### Usage diff --git a/website/docs/using-themes.md b/website/docs/using-themes.md index 143098d4cf..9c0986e6f5 100644 --- a/website/docs/using-themes.md +++ b/website/docs/using-themes.md @@ -161,8 +161,8 @@ website There are two lifecycle methods that are essential to theme implementation: -- [getThemePath](lifecycle-apis.md#getthemepath) -- [getClientModules](lifecycle-apis.md#getclientmodules) +- [`getThemePath()`](lifecycle-apis.md#getthemepath) +- [`getClientModules()`](lifecycle-apis.md#getclientmodules)