diff --git a/website/docs/api/plugin-methods/extend-infrastructure.md b/website/docs/api/plugin-methods/extend-infrastructure.md index fffc17b2e4..f4a5bc89db 100644 --- a/website/docs/api/plugin-methods/extend-infrastructure.md +++ b/website/docs/api/plugin-methods/extend-infrastructure.md @@ -14,15 +14,17 @@ Use this for files that are consumed server-side, because theme files are automa Example: -```js {5-7} title="docusaurus-plugin/src/index.js" +```js title="docusaurus-plugin/src/index.js" const path = require('path'); module.exports = function (context, options) { return { name: 'docusaurus-plugin', + // highlight-start getPathsToWatch() { const contentPath = path.resolve(context.siteDir, options.path); return [`${contentPath}/**/*.{ts,tsx}`]; }, + // highlight-end }; }; ``` @@ -39,10 +41,11 @@ The commander version matters! We use commander v5, and make sure you are referr Example: -```js {4-11} title="docusaurus-plugin/src/index.js" +```js title="docusaurus-plugin/src/index.js" module.exports = function (context, options) { return { name: 'docusaurus-plugin', + // highlight-start extendCli(cli) { cli .command('roll') @@ -51,6 +54,7 @@ module.exports = function (context, options) { console.log(Math.floor(Math.random() * 1000 + 1)); }); }, + // highlight-end }; }; ``` @@ -61,15 +65,17 @@ Returns the path to the directory where the theme components can be found. When For example, your `getThemePath` can be: -```js {6-8} title="my-theme/src/index.js" +```js title="my-theme/src/index.js" const path = require('path'); module.exports = function (context, options) { return { name: 'my-theme', + // highlight-start getThemePath() { return path.resolve(__dirname, './theme'); }, + // highlight-end }; }; ``` @@ -88,12 +94,13 @@ You should also format these files with Prettier. Remember—JS files can and wi Example: -```js {6-13} title="my-theme/src/index.js" +```js title="my-theme/src/index.js" const path = require('path'); module.exports = function (context, options) { return { name: 'my-theme', + // highlight-start getThemePath() { // Where compiled JavaScript output lives return path.join(__dirname, '../lib/theme'); @@ -102,6 +109,7 @@ module.exports = function (context, options) { // Where TypeScript source code lives return path.resolve(__dirname, '../src/theme'); }, + // highlight-end }; }; ``` @@ -112,7 +120,7 @@ module.exports = function (context, options) { Returns a list of stable components that are considered safe for swizzling. These components will be swizzlable without `--danger`. All components are considered unstable by default. If an empty array is returned, all components are considered unstable. If `undefined` is returned, all components are considered stable. -```js {0-12} title="my-theme/src/index.js" +```js title="my-theme/src/index.js" const swizzleAllowedComponents = [ 'CodeBlock', 'DocSidebar', diff --git a/website/docs/api/plugin-methods/lifecycle-apis.md b/website/docs/api/plugin-methods/lifecycle-apis.md index de4f7677d7..1b3afebe59 100644 --- a/website/docs/api/plugin-methods/lifecycle-apis.md +++ b/website/docs/api/plugin-methods/lifecycle-apis.md @@ -13,13 +13,15 @@ Plugins should use this lifecycle to fetch from data sources (filesystem, remote For example, this plugin below return a random integer between 1 to 10 as content. -```js {5-6} title="docusaurus-plugin/src/index.js" +```js title="docusaurus-plugin/src/index.js" module.exports = function (context, options) { return { name: 'docusaurus-plugin', + // highlight-start async loadContent() { return 1 + Math.floor(Math.random() * 10); }, + // highlight-end }; }; ``` @@ -75,10 +77,11 @@ export default function FriendsComponent({friends}) { } ``` -```js {4-23} title="docusaurus-friends-plugin/src/index.js" +```js title="docusaurus-friends-plugin/src/index.js" export default function friendsPlugin(context, options) { return { name: 'docusaurus-friends-plugin', + // highlight-start async contentLoaded({content, actions}) { const {createData, addRoute} = actions; // Create friends.json @@ -99,6 +102,7 @@ export default function friendsPlugin(context, options) { exact: true, }); }, + // highlight-end }; } ``` @@ -127,10 +131,11 @@ export default function FriendsComponent() { } ``` -```js {4-14} title="docusaurus-friends-plugin/src/index.js" +```js title="docusaurus-friends-plugin/src/index.js" export default function friendsPlugin(context, options) { return { name: 'docusaurus-friends-plugin', + // highlight-start async contentLoaded({content, actions}) { const {setGlobalData, addRoute} = actions; // Create friends global data @@ -143,6 +148,7 @@ export default function friendsPlugin(context, options) { exact: true, }); }, + // highlight-end }; } ``` @@ -280,16 +286,18 @@ interface Props { Example: -```js {4-11} title="docusaurus-plugin/src/index.js" +```js title="docusaurus-plugin/src/index.js" module.exports = function (context, options) { return { name: 'docusaurus-plugin', + // highlight-start async postBuild({siteConfig = {}, routesPaths = [], outDir}) { // Print out to console all the rendered routes. routesPaths.map((route) => { console.log(route); }); }, + // highlight-end }; }; ``` @@ -373,16 +381,18 @@ Returns an array of paths to the modules that are to be imported into the client As an example, to make your theme load a `customCss` or `customJs` file path from `options` passed in by the user: -```js {7-9} title="my-theme/src/index.js" +```js title="my-theme/src/index.js" const path = require('path'); module.exports = function (context, options) { const {customCss, customJs} = options || {}; return { name: 'name-of-my-theme', + // highlight-start getClientModules() { return [customCss, customJs]; }, + // highlight-end }; }; ``` diff --git a/website/docs/api/plugin-methods/static-methods.md b/website/docs/api/plugin-methods/static-methods.md index c3bb4e730f..e9caa3ba38 100644 --- a/website/docs/api/plugin-methods/static-methods.md +++ b/website/docs/api/plugin-methods/static-methods.md @@ -28,7 +28,7 @@ To avoid mixing Joi versions, use `const {Joi} = require("@docusaurus/utils-vali If you don't use **[Joi](https://www.npmjs.com/package/joi)** for validation you can throw an Error in case of invalid options and return options in case of success. -```js {8-11} title="my-plugin/src/index.js" +```js title="my-plugin/src/index.js" function myPlugin(context, options) { return { name: 'docusaurus-plugin', @@ -36,17 +36,19 @@ function myPlugin(context, options) { }; } +// highlight-start myPlugin.validateOptions = ({options, validate}) => { const validatedOptions = validate(myValidationSchema, options); return validationOptions; }; +// highlight-end module.exports = myPlugin; ``` In TypeScript, you can also choose to export this as a separate named export. -```ts {8-11} title="my-plugin/src/index.ts" +```ts title="my-plugin/src/index.ts" export default function (context, options) { return { name: 'docusaurus-plugin', @@ -54,10 +56,12 @@ export default function (context, options) { }; } +// highlight-start export function validateOptions({options, validate}) { const validatedOptions = validate(myValidationSchema, options); return validationOptions; } +// highlight-end ``` ## `validateThemeConfig({themeConfig, validate})` {#validateThemeConfig} @@ -82,7 +86,7 @@ To avoid mixing Joi versions, use `const {Joi} = require("@docusaurus/utils-vali If you don't use **[Joi](https://www.npmjs.com/package/joi)** for validation you can throw an Error in case of invalid options. -```js {8-11} title="my-theme/src/index.js" +```js title="my-theme/src/index.js" function myPlugin(context, options) { return { name: 'docusaurus-plugin', @@ -90,17 +94,19 @@ function myPlugin(context, options) { }; } +// highlight-start myPlugin.validateThemeConfig = ({themeConfig, validate}) => { const validatedThemeConfig = validate(myValidationSchema, options); return validatedThemeConfig; }; +// highlight-end module.exports = validateThemeConfig; ``` In TypeScript, you can also choose to export this as a separate named export. -```ts {8-11} title="my-theme/src/index.ts" +```ts title="my-theme/src/index.ts" export default function (context, options) { return { name: 'docusaurus-plugin', @@ -108,8 +114,10 @@ export default function (context, options) { }; } +// highlight-start export function validateThemeConfig({themeConfig, validate}) { const validatedThemeConfig = validate(myValidationSchema, options); return validatedThemeConfig; } +// highlight-end ``` diff --git a/website/docs/api/themes/theme-live-codeblock.md b/website/docs/api/themes/theme-live-codeblock.md index 71e04a33ae..75e803499e 100644 --- a/website/docs/api/themes/theme-live-codeblock.md +++ b/website/docs/api/themes/theme-live-codeblock.md @@ -13,7 +13,7 @@ npm install --save @docusaurus/theme-live-codeblock ### Configuration {#configuration} -```jsx title="docusaurus.config.js" +```js title="docusaurus.config.js" module.exports = { plugins: ['@docusaurus/theme-live-codeblock'], themeConfig: { diff --git a/website/docs/blog.mdx b/website/docs/blog.mdx index 04e495224a..f8cd8b7bdf 100644 --- a/website/docs/blog.mdx +++ b/website/docs/blog.mdx @@ -475,7 +475,7 @@ type BlogOptions = { Example usage: -```js {8-11} title="docusaurus.config.js" +```js title="docusaurus.config.js" module.exports = { // ... presets: [ @@ -483,10 +483,12 @@ module.exports = { '@docusaurus/preset-classic', { blog: { + // highlight-start feedOptions: { type: 'all', copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`, }, + // highlight-end }, }, ], diff --git a/website/docs/browser-support.md b/website/docs/browser-support.md index 4f374c7e9d..0161d041f4 100644 --- a/website/docs/browser-support.md +++ b/website/docs/browser-support.md @@ -21,10 +21,11 @@ On old browsers, the compiled output will use unsupported (too recent) JS syntax Websites initialized with the default classic template has the following in `package.json`: -```json {4-11} title="package.json" +```json title="package.json" { "name": "docusaurus", // ... + // highlight-start "browserslist": { "production": [">0.5%", "not dead", "not op_mini all"], "development": [ @@ -33,6 +34,7 @@ Websites initialized with the default classic template has the following in `pac "last 1 safari version" ] } + // highlight-end // ... } ``` diff --git a/website/docs/deployment.mdx b/website/docs/deployment.mdx index 67a558c0c6..942559e2cf 100644 --- a/website/docs/deployment.mdx +++ b/website/docs/deployment.mdx @@ -124,10 +124,12 @@ For the same concern of up-to-datedness, we have stopped accepting PRs adding ne To deploy your Docusaurus 2 sites to [Netlify](https://www.netlify.com/), first make sure the following options are properly configured: -```js {2-3} title="docusaurus.config.js" +```js title="docusaurus.config.js" module.exports = { + // highlight-start url: 'https://docusaurus-2.netlify.app', // Url to your site with no trailing slash baseUrl: '/', // Base directory of your site relative to your repo + // highlight-end // ... }; ``` @@ -228,14 +230,16 @@ GitHub Pages adds a trailing slash to Docusaurus URLs by default. It is recommen Example: -```jsx {3-6} title="docusaurus.config.js" +```js title="docusaurus.config.js" module.exports = { // ... url: 'https://endiliey.github.io', // Your website URL baseUrl: '/', + // highlight-start projectName: 'endiliey.github.io', organizationName: 'endiliey', trailingSlash: false, + // highlight-end // ... }; ``` diff --git a/website/docs/docusaurus-core.md b/website/docs/docusaurus-core.md index ec35ee0652..6fec152f62 100644 --- a/website/docs/docusaurus-core.md +++ b/website/docs/docusaurus-core.md @@ -63,33 +63,40 @@ This reusable React component will manage all of your changes to the document he Usage Example: -```jsx {2,5,10} +```jsx import React from 'react'; +// highlight-next-line import Head from '@docusaurus/Head'; const MySEO = () => ( + // highlight-start My Title + // highlight-end ); ``` Nested or latter components will override duplicate usages: -```jsx {2,5,8,11} +```jsx + {/* highlight-start */} My Title + {/* highlight-end */} + {/* highlight-start */} Nested Title + {/* highlight-end */} ``` @@ -111,16 +118,19 @@ The component is a wrapper around react-router’s `` component that adds External links also work, and automatically have these props: `target="_blank" rel="noopener noreferrer"`. -```jsx {2,7} +```jsx import React from 'react'; +// highlight-next-line import Link from '@docusaurus/Link'; const Page = () => (

+ {/* highlight-next-line */} Check out my blog!

+ {/* highlight-next-line */} Follow me on Twitter!

@@ -147,11 +157,13 @@ Rendering a `` will navigate to a new location. The new location will Example usage: -```jsx {2,5} +```jsx import React from 'react'; +// highlight-next-line import {Redirect} from '@docusaurus/router'; const Home = () => { + // highlight-next-line return ; }; ``` @@ -358,17 +370,20 @@ interface DocusaurusContext { Usage example: -```jsx {5,8-10} +```jsx import React from 'react'; import useDocusaurusContext from '@docusaurus/useDocusaurusContext'; const MyComponent = () => { + // highlight-next-line const {siteConfig, siteMetadata} = useDocusaurusContext(); return (
+ {/* highlight-start */}

{siteConfig.title}

{siteMetadata.siteVersion}
{siteMetadata.docusaurusVersion}
+ {/* highlight-end */}
); }; @@ -500,14 +515,17 @@ type GlobalData = Record< Usage example: -```jsx {2,5-7} +```jsx import React from 'react'; +// highlight-next-line import useGlobalData from '@docusaurus/useGlobalData'; const MyComponent = () => { + // highlight-start const globalData = useGlobalData(); const myPluginData = globalData['my-plugin']['default']; return
{myPluginData.someAttribute}
; + // highlight-end }; ``` @@ -531,13 +549,16 @@ function usePluginData(pluginName: string, pluginId?: string); Usage example: -```jsx {2,5-6} +```jsx import React from 'react'; +// highlight-next-line import {usePluginData} from '@docusaurus/useGlobalData'; const MyComponent = () => { + // highlight-start const myPluginData = usePluginData('my-plugin'); return
{myPluginData.someAttribute}
; + // highlight-end }; ``` @@ -551,14 +572,17 @@ useAllPluginInstancesData(pluginName: string) Usage example: -```jsx {2,5-7} +```jsx import React from 'react'; +// highlight-next-line import {useAllPluginInstancesData} from '@docusaurus/useGlobalData'; const MyComponent = () => { + // highlight-start const allPluginInstancesData = useAllPluginInstancesData('my-plugin'); const myPluginData = allPluginInstancesData['default']; return
{myPluginData.someAttribute}
; + // highlight-end }; ``` @@ -583,10 +607,9 @@ function interpolate( #### Example {#example-1} -```jsx -// highlight-start +```js +// highlight-next-line import {interpolate} from '@docusaurus/Interpolate'; -// highlight-end const message = interpolate('Welcome {firstName}', {firstName: 'Sébastien'}); ``` @@ -620,17 +643,14 @@ function translate( import React from 'react'; import Layout from '@theme/Layout'; -// highlight-start +// highlight-next-line import {translate} from '@docusaurus/Translate'; -// highlight-end export default function Home() { return ( + // highlight-next-line + title={translate({message: 'My page meta title'})}> Docusaurus themed image; ``` diff --git a/website/docs/guides/markdown-features/markdown-features-code-blocks.mdx b/website/docs/guides/markdown-features/markdown-features-code-blocks.mdx index d3638dd7ba..42c9ad3340 100644 --- a/website/docs/guides/markdown-features/markdown-features-code-blocks.mdx +++ b/website/docs/guides/markdown-features/markdown-features-code-blocks.mdx @@ -34,7 +34,7 @@ function HelloCodeTitle(props) { Code blocks are text blocks wrapped around by strings of 3 backticks. You may check out [this reference](https://github.com/mdx-js/specification) for the specifications of MDX. - ```jsx + ```js console.log('Every repo must come with a mascot.'); ``` @@ -44,7 +44,7 @@ Use the matching language meta string for your code block, and Docusaurus will p -```jsx +```js console.log('Every repo must come with a mascot.'); ``` @@ -56,10 +56,11 @@ By default, the Prism [syntax highlighting theme](https://github.com/FormidableL For example, if you prefer to use the `dracula` highlighting theme: -```js {4} title="docusaurus.config.js" +```js title="docusaurus.config.js" module.exports = { themeConfig: { prism: { + // highlight-next-line theme: require('prism-react-renderer/themes/dracula'), }, }, @@ -80,11 +81,12 @@ To add syntax highlighting for any of the other [Prism-supported languages](http For example, if you want to add highlighting for the PowerShell language: -```js {5} title="docusaurus.config.js" +```js title="docusaurus.config.js" module.exports = { // ... themeConfig: { prism: { + // highlight-next-line additionalLanguages: ['powershell'], }, // ... @@ -102,14 +104,15 @@ npm run swizzle @docusaurus/theme-classic prism-include-languages It will produce `prism-include-languages.js` in your `src/theme` folder. You can add highlighting support for custom languages by editing `prism-include-languages.js`: -```js {8} title="src/theme/prism-include-languages.js" +```js title="src/theme/prism-include-languages.js" const prismIncludeLanguages = (Prism) => { // ... additionalLanguages.forEach((lang) => { - require(`prismjs/components/prism-${lang}`); // eslint-disable-line + require(`prismjs/components/prism-${lang}`); }); + // highlight-next-line require('/path/to/your/prism-language-definition'); // ... @@ -124,7 +127,7 @@ You can refer to [Prism's official language definitions](https://github.com/Pris You can use comments with `highlight-next-line`, `highlight-start`, and `highlight-end` to select which lines are highlighted. - ```jsx + ```js function HighlightSomeText(highlight) { if (highlight) { // highlight-next-line @@ -148,7 +151,7 @@ You can use comments with `highlight-next-line`, `highlight-start`, and `highlig ````mdx-code-block -```jsx +```js function HighlightSomeText(highlight) { if (highlight) { // highlight-next-line @@ -348,9 +351,10 @@ By default, all React imports are available. If you need more imports available, npm run swizzle @docusaurus/theme-live-codeblock ReactLiveScope ``` -```jsx {3-15,21} title="src/theme/ReactLiveScope/index.js" +```jsx title="src/theme/ReactLiveScope/index.js" import React from 'react'; +// highlight-start const ButtonExample = (props) => (