feat(v2): add plugin for creating search using fuse and scrapping #3153
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
added 2 commits
July 28, 2020 12:30
|
Deploy preview for docusaurus-2 ready! Built with commit 08feab8 |
added 2 commits
July 29, 2020 15:29
Drewbi
suggested changes
Jul 30, 2020
| lv2: 'h3', | ||
| }; | ||
|
|
||
| export const WIEGHT = { |
There was a problem hiding this comment.
Suggested change
| export const WIEGHT = { | |
| export const WEIGHT = { |
Comment on lines
+29
to
+40
| const anchorTest = (node: Node) => | ||
| node && node.properties && (node.properties as Record<string, string>).id; | ||
|
|
||
| const checkAnchor = (node: Node) => | ||
| anchorTest(node) && | ||
| !(node.properties as Record<string, string>).id.startsWith('__'); | ||
|
|
||
| const extractAnchor = (node: Node) => | ||
| checkAnchor(node) | ||
| ? (node.properties as Record<string, string>).id | ||
| : undefined; | ||
|
|
There was a problem hiding this comment.
These could benefit from optional chaining which I believe is supported.
| @@ -0,0 +1,63 @@ | |||
| .modal { | |||
| background: #f5f6f7; | |||
There was a problem hiding this comment.
Take a look at Infima color variables after you've settled on a design. Will help make it easier for people to match this with the rest of their website.
slorber
reviewed
Aug 11, 2020
| import Fuse from 'fuse.js'; | ||
|
|
||
| const flat = <T>(arr: Array<Array<T>>) => | ||
| arr.reduce((acc, curr) => [...acc, ...curr]); |
There was a problem hiding this comment.
I'm fine if you uses Lodash as long as it's only in node code
| }, | ||
|
|
||
| getClientModules() { | ||
| const modules = [require.resolve('infima/dist/css/default/default.css')]; |
There was a problem hiding this comment.
Not sure we want infima here
| async postBuild(props: Props) { | ||
| const files = await Promise.all( | ||
| options.include.map((pattern) => | ||
| promisify(glob)(`${pattern}/index.html`, { |
There was a problem hiding this comment.
Not sure but we may not always end up outputting index.html files here
Also, will this work great with the redirect plugin that write redirect files too?
| const scrapedData = await Promise.all( | ||
| Array.from(uniquefiles).map(async (file) => { | ||
| const content = await readFile(join(props.outDir, file)); | ||
| return {url: dirname(file), dataNodes: scrap(String(content))}; |
There was a problem hiding this comment.
wonder if we shouldn't look for a caninocal url in the HTML doc instead of inferring the URL from dirname?
| }); | ||
| }); | ||
| return nodes; | ||
| } |
There was a problem hiding this comment.
Wonder if you wouldn't have an easier time using JSDom instead of rehype, so that you could write regular selectors directly:
website/static/search_index.json
Outdated
| @@ -0,0 +1 @@ | |||
| {"keys":[{"path":["body"],"id":"body","weight":1,"src":"body"}],"records":[{"i":0,"$":{"0":{"v":"Blog","n":1}}},{"i":1,"$":{"0":{"v":"Initial setup","n":0.707}}},{"i":2,"$":{"0":{"v":"To setup your site's blog, start by creating a blog directory.","n":0.302}}},{"i":3,"$":{"0":{"v":"Then, add a item link to your blog within docusaurus.config.js:","n":0.316}}},{"i":4,"$":{"0":{"v":"Adding posts","n":0.707}}},{"i":5,"$":{"0":{"v":"To publish in the blog, create a file within the blog directory with a formatted name of YYYY-MM-DD-my-blog-post-title.md. The post date is extracted from the file name.","n":0.192}}},{"i":6,"$":{"0":{"v":"For example, at my-website/blog/2019-09-05-hello-docusaurus-v2.md:","n":0.5}}},{"i":7,"$":{"0":{"v":"Header options","n":0.707}}},{"i":8,"$":{"0":{"v":"The only required field is title; however, we provide options to add author information to your blog post as well along with other options.","n":0.204}}},{"i":9,"$":{"0":{"v":"Summary truncation","n":0.707}}},{"i":10,"$":{"0":{"v":"Use the <!--truncate--> marker in your blog post to represent what will be shown as the summary when viewing all published blog posts. Anything above <!--truncate--> will be part of the summary. For example:","n":0.171}}},{"i":11,"$":{"0":{"v":"Feed","n":1}}},{"i":12,"$":{"0":{"v":"You can generate RSS/ Atom feed by passing feedOptions.","n":0.333}}},{"i":13,"$":{"0":{"v":"Example usage:","n":0.707}}},{"i":14,"$":{"0":{"v":"Accessing the feed:","n":0.577}}},{"i":15,"$":{"0":{"v":"The feed for RSS can be found at:","n":0.354}}},{"i":16,"$":{"0":{"v":"and for Atom:","n":0.577}}},{"i":17,"$":{"0":{"v":"Advanced topics","n":0.707}}},{"i":18,"$":{"0":{"v":"Blog-only mode","n":0.707}}},{"i":19,"$":{"0":{"v":"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.","n":0.169}}},{"i":20,"$":{"0":{"v":"Don't forget to delete the existing homepage at ./src/pages/index.js or else there will be two files mapping to the same route!","n":0.218}}},{"i":21,"$":{"0":{"v":"Multiple blogs","n":0.707}}},{"i":22,"$":{"0":{"v":"By default, the classic theme assumes only one blog per website and hence includes only one instance of the blog plugin. If you would like to have multiple blogs on a single website, it's possible too! You can add another blog by specifying another blog plugin in the plugins option for docusaurus.config.js.","n":0.139}}},{"i":23,"$":{"0":{"v":"Set the routeBasePath to the URL route that you want your second blog to be accessed on. Note that the routeBasePath here has to be different from the first blog or else there could be a collision of paths! Also, set path to the path to the directory containing your second blog's entries.","n":0.137}}},{"i":24,"$":{"0":{"v":"CLI","n":1}}},{"i":25,"$":{"0":{"v":"Docusaurus provides a set of scripts to help you generate, serve, and deploy your website.","n":0.258}}},{"i":26,"$":{"0":{"v":"Once your website is bootstrapped, the website source will contain the Docusaurus scripts that you can invoke with your package manager:","n":0.218}}},{"i":27,"$":{"0":{"v":"Docusaurus CLI commands","n":0.577}}},{"i":28,"$":{"0":{"v":"Below is a list of Docusaurus CLI commands and their usages:","n":0.302}}},{"i":29,"$":{"0":{"v":"docusaurus start","n":0.707}}},{"i":30,"$":{"0":{"v":"Builds and serves a preview of your site locally with Webpack Dev Server.","n":0.277}}},{"i":31,"$":{"0":{"v":"Please note that some functionality (for example, anchor links) will not work in development. The functionality will work as expected in production.","n":0.213}}},{"i":32,"$":{"0":{"v":"docusaurus build","n":0.707}}},{"i":33,"$":{"0":{"v":"Compiles your site for production.","n":0.447}}},{"i":34,"$":{"0":{"v":"docusaurus swizzle","n":0.707}}},{"i":35,"$":{"0":{"v":"We highly discourage swizzling of components until we've reached a Beta stage. The components APIs have been changing rapidly and are likely to keep changing until we reach Beta. Stick with the default appearance for now if possible to save yourself some potential pain in future.","n":0.147}}},{"i":36,"$":{"0":{"v":"Change any Docusaurus theme components to your liking with docusaurus swizzle.","n":0.302}}},{"i":37,"$":{"0":{"v":"Running the command will copy the relevant theme files to your site folder. You may then make any changes to it and Docusaurus will use it instead of the one provided from the theme.","n":0.171}}},{"i":38,"$":{"0":{"v":"To unswizzle a component, simply delete the files of the swizzled component.","n":0.289}}},{"i":39,"$":{"0":{"v":"docusaurus deploy","n":0.707}}},{"i":40,"$":{"0":{"v":"Deploys your site with GitHub Pages. Check out the docs on deployment for more details.","n":0.258}}},{"i":41,"$":{"0":{"v":"docusaurus serve","n":0.707}}},{"i":42,"$":{"0":{"v":"Serve your built website localy.","n":0.447}}},{"i":43,"$":{"0":{"v":"Configuration","n":1}}},{"i":44,"$":{"0":{"v":"Docusaurus has a unique take on configurations. We encourage you to congregate information of your site into one place. We guard the fields of this file, and facilitate making this data object accessible across your site.","n":0.167}}},{"i":45,"$":{"0":{"v":"Keeping a well-maintained docusaurus.config.js helps you, your collaborators, and your open source contributors be able to focus on documentation while still being able to customize the site.","n":0.192}}},{"i":46,"$":{"0":{"v":"What goes into a docusaurus.config.js?","n":0.447}}},{"i":47,"$":{"0":{"v":"You should not have to write your docusaurus.config.js from scratch even if you are developing your site. All templates come with a docusaurus.config.js that includes defaults for the common options.","n":0.183}}},{"i":48,"$":{"0":{"v":"However, it can be helpful if you have a high-level understanding of how the configurations are designed and implemented.","n":0.229}}},{"i":49,"$":{"0":{"v":"The high-level overview of Docusaurus configuration can be categorized into:","n":0.316}}},{"i":50,"$":{"0":{"v":"For exact reference to each of the configurable fields, you may refer to docusaurus.config.js API reference.","n":0.25}}},{"i":51,"$":{"0":{"v":"Site metadata","n":0.707}}},{"i":52,"$":{"0":{"v":"Site metadata contains the essential global metadata such as title, url, baseUrl and favicon.","n":0.267}}},{"i":53,"$":{"0":{"v":"They are used in a number of places such as your site's title and headings, browser tab icon, social sharing (Facebook, Twitter) information or even to generate the correct path to serve your static files.","n":0.169}}},{"i":54,"$":{"0":{"v":"Deployment configurations","n":0.707}}},{"i":55,"$":{"0":{"v":"Deployment configurations such as projectName and organizationName are used when you deploy your site with the deploy command.","n":0.236}}},{"i":56,"$":{"0":{"v":"It is recommended to check the deployment docs for more information.","n":0.302}}},{"i":57,"$":{"0":{"v":"Theme, plugin, and preset configurations","n":0.447}}},{"i":58,"$":{"0":{"v":"List the theme, plugins, and presets for your site in the themes, plugins, and presets fields, respectively. These are typically npm packages:","n":0.213}}},{"i":59,"$":{"0":{"v":"They can also be loaded from local directories:","n":0.354}}},{"i":60,"$":{"0":{"v":"To specify options for a plugin or theme, replace the name of the plugin or theme in the config file with an array containing the name and an options object:","n":0.183}}},{"i":61,"$":{"0":{"v":"To specify options for a plugin or theme that is bundled in a preset, pass the options through the presets field. In this example, docs refers to @docusaurus/plugin-content-docs and theme refers to @docusaurus/theme-classic.","n":0.174}}},{"i":62,"$":{"0":{"v":"For further help configuring themes, plugins, and presets, see Using Themes, Using Plugins, and Using Presets.","n":0.25}}},{"i":63,"$":{"0":{"v":"Custom configurations","n":0.707}}},{"i":64,"$":{"0":{"v":"Docusaurus guards docusaurus.config.js from unknown fields. To add custom fields, define them in customFields.","n":0.267}}},{"i":65,"$":{"0":{"v":"Example:","n":1}}},{"i":66,"$":{"0":{"v":"Accessing configuration from components","n":0.5}}},{"i":67,"$":{"0":{"v":"Your configuration object will be made available to all the components of your site. And you may access them via React context as siteConfig.","n":0.204}}},{"i":68,"$":{"0":{"v":"Basic example:","n":0.707}}},{"i":69,"$":{"0":{"v":"If you just want to use those fields on the client side, you could create your own JS files and import them as ES6 modules, there is no need to put them in docusaurus.config.js.","n":0.171}}},{"i":70,"$":{"0":{"v":"Customizing Babel Configuration","n":0.577}}},{"i":71,"$":{"0":{"v":"For new Docusaurus projects, we automatically generated a babel.config.js in project root.","n":0.289}}},{"i":72,"$":{"0":{"v":"Most of the times, this configuration will work just fine. If you want to customize it, you can directly edit this file to customize babel configuration. For your changes to take effect, you need to restart Docusaurus devserver.","n":0.162}}},{"i":73,"$":{"0":{"v":"Contributing","n":1}}},{"i":74,"$":{"0":{"v":"Docusaurus 2 is currently under alpha development. We have early adopters who already started using it. We are now welcoming contributors to collaborate on the next Docusaurus.","n":0.192}}},{"i":75,"$":{"0":{"v":"The Open Source Guides website has a collection of resources for individuals, communities, and companies who want to learn how to run and contribute to an open source project. Contributors and people new to open source alike will find the following guides especially useful:","n":0.151}}},{"i":76,"$":{"0":{"v":"Code of Conduct","n":0.577}}},{"i":77,"$":{"0":{"v":"Facebook has adopted a Code of Conduct that we expect project participants to adhere to. Please read the full text so that you can understand what actions will and will not be tolerated.","n":0.174}}},{"i":78,"$":{"0":{"v":"Get involved","n":0.707}}},{"i":79,"$":{"0":{"v":"There are many ways to contribute to Docusaurus, and many of them do not involve writing any code. Here's a few ideas to get started:","n":0.2}}},{"i":80,"$":{"0":{"v":"Contributions are very welcome. If you think you need help planning your contribution, please ping us on Twitter at @docusaurus and let us know you are looking for a bit of help.","n":0.177}}},{"i":81,"$":{"0":{"v":"Join our Discord channel","n":0.5}}},{"i":82,"$":{"0":{"v":"To participate in Docusaurus 2 dev, join the #docusaurus-2-dev channel.","n":0.316}}},{"i":83,"$":{"0":{"v":"Our development process","n":0.577}}},{"i":84,"$":{"0":{"v":"Docusaurus uses GitHub as its source of truth. The core team will be working directly there. All changes will be public from the beginning.","n":0.204}}},{"i":85,"$":{"0":{"v":"When a change made on GitHub is approved, it will be checked by our continuous integration system, CircleCI.","n":0.236}}},{"i":86,"$":{"0":{"v":"Reporting new issues","n":0.577}}},{"i":87,"$":{"0":{"v":"When opening a new issue, always make sure to fill out the issue template. This step is very important! Not doing so may result in your issue not managed in a timely fashion. Don't take this personally if this happens, and feel free to open a new issue once you've gathered all the information required by the template.","n":0.131}}},{"i":88,"$":{"0":{"v":"Reporting bugs","n":0.707}}},{"i":89,"$":{"0":{"v":"We use GitHub Issues for our public bugs. If you would like to report a problem, take a look around and see if someone already opened an issue about it. If you a are certain this is a new, unreported bug, you can submit a bug report.","n":0.146}}},{"i":90,"$":{"0":{"v":"If you have questions about using Docusaurus, contact the Docusaurus Twitter account at @docusaurus, and we will do our best to answer your questions.","n":0.204}}},{"i":91,"$":{"0":{"v":"You can also file issues as feature requests or enhancements. If you see anything you'd like to be implemented, create an issue with feature template","n":0.2}}},{"i":92,"$":{"0":{"v":"Reporting security bugs","n":0.577}}},{"i":93,"$":{"0":{"v":"Facebook has a bounty program for the safe disclosure of security bugs. With that in mind, please do not file public issues; go through the process outlined on that page.","n":0.183}}},{"i":94,"$":{"0":{"v":"Working on Docusaurus code","n":0.5}}},{"i":95,"$":{"0":{"v":"Installation","n":1}}},{"i":96,"$":{"0":{"v":"Semantic commit messages","n":0.577}}},{"i":97,"$":{"0":{"v":"See how a minor change to your commit message style can make you a better programmer.","n":0.25}}},{"i":98,"$":{"0":{"v":"Format: <type>(<scope>): <subject>","n":0.577}}},{"i":99,"$":{"0":{"v":"<scope> is optional","n":0.577}}},{"i":100,"$":{"0":{"v":"Example","n":1}}},{"i":101,"$":{"0":{"v":"The various types of commits:","n":0.447}}},{"i":102,"$":{"0":{"v":"Use lower case not title case!","n":0.408}}},{"i":103,"$":{"0":{"v":"Code conventions","n":0.707}}},{"i":104,"$":{"0":{"v":"Prettier will catch most styling issues that may exist in your code. You can check the status of your code styling by simply running npm run prettier.","n":0.192}}},{"i":105,"$":{"0":{"v":"However, there are still some styles that Prettier cannot pick up.","n":0.302}}},{"i":106,"$":{"0":{"v":"Pull requests","n":0.707}}},{"i":107,"$":{"0":{"v":"Your first pull request","n":0.5}}},{"i":108,"$":{"0":{"v":"So you have decided to contribute code back to upstream by opening a pull request. You've invested a good chunk of time, and we appreciate it. We will do our best to work with you and get the PR looked at.","n":0.156}}},{"i":109,"$":{"0":{"v":"Working on your first Pull Request? You can learn how from this free video series:","n":0.258}}},{"i":110,"$":{"0":{"v":"How to Contribute to an Open Source Project on GitHub","n":0.316}}},{"i":111,"$":{"0":{"v":"We have a list of beginner friendly issues to help you get your feet wet in the Docusaurus codebase and familiar with our contribution process. This is a great place to get started.","n":0.174}}},{"i":112,"$":{"0":{"v":"Proposing a change","n":0.577}}},{"i":113,"$":{"0":{"v":"If you would like to request a new feature or enhancement but are not yet thinking about opening a pull request, you can also file an issue with feature template.","n":0.183}}},{"i":114,"$":{"0":{"v":"If you intend to change the public API (e.g., something in docusaurus.config.js), or make any non-trivial changes to the implementation, we recommend filing an issue with proposal template and including [Proposal] in the title. This lets us reach an agreement on your proposal before you put significant effort into it. These types of issues should be rare.","n":0.132}}},{"i":115,"$":{"0":{"v":"If you're only fixing a bug, it's fine to submit a pull request right away but we still recommend to file an issue detailing what you're fixing. This is helpful in case we don't accept that specific fix but want to keep track of the issue.","n":0.147}}},{"i":116,"$":{"0":{"v":"Sending a pull request","n":0.5}}},{"i":117,"$":{"0":{"v":"Small pull requests are much easier to review and more likely to get merged. Make sure the PR does only one thing, otherwise please split it. It is recommended to follow this commit message style.","n":0.169}}},{"i":118,"$":{"0":{"v":"Please make sure the following is done when submitting a pull request:","n":0.289}}},{"i":119,"$":{"0":{"v":"All pull requests should be opened against the master branch.","n":0.316}}},{"i":120,"$":{"0":{"v":"A good test plan has the exact commands you ran and their output, provides screenshots or videos if the pull request changes UI.","n":0.209}}},{"i":121,"$":{"0":{"v":"When adding a new breaking change, follow this template in your pull request:","n":0.277}}},{"i":122,"$":{"0":{"v":"Copy and paste this to the top of your new file(s):","n":0.302}}},{"i":123,"$":{"0":{"v":"In order to accept your pull request, we need you to submit a CLA. You only need to do this once, so if you've done this for another Facebook open source project, you're good to go. If you are submitting a pull request for the first time, the Facebook GitHub Bot will reply with a link to the CLA form. You may also complete your CLA here.","n":0.122}}},{"i":124,"$":{"0":{"v":"What happens next?","n":0.577}}},{"i":125,"$":{"0":{"v":"The core Docusaurus team will be monitoring for pull requests. Do help us by keeping pull requests consistent by following the guidelines above.","n":0.209}}},{"i":126,"$":{"0":{"v":"License","n":1}}},{"i":127,"$":{"0":{"v":"By contributing to Docusaurus, you agree that your contributions will be licensed under its MIT license.","n":0.25}}},{"i":128,"$":{"0":{"v":"Creating Pages","n":0.707}}},{"i":129,"$":{"0":{"v":"In this section, we will learn about creating ad-hoc pages in Docusaurus using React. This is most useful for creating one-off standalone pages like a showcase page, playground page or support page.","n":0.177}}},{"i":130,"$":{"0":{"v":"The functionality of pages is powered by @docusaurus/plugin-content-pages.","n":0.354}}},{"i":131,"$":{"0":{"v":"Adding a new page","n":0.5}}},{"i":132,"$":{"0":{"v":"In the /src/pages/ directory, create a file called hello.js with the following contents:","n":0.277}}},{"i":133,"$":{"0":{"v":"Once you save the file, the development server will automatically reload the changes. Now open http://localhost:3000/hello, you will see the new page you just created.","n":0.2}}},{"i":134,"$":{"0":{"v":"Each page doesn't come with any styling. You will need to import the Layout component from @theme/Layout and wrap your contents within that component if you want the navbar and/or footer to appear.","n":0.174}}},{"i":135,"$":{"0":{"v":"You can also create a page in TypeScript, in which case the file name should use the .tsx extension, eg. hello.tsx.","n":0.218}}},{"i":136,"$":{"0":{"v":"Routing","n":1}}},{"i":137,"$":{"0":{"v":"If you are familiar with other static site generators like Jekyll and Next, this routing approach will feel familiar to you. Any JavaScript file you create under /src/pages/ directory will be automatically converted to a website page, following the /src/pages/ directory hierarchy. For example:","n":0.151}}},{"i":138,"$":{"0":{"v":"In this component-based development era, it is encouraged to co-locate your styling, markup and behavior together into components. Each page is a component, and if you need to customize your page design with your own styles, we recommend co-locating your styles with the page component in its own directory. For example, to create a \"Support\" page, you could do one of the following:","n":0.126}}},{"i":139,"$":{"0":{"v":"The latter is preferred as it has the benefits of letting you put files related to the page within that directory. For example, a CSS module file (styles.module.css) with styles meant to only be used on the \"Support\" page. Note: this is merely a recommended directory structure and you will still need to manually import the CSS module file within your component module (support/index.js).","n":0.125}}},{"i":140,"$":{"0":{"v":"All JavaScript/TypeScript files within the src/pages/ directory will have corresponding website paths generated for them. Do not put reusable components or test files (ending with .test.js) into that directory otherwise they will be turned into pages, which might not be intended.","n":0.156}}},{"i":141,"$":{"0":{"v":"Using React","n":0.707}}},{"i":142,"$":{"0":{"v":"React is used as the UI library to create pages. Every page component should export a React component and you can leverage on the expressiveness of React to build rich and interactive content.","n":0.174}}},{"i":143,"$":{"0":{"v":"Deployment","n":1}}},{"i":144,"$":{"0":{"v":"To build the static files of your website for production, run:","n":0.302}}},{"i":145,"$":{"0":{"v":"Once it finishes, the static files will be generated within the build/ directory.","n":0.277}}},{"i":146,"$":{"0":{"v":"You can deploy your site to static site hosting services such as Vercel, GitHub Pages, Netlify, Render, and Surge. Docusaurus sites are statically rendered so they work without JavaScript too!","n":0.183}}},{"i":147,"$":{"0":{"v":"Testing Build Local","n":0.577}}},{"i":148,"$":{"0":{"v":"It is important to test build before deploying to a production. Docusaurus includes a docusaurus serve command to test build localy.","n":0.218}}},{"i":149,"$":{"0":{"v":"Self Hosting","n":0.707}}},{"i":150,"$":{"0":{"v":"It is not the most performant solution","n":0.378}}},{"i":151,"$":{"0":{"v":"Docusaurus can be self hosted using docusaurus serve. Change port using --port and --host to change host.","n":0.243}}},{"i":152,"$":{"0":{"v":"Deploying to GitHub Pages","n":0.5}}},{"i":153,"$":{"0":{"v":"Docusaurus provides an easy way to publish to GitHub Pages. Which is hosting that comes for free with every GitHub repository.","n":0.218}}},{"i":154,"$":{"0":{"v":"docusaurus.config.js settings","n":0.707}}},{"i":155,"$":{"0":{"v":"First, modify your docusaurus.config.js and add the required params:","n":0.333}}},{"i":156,"$":{"0":{"v":"In case you want to use your custom domain for GitHub Pages, create a CNAME file in the static directory. Anything within the static directory will be copied to the root of the build directory for deployment.","n":0.164}}},{"i":157,"$":{"0":{"v":"You may refer to GitHub Pages' documentation User, Organization, and Project Pages for more details.","n":0.258}}},{"i":158,"$":{"0":{"v":"Example:","n":1}}},{"i":159,"$":{"0":{"v":"By default, GitHub Pages runs published files through Jekyll. Since Jekyll will discard any files that begin with _, it is recommended that you disable Jekyll by adding an empty file named .nojekyll file to your static directory.","n":0.162}}},{"i":160,"$":{"0":{"v":"Environment settings","n":0.707}}},{"i":161,"$":{"0":{"v":"Specify the Git user as an environment variable.","n":0.354}}},{"i":162,"$":{"0":{"v":"There are two more optional parameters that are set as environment variables:","n":0.289}}},{"i":163,"$":{"0":{"v":"Deploy","n":1}}},{"i":164,"$":{"0":{"v":"Finally, to deploy your site to GitHub Pages, run:","n":0.333}}},{"i":165,"$":{"0":{"v":"Bash","n":1}}},{"i":166,"$":{"0":{"v":"Windows","n":1}}},{"i":167,"$":{"0":{"v":"Triggering deployment with GitHub Actions","n":0.447}}},{"i":168,"$":{"0":{"v":"GitHub Actions allow you to automate, customize, and execute your software development workflows right in your repository.","n":0.243}}},{"i":169,"$":{"0":{"v":"This workflow assumes your documentation resided in documentation branch of your repository and your publishing source is configured for gh-pages branch.","n":0.218}}},{"i":170,"$":{"0":{"v":"Triggering deployment with Travis CI","n":0.447}}},{"i":171,"$":{"0":{"v":"Continuous integration (CI) services are typically used to perform routine tasks whenever new commits are checked in to source control. These tasks can be any combination of running unit tests and integration tests, automating builds, publishing packages to NPM, and deploying changes to your website. All you need to do to automate the deployment of your website is to invoke the yarn deploy script whenever your website is updated. The following section covers how to do just that using Travis CI, a popular continuous integration service provider.","n":0.107}}},{"i":172,"$":{"0":{"v":"Now, whenever a new commit lands in master, Travis CI will run your suite of tests and if everything passes, your website will be deployed via the yarn deploy script.","n":0.183}}},{"i":173,"$":{"0":{"v":"Using Azure Pipelines","n":0.577}}},{"i":174,"$":{"0":{"v":"Deploying to Netlify","n":0.577}}},{"i":175,"$":{"0":{"v":"To deploy your Docusaurus 2 sites to Netlify, first make sure the following options are properly configured:","n":0.243}}},{"i":176,"$":{"0":{"v":"Then, create your site with Netlify.","n":0.408}}},{"i":177,"$":{"0":{"v":"While you set up the site, specify the build commands and directories as follows:","n":0.267}}},{"i":178,"$":{"0":{"v":"If you did not configure these build options, you may still go to \"Site settings\" -> \"Build and deploy\" after your site is created.","n":0.204}}},{"i":179,"$":{"0":{"v":"Once properly configured with the above options, your site should deploy and automatically redeploy upon merging to your deploy branch, which defaults to master.","n":0.204}}},{"i":180,"$":{"0":{"v":"Make sure to disable Netlify setting Pretty URLs to prevent lowercased URLs, unnecessary redirects and 404 errors.","n":0.243}}},{"i":181,"$":{"0":{"v":"Deploying to Vercel","n":0.577}}},{"i":182,"$":{"0":{"v":"Deploying your Docusaurus project to Vercel will provide you with various benefits in the areas of performance and ease of use.","n":0.218}}},{"i":183,"$":{"0":{"v":"Most importantly, however, deploying a Docusaurus project only takes a couple of seconds:","n":0.277}}},{"i":184,"$":{"0":{"v":"That's all. Your docs will automatically be deployed.","n":0.354}}},{"i":185,"$":{"0":{"v":"Now you can connect your site to GitHub or GitLab to automatically receive a new deployment every time you push a commit.","n":0.213}}},{"i":186,"$":{"0":{"v":"Deploying to Render","n":0.577}}},{"i":187,"$":{"0":{"v":"Render offers free static site hosting with fully managed SSL, custom domains, a global CDN and continuous auto-deploy from your Git repo. Deploy your app in just a few minutes by following these steps.","n":0.171}}},{"i":188,"$":{"0":{"v":"Create a new Web Service on Render, and give Render permission to access your Docusaurus repo.","n":0.25}}},{"i":189,"$":{"0":{"v":"Select the branch to deploy. The default is master.","n":0.333}}},{"i":190,"$":{"0":{"v":"Enter the following values during creation.","n":0.408}}},{"i":191,"$":{"0":{"v":"That's it! Your app will be live on your Render URL as soon as the build finishes.","n":0.243}}},{"i":192,"$":{"0":{"v":"Deploying to Surge","n":0.577}}},{"i":193,"$":{"0":{"v":"Surge is a static web hosting platform, it is used to deploy your Docusaurus project from the command line in a minute. Deploying your project to Surge is easy and it is also free (including a custom domain and SSL).","n":0.158}}},{"i":194,"$":{"0":{"v":"Deploy your app in a matter of seconds using surge with the following steps:","n":0.267}}},{"i":195,"$":{"0":{"v":"First-time users of Surge would be prompted to create an account from the command line(happens only once).","n":0.243}}},{"i":196,"$":{"0":{"v":"Confirm that the site you want to publish is in the build directory, a randomly generated subdomain *.surge.sh subdomain is always given(which can be edited).","n":0.2}}},{"i":197,"$":{"0":{"v":"Using your domain","n":0.577}}},{"i":198,"$":{"0":{"v":"If you have a domain name you can deploy your site using surge to your domain using the command:","n":0.229}}},{"i":199,"$":{"0":{"v":"Your site is now deployed for free at subdomain.surge.sh or yourdomain.com depending on the method you chose.","n":0.243}}},{"i":200,"$":{"0":{"v":"Setting up CNAME file","n":0.5}}},{"i":201,"$":{"0":{"v":"Store your domain in a CNAME file for future deployments with the following command:","n":0.267}}},{"i":202,"$":{"0":{"v":"You can deploy any other changes in the future with the command surge.","n":0.277}}},{"i":203,"$":{"0":{"v":"Design Principles","n":0.707}}},{"i":204,"$":{"0":{"v":"This section is a work in progress.","n":0.378}}},{"i":205,"$":{"0":{"v":"How Docusaurus works","n":0.577}}},{"i":206,"$":{"0":{"v":"We believe that as developers, knowing how a library works is helpful in allowing us to become better at using it. Hence we're dedicating effort into explaining the architecture and various components of Docusaurus with the hope that users reading it will gain a deeper understanding of the tool and be even more proficient in using it.","n":0.132}}},{"i":207,"$":{"0":{"v":"Docs Introduction","n":0.707}}},{"i":208,"$":{"0":{"v":"The docs feature provides users with a way to organize Markdown files in a hierarchical format.","n":0.25}}},{"i":209,"$":{"0":{"v":"Document ID","n":0.707}}},{"i":210,"$":{"0":{"v":"Every document has a unique id. By default, a document id is the name of the document (without the extension) relative to the root docs directory.","n":0.196}}},{"i":211,"$":{"0":{"v":"For example, greeting.md id is greeting and guide/hello.md id is guide/hello.","n":0.302}}},{"i":212,"$":{"0":{"v":"However, the last part of the id can be defined by user in the front matter. For example, if guide/hello.md's content is defined as below, its final id is guide/part1.","n":0.183}}},{"i":213,"$":{"0":{"v":"If you want more control over the last part of the document URL, it is possible to add a slug (defaults to the id).","n":0.204}}},{"i":214,"$":{"0":{"v":"Home page docs","n":0.577}}},{"i":215,"$":{"0":{"v":"Using the homePageId property, you can create a home page of your docs. To do this, you can create a new document, especially for this purpose with the id as _index, or you could specify an existing document id.","n":0.16}}},{"i":216,"$":{"0":{"v":"Given the example above, now when you navigate to the path /docs you will see that the document content with id is getting-started. This functionality also works for docs with versioning enabled. Importantly, with document serves as home docs page, it will not be available at its URL. Following the example above, this means that the docs/getting-started URL will be lead to a 404 error.","n":0.124}}},{"i":217,"$":{"0":{"v":"The document id of _index is reserved exclusively for the home doc page, so it will not work as a standalone route. If left to the default, the page will not show a sidebar. If you wish to have a sidebar for this page, specify the document id that is listed in the sidebar file.","n":0.135}}},{"i":218,"$":{"0":{"v":"The page docs that you created (eg. src/pages/docs.js) will take precedence over the route generated via the homePageId option.","n":0.229}}},{"i":219,"$":{"0":{"v":"Sidebar","n":1}}},{"i":220,"$":{"0":{"v":"To generate a sidebar to your Docusaurus site, you need to define a file that exports a sidebar object and pass that into the @docusaurus/plugin-docs plugin directly or via @docusaurus/preset-classic.","n":0.183}}},{"i":221,"$":{"0":{"v":"Sidebar object","n":0.707}}},{"i":222,"$":{"0":{"v":"A sidebar object is defined like this:","n":0.378}}},{"i":223,"$":{"0":{"v":"Below is an example of a sidebar object. The key docs is the id of the sidebar (can be renamed to something else) and Getting Started is a category within the sidebar. greeting and doc1 are both sidebar item.","n":0.16}}},{"i":224,"$":{"0":{"v":"Keep in mind that EcmaScript does not guarantee Object.keys({a,b}) === ['a','b'] (yet, this is generally true). If you don't want to rely on iteration order of JavaScript object keys for the category name, the following sidebar object is also equivalent of the above shorthand syntax.","n":0.149}}},{"i":225,"$":{"0":{"v":"You can also have multiple sidebars for different Markdown files by adding more top-level keys to the exported object.","n":0.229}}},{"i":226,"$":{"0":{"v":"Example:","n":1}}},{"i":227,"$":{"0":{"v":"As the name implies, SidebarItem is an item defined in a Sidebar. There are a few types we support:","n":0.229}}},{"i":228,"$":{"0":{"v":"Sidebar item type that links to a doc page. Example:","n":0.316}}},{"i":229,"$":{"0":{"v":"Using just the Document ID is perfectly valid as well, the following is equivalent to the above:","n":0.243}}},{"i":230,"$":{"0":{"v":"Note that using this type will bind the linked doc to current sidebar, this means that if you access doc1 page, the sidebar displayed will be the sidebar this item is on. For below case, doc1 is bounded to firstSidebar.","n":0.158}}},{"i":231,"$":{"0":{"v":"Sidebar item type that links to a non-document page. Example:","n":0.316}}},{"i":232,"$":{"0":{"v":"Sidebar item type that links to doc without bounding it to the sidebar. Example:","n":0.267}}},{"i":233,"$":{"0":{"v":"This is used to add hierarchies to the sidebar:","n":0.333}}},{"i":234,"$":{"0":{"v":"As an example, here's how we created the subcategory for \"Docs\" under \"Guides\" in this site:","n":0.25}}},{"i":235,"$":{"0":{"v":"Note: it's possible to use the shorthand syntax to create nested categories:","n":0.289}}},{"i":236,"$":{"0":{"v":"For sites with a sizable amount of content, we support the option to expand/collapse a category to toggle the display of its contents. Categories are collapsible by default. If you want them to be always expanded, set themeConfig.sidebarCollapsible to false:","n":0.158}}},{"i":237,"$":{"0":{"v":"For docs that have collapsible categories, you may want more fine-grain control over certain categories. If you want specific categories to be always expanded, you can set collapsed to false:","n":0.183}}},{"i":238,"$":{"0":{"v":"Docs-only mode","n":0.707}}},{"i":239,"$":{"0":{"v":"If you only want the documentation feature, you can run your Docusaurus 2 site without a landing page and display your documentation page as the index page instead.","n":0.189}}},{"i":240,"$":{"0":{"v":"To enable docs-only mode, set the routeBasePath property of the docs object to the root of your site. Also, set the homePageId property to the ID of the document that you wish to show by default.","n":0.167}}},{"i":241,"$":{"0":{"v":"More details on functionality of home page for docs can be found in appropriate section.","n":0.258}}},{"i":242,"$":{"0":{"v":"Now, when visiting your site, it will show your initial document instead of a landing page.","n":0.25}}},{"i":243,"$":{"0":{"v":"You should delete the existing homepage at ./src/pages/index.js, or else there will be two files mapping to the same route!","n":0.224}}},{"i":244,"$":{"0":{"v":"There's also a \"blog-only mode\" for those who only want to use the blog feature of Docusaurus 2. You can use the same method detailed above. Follow the setup instructions on Blog-only mode.","n":0.174}}},{"i":245,"$":{"0":{"v":"Docusaurus Client API","n":0.577}}},{"i":246,"$":{"0":{"v":"Docusaurus provides some APIs on the clients that can be helpful to you when building your site.","n":0.243}}},{"i":247,"$":{"0":{"v":"Components","n":1}}},{"i":248,"$":{"0":{"v":"<Head/>","n":1}}},{"i":249,"$":{"0":{"v":"This reusable React component will manage all of your changes to the document head. It takes plain HTML tags and outputs plain HTML tags and is beginner-friendly. It is a wrapper around React Helmet.","n":0.171}}},{"i":250,"$":{"0":{"v":"Usage Example:","n":0.707}}},{"i":251,"$":{"0":{"v":"Nested or latter components will override duplicate usages:","n":0.354}}},{"i":252,"$":{"0":{"v":"Outputs","n":1}}},{"i":253,"$":{"0":{"v":"<Link/>","n":1}}},{"i":254,"$":{"0":{"v":"This component enables linking to internal pages as well as a powerful performance feature called preloading. Preloading is used to prefetch resources so that the resources are fetched by the time the user navigates with this component. We use an IntersectionObserver to fetch a low-priority request when the <Link> is in the viewport and then use an onMouseOver event to trigger a high-priority request when it is likely that a user will navigate to the requested resource.","n":0.114}}},{"i":255,"$":{"0":{"v":"The component is a wrapper around react-router’s <Link> component that adds useful enhancements specific to Docusaurus. All props are passed through to react-router’s <Link> component.","n":0.2}}},{"i":256,"$":{"0":{"v":"The target location to navigate to. Example: /docs/introduction.","n":0.354}}},{"i":257,"$":{"0":{"v":"<Redirect/>","n":1}}},{"i":258,"$":{"0":{"v":"Rendering a <Redirect> will navigate to a new location. The new location will override the current location in the history stack, like server-side redirects (HTTP 3xx) do. You can refer to React Router's Redirect documentation for more info on available props.","n":0.156}}},{"i":259,"$":{"0":{"v":"Example usage:","n":0.707}}},{"i":260,"$":{"0":{"v":"@docusaurus/router implements React Router and supports its features.","n":0.354}}},{"i":261,"$":{"0":{"v":"<BrowserOnly/>","n":1}}},{"i":262,"$":{"0":{"v":"The <BrowserOnly> component accepts a children prop, a render function which will not be executed during the pre-rendering phase of the build process. This is useful for hiding code that is only meant to run in the browsers (e.g. where the window/document objects are being accessed). To improve SEO, you can also provide fallback content using the fallback prop, which will be prerendered until in the build process and replaced with the client-side only contents when viewed in the browser.","n":0.112}}},{"i":263,"$":{"0":{"v":"Hooks","n":1}}},{"i":264,"$":{"0":{"v":"useDocusaurusContext","n":1}}},{"i":265,"$":{"0":{"v":"React hook to access Docusaurus Context. Context contains siteConfig object from docusaurus.config.js, and some additional site metadata.","n":0.243}}},{"i":266,"$":{"0":{"v":"Usage example:","n":0.707}}},{"i":267,"$":{"0":{"v":"useBaseUrl","n":1}}},{"i":268,"$":{"0":{"v":"React hook to automatically prepend baseUrl to a string automatically. This is particularly useful if you don't want to hardcode your config's baseUrl. We highly recommend you to use this.","n":0.183}}},{"i":269,"$":{"0":{"v":"Example usage:","n":0.707}}},{"i":270,"$":{"0":{"v":"useBaseUrlUtils","n":1}}},{"i":271,"$":{"0":{"v":"Sometimes useBaseUrl is not good enough. This hook return additional utils related to your site's base url.","n":0.243}}},{"i":272,"$":{"0":{"v":"useGlobalData()","n":1}}},{"i":273,"$":{"0":{"v":"React hook to access Docusaurus global data created by all the plugins.","n":0.289}}},{"i":274,"$":{"0":{"v":"Global data is namespaced by plugin name, and plugin id.","n":0.316}}},{"i":275,"$":{"0":{"v":"Plugin id is only useful when a plugin is used multiple times on the same site. Each plugin instance is able to create its own global data.","n":0.192}}},{"i":276,"$":{"0":{"v":"Usage example:","n":0.707}}},{"i":277,"$":{"0":{"v":"Inspect your site's global data at ./docusaurus/globalData.json","n":0.378}}},{"i":278,"$":{"0":{"v":"usePluginData(pluginName: string, pluginId?: string)","n":0.5}}},{"i":279,"$":{"0":{"v":"Access global data created by a specific plugin instance.","n":0.333}}},{"i":280,"$":{"0":{"v":"This is the most convenient hook to access plugin global data, and should be used most of the time.","n":0.229}}},{"i":281,"$":{"0":{"v":"pluginId is optional if you don't use multi-instance plugins.","n":0.333}}},{"i":282,"$":{"0":{"v":"Usage example:","n":0.707}}},{"i":283,"$":{"0":{"v":"useAllPluginInstancesData(pluginName: string)","n":0.707}}},{"i":284,"$":{"0":{"v":"Access global data created by a specific plugin. Given a plugin name, it returns the data of all the plugins instances of that name, by pluginId.","n":0.196}}},{"i":285,"$":{"0":{"v":"Usage example:","n":0.707}}},{"i":286,"$":{"0":{"v":"Modules","n":1}}},{"i":287,"$":{"0":{"v":"ExecutionEnvironment","n":1}}},{"i":288,"$":{"0":{"v":"A module which exposes a few boolean variables to check the current rendering environment. Useful if you want to only run certain code on client/server or need to write server-side rendering compatible code.","n":0.174}}},{"i":289,"$":{"0":{"v":"docusaurus.config.js","n":1}}},{"i":290,"$":{"0":{"v":"Overview","n":1}}},{"i":291,"$":{"0":{"v":"docusaurus.config.js contains configurations for your site and is placed in the root directory of your site.","n":0.25}}},{"i":292,"$":{"0":{"v":"Required fields","n":0.707}}},{"i":293,"$":{"0":{"v":"title","n":1}}},{"i":294,"$":{"0":{"v":"Title for your website.","n":0.5}}},{"i":295,"$":{"0":{"v":"favicon","n":1}}},{"i":296,"$":{"0":{"v":"URL for site favicon. Example:","n":0.447}}},{"i":297,"$":{"0":{"v":"You can also use the favicon URL relative to the static directory of your site. For example, your site has the following directory structure:","n":0.204}}},{"i":298,"$":{"0":{"v":"So you can refer it like below:","n":0.378}}},{"i":299,"$":{"0":{"v":"url","n":1}}},{"i":300,"$":{"0":{"v":"URL for your website. This can also be considered the top-level hostname. For example, https://facebook.github.io is the URL of https://facebook.github.io/metro/, and https://docusaurus.io is the URL for https://docusaurus.io. This field is related to the baseUrl field.","n":0.169}}},{"i":301,"$":{"0":{"v":"baseUrl","n":1}}},{"i":302,"$":{"0":{"v":"Base URL for your site. This can also be considered the path after the host. For example, /metro/ is the baseUrl of https://facebook.github.io/metro/. For URLs that have no path, the baseUrl should be set to /. This field is related to the url field.","n":0.151}}},{"i":303,"$":{"0":{"v":"Optional fields","n":0.707}}},{"i":304,"$":{"0":{"v":"onBrokenLinks","n":1}}},{"i":305,"$":{"0":{"v":"The behavior of Docusaurus, when it detects any broken link.","n":0.316}}},{"i":306,"$":{"0":{"v":"By default, it throws an error, to ensure you never ship any broken link, but you can lower this security if needed.","n":0.213}}},{"i":307,"$":{"0":{"v":"The broken links detection is only available for a production build (docusaurus build).","n":0.277}}},{"i":308,"$":{"0":{"v":"tagline","n":1}}},{"i":309,"$":{"0":{"v":"The tagline for your website.","n":0.447}}},{"i":310,"$":{"0":{"v":"organizationName","n":1}}},{"i":311,"$":{"0":{"v":"The GitHub user or organization that owns the repository. Used by the deployment command.","n":0.267}}},{"i":312,"$":{"0":{"v":"projectName","n":1}}},{"i":313,"$":{"0":{"v":"The name of the GitHub repository. Used by the deployment command.","n":0.302}}},{"i":314,"$":{"0":{"v":"githubHost","n":1}}},{"i":315,"$":{"0":{"v":"The hostname of your server. Useful if you are using GitHub Enterprise.","n":0.289}}},{"i":316,"$":{"0":{"v":"themeConfig","n":1}}},{"i":317,"$":{"0":{"v":"An object containing data needed by the theme you use.","n":0.316}}},{"i":318,"$":{"0":{"v":"For Docusaurus' default theme classic, we use themeConfig to customize your navbar and footer links:","n":0.258}}},{"i":319,"$":{"0":{"v":"Example:","n":1}}},{"i":320,"$":{"0":{"v":"plugins","n":1}}},{"i":321,"$":{"0":{"v":"themes","n":1}}},{"i":322,"$":{"0":{"v":"presets","n":1}}},{"i":323,"$":{"0":{"v":"customFields","n":1}}},{"i":324,"$":{"0":{"v":"Docusaurus guards docusaurus.config.js from unknown fields. To add a custom field, define it on customFields.","n":0.258}}},{"i":325,"$":{"0":{"v":"Attempting to add unknown field in the config will lead to error in build time:","n":0.258}}},{"i":326,"$":{"0":{"v":"scripts","n":1}}},{"i":327,"$":{"0":{"v":"An array of scripts to load. The values can be either strings or plain objects of attribute-value maps. The <script> tags will be inserted in the HTML <head>.","n":0.189}}},{"i":328,"$":{"0":{"v":"Note that <script> added here are render-blocking so you might want to add async: true/defer: true to the objects.","n":0.229}}},{"i":329,"$":{"0":{"v":"Example:","n":1}}},{"i":330,"$":{"0":{"v":"stylesheets","n":1}}},{"i":331,"$":{"0":{"v":"An array of CSS sources to load. The values can be either strings or plain objects of attribute-value maps. The <link> tags will be inserted in the HTML <head>.","n":0.186}}},{"i":332,"$":{"0":{"v":"Example:","n":1}}},{"i":333,"$":{"0":{"v":"Installation","n":1}}},{"i":334,"$":{"0":{"v":"Docusaurus is essentially a set of npm packages that can be installed over npm.","n":0.267}}},{"i":335,"$":{"0":{"v":"Requirements","n":1}}},{"i":336,"$":{"0":{"v":"Scaffold project website","n":0.577}}},{"i":337,"$":{"0":{"v":"The easiest way to install Docusaurus is to use the command line tool that helps you scaffold a skeleton Docusaurus website. You can run this command anywhere in a new empty repository or within an existing repository, it will create a new directory containing the scaffolded files.","n":0.146}}},{"i":338,"$":{"0":{"v":"Example:","n":1}}},{"i":339,"$":{"0":{"v":"If you do not specify name or template, it will prompt you for them. We recommend the classic template so that you can get started quickly and it contains features found in Docusaurus 1. The classic template contains @docusaurus/preset-classic which includes standard documentation, a blog, custom pages, and a CSS framework (with dark mode support). You can get up and running extremely quickly with the classic template and customize things later on when you have gained more familiarity with Docusaurus.","n":0.112}}},{"i":340,"$":{"0":{"v":"[FB-Only]: If you are setting up a new Docusaurus website for a Facebook open source project, use the facebook template instead, which comes with some useful Facebook-specific defaults:","n":0.189}}},{"i":341,"$":{"0":{"v":"Project structure","n":0.707}}},{"i":342,"$":{"0":{"v":"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/:","n":0.209}}},{"i":343,"$":{"0":{"v":"Project structure rundown","n":0.577}}},{"i":344,"$":{"0":{"v":"Running the development server","n":0.5}}},{"i":345,"$":{"0":{"v":"To preview your changes as you edit the files, you can run a local development server that will serve your website and it will reflect the latest changes.","n":0.189}}},{"i":346,"$":{"0":{"v":"By default, a browser window will open at http://localhost:3000.","n":0.333}}},{"i":347,"$":{"0":{"v":"Congratulations! You have just created your first Docusaurus site! Browse around the site to see what's available.","n":0.243}}},{"i":348,"$":{"0":{"v":"Build","n":1}}},{"i":349,"$":{"0":{"v":"Docusaurus is a modern static website generator so we need to build the website into a directory of static contents and put it on a web server so that it can be viewed. To build the website:","n":0.164}}},{"i":350,"$":{"0":{"v":"and contents will be generated within the /build directory, which can be copied to any static file hosting service like GitHub pages, Now or Netlify. Check out the docs on deployment for more details.","n":0.171}}},{"i":351,"$":{"0":{"v":"Updating your Docusaurus version","n":0.5}}},{"i":352,"$":{"0":{"v":"There are many ways to update your Docusaurus version. One guaranteed way is to manually change the version number in package.json to the desired version. Note that all @docusaurus/-namespaced packages should be using the same version.","n":0.167}}},{"i":353,"$":{"0":{"v":"Please update to the latest Docusaurus 2 version shown at the top of the page, not what is shown below.","n":0.224}}},{"i":354,"$":{"0":{"v":"Then, in the directory containing package.json, run your package manager's install command:","n":0.289}}},{"i":355,"$":{"0":{"v":"To check that that the update occurred successfully, run:","n":0.333}}},{"i":356,"$":{"0":{"v":"You should see the correct version as output.","n":0.354}}},{"i":357,"$":{"0":{"v":"Alternatively, if you are using Yarn, you can do:","n":0.333}}},{"i":358,"$":{"0":{"v":"Problems?","n":1}}},{"i":359,"$":{"0":{"v":"Ask for help on Stack Overflow, on our GitHub repository or Twitter.","n":0.289}}},{"i":360,"$":{"0":{"v":"Lifecycle APIs","n":0.707}}},{"i":361,"$":{"0":{"v":"This section is a work in progress.","n":0.378}}},{"i":362,"$":{"0":{"v":"Lifecycle APIs are shared by Themes and Plugins.","n":0.354}}},{"i":363,"$":{"0":{"v":"validateOptions({options,validate})","n":1}}},{"i":364,"$":{"0":{"v":"Return validated and normalized options for the plugin. This method is called before the plugin is initialized.You must return options since the returned options will be passed to plugin during intialization.","n":0.18}}},{"i":365,"$":{"0":{"v":"options","n":1}}},{"i":366,"$":{"0":{"v":"validateOptions is called with options passed to plugin for validation and normalization.","n":0.289}}},{"i":367,"$":{"0":{"v":"validate","n":1}}},{"i":368,"$":{"0":{"v":"validateOptions is called with validate function which takes a Joi schema and options as argument, returns validated and normalized options. validate will automatically handle error and validation config.","n":0.189}}},{"i":369,"$":{"0":{"v":"Joi is recommended for validation and normalization of options.","n":0.333}}},{"i":370,"$":{"0":{"v":"If you don't use Joi for validation you can throw an Error in case of invalid options and return options in case of success.","n":0.204}}},{"i":371,"$":{"0":{"v":"You can also use ES modules style exports.","n":0.354}}},{"i":372,"$":{"0":{"v":"validateThemeConfig({themeConfig,validate})","n":1}}},{"i":373,"$":{"0":{"v":"Return validated and normalized configuration for the theme.","n":0.354}}},{"i":374,"$":{"0":{"v":"themeConfig","n":1}}},{"i":375,"$":{"0":{"v":"validateThemeConfig is called with themeConfig provided in docusaurus.config.js for validation and normalization.","n":0.289}}},{"i":376,"$":{"0":{"v":"validate","n":1}}},{"i":377,"$":{"0":{"v":"validateThemeConfig is called with validate function which takes a Joi schema and themeConfig as argument, returns validated and normalized options. validate will automatically handle error and validation config.","n":0.189}}},{"i":378,"$":{"0":{"v":"Joi is recommended for validation and normalization of theme config.","n":0.316}}},{"i":379,"$":{"0":{"v":"If you don't use Joi for validation you can throw an Error in case of invalid options.","n":0.243}}},{"i":380,"$":{"0":{"v":"You can also use ES modules style exports.","n":0.354}}},{"i":381,"$":{"0":{"v":"getPathsToWatch()","n":1}}},{"i":382,"$":{"0":{"v":"Specifies the paths to watch for plugins and themes. The paths are watched by the dev server so that the plugin lifecycles are reloaded when contents in the watched paths change. Note that the plugins and themes modules are initially called with context and options from Node, which you may use to find the necessary directory information about the site.","n":0.129}}},{"i":383,"$":{"0":{"v":"Example:","n":1}}},{"i":384,"$":{"0":{"v":"async loadContent()","n":0.707}}},{"i":385,"$":{"0":{"v":"Plugins should use this lifecycle to fetch from data sources (filesystem, remote API, headless CMS, etc) or doing some server processing.","n":0.218}}},{"i":386,"$":{"0":{"v":"For example, this plugin below return a random integer between 1 to 10 as content;","n":0.258}}},{"i":387,"$":{"0":{"v":"async contentLoaded({content, actions})","n":0.577}}},{"i":388,"$":{"0":{"v":"Plugins should use the data loaded in loadContent and construct the pages/routes that consume the loaded data (optional).","n":0.236}}},{"i":389,"$":{"0":{"v":"content","n":1}}},{"i":390,"$":{"0":{"v":"contentLoaded will be called after loadContent is done, the return value of loadContent() will be passed to contentLoaded as content.","n":0.224}}},{"i":391,"$":{"0":{"v":"actions","n":1}}},{"i":392,"$":{"0":{"v":"actions contain two functions:","n":0.5}}},{"i":393,"$":{"0":{"v":"Create a route to add to the website.","n":0.354}}},{"i":394,"$":{"0":{"v":"A function to help you create static data (generally json or string), that you can provide to your routes as props.","n":0.218}}},{"i":395,"$":{"0":{"v":"For example, this plugin below create a /friends page which display Your friends are: Yangshun, Sebastien:","n":0.25}}},{"i":396,"$":{"0":{"v":"This function permits to create some global plugin data, that can be read from any page, including the pages created by other plugins, and your theme layout.","n":0.192}}},{"i":397,"$":{"0":{"v":"This data become accessible to your client-side/theme code, through the useGlobalData and usePluginData","n":0.277}}},{"i":398,"$":{"0":{"v":"One this data is created, you can access it with the global data hooks APIs","n":0.258}}},{"i":399,"$":{"0":{"v":"Global data is... global: its size affects the loading time of all pages of your site, so try to keep it small.","n":0.213}}},{"i":400,"$":{"0":{"v":"Prefer createData and page-specific data whenever possible.","n":0.378}}},{"i":401,"$":{"0":{"v":"For example, this plugin below create a /friends page which display Your friends are: Yangshun, Sebastien:","n":0.25}}},{"i":402,"$":{"0":{"v":"async routesLoaded(routes)","n":0.707}}},{"i":403,"$":{"0":{"v":"Plugins can modify the routes that were generated by all plugins. routesLoaded is called after contentLoaded hook.","n":0.243}}},{"i":404,"$":{"0":{"v":"configureWebpack(config, isServer, utils)","n":0.577}}},{"i":405,"$":{"0":{"v":"Modifies the internal webpack config. If the return value is a JavaScript object, it will be merged into the final config using webpack-merge. If it is a function, it will be called and receive config as the first argument and an isServer flag as the argument argument.","n":0.146}}},{"i":406,"$":{"0":{"v":"config","n":1}}},{"i":407,"$":{"0":{"v":"configureWebpack is called with config generated according to client/server build. You may treat this as the base config to be merged with.","n":0.213}}},{"i":408,"$":{"0":{"v":"isServer","n":1}}},{"i":409,"$":{"0":{"v":"configureWebpack will be called both in server build and in client build. The server build receives true and the client build receives false as isServer.","n":0.2}}},{"i":410,"$":{"0":{"v":"utils","n":1}}},{"i":411,"$":{"0":{"v":"The initial call to configureWebpack also receives a util object consists of three functions:","n":0.267}}},{"i":412,"$":{"0":{"v":"You may use them to return your webpack configures conditionally.","n":0.316}}},{"i":413,"$":{"0":{"v":"For example, this plugin below modify the webpack config to transpile .foo file.","n":0.277}}},{"i":414,"$":{"0":{"v":"Merge strategy","n":0.707}}},{"i":415,"$":{"0":{"v":"We merge the Webpack configuration parts of plugins into the global Webpack config using webpack-merge.","n":0.258}}},{"i":416,"$":{"0":{"v":"It is possible to specify the merge strategy. For example, if you want a webpack rule to be prepended instead of appended:","n":0.213}}},{"i":417,"$":{"0":{"v":"Read the webpack-merge strategy doc for more details.","n":0.354}}},{"i":418,"$":{"0":{"v":"postBuild(props)","n":1}}},{"i":419,"$":{"0":{"v":"Called when a (production) build finishes.","n":0.408}}},{"i":420,"$":{"0":{"v":"Example:","n":1}}},{"i":421,"$":{"0":{"v":"extendCli(cli)","n":1}}},{"i":422,"$":{"0":{"v":"Register an extra command to enhance the CLI of docusaurus. cli is commander object.","n":0.267}}},{"i":423,"$":{"0":{"v":"Example:","n":1}}},{"i":424,"$":{"0":{"v":"injectHtmlTags()","n":1}}},{"i":425,"$":{"0":{"v":"Inject head and/or body HTML tags to Docusaurus generated HTML.","n":0.316}}},{"i":426,"$":{"0":{"v":"Example:","n":1}}},{"i":427,"$":{"0":{"v":"getThemePath()","n":1}}},{"i":428,"$":{"0":{"v":"Returns the path to the directory where the theme components can be found. When your users calls swizzle, getThemePath is called and its returned path is used to find your theme components.","n":0.177}}},{"i":429,"$":{"0":{"v":"If you use the folder directory above, your getThemePath can be:","n":0.302}}},{"i":430,"$":{"0":{"v":"getTypeScriptThemePath()","n":1}}},{"i":431,"$":{"0":{"v":"Similar to getThemePath(), it should return the path to the directory where the source code of TypeScript theme components can be found. Theme components under this path will not be resolved by Webpack. Therefore, it is not a replacement of getThemePath(). Instead, this path is purely for swizzling TypeScript theme components.","n":0.14}}},{"i":432,"$":{"0":{"v":"If you want to support TypeScript component swizzling for your theme, you can make the path returned by getTypeScriptThemePath() be your source directory, and make path returned by getThemePath() be the compiled JavaScript output.","n":0.171}}},{"i":433,"$":{"0":{"v":"Example:","n":1}}},{"i":434,"$":{"0":{"v":"getClientModules()","n":1}}},{"i":435,"$":{"0":{"v":"Returns an array of paths to the modules that are to be imported in the client bundle. These modules are imported globally before React even renders the initial UI.","n":0.186}}},{"i":436,"$":{"0":{"v":"As an example, to make your theme load a customCss object from options passed in by the user:","n":0.236}}},{"i":437,"$":{"0":{"v":"Example","n":1}}},{"i":438,"$":{"0":{"v":"Here's a mind model for a presumptuous plugin implementation.","n":0.333}}},{"i":439,"$":{"0":{"v":"Markdown Features","n":0.707}}},{"i":440,"$":{"0":{"v":"Documentation is one of your product's interfaces with your users. A well-written and well-organized set of docs helps your users understand your product quickly. Our aligned goal here is to help your users find and understand the information they need, as quickly as possible.","n":0.151}}},{"i":441,"$":{"0":{"v":"Docusaurus 2 uses modern tooling to help you compose your interactive documentations with ease. You may embed React components, or build live coding blocks where your users may play with the code on the spot. Start sharing your eureka moments with the code your audience cannot walk away from. It is perhaps the most effective way of attracting potential users.","n":0.129}}},{"i":442,"$":{"0":{"v":"In this section, we'd like to introduce you to the tools we've picked that we believe will help you build powerful documentation. Let us walk you through with an example.","n":0.183}}},{"i":443,"$":{"0":{"v":"All the following content assumes you are using @docusaurus/preset-classic or @docusaurus/plugin-content-docs.","n":0.302}}},{"i":444,"$":{"0":{"v":"Markdown is a syntax that enables you to write formatted content in a readable syntax. The standard Markdown syntax is supported and we use MDX as the parsing engine, which can do much more than just parsing Markdown. More on that later.","n":0.154}}},{"i":445,"$":{"0":{"v":"Create a markdown file, greeting.md, and place it under the docs directory.","n":0.289}}},{"i":446,"$":{"0":{"v":"At the top of the file, specify id and title in the front matter, so that Docusaurus will pick them up correctly when generating your site.","n":0.196}}},{"i":447,"$":{"0":{"v":"This will render in the browser as follows:","n":0.354}}},{"i":448,"$":{"0":{"v":"Hello from Docusaurus","n":0.577}}},{"i":449,"$":{"0":{"v":"Are you ready to create the documentation site for your open source project?","n":0.277}}},{"i":450,"$":{"0":{"v":"Headers","n":1}}},{"i":451,"$":{"0":{"v":"will show up on the table of contents on the upper right","n":0.289}}},{"i":452,"$":{"0":{"v":"So that your users will know what this page is all about without scrolling down or even without reading too much.","n":0.218}}},{"i":453,"$":{"0":{"v":"Only h2 and h3 will be in the toc","n":0.333}}},{"i":454,"$":{"0":{"v":"The headers are well-spaced so that the hierarchy is clear.","n":0.316}}},{"i":455,"$":{"0":{"v":"Markdown headers","n":0.707}}},{"i":456,"$":{"0":{"v":"Documents use the following markdown header fields that are enclosed by a line --- on either side:","n":0.243}}},{"i":457,"$":{"0":{"v":"Example:","n":1}}},{"i":458,"$":{"0":{"v":"Referencing other documents","n":0.577}}},{"i":459,"$":{"0":{"v":"If you want to reference another document file, you could use the name of the document you want to reference. Docusaurus will convert the file path to be the final website path (and remove the .md).","n":0.167}}},{"i":460,"$":{"0":{"v":"For example, if you are in doc2.md and you want to reference doc1.md and folder/doc3.md:","n":0.258}}},{"i":461,"$":{"0":{"v":"One benefit of this approach is that the links to external files will still work if you are viewing the file on GitHub.","n":0.209}}},{"i":462,"$":{"0":{"v":"Embedding React components with MDX","n":0.447}}},{"i":463,"$":{"0":{"v":"Docusaurus has built-in support for MDX, which allows you to write JSX within your Markdown files and render them as React components.","n":0.213}}},{"i":464,"$":{"0":{"v":"Note 1: While both .md and .mdx files are parsed using MDX, some of the syntax are treated slightly differently. For the most accurate parsing and better editor support, we recommend using the .mdx extension for files containing MDX syntax. Let's rename the previous file to greeting.mdx.","n":0.146}}},{"i":465,"$":{"0":{"v":"Note 2: Since all doc files are parsed using MDX, any HTML is treated as JSX. Therefore, if you need to inline-style a component, follow JSX flavor and provide style objects. This behavior is different from Docusaurus 1. See also Migrating from v1 to v2.","n":0.149}}},{"i":466,"$":{"0":{"v":"Try this block here:","n":0.5}}},{"i":467,"$":{"0":{"v":"Notice how it renders both the markup from your React component and the Markdown syntax:","n":0.258}}},{"i":468,"$":{"0":{"v":"I can write Markdown alongside my JSX!","n":0.378}}},{"i":469,"$":{"0":{"v":"You can also import your own components defined in other files or third-party components installed via npm! Check out the MDX docs to see what other fancy stuff you can do with MDX.","n":0.174}}},{"i":470,"$":{"0":{"v":"Configuring plugins","n":0.707}}},{"i":471,"$":{"0":{"v":"You can expand the MDX functionalities, using plugins. An MDX plugin is usually a npm package, so you install them like other npm packages using npm. Docusaurus supports both Remark and Rehype plugins that work with MDX.","n":0.164}}},{"i":472,"$":{"0":{"v":"First, install your Remark and Rehype plugins.","n":0.378}}},{"i":473,"$":{"0":{"v":"For example:","n":0.707}}},{"i":474,"$":{"0":{"v":"Next, import the plugins:","n":0.5}}},{"i":475,"$":{"0":{"v":"Finally, add them to the @docusaurus/preset-classic options in docusaurus.config.js:","n":0.333}}},{"i":476,"$":{"0":{"v":"Configuring plugin options","n":0.577}}},{"i":477,"$":{"0":{"v":"Some plugins can be configured and accept their own options. In that case, use the [plugin, pluginOptions] syntax, like so:","n":0.224}}},{"i":478,"$":{"0":{"v":"See more information in the MDX documentation.","n":0.378}}},{"i":479,"$":{"0":{"v":"Tabs","n":1}}},{"i":480,"$":{"0":{"v":"To show tabbed content within Markdown files, you can fall back on MDX. Docusaurus provides <Tabs> components out-of-the-box.","n":0.236}}},{"i":481,"$":{"0":{"v":"will result in","n":0.577}}},{"i":482,"$":{"0":{"v":"Syncing tab choices","n":0.577}}},{"i":483,"$":{"0":{"v":"You may want choices of the same kind of tabs to sync with each other. For example, you might want to provide different instructions for users on Windows vs users on macOS, and you want to changing all OS-specific instructions tabs in one click. To achieve that, you can give all related tabs the same groupId prop. Note that doing this will persist the choice in localStorage and all <Tab> instances with the same groupId will update automatically when the value of one of them is changed. Not that groupID are globally-namespaced.","n":0.104}}},{"i":484,"$":{"0":{"v":"For all tab groups that have the same groupId, the possible values do not need to be the same. If one tab group with chooses an value that does not exist in another tab group with the same groupId, the tab group with the missing value won't change its tab. You can see that from the following example. Try to select Linux, and the above tab groups doesn't change.","n":0.12}}},{"i":485,"$":{"0":{"v":"Tab choices with different groupIds will not interfere with each other:","n":0.302}}},{"i":486,"$":{"0":{"v":"Callouts/admonitions","n":1}}},{"i":487,"$":{"0":{"v":"In addition to the basic Markdown syntax, we use remark-admonitions alongside MDX to add support for admonitions. Admonitions are wrapped by a set of 3 colons.","n":0.196}}},{"i":488,"$":{"0":{"v":"Example:","n":1}}},{"i":489,"$":{"0":{"v":"The content and title can include markdown.","n":0.378}}},{"i":490,"$":{"0":{"v":"Heads up! Here's a pro-tip.","n":0.447}}},{"i":491,"$":{"0":{"v":"Useful information.","n":0.707}}},{"i":492,"$":{"0":{"v":"Warning! You better pay attention!","n":0.447}}},{"i":493,"$":{"0":{"v":"Danger danger, mayday!","n":0.577}}},{"i":494,"$":{"0":{"v":"Specifying title","n":0.707}}},{"i":495,"$":{"0":{"v":"You may also specify an optional title","n":0.378}}},{"i":496,"$":{"0":{"v":"The content and title can include Markdown.","n":0.378}}},{"i":497,"$":{"0":{"v":"Code blocks","n":0.707}}},{"i":498,"$":{"0":{"v":"Code blocks within documentation are super-powered 💪.","n":0.378}}},{"i":499,"$":{"0":{"v":"Code title","n":0.707}}},{"i":500,"$":{"0":{"v":"You can add a title to the code block by adding title key after the language (leave a space between them).","n":0.218}}},{"i":501,"$":{"0":{"v":"Syntax highlighting","n":0.707}}},{"i":502,"$":{"0":{"v":"Code blocks are text blocks wrapped around by strings of 3 backticks. You may check out this reference for specifications of MDX.","n":0.213}}},{"i":503,"$":{"0":{"v":"Use the matching language meta string for your code block, and Docusaurus will pick up syntax highlighting automatically, powered by Prism React Renderer.","n":0.209}}},{"i":504,"$":{"0":{"v":"By default, the Prism syntax highlighting theme we use is Palenight. You can change this to another theme by passing theme field in prism as themeConfig in your docusaurus.config.js.","n":0.186}}},{"i":505,"$":{"0":{"v":"For example, if you prefer to use the dracula highlighting theme:","n":0.302}}},{"i":506,"$":{"0":{"v":"By default, Docusaurus comes with this subset of commonly used languages.","n":0.302}}},{"i":507,"$":{"0":{"v":"To add syntax highlighting for any of the other Prism supported languages, define it in an array of additional languages.","n":0.224}}},{"i":508,"$":{"0":{"v":"For example, if you want to add highlighting for the powershell language:","n":0.289}}},{"i":509,"$":{"0":{"v":"If you want to add highlighting for languages not yet supported by Prism, you can swizzle prism-include-languages:","n":0.243}}},{"i":510,"$":{"0":{"v":"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:","n":0.229}}},{"i":511,"$":{"0":{"v":"You can refer to Prism's official language definitions when you are writing your own language definitions.","n":0.25}}},{"i":512,"$":{"0":{"v":"Line highlighting","n":0.707}}},{"i":513,"$":{"0":{"v":"You can bring emphasis to certain lines of code by specifying line ranges after the language meta string (leave a space after the language).","n":0.204}}},{"i":514,"$":{"0":{"v":"To accomplish this, Docusaurus adds the docusaurus-highlight-code-line class to the highlighted lines. You will need to define your own styling for this CSS, possibly in your src/css/custom.css with a custom background color which is dependent on your selected syntax highlighting theme. The color given below works for the default highlighting theme (Palenight), so if you are using another theme, you will have to tweak the color accordingly.","n":0.122}}},{"i":515,"$":{"0":{"v":"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 on their project details.","n":0.164}}},{"i":516,"$":{"0":{"v":"You can also use comments with highlight-next-line, highlight-start, and highlight-end to select which lines are highlighted.","n":0.25}}},{"i":517,"$":{"0":{"v":"Supported commenting syntax:","n":0.577}}},{"i":518,"$":{"0":{"v":"If there's a syntax that is not currently supported, we are open to adding them! Pull requests welcome.","n":0.236}}},{"i":519,"$":{"0":{"v":"Interactive code editor","n":0.577}}},{"i":520,"$":{"0":{"v":"(Powered by React Live)","n":0.5}}},{"i":521,"$":{"0":{"v":"You can create an interactive coding editor with the @docusaurus/theme-live-codeblock plugin.","n":0.302}}},{"i":522,"$":{"0":{"v":"First, add the plugin to your package.","n":0.378}}},{"i":523,"$":{"0":{"v":"You will also need to add the plugin to your docusaurus.config.js.","n":0.302}}},{"i":524,"$":{"0":{"v":"To use the plugin, create a code block with live attached to the language meta string.","n":0.25}}},{"i":525,"$":{"0":{"v":"The code block will be rendered as an interactive editor. Changes to the code will reflect on the result panel live.","n":0.218}}},{"i":526,"$":{"0":{"v":"It is 6:08:30 pm.","n":0.5}}},{"i":527,"$":{"0":{"v":"It is not possible to import components directly from the react-live code editor, you have to define available imports upfront.","n":0.224}}},{"i":528,"$":{"0":{"v":"By default, all React imports are available. If you need more imports available, swizzle the react-live scope:","n":0.243}}},{"i":529,"$":{"0":{"v":"The ButtonExample component is now available to use:","n":0.354}}},{"i":530,"$":{"0":{"v":"Multi-language support code blocks","n":0.5}}},{"i":531,"$":{"0":{"v":"With MDX, you can easily create interactive components within your documentation, for example, to display code in multiple programming languages and switching between them using a tabs component.","n":0.189}}},{"i":532,"$":{"0":{"v":"Instead of implementing a dedicated component for multi-language support code blocks, we've implemented a generic Tabs component in the classic theme so that you can use it for other non-code scenarios as well.","n":0.174}}},{"i":533,"$":{"0":{"v":"The following example is how you can have multi-language code tabs in your docs. Note that the empty lines above and below each language block is intentional. This is a current limitation of MDX, you have to leave empty lines around Markdown syntax for the MDX parser to know that it's Markdown syntax and not JSX.","n":0.134}}},{"i":534,"$":{"0":{"v":"And you will get the following:","n":0.408}}},{"i":535,"$":{"0":{"v":"You may want to implement your own <MultiLanguageCode /> abstraction if you find the above approach too verbose. We might just implement one in future for convenience.","n":0.192}}},{"i":536,"$":{"0":{"v":"If you have multiple of these multi-language code tabs, and you want to sync the selection across the tab instances, refer to the Syncing tab choices section.","n":0.192}}},{"i":537,"$":{"0":{"v":"Assets","n":1}}},{"i":538,"$":{"0":{"v":"Sometimes you want to link to static assets directly from markdown files, and it is convenient to co-locate the asset next to the markdown file using it.","n":0.192}}},{"i":539,"$":{"0":{"v":"We have setup Webpack loaders to handle most common file types, so that when you import a file, you get its url, and the asset is automatically copied to the output folder.","n":0.177}}},{"i":540,"$":{"0":{"v":"Let's imagine the following file structure:","n":0.408}}},{"i":541,"$":{"0":{"v":"Image assets","n":0.707}}},{"i":542,"$":{"0":{"v":"You can use images by requiring them and using an image tag through MDX:","n":0.267}}},{"i":543,"$":{"0":{"v":"The ES imports syntax also works:","n":0.408}}},{"i":544,"$":{"0":{"v":"This results in displaying the image:","n":0.408}}},{"i":545,"$":{}},{"i":546,"$":{"0":{"v":"If you are using @docusaurus/plugin-ideal-image, you need to use the dedicated image component, as documented.","n":0.258}}},{"i":547,"$":{"0":{"v":"Common assets","n":0.707}}},{"i":548,"$":{"0":{"v":"In the same way, you can link to existing assets by requiring them and using the returned url in videos, links etc...","n":0.213}}},{"i":549,"$":{"0":{"v":"Unknown assets","n":0.707}}},{"i":550,"$":{"0":{"v":"This require behavior is not supported for all file extensions, but as an escape hatch you can use the special Webpack syntax to force the file-loader to kick-in:","n":0.189}}},{"i":551,"$":{"0":{"v":"Migrating from v1 to v2","n":0.447}}},{"i":552,"$":{"0":{"v":"This migration guide is targeted at Docusaurus users without translation and/or versioning features.","n":0.277}}},{"i":553,"$":{"0":{"v":"This doc guides you through migrating an existing Docusaurus 1 site to Docusaurus 2.","n":0.267}}},{"i":554,"$":{"0":{"v":"Your Docusaurus 1 site should have the following structure:","n":0.333}}},{"i":555,"$":{"0":{"v":"After the migration, your Docusaurus 2 site could look like:","n":0.316}}},{"i":556,"$":{"0":{"v":"You can use the migration command to take care of some of the migration chores.","n":0.258}}},{"i":557,"$":{"0":{"v":"Project setup","n":0.707}}},{"i":558,"$":{"0":{"v":"package.json","n":1}}},{"i":559,"$":{"0":{"v":"In Docusaurus 2, we use scoped package names:","n":0.354}}},{"i":560,"$":{"0":{"v":"This provides a clear distinction between Docusaurus' official packages and community maintained packages. In another words, all Docusaurus' official packages are namespaced under @docusaurus/.","n":0.204}}},{"i":561,"$":{"0":{"v":"Meanwhile, the default doc site functionalities provided by Docusaurus 1 are now provided by @docusaurus/preset-classic. Therefore, we need to add this dependency as well:","n":0.204}}},{"i":562,"$":{"0":{"v":"Please use the most recent Docusaurus 2 alpha version, which you can check out here (it's tagged next).","n":0.236}}},{"i":563,"$":{"0":{"v":"Meanwhile, CLI commands are renamed to docusaurus <command> (instead of docusaurus-command).","n":0.302}}},{"i":564,"$":{"0":{"v":"The \"scripts\" section of your package.json should be updated as follows:","n":0.302}}},{"i":565,"$":{"0":{"v":"A typical Docusaurus 2 package.json may look like this:","n":0.333}}},{"i":566,"$":{"0":{"v":"Update references to the build directory","n":0.408}}},{"i":567,"$":{"0":{"v":"In Docusaurus 1, all the build artifacts are located within website/build/<PROJECT_NAME>.","n":0.302}}},{"i":568,"$":{"0":{"v":"In Docusaurus 2, it is now moved to just website/build. Make sure that you update your deployment configuration to read the generated files from the correct build directory.","n":0.189}}},{"i":569,"$":{"0":{"v":"If you are deploying to GitHub pages, make sure to run yarn deploy instead of yarn publish-gh-pages script.","n":0.236}}},{"i":570,"$":{"0":{"v":".gitignore","n":1}}},{"i":571,"$":{"0":{"v":"The .gitignore in your website should contain:","n":0.378}}},{"i":572,"$":{"0":{"v":"README","n":1}}},{"i":573,"$":{"0":{"v":"The D1 website may have an existing README file. You can modify it to reflect the D2 changes, or copy the default Docusaurus v2 README.","n":0.2}}},{"i":574,"$":{"0":{"v":"Site configurations","n":0.707}}},{"i":575,"$":{"0":{"v":"docusaurus.config.js","n":1}}},{"i":576,"$":{"0":{"v":"Rename siteConfig.js to docusaurus.config.js.","n":0.5}}},{"i":577,"$":{"0":{"v":"In Docusaurus 2, we split each functionality (blog, docs, pages) into plugins for modularity. Presets are bundles of plugins and for backward compatibility we built a @docusaurus/preset-classic preset which bundles most of the essential plugins present in Docusaurus 1.","n":0.16}}},{"i":578,"$":{"0":{"v":"Add the following preset configuration to your docusaurus.config.js.","n":0.354}}},{"i":579,"$":{"0":{"v":"We recommend moving the docs folder into the website folder and that is also the default directory structure in v2. Now supports Docusaurus project deployments out-of-the-box if the docs directory is within the website. It is also generally better for the docs to be within the website so that the docs and the rest of the website code are co-located within one website directory.","n":0.125}}},{"i":580,"$":{"0":{"v":"If you are migrating your Docusaurus v1 website, and there are pending documentation pull requests, you can temporarily keep the /docs folder to its original place, to avoid producing conflicts.","n":0.183}}},{"i":581,"$":{"0":{"v":"Refer to migration guide below for each field in siteConfig.js.","n":0.316}}},{"i":582,"$":{"0":{"v":"Updated fields","n":0.707}}},{"i":583,"$":{"0":{"v":"No actions needed, these configuration fields were not modified.","n":0.333}}},{"i":584,"$":{"0":{"v":"Deprecated. We wrote a custom CSS framework for Docusaurus 2 called Infima which uses CSS variables for theming. The docs are not quite ready yet and we will update here when it is. To overwrite Infima's CSS variables, create your own CSS file (e.g. ./src/css/custom.css) and import it globally by passing it as an option to @docusaurus/preset-classic:","n":0.132}}},{"i":585,"$":{"0":{"v":"Infima uses 7 shades of each color.","n":0.378}}},{"i":586,"$":{"0":{"v":"We recommend using ColorBox to find the different shades of colors for your chosen primary color.","n":0.25}}},{"i":587,"$":{"0":{"v":"Alteratively, use the following tool to generate the different shades for your website and copy the variables into src/css/custom.css.","n":0.229}}},{"i":588,"$":{"0":{"v":"Primary Color:","n":0.707}}},{"i":589,"$":{"0":{"v":"Replace the variables in src/css/custom.css with these new variables.","n":0.333}}},{"i":590,"$":{"0":{"v":"Site meta info such as assets, SEO, copyright info are now handled by themes. To customize them, use the themeConfig field in your docusaurus.config.js:","n":0.204}}},{"i":591,"$":{"0":{"v":"In Docusaurus 1, header icon and header links were root fields in siteConfig:","n":0.277}}},{"i":592,"$":{"0":{"v":"Now, these two fields are both handled by the theme:","n":0.316}}},{"i":593,"$":{"0":{"v":"Deprecated. Pass it as a blog option to @docusaurus/preset-classic instead:","n":0.316}}},{"i":594,"$":{"0":{"v":"Deprecated. Create a CNAME file in your static folder instead with your custom domain. Files in the static folder will be copied into the root of the build folder during execution of the build command.","n":0.169}}},{"i":595,"$":{"0":{"v":"BREAKING: editUrl should point to (website) docusaurus project instead of docs directory.","n":0.289}}},{"i":596,"$":{"0":{"v":"Deprecated. Pass it as an option to @docusaurus/preset-classic docs instead:","n":0.316}}},{"i":597,"$":{"0":{"v":"Removed fields","n":0.707}}},{"i":598,"$":{"0":{"v":"The following fields are all deprecated, you may remove from your configuration file.","n":0.277}}},{"i":599,"$":{"0":{"v":"We intend to implement many of the deprecated config fields as plugins in future. Help will be appreciated!","n":0.236}}},{"i":600,"$":{"0":{"v":"Urls","n":1}}},{"i":601,"$":{"0":{"v":"In v1, all pages were available with or without the .html extension.","n":0.289}}},{"i":602,"$":{"0":{"v":"For example, these 2 pages exist:","n":0.408}}},{"i":603,"$":{"0":{"v":"If cleanUrl was:","n":0.577}}},{"i":604,"$":{"0":{"v":"In v2, by default, the canonical page is /installation, and not /installation.html.","n":0.289}}},{"i":605,"$":{"0":{"v":"If you had cleanUrl: false in v1, it's possible that people published links to /installation.html.","n":0.258}}},{"i":606,"$":{"0":{"v":"For SEO reasons, and avoiding breaking links, you should configure server-side redirect rules on your hosting provider.","n":0.243}}},{"i":607,"$":{"0":{"v":"As an escape hatch, you could use @docusaurus/plugin-client-redirects to create client-side redirects from /installation.html to /installation.","n":0.25}}},{"i":608,"$":{"0":{"v":"If you want to keep the .html extension as the canonical url of a page, docs can declare a slug: installation.html frontmatter.","n":0.213}}},{"i":609,"$":{"0":{"v":"Components","n":1}}},{"i":610,"$":{"0":{"v":"Sidebar","n":1}}},{"i":611,"$":{"0":{"v":"In previous version, nested sidebar category is not allowed and sidebar category can only contain doc id. However, v2 allows infinite nested sidebar and we have many types of Sidebar Item other than document.","n":0.171}}},{"i":612,"$":{"0":{"v":"You'll have to migrate your sidebar if it contains category type. Rename subcategory to category and ids to items.","n":0.229}}},{"i":613,"$":{"0":{"v":"Footer","n":1}}},{"i":614,"$":{"0":{"v":"website/core/Footer.js is no longer needed. If you want to modify the default footer provided by Docusaurus, swizzle it:","n":0.236}}},{"i":615,"$":{"0":{"v":"This will copy the current <Footer /> component used by the theme to a src/theme/Footer directory under the root of your site, you may then edit this component for customization.","n":0.183}}},{"i":616,"$":{"0":{"v":"Do not swizzle the Footer just to add the logo on the left. The logo is intentionally removed in v2 and moved to the bottom. Just configure the footer in docusaurus.config.js with themeConfig.footer:","n":0.174}}},{"i":617,"$":{"0":{"v":"Pages","n":1}}},{"i":618,"$":{"0":{"v":"Please refer to creating pages to learn how Docusaurus 2 pages work. After reading that, notice that you have to move pages/en files in v1 to src/pages instead.","n":0.189}}},{"i":619,"$":{"0":{"v":"In Docusaurus v1, pages received the siteConfig object as props.","n":0.316}}},{"i":620,"$":{"0":{"v":"In Docusaurus v2, get the siteConfig object from useDocusaurusContext instead.","n":0.316}}},{"i":621,"$":{"0":{"v":"In v2, you have to apply the theme layout around each page. The Layout component takes metadata props (permalink is important, as it defines the canonical url of your page).","n":0.183}}},{"i":622,"$":{"0":{"v":"CompLibrary is deprecated in v2, so you have to write your own React component or use Infima styles (Docs will be available soon, sorry about that! In the meanwhile, inspect the V2 website or view https://facebookincubator.github.io/infima/ to see what styles are available).","n":0.154}}},{"i":623,"$":{"0":{"v":"You can migrate CommonJS to ES6 imports/exports.","n":0.378}}},{"i":624,"$":{"0":{"v":"Here's a typical Docusaurus v2 page:","n":0.408}}},{"i":625,"$":{"0":{"v":"The following code could be helpful for migration of various pages:","n":0.302}}},{"i":626,"$":{"0":{"v":"Content","n":1}}},{"i":627,"$":{"0":{"v":"Remove AUTOGENERATED_TABLE_OF_CONTENTS","n":0.707}}},{"i":628,"$":{"0":{"v":"This feature is deprecated. You may read more about it in this issue. If you need the feature, use remark-toc instead and pass it to docs plugin's remarkPlugins option.","n":0.186}}},{"i":629,"$":{"0":{"v":"Update Markdown syntax to be MDX-compatible","n":0.408}}},{"i":630,"$":{"0":{"v":"In Docusaurus 2, the markdown syntax has been changed to MDX. Hence there might be some broken syntax in the existing docs which you would have to update. A common example is self-closing tags like <img> and <br> which are valid in HTML would have to be explicitly closed now ( <img/> and <br/>). All tags in MDX documents have to be valid JSX.","n":0.125}}},{"i":631,"$":{"0":{"v":"Frontmatter is parsed by gray-matter. If your frontmatter use special characters like :, you now need to quote it: title: Part 1: my part1 title -> title: Part 1: \"my part1 title\".","n":0.177}}},{"i":632,"$":{"0":{"v":"Tips: You might want to use some online tools like HTML to JSX to make the migration easier.","n":0.236}}},{"i":633,"$":{"0":{"v":"Language-specific code tabs","n":0.577}}},{"i":634,"$":{"0":{"v":"Refer to the multi-language support code blocks section.","n":0.354}}},{"i":635,"$":{"0":{"v":"Front matter","n":0.707}}},{"i":636,"$":{"0":{"v":"The Docusaurus front matter fields for the blog have been changed from camelCase to snake_case to be consistent with the docs.","n":0.218}}},{"i":637,"$":{"0":{"v":"The fields authorFBID and authorTwitter have been deprecated. They are only used for generating the profile image of the author which can be done via the author_image_url field.","n":0.189}}},{"i":638,"$":{"0":{"v":"Test your site","n":0.577}}},{"i":639,"$":{"0":{"v":"After migration, your folder structure should look like this:","n":0.333}}},{"i":640,"$":{"0":{"v":"Start the development server and fix any errors:","n":0.354}}},{"i":641,"$":{"0":{"v":"Migration command","n":0.707}}},{"i":642,"$":{"0":{"v":"The migration command automatically migrates your v1 website to a v2 website.","n":0.289}}},{"i":643,"$":{"0":{"v":"The migration command migrates:","n":0.5}}},{"i":644,"$":{"0":{"v":"Manual tweaking is still required after using the migration command. You still need to migrate your footer, pages and content.","n":0.224}}},{"i":645,"$":{"0":{"v":"To use the migration command, follow these steps:","n":0.354}}},{"i":646,"$":{"0":{"v":"Before using the migration command, ensure that /docs, /blog, /static, sidebars.json, siteConfig.js, package.json follow the structure shown at the start of this page.","n":0.209}}},{"i":647,"$":{"0":{"v":"To migrate your v1 website, run the migration command with the appropriate filesystem paths:","n":0.267}}},{"i":648,"$":{"0":{"v":"You can add option flags to the migration command to automatically migrate markdown content and pages to v2. It is likely that you will still need to make some manual changes to achieve your desired result.","n":0.167}}},{"i":649,"$":{"0":{"v":"The migration of pages and MDX is still a work in progress.","n":0.289}}},{"i":650,"$":{"0":{"v":"We recommend you to try to run the pages without these options, commit, and then try to run the migration again with the --page and --mdx options.","n":0.192}}},{"i":651,"$":{"0":{"v":"This way, you'd be able to easily inspect and fix the diff.","n":0.289}}},{"i":652,"$":{"0":{"v":"Example migration PRs","n":0.577}}},{"i":653,"$":{"0":{"v":"You might want to refer to our migration PRs for Create React App and Flux as examples of how a migration for a basic Docusaurus v1 site can be done.","n":0.183}}},{"i":654,"$":{"0":{"v":"Support","n":1}}},{"i":655,"$":{"0":{"v":"For any questions, you can ask in the #docusaurus-1-to-2-migration Discord channel. Feel free to tag @yangshun in any migration PRs if you would like us to have a look.","n":0.186}}},{"i":656,"$":{"0":{"v":"Versioned Site","n":0.707}}},{"i":657,"$":{"0":{"v":"The versioning feature is a work in progress! Although we've implemented docs versioning since 2.0.0-alpha.37, we'd like to test it out for v2 users first before we recommend v1 users to migrate to v2. There are some changes in how v2 versioning works compared to v1. In the future, we might create a script to migrate your versioned docs easier. However, if you are adventurous enough to manually migrate, feel free to do so. Be warned though, the manual migration requires lot of work.","n":0.109}}},{"i":658,"$":{"0":{"v":"Read up https://v2.docusaurus.io/blog/2018/09/11/Towards-Docusaurus-2#versioning first for problems in v1's approach.","n":0.333}}},{"i":659,"$":{"0":{"v":"Migrate your versioned_docs front matter","n":0.447}}},{"i":660,"$":{"0":{"v":"Unlike v1, The markdown header for each versioned doc is no longer altered by using version-${version}-${original_id} as the value for the actual id field. See scenario below for better explanation.","n":0.183}}},{"i":661,"$":{"0":{"v":"For example, if you have a docs/hello.md.","n":0.378}}},{"i":662,"$":{"0":{"v":"When you cut a new version 1.0.0, in Docusaurus v1, website/versioned_docs/version-1.0.0/hello.md looks like this:","n":0.267}}},{"i":663,"$":{"0":{"v":"In comparison, Docusaurus 2 website/versioned_docs/version-1.0.0/hello.md looks like this (exactly same as original)","n":0.289}}},{"i":664,"$":{"0":{"v":"Since we're going for snapshot and allow people to move (and edit) docs easily inside version. The id frontmatter is no longer altered and will remain the same. Internally, it is set as version-${version}/${id}.","n":0.171}}},{"i":665,"$":{"0":{"v":"Essentially, here are the necessary changes in each versioned_docs file:","n":0.316}}},{"i":666,"$":{"0":{"v":"Migrate your versioned_sidebars","n":0.577}}},{"i":667,"$":{"0":{"v":"Because in v1 there is a good chance someone created a new file with front matter id \"version-${version}-${id}\" that can conflict with versioned_docs id.","n":0.204}}},{"i":668,"$":{"0":{"v":"For example, Docusaurus 1 can't differentiate docs/xxx.md","n":0.378}}},{"i":669,"$":{"0":{"v":"vs website/versioned_docs/version-1.0.0/hello.md","n":0.707}}},{"i":670,"$":{"0":{"v":"Since we don't allow / in v1 & v2 for frontmatter, conflicts are less likely to occur.","n":0.243}}},{"i":671,"$":{"0":{"v":"So v1 users need to migrate their versioned_sidebars file","n":0.333}}},{"i":672,"$":{"0":{"v":"Example versioned_sidebars/version-1.0.0-sidebars.json:","n":0.707}}},{"i":673,"$":{"0":{"v":"Populate your versioned_sidebars and versioned_docs","n":0.447}}},{"i":674,"$":{"0":{"v":"In v2, we use snapshot approach for documentation versioning. Every versioned docs does not depends on other version. It is possible to have foo.md in version-1.0.0 but it doesn't exist in version-1.2.0. This is not possible in previous version due to Docusaurus v1 fallback functionality (https://docusaurus.io/docs/en/versioning#fallback-functionality).","n":0.147}}},{"i":675,"$":{"0":{"v":"For example, if your versions.json looks like this in v1","n":0.316}}},{"i":676,"$":{"0":{"v":"Docusaurus v1 creates versioned docs if and only if the doc content is different. Your docs structure might look like this if the only doc changed from v1.0.0 to v1.1.0 is hello.md.","n":0.177}}},{"i":677,"$":{"0":{"v":"In v2, you have to populate the missing versioned_docs and versioned_sidebars (with the right frontmatter and id reference too).","n":0.229}}},{"i":678,"$":{"0":{"v":"Convert style attributes to style objects in MDX","n":0.354}}},{"i":679,"$":{"0":{"v":"Docusaurus 2 uses JSX for doc files. If you have any style attributes in your Docusaurus 1 docs, convert them to style objects, like this:","n":0.2}}},{"i":680,"$":{"0":{"v":"Introduction","n":1}}},{"i":681,"$":{"0":{"v":"Disclaimer","n":1}}},{"i":682,"$":{"0":{"v":"It has been a year since we made the first alpha release of Docusaurus 2 and things have been pretty stable since then. Many of Facebook's new open source websites are using Docusaurus 2 now. At this point, we highly encourage you to use Docusaurus 2 over Docusaurus 1 for your new websites. For feedback and questions, chat with us on Discord 😉","n":0.126}}},{"i":683,"$":{"0":{"v":"You should use this if:","n":0.447}}},{"i":684,"$":{"0":{"v":"Do not use this if:","n":0.447}}},{"i":685,"$":{"0":{"v":"A better Docusaurus is coming to town","n":0.378}}},{"i":686,"$":{"0":{"v":"Docusaurus 1 used to be a pure documentation site generator. In Docusaurus 2, we rebuilt it from the ground up, allowing for more customizability but preserved the best parts of Docusaurus 1 - easy to get started, versioned docs, and i18n (coming soon).","n":0.152}}},{"i":687,"$":{"0":{"v":"Beyond that, Docusaurus 2 is a performant static site generator and can be used to create common content-driven websites (e.g. Documentation, Blogs, Product Landing and Marketing Pages, etc) extremely quickly.","n":0.183}}},{"i":688,"$":{"0":{"v":"While our main focus will still be helping you get your documentations right and well, it is possible to build this any kind of website using Docusaurus 2 as it is just a React application. Docusaurus can now be used to build any website, not just documentation websites.","n":0.144}}},{"i":689,"$":{"0":{"v":"Features","n":1}}},{"i":690,"$":{"0":{"v":"Docusaurus is built with high attention to your experience building your site and maintaining it with your collaborators and contributors.","n":0.224}}},{"i":691,"$":{"0":{"v":"Our shared goal — to help your users find what they need fast, and understand your products better. With the experience of Docusaurus 1, we share with you our best practices to help you build your doc site right and well.","n":0.156}}},{"i":692,"$":{"0":{"v":"Docusaurus 2 is born to be compassionately accessible to all your users, and lightning fast.","n":0.258}}},{"i":693,"$":{"0":{"v":"Comparison with other tools","n":0.5}}},{"i":694,"$":{"0":{"v":"Across all static site generators, Docusaurus has a unique focus on doc sites and has out-of-the-box structure you need.","n":0.229}}},{"i":695,"$":{"0":{"v":"We've also studied other main static site generators and would like to share our insights on the comparison, hopefully to help you navigate through the prismatic choices out there.","n":0.186}}},{"i":696,"$":{"0":{"v":"Gatsby","n":1}}},{"i":697,"$":{"0":{"v":"Gatsby is packed with a lot of features, has a rich ecosystem of plugins and is capable of doing everything that Docusaurus does. Naturally, that comes at a cost of a higher learning curve. Gatsby does many things well and is suitable for building many types of websites. On the other hand, Docusaurus tries to do one thing super well - be the best tool for writing and publishing content.","n":0.12}}},{"i":698,"$":{"0":{"v":"GraphQL is also pretty core to Gatsby, although you don't necessarily need GraphQL to build a Gatsby site. In most cases when building static websites, you won't need the flexibility that GraphQL provides.","n":0.174}}},{"i":699,"$":{"0":{"v":"Many aspects of Docusaurus 2 were inspired by the best things about Gatsby and it's a great alternative.","n":0.236}}},{"i":700,"$":{"0":{"v":"GitBook","n":1}}},{"i":701,"$":{"0":{"v":"GitBook has very clean design and has been used by many open source projects. With its focus shifting towards a commercial product rather than an open-source tool, many of its requirements no longer fit the needs as an open source project's documentation site. As a result, many have turned to other products. You may read about Redux's switch to Docusaurus here.","n":0.128}}},{"i":702,"$":{"0":{"v":"Currently, GitBook is only free for open-source and non-profit teams. Docusaurus is free for everyone.","n":0.258}}},{"i":703,"$":{"0":{"v":"Jekyll","n":1}}},{"i":704,"$":{"0":{"v":"Jekyll is one of the most mature static site generators around and has been a great tool to use — in fact, before Docusaurus, most of Facebook's Open Source websites are/were built on Jekyll! It is extremely simple to get started. We want to bring a similar developer experience as building a static site with Jekyll.","n":0.134}}},{"i":705,"$":{"0":{"v":"In comparison with statically generated HTML and interactivity added using <script /> tags, Docusaurus sites are React apps. Using modern JavaScript ecosystem tooling, we hope to set new standards on doc sites performance, asset build pipeline and optimizations, and ease to setup.","n":0.154}}},{"i":706,"$":{"0":{"v":"VuePress","n":1}}},{"i":707,"$":{"0":{"v":"VuePress has many similarities with Docusaurus - both focus heavily on content-centric website and provides tailored documentation features out of the box. However, VuePress is powered by Vue, while Docusaurus is powered by React. If you want a Vue-based solution, VuePress would be a decent choice.","n":0.147}}},{"i":708,"$":{"0":{"v":"Staying informed","n":0.707}}},{"i":709,"$":{"0":{"v":"Something missing?","n":0.707}}},{"i":710,"$":{"0":{"v":"If you find issues with the documentation or have suggestions on how to improve the documentation or the project in general, please file an issue for us, or send a tweet mentioning the @docusaurus Twitter account.","n":0.167}}},{"i":711,"$":{"0":{"v":"For new feature requests, you can create a post on our Canny board, which is a handy tool for roadmapping and allows for sorting by upvotes, which gives the core team a better indicator of what features are in high demand, as compared to GitHub issues which are harder to triage. Refrain from making a Pull Request for new features (especially large ones) as someone might already be working on it or will be part of our roadmap. Talk to us first!","n":0.11}}},{"i":712,"$":{"0":{"v":"Presets","n":1}}},{"i":713,"$":{"0":{"v":"Presets are collections of plugins and themes.","n":0.378}}},{"i":714,"$":{"0":{"v":"Using presets","n":0.707}}},{"i":715,"$":{"0":{"v":"A preset is usually a npm package, so you install them like other npm packages using npm.","n":0.243}}},{"i":716,"$":{"0":{"v":"Then, add it in your site's docusaurus.config.js's presets option:","n":0.333}}},{"i":717,"$":{"0":{"v":"To load presets from your local directory, specify how to resolve them:","n":0.289}}},{"i":718,"$":{"0":{"v":"Presets -> themes and plugins","n":0.447}}},{"i":719,"$":{"0":{"v":"Presets in some way are a shorthand function to add plugins and themes to your docusaurus config. For example, you can specify a preset that includes the following themes and plugins,","n":0.18}}},{"i":720,"$":{"0":{"v":"then in your Docusaurus config, you may configure the preset instead:","n":0.302}}},{"i":721,"$":{"0":{"v":"This is equivalent of doing:","n":0.447}}},{"i":722,"$":{"0":{"v":"This is especially useful when some plugins and themes are intended to be used together.","n":0.258}}},{"i":723,"$":{"0":{"v":"Official presets","n":0.707}}},{"i":724,"$":{"0":{"v":"@docusaurus/preset-classic","n":1}}},{"i":725,"$":{"0":{"v":"The classic preset that is usually shipped by default to new docusaurus website. It is a set of plugins and themes.","n":0.218}}},{"i":726,"$":{"0":{"v":"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:","n":0.196}}},{"i":727,"$":{"0":{"v":"In addition to these plugins and themes, @docusaurus/theme-classic adds remark-admonitions as a remark plugin to @docusaurus/plugin-content-blog and @docusaurus/plugin-content-docs.","n":0.236}}},{"i":728,"$":{"0":{"v":"The admonitions key will be passed as the options to remark-admonitions. Passing false will prevent the plugin from being added to MDX.","n":0.213}}},{"i":729,"$":{"0":{"v":"Awesome Resources","n":0.707}}},{"i":730,"$":{"0":{"v":"A curated list of interesting Docusaurus community projects.","n":0.354}}},{"i":731,"$":{"0":{"v":"Videos","n":1}}},{"i":732,"$":{"0":{"v":"Articles","n":1}}},{"i":733,"$":{"0":{"v":"Showcase","n":1}}},{"i":734,"$":{"0":{"v":"See the showcase.","n":0.577}}},{"i":735,"$":{"0":{"v":"Official plugins","n":0.707}}},{"i":736,"$":{"0":{"v":"Community plugins","n":0.707}}},{"i":737,"$":{"0":{"v":"Enterprise usage","n":0.707}}},{"i":738,"$":{"0":{"v":"Search","n":1}}},{"i":739,"$":{"0":{"v":"Docusaurus' own @docusaurus/preset-classic supports a search integration.","n":0.378}}},{"i":740,"$":{"0":{"v":"There are two main options, you can use Algolia DocSearch or bring in your own SearchBar component.","n":0.243}}},{"i":741,"$":{"0":{"v":"Using Algolia DocSearch","n":0.577}}},{"i":742,"$":{"0":{"v":"Algolia DocSearch works by crawling the content of your website every 24 hours and putting all the content in an Algolia index. This content is then queried directly from your front-end using the Algolia API. Note that your website needs to be publicly available for this to work (i.e., not behind a firewall). The service is free.","n":0.132}}},{"i":743,"$":{"0":{"v":"Connecting Algolia","n":0.707}}},{"i":744,"$":{"0":{"v":"To connect your docs with Algolia, add an algolia field in your themeConfig. Apply for DocSearch to get your Algolia index and API key.","n":0.204}}},{"i":745,"$":{"0":{"v":"The searchParameters option used to be named algoliaOptions in Docusaurus v1.","n":0.302}}},{"i":746,"$":{"0":{"v":"Styling your Algolia search","n":0.5}}},{"i":747,"$":{"0":{"v":"By default, DocSearch comes with a fine-tuned theme that was designed for accessibility, making sure that colors and contrasts respect standards.","n":0.218}}},{"i":748,"$":{"0":{"v":"Still, you can reuse the Infima CSS variables from Docusaurus to style DocSearch by editing the /src/css/custom.css file.","n":0.236}}},{"i":749,"$":{"0":{"v":"Customizing the Algolia search behavior","n":0.447}}},{"i":750,"$":{"0":{"v":"Algolia DocSearch supports a list of options that you can pass to the algolia field in the docusaurus.config.js file.","n":0.229}}},{"i":751,"$":{"0":{"v":"Editing the Algolia search component","n":0.447}}},{"i":752,"$":{"0":{"v":"If you prefer to edit the Algolia search React component, swizzle the SearchBar component in @docusaurus/theme-search-algolia:","n":0.25}}},{"i":753,"$":{"0":{"v":"Using your own search","n":0.5}}},{"i":754,"$":{"0":{"v":"To use your own search, swizzle the SearchBar component in @docusaurus/theme-classic","n":0.302}}},{"i":755,"$":{"0":{"v":"This will create a src/themes/SearchBar file in your project folder. Restart your dev server and edit the component, you will see that Docusaurus uses your own SearchBar component now.","n":0.186}}},{"i":756,"$":{"0":{"v":"Notes: You can alternatively swizzle from Algolia SearchBar and create your own search component from there.","n":0.25}}},{"i":757,"$":{"0":{"v":"Static Assets","n":0.707}}},{"i":758,"$":{"0":{"v":"In general, every website needs assets: images, stylesheets, favicons and etc. In such cases, you can create a directory named static at the root of your project. Every file you put into that directory will be copied into the the root of the generated build folder with the directory hierarchy preserved. E.g. if you add a file named sun.jpg to the static folder, it’ll be copied to build/sun.jpg.","n":0.121}}},{"i":759,"$":{"0":{"v":"This means that if the site's baseUrl is /, an image in /static/img/docusaurus_keytar.svg is available at /img/docusaurus_keytar.svg.","n":0.243}}},{"i":760,"$":{"0":{"v":"Referencing your static asset","n":0.5}}},{"i":761,"$":{"0":{"v":"You can reference assets from the static folder in your code. You could use hardcoded absolute paths, i.e. starting with a slash /, but remember to include the baseUrl if it is not /. However, this will break if you change your baseUrl in the config.","n":0.147}}},{"i":762,"$":{"0":{"v":"A better way would be to use the useBaseUrl utility function which appends the baseUrl to paths for you.","n":0.229}}},{"i":763,"$":{"0":{"v":"JSX example","n":0.707}}},{"i":764,"$":{"0":{"v":"You can also import SVG images, which will be transformed into React components.","n":0.277}}},{"i":765,"$":{"0":{"v":"Markdown example","n":0.707}}},{"i":766,"$":{"0":{"v":"Thanks to MDX, you can also use useBaseUrl utility function in Markdown files! You'd have to use <img> tags instead of the Markdown image syntax though. The syntax is exactly the same as in JSX.","n":0.169}}},{"i":767,"$":{"0":{"v":"You could also just use Markdown image syntax, but you would have to manually maintain the image paths yourself and isn't recommended.","n":0.213}}},{"i":768,"$":{"0":{"v":"Caveats","n":1}}},{"i":769,"$":{"0":{"v":"Keep in mind that:","n":0.5}}},{"i":770,"$":{"0":{"v":"Styling and Layout","n":0.577}}},{"i":771,"$":{"0":{"v":"Traditional CSS","n":0.707}}},{"i":772,"$":{"0":{"v":"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.","n":0.196}}},{"i":773,"$":{"0":{"v":"Any CSS you write within that file will be available globally and can be referenced directly using string literals. This is the most traditional approach to writing CSS and is fine for small websites that do not have much customization.","n":0.158}}},{"i":774,"$":{"0":{"v":"Styling your site with Infima","n":0.447}}},{"i":775,"$":{"0":{"v":"@docusaurus/preset-classic uses 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.","n":0.174}}},{"i":776,"$":{"0":{"v":"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.","n":0.186}}},{"i":777,"$":{"0":{"v":"Infima uses 7 shades of each color. We recommend using ColorBox to find the different shades of colors for your chosen primary color.","n":0.209}}},{"i":778,"$":{"0":{"v":"Alternatively, use the following tool to generate the different shades for your website and copy the variables into /src/css/custom.css.","n":0.229}}},{"i":779,"$":{"0":{"v":"Primary Color:","n":0.707}}},{"i":780,"$":{"0":{"v":"Replace the variables in src/css/custom.css with these new variables.","n":0.333}}},{"i":781,"$":{"0":{"v":"Styling approaches","n":0.707}}},{"i":782,"$":{"0":{"v":"A Docusaurus site is a single-page React application. You can style it the way you style React apps.","n":0.236}}},{"i":783,"$":{"0":{"v":"There are a few approaches/frameworks which will work, depending on your preferences and the type of website you are trying to build. Websites that are highly interactive and behave more like web apps will benefit from a more modern styling approaches that co-locate styles with the components. Component styling can also be particularly useful when you wish to customize or swizzle a component.","n":0.126}}},{"i":784,"$":{"0":{"v":"Global styles","n":0.707}}},{"i":785,"$":{"0":{"v":"This is the most traditional way of styling that most developers (including non-front end developers) would be familiar with.","n":0.229}}},{"i":786,"$":{"0":{"v":"Assuming you are using @docusaurus/preset-classic and /src/css/custom.css was passed in to the preset config, styles inside that file would be available globally.","n":0.213}}},{"i":787,"$":{"0":{"v":"CSS modules","n":0.707}}},{"i":788,"$":{"0":{"v":"To style your components using CSS Modules, name your stylesheet files with the .module.css suffix (e.g. welcome.module.css). webpack will load such CSS files as CSS modules and you have to reference the class names from the imported CSS module (as opposed to using plain strings). This is similar to the convention used in Create React App.","n":0.134}}},{"i":789,"$":{"0":{"v":"The class names which will be processed by webpack into a globally unique class name during build.","n":0.243}}},{"i":790,"$":{"0":{"v":"CSS-in-JS","n":1}}},{"i":791,"$":{"0":{"v":"This section is a work in progress. Welcoming PRs.","n":0.333}}},{"i":792,"$":{"0":{"v":"Sass/SCSS","n":1}}},{"i":793,"$":{"0":{"v":"To use Sass/SCSS as your CSS preprocessor, install the unofficial Docusaurus 2 plugin docusaurus-plugin-sass. This plugin works for both global styles and the CSS modules approach:","n":0.196}}},{"i":794,"$":{"0":{"v":"You can now set the customCss property of @docusaurus/preset-classic to point to your Sass/SCSS file:","n":0.258}}},{"i":795,"$":{"0":{"v":"Name your stylesheet files with the .module.scss suffix (e.g. welcome.module.scss) instead of .css. Webpack will use sass-loader to preprocess your stylesheets and load them as CSS modules.","n":0.192}}},{"i":796,"$":{"0":{"v":"Support","n":1}}},{"i":797,"$":{"0":{"v":"Docusaurus has a community of thousands of developers.","n":0.354}}},{"i":798,"$":{"0":{"v":"On this page we've listed some Docusaurus-related communities that you can be a part of; see the other pages in this section for additional online and in-person learning materials.","n":0.186}}},{"i":799,"$":{"0":{"v":"Before participating in Docusaurus' communities, please read our Code of Conduct. We have adopted the Contributor Covenant and we expect that all community members adhere to the guidelines within.","n":0.186}}},{"i":800,"$":{"0":{"v":"Stack Overflow","n":0.707}}},{"i":801,"$":{"0":{"v":"Stack Overflow is a popular forum to ask code-level questions or if you're stuck with a specific error. Read through the existing questions tagged with docusaurus or ask your own!","n":0.183}}},{"i":802,"$":{"0":{"v":"Discussion forums","n":0.707}}},{"i":803,"$":{"0":{"v":"There are many online forums which are a great place for discussion about best practices and application architecture as well as the future of Docusaurus. If you have an answerable code-level question, Stack Overflow is usually a better fit.","n":0.16}}},{"i":804,"$":{"0":{"v":"Feature requests","n":0.707}}},{"i":805,"$":{"0":{"v":"For new feature requests, you can create a post on our Canny board, which is a handy tool for roadmapping and allows for sorting by upvotes, which gives the core team a better indicator of what features are in high demand, as compared to GitHub issues which are harder to triage. Refrain from making a Pull Request for new features (especially large ones) as someone might already be working on it or will be part of our roadmap. Talk to us first!","n":0.11}}},{"i":806,"$":{"0":{"v":"News","n":1}}},{"i":807,"$":{"0":{"v":"For the latest news about Docusaurus, follow @docusaurus on Twitter and the official Docusaurus blog on this website.","n":0.236}}},{"i":808,"$":{"0":{"v":"Team","n":1}}},{"i":809,"$":{"0":{"v":"Active Team","n":0.707}}},{"i":810,"$":{"0":{"v":"Alexey Pyltsyn","n":0.707}}},{"i":811,"$":{"0":{"v":"Fanny Vieira","n":0.707}}},{"i":812,"$":{"0":{"v":"Joel Marcey","n":0.707}}},{"i":813,"$":{"0":{"v":"Yangshun Tay","n":0.707}}},{"i":814,"$":{"0":{"v":"Honorary Alumni","n":0.707}}},{"i":815,"$":{"0":{"v":"Endilie Yacop Sucipto","n":0.577}}},{"i":816,"$":{"0":{"v":"Wei Gao","n":0.707}}},{"i":817,"$":{"0":{"v":"Acknowledgements","n":1}}},{"i":818,"$":{"0":{"v":"Docusaurus was originally created by Joel Marcey. Today, Docusaurus has a few hundred open source contributors. We’d like to recognize a few people who have made significant contributions to Docusaurus and its documentation in the past and have helped maintain them over the years:","n":0.151}}},{"i":819,"$":{"0":{"v":"@docusaurus/theme-classic","n":1}}},{"i":820,"$":{"0":{"v":"This section is a work in progress.","n":0.378}}},{"i":821,"$":{"0":{"v":"Common","n":1}}},{"i":822,"$":{"0":{"v":"Color mode - dark mode","n":0.447}}},{"i":823,"$":{"0":{"v":"The classic theme provides by default light and dark mode support, with a navbar switch for the user.","n":0.236}}},{"i":824,"$":{"0":{"v":"It is possible to customize the color mode support with the following configuration:","n":0.277}}},{"i":825,"$":{"0":{"v":"With respectPrefersColorScheme: true, the defaultMode is overridden by user system preferences.","n":0.302}}},{"i":826,"$":{"0":{"v":"If you only want to support one color mode, you likely want to ignore user system preferences.","n":0.243}}},{"i":827,"$":{"0":{"v":"Meta image","n":0.707}}},{"i":828,"$":{"0":{"v":"You can configure a default image that will be used for your meta tag, in particular og:image and twitter:image.","n":0.229}}},{"i":829,"$":{"0":{"v":"Announcement bar","n":0.707}}},{"i":830,"$":{"0":{"v":"Sometimes you want to announce something in your website. Just for such a case, you can add an announcement bar. This is a non-fixed and dismissable panel above the navbar.","n":0.183}}},{"i":831,"$":{"0":{"v":"Hooks","n":1}}},{"i":832,"$":{"0":{"v":"useThemeContext","n":1}}},{"i":833,"$":{"0":{"v":"React hook to access theme context. This context contains functions for setting light and dark mode and boolean property, indicating which mode is currently in use.","n":0.196}}},{"i":834,"$":{"0":{"v":"Usage example:","n":0.707}}},{"i":835,"$":{"0":{"v":"The component calling useThemeContext must be a child of the Layout component.","n":0.289}}},{"i":836,"$":{"0":{"v":"Navbar","n":1}}},{"i":837,"$":{"0":{"v":"Navbar title & logo","n":0.5}}},{"i":838,"$":{"0":{"v":"You can add a logo and title to the navbar via themeConfig.navbar. Logo can be placed in static folder. Logo URL is set to base URL of your site by default. Although you can specify your own URL for the logo, if it is an external link, it will open in a new tab. In addition, you can override a value for the target attribute of logo link, it can come in handy if you are hosting docs website in a subdirectory of your main website, and in which case you probably do not need a link in the logo to the main website will open in a new tab.","n":0.095}}},{"i":839,"$":{"0":{"v":"To improve dark mode support, you can also set a different logo for this mode.","n":0.258}}},{"i":840,"$":{"0":{"v":"Navbar items","n":0.707}}},{"i":841,"$":{"0":{"v":"You can add items to the navbar via themeConfig.navbar.items.","n":0.333}}},{"i":842,"$":{"0":{"v":"By default, Navbar items are regular links (internal or external).","n":0.316}}},{"i":843,"$":{"0":{"v":"React Router should automatically apply active link styling to links, but you can use activeBasePath in edge cases. For cases in which a link should be active on several different paths (such as when you have multiple doc folders under the same sidebar), you can use activeBaseRegex. activeBaseRegex is a more flexible alternative to activeBasePath and takes precedence over it -- Docusaurus parses it into a regular expression that is tested against the current URL.","n":0.115}}},{"i":844,"$":{"0":{"v":"Outbound (external) links automatically get target=\"_blank\" rel=\"noopener noreferrer\" attributes.","n":0.333}}},{"i":845,"$":{"0":{"v":"Navbar dropdown","n":0.707}}},{"i":846,"$":{"0":{"v":"Navbar items can also be dropdown items by specifying the items, an inner array of navbar items.","n":0.243}}},{"i":847,"$":{"0":{"v":"Navbar docs version dropdown","n":0.5}}},{"i":848,"$":{"0":{"v":"If you use docs with versioning, this special navbar item type that will render a dropdown with all your site's available versions. The user will be able to switch from one version to another, while staying on the same doc (as long as the doc id is constant across versions).","n":0.141}}},{"i":849,"$":{"0":{"v":"Navbar docs version","n":0.577}}},{"i":850,"$":{"0":{"v":"If you use docs with versioning, this special navbar item type will link to the active/browsed version of your doc (depends on the current url), and fallback to the latest version.","n":0.18}}},{"i":851,"$":{"0":{"v":"Auto-hide sticky navbar","n":0.577}}},{"i":852,"$":{"0":{"v":"You can enable this cool UI feature that automatically hides the navbar when a user starts scrolling down the page, and show it again when the user scrolls up.","n":0.186}}},{"i":853,"$":{"0":{"v":"CodeBlock","n":1}}},{"i":854,"$":{"0":{"v":"Docusaurus uses Prism React Renderer to highlight code blocks.","n":0.333}}},{"i":855,"$":{"0":{"v":"Theme","n":1}}},{"i":856,"$":{"0":{"v":"By default, we use Palenight as syntax highlighting theme. You can specify a custom theme from the list of available themes. If you want to use a different syntax highlighting theme when the site is in dark mode, you may also do so.","n":0.152}}},{"i":857,"$":{"0":{"v":"If you use the line highlighting Markdown syntax, you might need to specify a different highlight background color for the dark mode syntax highlighting theme. Refer to the docs for guidance.","n":0.18}}},{"i":858,"$":{"0":{"v":"Default language","n":0.707}}},{"i":859,"$":{"0":{"v":"You can set a default language for code blocks if no language is added after the opening triple backticks (i.e. ```). Note that a valid language name must be passed, e.g.:","n":0.18}}},{"i":860,"$":{"0":{"v":"TypeScript Support","n":0.707}}},{"i":861,"$":{"0":{"v":"Setup","n":1}}},{"i":862,"$":{"0":{"v":"Docusaurus supports writing and using TypeScript theme components. To start using TypeScript, add @docusaurus/module-type-aliases to your project:","n":0.243}}},{"i":863,"$":{"0":{"v":"Then add tsconfig.json to your project root with following content:","n":0.316}}},{"i":864,"$":{"0":{"v":"Docusaurus doesn't use this tsconfig.json to compile your TypeScript. It is added just for a nicer Editor experience, although you can choose to run tsc --noEmit to type check your code for yourself.","n":0.174}}},{"i":865,"$":{"0":{"v":"Then add types.d.ts in your src folder with the following content:","n":0.302}}},{"i":866,"$":{"0":{"v":"This file makes TypeScript recognize various Docusaurus specific webpack aliases like @theme, @docusaurus, @generated.","n":0.267}}},{"i":867,"$":{"0":{"v":"Now you can start writing TypeScript theme components.","n":0.354}}},{"i":868,"$":{"0":{"v":"Swizzling TypeScript theme components","n":0.5}}},{"i":869,"$":{"0":{"v":"For themes that supports TypeScript theme components, you can add the --typescript flag to the end of swizzling command to get TypeScript source code. For example, the following command will generate index.tsx and styles.module.css into src/theme/Footer.","n":0.167}}},{"i":870,"$":{"0":{"v":"At this moment, the only official Docusaurus theme that supports TypeScript theme components is @docusaurus/theme-classic. If you are a Docusaurus theme package author who wants to add TypeScript support, see the Lifecycle APIs docs.","n":0.171}}},{"i":871,"$":{"0":{"v":"Plugins","n":1}}},{"i":872,"$":{"0":{"v":"Plugins are the building blocks of features in a Docusaurus 2 site. Each plugin handles its own individual feature. Plugins may work and be distributed as part of bundle via presets.","n":0.18}}},{"i":873,"$":{"0":{"v":"Installing a plugin","n":0.577}}},{"i":874,"$":{"0":{"v":"A plugin is usually a npm package, so you install them like other npm packages using npm.","n":0.243}}},{"i":875,"$":{"0":{"v":"Then you add it in your site's docusaurus.config.js's plugins option:","n":0.316}}},{"i":876,"$":{"0":{"v":"Docusaurus can also load plugins from your local directory, you can do something like the following:","n":0.25}}},{"i":877,"$":{"0":{"v":"Configuring plugins","n":0.707}}},{"i":878,"$":{"0":{"v":"For the most basic usage of plugins, you can provide just the plugin name or the absolute path to the plugin.","n":0.218}}},{"i":879,"$":{"0":{"v":"However, plugins can have options specified by wrapping the name and an options object in an array inside your config. This style is usually called Babel Style.","n":0.192}}},{"i":880,"$":{"0":{"v":"Example:","n":1}}},{"i":881,"$":{"0":{"v":"Multi-instance plugins and plugin ids","n":0.447}}},{"i":882,"$":{"0":{"v":"It is possible to use multiple times the same plugin, on the same Docusaurus website.","n":0.258}}},{"i":883,"$":{"0":{"v":"In this case, you it is required to assign a unique id to each plugin instance.","n":0.25}}},{"i":884,"$":{"0":{"v":"By default, the plugin id is default.","n":0.378}}},{"i":885,"$":{"0":{"v":"Plugins design","n":0.707}}},{"i":886,"$":{"0":{"v":"Docusaurus' implementation of the plugins system provides us with a convenient way to hook into the website's lifecycle to modify what goes on during development/build, which involves (but not limited to) extending the webpack config, modifying the data being loaded and creating new components to be used in a page.","n":0.141}}},{"i":887,"$":{"0":{"v":"Creating plugins","n":0.707}}},{"i":888,"$":{"0":{"v":"A plugin is a module which exports a function that takes two parameters and returns an object when executed.","n":0.229}}},{"i":889,"$":{"0":{"v":"Module definition","n":0.707}}},{"i":890,"$":{"0":{"v":"The exported modules for plugins are called with two parameters: context and options and returns a JavaScript object with defining the lifecycle APIs.","n":0.209}}},{"i":891,"$":{"0":{"v":"For example if you have a reference to a local folder such as this in your docusaurus.config.js:","n":0.243}}},{"i":892,"$":{"0":{"v":"Then in the folder my-plugin you can create an index.js such as this","n":0.277}}},{"i":893,"$":{"0":{"v":"The my-plugin folder could also be a fully fledged package with it's own package.json and a src/index.js file for example","n":0.224}}},{"i":894,"$":{"0":{"v":"context is plugin-agnostic and the same object will be passed into all plugins used for a Docusaurus website. The context object contains the following fields:","n":0.2}}},{"i":895,"$":{"0":{"v":"options are the second optional parameter when the plugins are used. options are plugin-specific and are specified by users when they use them in docusaurus.config.js. Alternatively, if preset contains the plugin, the preset will then be in charge of passing the correct options into the plugin. It is up to individual plugin to define what options it takes.","n":0.131}}},{"i":896,"$":{"0":{"v":"The returned object value should implement the lifecycle APIs.","n":0.333}}},{"i":897,"$":{"0":{"v":"Official plugins","n":0.707}}},{"i":898,"$":{"0":{"v":"Find the list of official Docusaurus plugins here.","n":0.354}}},{"i":899,"$":{"0":{"v":"@docusaurus/plugin-content-blog","n":1}}},{"i":900,"$":{"0":{"v":"Provides the Blog feature and is the default blog plugin for Docusaurus.","n":0.289}}},{"i":901,"$":{"0":{"v":"Installation","n":1}}},{"i":902,"$":{"0":{"v":"If you have installed @docusaurus/preset-classic, you don't need to install it as a dependency. You can also configure it through the classic preset options instead of doing it like below.","n":0.183}}},{"i":903,"$":{"0":{"v":"@docusaurus/plugin-content-docs","n":1}}},{"i":904,"$":{"0":{"v":"Provides the Docs functionality and is the default docs plugin for Docusaurus.","n":0.289}}},{"i":905,"$":{"0":{"v":"Installation","n":1}}},{"i":906,"$":{"0":{"v":"If you have installed @docusaurus/preset-classic, you don't need to install it as a dependency. You can also configure it through the classic preset options instead of doing it like below.","n":0.183}}},{"i":907,"$":{"0":{"v":"@docusaurus/plugin-content-pages","n":1}}},{"i":908,"$":{"0":{"v":"The default pages plugin for Docusaurus. The classic template ships with this plugin with default configurations. This plugin provides creating pages functionality.","n":0.213}}},{"i":909,"$":{"0":{"v":"Installation","n":1}}},{"i":910,"$":{"0":{"v":"If you have installed @docusaurus/preset-classic, you don't need to install it as a dependency. You can also configure it through the classic preset options instead of doing it like below.","n":0.183}}},{"i":911,"$":{"0":{"v":"@docusaurus/plugin-google-analytics","n":1}}},{"i":912,"$":{"0":{"v":"The default Google Analytics plugin. It is a JavaScript library for measuring how users interact with your website.","n":0.236}}},{"i":913,"$":{"0":{"v":"Installation","n":1}}},{"i":914,"$":{"0":{"v":"If you have installed @docusaurus/preset-classic, you don't need to install it as a dependency.","n":0.267}}},{"i":915,"$":{"0":{"v":"Configuration","n":1}}},{"i":916,"$":{"0":{"v":"@docusaurus/plugin-google-gtag","n":1}}},{"i":917,"$":{"0":{"v":"The default Global Site Tag (gtag.js) plugin. It is a JavaScript tagging framework and API that allows you to send event data to Google Analytics, Google Ads, and Google Marketing Platform. This section describes how to configure a Docusaurus site to enable global site tag for Google Analytics.","n":0.144}}},{"i":918,"$":{"0":{"v":"Installation","n":1}}},{"i":919,"$":{"0":{"v":"If you have installed @docusaurus/preset-classic, you don't need to install it as a dependency.","n":0.267}}},{"i":920,"$":{"0":{"v":"Configuration","n":1}}},{"i":921,"$":{"0":{"v":"@docusaurus/plugin-sitemap","n":1}}},{"i":922,"$":{"0":{"v":"This plugin creates sitemap for your site so that search engine crawlers can crawl your site more accurately.","n":0.236}}},{"i":923,"$":{"0":{"v":"Installation","n":1}}},{"i":924,"$":{"0":{"v":"If you have installed @docusaurus/preset-classic, you don't need to install it as a dependency. You can also configure it through the classic preset options instead of doing it like below.","n":0.183}}},{"i":925,"$":{"0":{"v":"@docusaurus/plugin-ideal-image","n":1}}},{"i":926,"$":{"0":{"v":"Docusaurus Plugin to generate an almost ideal image (responsive, lazy-loading, and low quality placeholder) in the production builds.","n":0.236}}},{"i":927,"$":{"0":{"v":"Modify your docusaurus.config.js","n":0.577}}},{"i":928,"$":{"0":{"v":"This plugin supports the PNG, GIF and JPG formats only.","n":0.316}}},{"i":929,"$":{"0":{"v":"@docusaurus/plugin-client-redirects","n":1}}},{"i":930,"$":{"0":{"v":"Docusaurus Plugin to generate client-side redirects.","n":0.408}}},{"i":931,"$":{"0":{"v":"This plugin will write additional HTML pages to your static site, that redirects the user to your existing Docusaurus pages with JavaScript.","n":0.213}}},{"i":932,"$":{"0":{"v":"This plugin only create redirects for the production build.","n":0.333}}},{"i":933,"$":{"0":{"v":"It is better to use server-side redirects whenever possible.","n":0.333}}},{"i":934,"$":{"0":{"v":"Before using this plugin, you should look if your hosting provider doesn't offer this feature.","n":0.258}}},{"i":935,"$":{"0":{"v":"Installation","n":1}}},{"i":936,"$":{"0":{"v":"Configuration","n":1}}},{"i":937,"$":{"0":{"v":"Main usecase: you have /myDocusaurusPage, and you want to redirect to this page from /myDocusaurusPage.html:","n":0.258}}},{"i":938,"$":{"0":{"v":"Second usecase: you have /myDocusaurusPage.html, and you want to redirect to this page from /myDocusaurusPage.","n":0.258}}},{"i":939,"$":{"0":{"v":"For custom redirect logic, provide your own createRedirects function.","n":0.333}}},{"i":940,"$":{"0":{"v":"Let's imagine you change the url of an existing page, you might want to make sure the old url still works:","n":0.218}}},{"i":941,"$":{"0":{"v":"It's possible to use a function to create the redirects for each existing path:","n":0.267}}},{"i":942,"$":{"0":{"v":"Finally, it's possible to use all options at the same time:","n":0.302}}},{"i":943,"$":{"0":{"v":"@docusaurus/plugin-pwa","n":1}}},{"i":944,"$":{"0":{"v":"Docusaurus Plugin to add PWA support using Workbox. This plugin generates a Service Worker in production build only, and allows you to create fully PWA-compliant documentation site with offline and installation support.","n":0.177}}},{"i":945,"$":{"0":{"v":"Create a PWA manifest at ./static/manifest.json.","n":0.408}}},{"i":946,"$":{"0":{"v":"Modify docusaurus.config.js with a minimal PWA config, like:","n":0.354}}},{"i":947,"$":{"0":{"v":"Having a service worker installed is not enough to make your application a PWA. You'll need to at least include a Web App Manifest and have the correct tags in <head> (Options > pwaHead).","n":0.171}}},{"i":948,"$":{"0":{"v":"After deployment, you can use Lighthouse to run an audit on your site.","n":0.277}}},{"i":949,"$":{"0":{"v":"For a more exhaustive list of what it takes for your site to be a PWA, refer to the PWA Checklist","n":0.218}}},{"i":950,"$":{"0":{"v":"If your browser supports it, you should be able to install a Docusaurus site as an app.","n":0.243}}},{"i":951,"$":{}},{"i":952,"$":{"0":{"v":"We enable users to browse a Docusaurus site offline, by using service-worker precaching.","n":0.277}}},{"i":953,"$":{"0":{"v":"What is Precaching?","n":0.577}}},{"i":954,"$":{"0":{"v":"One feature of service workers is the ability to save a set of files to the cache when the service worker is installing. This is often referred to as \"precaching\", since you are caching content ahead of the service worker being used.","n":0.154}}},{"i":955,"$":{"0":{"v":"The main reason for doing this is that it gives developers control over the cache, meaning they can determine when and how long a file is cached as well as serve it to the browser without going to the network, meaning it can be used to create web apps that work offline.","n":0.139}}},{"i":956,"$":{"0":{"v":"Workbox takes a lot of the heavy lifting out of precaching by simplifying the API and ensuring assets are downloaded efficiently.","n":0.218}}},{"i":957,"$":{"0":{"v":"By default, offline mode is enabled when the site is installed as an app. See the offlineModeActivationStrategies option for details.","n":0.224}}},{"i":958,"$":{"0":{"v":"After the site has been precached, the service worker will serve cached responses for later visits. When a new build is deployed along with a new service worker, the new one will begin installing and eventually move to a waiting state. During this waiting state, a reload popup will show and ask the user to reload the page for new content. Until the user either clears the application cache or clicks the reload button on the popup, the service worker will continue serving the old content.","n":0.108}}},{"i":959,"$":{"0":{"v":"Offline mode / precaching requires downloading all the static assets of the site ahead of time, and can consume unnecessary bandwidth. It may not be a good idea to activate it for all kind of sites.","n":0.167}}},{"i":960,"$":{"0":{"v":"Turn debug mode on:","n":0.5}}},{"i":961,"$":{"0":{"v":"Strategies used to turn the offline mode on:","n":0.354}}},{"i":962,"$":{"0":{"v":"Use this carefully: some users may not like to be forced to use the offline mode.","n":0.25}}},{"i":963,"$":{"0":{"v":"Workbox options to pass to workbox.injectManifest(). This gives you control over which assets will be precached, and be available offline.","n":0.224}}},{"i":964,"$":{"0":{"v":"Module path to reload popup component. This popup is rendered when a new service worker is waiting to be installed, and we suggest a reload to the user.","n":0.189}}},{"i":965,"$":{"0":{"v":"Passing false will disable the popup, but this is not recommended: users won't have a way to get up-to-date content.","n":0.224}}},{"i":966,"$":{"0":{"v":"A custom component can be used, as long as it accepts onReload as a prop. The onReload callback should be called when the reload button is clicked. This will tell the service worker to install the waiting service worker and reload the page.","n":0.152}}},{"i":967,"$":{"0":{"v":"The default theme includes an implementation for the reload popup and uses Infima Alerts.","n":0.267}}},{"i":968,"$":{}},{"i":969,"$":{"0":{"v":"Array of objects containing tagName and key-value pairs for attributes to inject into the <head> tag. Technically you can inject any head tag through this, but it's ideally used for tags to make your site PWA compliant. Here's a list of tag to make your app fully compliant:","n":0.144}}},{"i":970,"$":{"0":{"v":"Useful for additional Workbox rules. You can do whatever a service worker can do here, and use the full power of workbox libraries. The code is transpiled, so you can use modern ES6+ syntax here.","n":0.169}}},{"i":971,"$":{"0":{"v":"For example, to cache files from external routes:","n":0.354}}},{"i":972,"$":{"0":{"v":"The module should have a default function export, and receives some params.","n":0.289}}},{"i":973,"$":{"0":{"v":"Adds an entry before the Docusaurus app so that registration can happen before the app runs. The default registerSW.js file is enough for simple registration.","n":0.2}}},{"i":974,"$":{"0":{"v":"Passing false will disable registration entirely.","n":0.408}}},{"i":975,"$":{"0":{"v":"Themes","n":1}}},{"i":976,"$":{"0":{"v":"Like plugins, themes are designed to add functionality to your Docusaurus site. As a good rule of thumb, themes are mostly focused on client-side, where plugins are more focused on server-side functionalities. Themes are also designed to be replace-able with other themes.","n":0.154}}},{"i":977,"$":{"0":{"v":"Using themes","n":0.707}}},{"i":978,"$":{"0":{"v":"To use themes, specify the themes in your docusaurus.config.js. You may use multiple themes:","n":0.267}}},{"i":979,"$":{"0":{"v":"Theme components","n":0.707}}},{"i":980,"$":{"0":{"v":"Most of the time, theme is used to provide a set of React components, e.g. Navbar, Layout, Footer.","n":0.236}}},{"i":981,"$":{"0":{"v":"Users can use these components in their code by importing them using the @theme webpack alias:","n":0.25}}},{"i":982,"$":{"0":{"v":"The alias @theme can refer to a few directories, in the following priority:","n":0.277}}},{"i":983,"$":{"0":{"v":"Given the following structure","n":0.5}}},{"i":984,"$":{"0":{"v":"website/src/theme/Navbar.js takes precedence whenever @theme/Navbar is imported. This behavior is called component swizzling. In iOS, method swizzling is the process of changing the implementation of an existing selector (method). In the context of a website, component swizzling means providing an alternative component that takes precedence over the component provided by the theme.","n":0.139}}},{"i":985,"$":{"0":{"v":"Themes are for providing UI components to present the content. Most content plugins need to be paired with a theme in order to be actually useful. The UI is a separate layer from the data schema, so it makes it easy to swap out the themes for other designs (i.e., Bootstrap).","n":0.14}}},{"i":986,"$":{"0":{"v":"For example, a Docusaurus blog consists of a blog plugin and a blog theme.","n":0.267}}},{"i":987,"$":{"0":{"v":"And if you want to use Bootstrap styling, you can swap out the theme with theme-blog-bootstrap (fictitious non-existing theme):","n":0.229}}},{"i":988,"$":{"0":{"v":"The content plugin remains the same and the only thing you need to change is the theme.","n":0.243}}},{"i":989,"$":{"0":{"v":"Swizzling theme components","n":0.577}}},{"i":990,"$":{"0":{"v":"We would like to discourage swizzling of components until we've minimally reached a Beta stage. The components APIs have been changing rapidly and are likely to keep changing until we reach Beta. Stick with the default appearance for now if possible to save yourself some potential pain in future.","n":0.143}}},{"i":991,"$":{"0":{"v":"Docusaurus Themes' components are designed to be replaceable. To make it easier for you, we created a command for you to replace theme components called swizzle.","n":0.196}}},{"i":992,"$":{"0":{"v":"To swizzle a component for a theme, run the following command in your doc site:","n":0.258}}},{"i":993,"$":{"0":{"v":"As an example, to swizzle the <Footer /> component in @docusaurus/theme-classic for your site, run:","n":0.258}}},{"i":994,"$":{"0":{"v":"This will copy the current <Footer /> component used by the theme to a src/theme/Footer directory under the root of your site, which is where Docusaurus will look for swizzled components. Docusaurus will then use swizzled component in place of the original one from the theme.","n":0.147}}},{"i":995,"$":{"0":{"v":"Although we highly discourage swizzling of all components, if you wish to do that, run:","n":0.258}}},{"i":996,"$":{"0":{"v":"Note: You need to restart your webpack dev server in order for Docusaurus to know about the new component.","n":0.229}}},{"i":997,"$":{"0":{"v":"Official themes by Docusaurus","n":0.5}}},{"i":998,"$":{"0":{"v":"@docusaurus/theme-classic","n":1}}},{"i":999,"$":{"0":{"v":"The classic theme for Docusaurus. You can refer to classic theme configuration for more details on the configuration.","n":0.236}}},{"i":1000,"$":{"0":{"v":"If you have installed @docusaurus/preset-classic, you don't need to install it as a dependency.","n":0.267}}},{"i":1001,"$":{"0":{"v":"@docusaurus/theme-search-algolia","n":1}}},{"i":1002,"$":{"0":{"v":"This theme provides a @theme/SearchBar component that integrates with Algolia DocSearch easily. Combined with @docusaurus/theme-classic, it provides a very easy search integration. You can read more on search documentation.","n":0.186}}},{"i":1003,"$":{"0":{"v":"This theme also adds search page available at /search path with OpenSearch support.","n":0.277}}},{"i":1004,"$":{"0":{"v":"If you have installed @docusaurus/preset-classic, you don't need to install it as a dependency.","n":0.267}}},{"i":1005,"$":{"0":{"v":"@docusaurus/theme-live-codeblock","n":1}}},{"i":1006,"$":{"0":{"v":"This theme provides a @theme/CodeBlock component that is powered by react-live. You can read more on interactive code editor documentation.","n":0.224}}},{"i":1007,"$":{"0":{"v":"Themes design","n":0.707}}},{"i":1008,"$":{"0":{"v":"While themes share the exact same lifecycle methods with plugins, their implementations can look very different from those of plugins based on themes' designed objectives.","n":0.2}}},{"i":1009,"$":{"0":{"v":"Themes are designed to complete the build of your Docusaurus site and supply the components used by your site, plugins, and the themes themselves. So a typical theme implementation would look like a src/index.js file that hooks it up to the lifecycle methods. Most likely they would not use loadContent, which plugins would use. And it is typically accompanied by a src/theme directory full of components.","n":0.123}}},{"i":1010,"$":{"0":{"v":"To summarize:","n":0.707}}},{"i":1011,"$":{"0":{"v":"Writing customized Docusaurus themes","n":0.5}}},{"i":1012,"$":{"0":{"v":"A Docusaurus theme normally includes an index.js file where you hook up to the lifecycle methods, alongside with a theme/ directory of components. A typical Docusaurus theme folder looks like this:","n":0.18}}},{"i":1013,"$":{"0":{"v":"There are two lifecycle methods that are essential to theme implementation:","n":0.302}}},{"i":1014,"$":{"0":{"v":"These lifecycle method are not essential but recommended:","n":0.354}}},{"i":1015,"$":{"0":{"v":"Versioning","n":1}}},{"i":1016,"$":{"0":{"v":"You can use the version script to create a new documentation version based on the latest content in the docs directory. That specific set of documentation will then be preserved and accessible even as the documentation in the docs directory changes moving forward.","n":0.152}}},{"i":1017,"$":{"0":{"v":"Think about it before starting to version your documentation - it can become difficult for contributors to help improve it!","n":0.224}}},{"i":1018,"$":{"0":{"v":"Most of the time, you don't need versioning as it will just increase your build time, and introduce complexity to your codebase. Versioning is best suited for websites with high-traffic and rapid changes to documentation between versions. If your documentation rarely changes, don't add versioning to your documentation.","n":0.144}}},{"i":1019,"$":{"0":{"v":"To better understand how versioning works and see if it suits your needs, you can read on below.","n":0.236}}},{"i":1020,"$":{"0":{"v":"Directory structure","n":0.707}}},{"i":1021,"$":{"0":{"v":"The table below explains how a versioned file maps to its version and the generated URL.","n":0.25}}},{"i":1022,"$":{"0":{"v":"Tagging a new version","n":0.5}}},{"i":1023,"$":{"0":{"v":"When tagging a new version, the document versioning mechanism will:","n":0.316}}},{"i":1024,"$":{"0":{"v":"Files","n":1}}},{"i":1025,"$":{"0":{"v":"Creating new files","n":0.577}}},{"i":1026,"$":{"0":{"v":"Master docs","n":0.707}}},{"i":1027,"$":{"0":{"v":"Older docs","n":0.707}}},{"i":1028,"$":{"0":{"v":"Linking files","n":0.707}}},{"i":1029,"$":{"0":{"v":"Versions","n":1}}},{"i":1030,"$":{"0":{"v":"Each directory in versioned_docs/ will represent a documentation version.","n":0.333}}},{"i":1031,"$":{"0":{"v":"Updating an existing version","n":0.5}}},{"i":1032,"$":{"0":{"v":"You can update multiple docs versions at the same time because each directory in versioned_docs/ represents specific routes when published.","n":0.224}}},{"i":1033,"$":{"0":{"v":"Example: When you change any file in versioned_docs/version-2.6/, it will only affect the docs for version 2.6.","n":0.243}}},{"i":1034,"$":{"0":{"v":"Deleting an existing version","n":0.5}}},{"i":1035,"$":{"0":{"v":"You can delete/remove versions as well.","n":0.408}}},{"i":1036,"$":{"0":{"v":"Example:","n":1}}},{"i":1037,"$":{"0":{"v":"Recommended practices","n":0.707}}},{"i":1038,"$":{"0":{"v":"Version your documentation only when needed","n":0.408}}},{"i":1039,"$":{"0":{"v":"For example, you are building a documentation for your npm package foo and you are currently in version 1.0.0. You then release a patch version for a minor bug fix and it's now 1.0.1.","n":0.171}}},{"i":1040,"$":{"0":{"v":"Should you cut a new documentation version 1.0.1? You probably shouldn't. 1.0.1 and 1.0.0 docs shouldn't differ according to semver because there are no new features!. Cutting a new version for it will only just create unnecessary duplicated files.","n":0.16}}},{"i":1041,"$":{"0":{"v":"Keep the number of versions small","n":0.408}}},{"i":1042,"$":{"0":{"v":"As a good rule of thumb, try to keep the number of your versions below 10. It is very likely that you will have a lot of obsolete versioned documentation that nobody even reads anymore. For example, Jest is currently in version 24.9, and only maintains several latest documentation version with the lowest being 22.X. Keep it small 😊","n":0.13}}},{"i":1043,"$":{"0":{"v":"Use absolute import within the docs","n":0.408}}},{"i":1044,"$":{"0":{"v":"Don't use relative paths import within the docs. Because when we cut a version the paths no longer work (the nesting level is different, among other reasons). You can utilize the @site alias provided by docusaurus, that points to the website directory. Example:","n":0.152}}}]} | |||
website/static/search_result.json
Outdated
| @@ -0,0 +1 @@ | |||
| [{"pageID":"docs/blog","id":1,"type":"h1","anchor":"initial-setup","body":"Blog","heading":"Blog"},{"pageID":"docs/blog","id":2,"type":"h2","anchor":"initial-setup","body":"Initial setup","heading":"Blog"},{"pageID":"docs/blog","id":3,"type":"p","anchor":"initial-setup","body":"To setup your site's blog, start by creating a blog directory.","heading":"Blog"},{"pageID":"docs/blog","id":4,"type":"p","anchor":"initial-setup","body":"Then, add a item link to your blog within docusaurus.config.js:","heading":"Blog"},{"pageID":"docs/blog","id":5,"type":"h2","anchor":"adding-posts","body":"Adding posts","heading":"Blog"},{"pageID":"docs/blog","id":6,"type":"p","anchor":"adding-posts","body":"To publish in the blog, create a file within the blog directory with a formatted name of YYYY-MM-DD-my-blog-post-title.md. The post date is extracted from the file name.","heading":"Blog"},{"pageID":"docs/blog","id":7,"type":"p","anchor":"adding-posts","body":"For example, at my-website/blog/2019-09-05-hello-docusaurus-v2.md:","heading":"Blog"},{"pageID":"docs/blog","id":8,"type":"h2","anchor":"header-options","body":"Header options","heading":"Blog"},{"pageID":"docs/blog","id":9,"type":"p","anchor":"header-options","body":"The only required field is title; however, we provide options to add author information to your blog post as well along with other options.","heading":"Blog"},{"pageID":"docs/blog","id":10,"type":"h2","anchor":"summary-truncation","body":"Summary truncation","heading":"Blog"},{"pageID":"docs/blog","id":11,"type":"p","anchor":"summary-truncation","body":"Use the <!--truncate--> marker in your blog post to represent what will be shown as the summary when viewing all published blog posts. Anything above <!--truncate--> will be part of the summary. For example:","heading":"Blog"},{"pageID":"docs/blog","id":12,"type":"h2","anchor":"feed","body":"Feed","heading":"Blog"},{"pageID":"docs/blog","id":13,"type":"p","anchor":"feed","body":"You can generate RSS/ Atom feed by passing feedOptions.","heading":"Blog"},{"pageID":"docs/blog","id":14,"type":"p","anchor":"feed","body":"Example usage:","heading":"Blog"},{"pageID":"docs/blog","id":15,"type":"p","anchor":"feed","body":"Accessing the feed:","heading":"Blog"},{"pageID":"docs/blog","id":16,"type":"p","anchor":"feed","body":"The feed for RSS can be found at:","heading":"Blog"},{"pageID":"docs/blog","id":17,"type":"p","anchor":"feed","body":"and for Atom:","heading":"Blog"},{"pageID":"docs/blog","id":18,"type":"h2","anchor":"advanced-topics","body":"Advanced topics","heading":"Blog"},{"pageID":"docs/blog","id":19,"type":"h3","anchor":"blog-only-mode","body":"Blog-only mode","heading":"Blog"},{"pageID":"docs/blog","id":20,"type":"p","anchor":"blog-only-mode","body":"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.","heading":"Blog"},{"pageID":"docs/blog","id":21,"type":"p","anchor":"blog-only-mode","body":"Don't forget to delete the existing homepage at ./src/pages/index.js or else there will be two files mapping to the same route!","heading":"Blog"},{"pageID":"docs/blog","id":22,"type":"h3","anchor":"multiple-blogs","body":"Multiple blogs","heading":"Blog"},{"pageID":"docs/blog","id":23,"type":"p","anchor":"multiple-blogs","body":"By default, the classic theme assumes only one blog per website and hence includes only one instance of the blog plugin. If you would like to have multiple blogs on a single website, it's possible too! You can add another blog by specifying another blog plugin in the plugins option for docusaurus.config.js.","heading":"Blog"},{"pageID":"docs/blog","id":24,"type":"p","anchor":"multiple-blogs","body":"Set the routeBasePath to the URL route that you want your second blog to be accessed on. Note that the routeBasePath here has to be different from the first blog or else there could be a collision of paths! Also, set path to the path to the directory containing your second blog's entries.","heading":"Blog"},{"pageID":"docs/cli","id":25,"type":"h1","anchor":"docusaurus-cli-commands","body":"CLI","heading":"CLI"},{"pageID":"docs/cli","id":26,"type":"p","anchor":"docusaurus-cli-commands","body":"Docusaurus provides a set of scripts to help you generate, serve, and deploy your website.","heading":"CLI"},{"pageID":"docs/cli","id":27,"type":"p","anchor":"docusaurus-cli-commands","body":"Once your website is bootstrapped, the website source will contain the Docusaurus scripts that you can invoke with your package manager:","heading":"CLI"},{"pageID":"docs/cli","id":28,"type":"h2","anchor":"docusaurus-cli-commands","body":"Docusaurus CLI commands","heading":"CLI"},{"pageID":"docs/cli","id":29,"type":"p","anchor":"docusaurus-cli-commands","body":"Below is a list of Docusaurus CLI commands and their usages:","heading":"CLI"},{"pageID":"docs/cli","id":30,"type":"h3","anchor":"docusaurus-start","body":"docusaurus start","heading":"CLI"},{"pageID":"docs/cli","id":31,"type":"p","anchor":"docusaurus-start","body":"Builds and serves a preview of your site locally with Webpack Dev Server.","heading":"CLI"},{"pageID":"docs/cli","id":32,"type":"p","anchor":"options","body":"Please note that some functionality (for example, anchor links) will not work in development. The functionality will work as expected in production.","heading":"CLI"},{"pageID":"docs/cli","id":33,"type":"h3","anchor":"docusaurus-build","body":"docusaurus build","heading":"CLI"},{"pageID":"docs/cli","id":34,"type":"p","anchor":"docusaurus-build","body":"Compiles your site for production.","heading":"CLI"},{"pageID":"docs/cli","id":35,"type":"h3","anchor":"docusaurus-swizzle","body":"docusaurus swizzle","heading":"CLI"},{"pageID":"docs/cli","id":36,"type":"p","anchor":"docusaurus-swizzle","body":"We highly discourage swizzling of components until we've reached a Beta stage. The components APIs have been changing rapidly and are likely to keep changing until we reach Beta. Stick with the default appearance for now if possible to save yourself some potential pain in future.","heading":"CLI"},{"pageID":"docs/cli","id":37,"type":"p","anchor":"docusaurus-swizzle","body":"Change any Docusaurus theme components to your liking with docusaurus swizzle.","heading":"CLI"},{"pageID":"docs/cli","id":38,"type":"p","anchor":"docusaurus-swizzle","body":"Running the command will copy the relevant theme files to your site folder. You may then make any changes to it and Docusaurus will use it instead of the one provided from the theme.","heading":"CLI"},{"pageID":"docs/cli","id":39,"type":"p","anchor":"options-2","body":"To unswizzle a component, simply delete the files of the swizzled component.","heading":"CLI"},{"pageID":"docs/cli","id":40,"type":"h3","anchor":"docusaurus-deploy","body":"docusaurus deploy","heading":"CLI"},{"pageID":"docs/cli","id":41,"type":"p","anchor":"docusaurus-deploy","body":"Deploys your site with GitHub Pages. Check out the docs on deployment for more details.","heading":"CLI"},{"pageID":"docs/cli","id":42,"type":"h3","anchor":"docusaurus-serve","body":"docusaurus serve","heading":"CLI"},{"pageID":"docs/cli","id":43,"type":"p","anchor":"docusaurus-serve","body":"Serve your built website localy.","heading":"CLI"},{"pageID":"docs/configuration","id":44,"type":"h1","anchor":"what-goes-into-a-docusaurusconfigjs","body":"Configuration","heading":"Configuration"},{"pageID":"docs/configuration","id":45,"type":"p","anchor":"what-goes-into-a-docusaurusconfigjs","body":"Docusaurus has a unique take on configurations. We encourage you to congregate information of your site into one place. We guard the fields of this file, and facilitate making this data object accessible across your site.","heading":"Configuration"},{"pageID":"docs/configuration","id":46,"type":"p","anchor":"what-goes-into-a-docusaurusconfigjs","body":"Keeping a well-maintained docusaurus.config.js helps you, your collaborators, and your open source contributors be able to focus on documentation while still being able to customize the site.","heading":"Configuration"},{"pageID":"docs/configuration","id":47,"type":"h2","anchor":"what-goes-into-a-docusaurusconfigjs","body":"What goes into a docusaurus.config.js?","heading":"Configuration"},{"pageID":"docs/configuration","id":48,"type":"p","anchor":"what-goes-into-a-docusaurusconfigjs","body":"You should not have to write your docusaurus.config.js from scratch even if you are developing your site. All templates come with a docusaurus.config.js that includes defaults for the common options.","heading":"Configuration"},{"pageID":"docs/configuration","id":49,"type":"p","anchor":"what-goes-into-a-docusaurusconfigjs","body":"However, it can be helpful if you have a high-level understanding of how the configurations are designed and implemented.","heading":"Configuration"},{"pageID":"docs/configuration","id":50,"type":"p","anchor":"what-goes-into-a-docusaurusconfigjs","body":"The high-level overview of Docusaurus configuration can be categorized into:","heading":"Configuration"},{"pageID":"docs/configuration","id":51,"type":"p","anchor":"what-goes-into-a-docusaurusconfigjs","body":"For exact reference to each of the configurable fields, you may refer to docusaurus.config.js API reference.","heading":"Configuration"},{"pageID":"docs/configuration","id":52,"type":"h3","anchor":"site-metadata","body":"Site metadata","heading":"Configuration"},{"pageID":"docs/configuration","id":53,"type":"p","anchor":"site-metadata","body":"Site metadata contains the essential global metadata such as title, url, baseUrl and favicon.","heading":"Configuration"},{"pageID":"docs/configuration","id":54,"type":"p","anchor":"site-metadata","body":"They are used in a number of places such as your site's title and headings, browser tab icon, social sharing (Facebook, Twitter) information or even to generate the correct path to serve your static files.","heading":"Configuration"},{"pageID":"docs/configuration","id":55,"type":"h3","anchor":"deployment-configurations","body":"Deployment configurations","heading":"Configuration"},{"pageID":"docs/configuration","id":56,"type":"p","anchor":"deployment-configurations","body":"Deployment configurations such as projectName and organizationName are used when you deploy your site with the deploy command.","heading":"Configuration"},{"pageID":"docs/configuration","id":57,"type":"p","anchor":"deployment-configurations","body":"It is recommended to check the deployment docs for more information.","heading":"Configuration"},{"pageID":"docs/configuration","id":58,"type":"h3","anchor":"theme-plugin-and-preset-configurations","body":"Theme, plugin, and preset configurations","heading":"Configuration"},{"pageID":"docs/configuration","id":59,"type":"p","anchor":"theme-plugin-and-preset-configurations","body":"List the theme, plugins, and presets for your site in the themes, plugins, and presets fields, respectively. These are typically npm packages:","heading":"Configuration"},{"pageID":"docs/configuration","id":60,"type":"p","anchor":"theme-plugin-and-preset-configurations","body":"They can also be loaded from local directories:","heading":"Configuration"},{"pageID":"docs/configuration","id":61,"type":"p","anchor":"theme-plugin-and-preset-configurations","body":"To specify options for a plugin or theme, replace the name of the plugin or theme in the config file with an array containing the name and an options object:","heading":"Configuration"},{"pageID":"docs/configuration","id":62,"type":"p","anchor":"theme-plugin-and-preset-configurations","body":"To specify options for a plugin or theme that is bundled in a preset, pass the options through the presets field. In this example, docs refers to @docusaurus/plugin-content-docs and theme refers to @docusaurus/theme-classic.","heading":"Configuration"},{"pageID":"docs/configuration","id":63,"type":"p","anchor":"theme-plugin-and-preset-configurations","body":"For further help configuring themes, plugins, and presets, see Using Themes, Using Plugins, and Using Presets.","heading":"Configuration"},{"pageID":"docs/configuration","id":64,"type":"h3","anchor":"custom-configurations","body":"Custom configurations","heading":"Configuration"},{"pageID":"docs/configuration","id":65,"type":"p","anchor":"custom-configurations","body":"Docusaurus guards docusaurus.config.js from unknown fields. To add custom fields, define them in customFields.","heading":"Configuration"},{"pageID":"docs/configuration","id":66,"type":"p","anchor":"custom-configurations","body":"Example:","heading":"Configuration"},{"pageID":"docs/configuration","id":67,"type":"h2","anchor":"accessing-configuration-from-components","body":"Accessing configuration from components","heading":"Configuration"},{"pageID":"docs/configuration","id":68,"type":"p","anchor":"accessing-configuration-from-components","body":"Your configuration object will be made available to all the components of your site. And you may access them via React context as siteConfig.","heading":"Configuration"},{"pageID":"docs/configuration","id":69,"type":"p","anchor":"accessing-configuration-from-components","body":"Basic example:","heading":"Configuration"},{"pageID":"docs/configuration","id":70,"type":"p","anchor":"accessing-configuration-from-components","body":"If you just want to use those fields on the client side, you could create your own JS files and import them as ES6 modules, there is no need to put them in docusaurus.config.js.","heading":"Configuration"},{"pageID":"docs/configuration","id":71,"type":"h2","anchor":"customizing-babel-configuration","body":"Customizing Babel Configuration","heading":"Configuration"},{"pageID":"docs/configuration","id":72,"type":"p","anchor":"customizing-babel-configuration","body":"For new Docusaurus projects, we automatically generated a babel.config.js in project root.","heading":"Configuration"},{"pageID":"docs/configuration","id":73,"type":"p","anchor":"customizing-babel-configuration","body":"Most of the times, this configuration will work just fine. If you want to customize it, you can directly edit this file to customize babel configuration. For your changes to take effect, you need to restart Docusaurus devserver.","heading":"Configuration"},{"pageID":"docs/contributing","id":74,"type":"h1","anchor":"code-of-conduct","body":"Contributing","heading":"Contributing"},{"pageID":"docs/contributing","id":75,"type":"p","anchor":"code-of-conduct","body":"Docusaurus 2 is currently under alpha development. We have early adopters who already started using it. We are now welcoming contributors to collaborate on the next Docusaurus.","heading":"Contributing"},{"pageID":"docs/contributing","id":76,"type":"p","anchor":"code-of-conduct","body":"The Open Source Guides website has a collection of resources for individuals, communities, and companies who want to learn how to run and contribute to an open source project. Contributors and people new to open source alike will find the following guides especially useful:","heading":"Contributing"},{"pageID":"docs/contributing","id":77,"type":"h2","anchor":"code-of-conduct","body":"Code of Conduct","heading":"Contributing"},{"pageID":"docs/contributing","id":78,"type":"p","anchor":"code-of-conduct","body":"Facebook has adopted a Code of Conduct that we expect project participants to adhere to. Please read the full text so that you can understand what actions will and will not be tolerated.","heading":"Contributing"},{"pageID":"docs/contributing","id":79,"type":"h2","anchor":"get-involved","body":"Get involved","heading":"Contributing"},{"pageID":"docs/contributing","id":80,"type":"p","anchor":"get-involved","body":"There are many ways to contribute to Docusaurus, and many of them do not involve writing any code. Here's a few ideas to get started:","heading":"Contributing"},{"pageID":"docs/contributing","id":81,"type":"p","anchor":"get-involved","body":"Contributions are very welcome. If you think you need help planning your contribution, please ping us on Twitter at @docusaurus and let us know you are looking for a bit of help.","heading":"Contributing"},{"pageID":"docs/contributing","id":82,"type":"h3","anchor":"join-our-discord-channel","body":"Join our Discord channel","heading":"Contributing"},{"pageID":"docs/contributing","id":83,"type":"p","anchor":"join-our-discord-channel","body":"To participate in Docusaurus 2 dev, join the #docusaurus-2-dev channel.","heading":"Contributing"},{"pageID":"docs/contributing","id":84,"type":"h2","anchor":"our-development-process","body":"Our development process","heading":"Contributing"},{"pageID":"docs/contributing","id":85,"type":"p","anchor":"our-development-process","body":"Docusaurus uses GitHub as its source of truth. The core team will be working directly there. All changes will be public from the beginning.","heading":"Contributing"},{"pageID":"docs/contributing","id":86,"type":"p","anchor":"our-development-process","body":"When a change made on GitHub is approved, it will be checked by our continuous integration system, CircleCI.","heading":"Contributing"},{"pageID":"docs/contributing","id":87,"type":"h3","anchor":"reporting-new-issues","body":"Reporting new issues","heading":"Contributing"},{"pageID":"docs/contributing","id":88,"type":"p","anchor":"reporting-new-issues","body":"When opening a new issue, always make sure to fill out the issue template. This step is very important! Not doing so may result in your issue not managed in a timely fashion. Don't take this personally if this happens, and feel free to open a new issue once you've gathered all the information required by the template.","heading":"Contributing"},{"pageID":"docs/contributing","id":89,"type":"h3","anchor":"reporting-bugs","body":"Reporting bugs","heading":"Contributing"},{"pageID":"docs/contributing","id":90,"type":"p","anchor":"reporting-bugs","body":"We use GitHub Issues for our public bugs. If you would like to report a problem, take a look around and see if someone already opened an issue about it. If you a are certain this is a new, unreported bug, you can submit a bug report.","heading":"Contributing"},{"pageID":"docs/contributing","id":91,"type":"p","anchor":"reporting-bugs","body":"If you have questions about using Docusaurus, contact the Docusaurus Twitter account at @docusaurus, and we will do our best to answer your questions.","heading":"Contributing"},{"pageID":"docs/contributing","id":92,"type":"p","anchor":"reporting-bugs","body":"You can also file issues as feature requests or enhancements. If you see anything you'd like to be implemented, create an issue with feature template","heading":"Contributing"},{"pageID":"docs/contributing","id":93,"type":"h3","anchor":"reporting-security-bugs","body":"Reporting security bugs","heading":"Contributing"},{"pageID":"docs/contributing","id":94,"type":"p","anchor":"reporting-security-bugs","body":"Facebook has a bounty program for the safe disclosure of security bugs. With that in mind, please do not file public issues; go through the process outlined on that page.","heading":"Contributing"},{"pageID":"docs/contributing","id":95,"type":"h2","anchor":"working-on-docusaurus-code","body":"Working on Docusaurus code","heading":"Contributing"},{"pageID":"docs/contributing","id":96,"type":"h3","anchor":"installation","body":"Installation","heading":"Contributing"},{"pageID":"docs/contributing","id":97,"type":"h3","anchor":"semantic-commit-messages","body":"Semantic commit messages","heading":"Contributing"},{"pageID":"docs/contributing","id":98,"type":"p","anchor":"semantic-commit-messages","body":"See how a minor change to your commit message style can make you a better programmer.","heading":"Contributing"},{"pageID":"docs/contributing","id":99,"type":"p","anchor":"semantic-commit-messages","body":"Format: <type>(<scope>): <subject>","heading":"Contributing"},{"pageID":"docs/contributing","id":100,"type":"p","anchor":"semantic-commit-messages","body":"<scope> is optional","heading":"Contributing"},{"pageID":"docs/contributing","id":101,"type":"p","anchor":"semantic-commit-messages","body":"Example","heading":"Contributing"},{"pageID":"docs/contributing","id":102,"type":"p","anchor":"semantic-commit-messages","body":"The various types of commits:","heading":"Contributing"},{"pageID":"docs/contributing","id":103,"type":"p","anchor":"semantic-commit-messages","body":"Use lower case not title case!","heading":"Contributing"},{"pageID":"docs/contributing","id":104,"type":"h3","anchor":"code-conventions","body":"Code conventions","heading":"Contributing"},{"pageID":"docs/contributing","id":105,"type":"p","anchor":"style-guide","body":"Prettier will catch most styling issues that may exist in your code. You can check the status of your code styling by simply running npm run prettier.","heading":"Contributing"},{"pageID":"docs/contributing","id":106,"type":"p","anchor":"style-guide","body":"However, there are still some styles that Prettier cannot pick up.","heading":"Contributing"},{"pageID":"docs/contributing","id":107,"type":"h2","anchor":"pull-requests","body":"Pull requests","heading":"Contributing"},{"pageID":"docs/contributing","id":108,"type":"h3","anchor":"your-first-pull-request","body":"Your first pull request","heading":"Contributing"},{"pageID":"docs/contributing","id":109,"type":"p","anchor":"your-first-pull-request","body":"So you have decided to contribute code back to upstream by opening a pull request. You've invested a good chunk of time, and we appreciate it. We will do our best to work with you and get the PR looked at.","heading":"Contributing"},{"pageID":"docs/contributing","id":110,"type":"p","anchor":"your-first-pull-request","body":"Working on your first Pull Request? You can learn how from this free video series:","heading":"Contributing"},{"pageID":"docs/contributing","id":111,"type":"p","anchor":"your-first-pull-request","body":"How to Contribute to an Open Source Project on GitHub","heading":"Contributing"},{"pageID":"docs/contributing","id":112,"type":"p","anchor":"your-first-pull-request","body":"We have a list of beginner friendly issues to help you get your feet wet in the Docusaurus codebase and familiar with our contribution process. This is a great place to get started.","heading":"Contributing"},{"pageID":"docs/contributing","id":113,"type":"h3","anchor":"proposing-a-change","body":"Proposing a change","heading":"Contributing"},{"pageID":"docs/contributing","id":114,"type":"p","anchor":"proposing-a-change","body":"If you would like to request a new feature or enhancement but are not yet thinking about opening a pull request, you can also file an issue with feature template.","heading":"Contributing"},{"pageID":"docs/contributing","id":115,"type":"p","anchor":"proposing-a-change","body":"If you intend to change the public API (e.g., something in docusaurus.config.js), or make any non-trivial changes to the implementation, we recommend filing an issue with proposal template and including [Proposal] in the title. This lets us reach an agreement on your proposal before you put significant effort into it. These types of issues should be rare.","heading":"Contributing"},{"pageID":"docs/contributing","id":116,"type":"p","anchor":"proposing-a-change","body":"If you're only fixing a bug, it's fine to submit a pull request right away but we still recommend to file an issue detailing what you're fixing. This is helpful in case we don't accept that specific fix but want to keep track of the issue.","heading":"Contributing"},{"pageID":"docs/contributing","id":117,"type":"h3","anchor":"sending-a-pull-request","body":"Sending a pull request","heading":"Contributing"},{"pageID":"docs/contributing","id":118,"type":"p","anchor":"sending-a-pull-request","body":"Small pull requests are much easier to review and more likely to get merged. Make sure the PR does only one thing, otherwise please split it. It is recommended to follow this commit message style.","heading":"Contributing"},{"pageID":"docs/contributing","id":119,"type":"p","anchor":"sending-a-pull-request","body":"Please make sure the following is done when submitting a pull request:","heading":"Contributing"},{"pageID":"docs/contributing","id":120,"type":"p","anchor":"sending-a-pull-request","body":"All pull requests should be opened against the master branch.","heading":"Contributing"},{"pageID":"docs/contributing","id":121,"type":"p","anchor":"test-plan","body":"A good test plan has the exact commands you ran and their output, provides screenshots or videos if the pull request changes UI.","heading":"Contributing"},{"pageID":"docs/contributing","id":122,"type":"p","anchor":"breaking-changes","body":"When adding a new breaking change, follow this template in your pull request:","heading":"Contributing"},{"pageID":"docs/contributing","id":123,"type":"p","anchor":"copyright-header-for-source-code","body":"Copy and paste this to the top of your new file(s):","heading":"Contributing"},{"pageID":"docs/contributing","id":124,"type":"p","anchor":"contributor-license-agreement-cla","body":"In order to accept your pull request, we need you to submit a CLA. You only need to do this once, so if you've done this for another Facebook open source project, you're good to go. If you are submitting a pull request for the first time, the Facebook GitHub Bot will reply with a link to the CLA form. You may also complete your CLA here.","heading":"Contributing"},{"pageID":"docs/contributing","id":125,"type":"h3","anchor":"what-happens-next","body":"What happens next?","heading":"Contributing"},{"pageID":"docs/contributing","id":126,"type":"p","anchor":"what-happens-next","body":"The core Docusaurus team will be monitoring for pull requests. Do help us by keeping pull requests consistent by following the guidelines above.","heading":"Contributing"},{"pageID":"docs/contributing","id":127,"type":"h2","anchor":"license","body":"License","heading":"Contributing"},{"pageID":"docs/contributing","id":128,"type":"p","anchor":"license","body":"By contributing to Docusaurus, you agree that your contributions will be licensed under its MIT license.","heading":"Contributing"},{"pageID":"docs/creating-pages","id":129,"type":"h1","anchor":"adding-a-new-page","body":"Creating Pages","heading":"Creating Pages"},{"pageID":"docs/creating-pages","id":130,"type":"p","anchor":"adding-a-new-page","body":"In this section, we will learn about creating ad-hoc pages in Docusaurus using React. This is most useful for creating one-off standalone pages like a showcase page, playground page or support page.","heading":"Creating Pages"},{"pageID":"docs/creating-pages","id":131,"type":"p","anchor":"adding-a-new-page","body":"The functionality of pages is powered by @docusaurus/plugin-content-pages.","heading":"Creating Pages"},{"pageID":"docs/creating-pages","id":132,"type":"h2","anchor":"adding-a-new-page","body":"Adding a new page","heading":"Creating Pages"},{"pageID":"docs/creating-pages","id":133,"type":"p","anchor":"adding-a-new-page","body":"In the /src/pages/ directory, create a file called hello.js with the following contents:","heading":"Creating Pages"},{"pageID":"docs/creating-pages","id":134,"type":"p","anchor":"adding-a-new-page","body":"Once you save the file, the development server will automatically reload the changes. Now open http://localhost:3000/hello, you will see the new page you just created.","heading":"Creating Pages"},{"pageID":"docs/creating-pages","id":135,"type":"p","anchor":"adding-a-new-page","body":"Each page doesn't come with any styling. You will need to import the Layout component from @theme/Layout and wrap your contents within that component if you want the navbar and/or footer to appear.","heading":"Creating Pages"},{"pageID":"docs/creating-pages","id":136,"type":"p","anchor":"adding-a-new-page","body":"You can also create a page in TypeScript, in which case the file name should use the .tsx extension, eg. hello.tsx.","heading":"Creating Pages"},{"pageID":"docs/creating-pages","id":137,"type":"h2","anchor":"routing","body":"Routing","heading":"Creating Pages"},{"pageID":"docs/creating-pages","id":138,"type":"p","anchor":"routing","body":"If you are familiar with other static site generators like Jekyll and Next, this routing approach will feel familiar to you. Any JavaScript file you create under /src/pages/ directory will be automatically converted to a website page, following the /src/pages/ directory hierarchy. For example:","heading":"Creating Pages"},{"pageID":"docs/creating-pages","id":139,"type":"p","anchor":"routing","body":"In this component-based development era, it is encouraged to co-locate your styling, markup and behavior together into components. Each page is a component, and if you need to customize your page design with your own styles, we recommend co-locating your styles with the page component in its own directory. For example, to create a \"Support\" page, you could do one of the following:","heading":"Creating Pages"},{"pageID":"docs/creating-pages","id":140,"type":"p","anchor":"routing","body":"The latter is preferred as it has the benefits of letting you put files related to the page within that directory. For example, a CSS module file (styles.module.css) with styles meant to only be used on the \"Support\" page. Note: this is merely a recommended directory structure and you will still need to manually import the CSS module file within your component module (support/index.js).","heading":"Creating Pages"},{"pageID":"docs/creating-pages","id":141,"type":"p","anchor":"routing","body":"All JavaScript/TypeScript files within the src/pages/ directory will have corresponding website paths generated for them. Do not put reusable components or test files (ending with .test.js) into that directory otherwise they will be turned into pages, which might not be intended.","heading":"Creating Pages"},{"pageID":"docs/creating-pages","id":142,"type":"h2","anchor":"using-react","body":"Using React","heading":"Creating Pages"},{"pageID":"docs/creating-pages","id":143,"type":"p","anchor":"using-react","body":"React is used as the UI library to create pages. Every page component should export a React component and you can leverage on the expressiveness of React to build rich and interactive content.","heading":"Creating Pages"},{"pageID":"docs/deployment","id":144,"type":"h1","anchor":"testing-build-local","body":"Deployment","heading":"Deployment"},{"pageID":"docs/deployment","id":145,"type":"p","anchor":"testing-build-local","body":"To build the static files of your website for production, run:","heading":"Deployment"},{"pageID":"docs/deployment","id":146,"type":"p","anchor":"testing-build-local","body":"Once it finishes, the static files will be generated within the build/ directory.","heading":"Deployment"},{"pageID":"docs/deployment","id":147,"type":"p","anchor":"testing-build-local","body":"You can deploy your site to static site hosting services such as Vercel, GitHub Pages, Netlify, Render, and Surge. Docusaurus sites are statically rendered so they work without JavaScript too!","heading":"Deployment"},{"pageID":"docs/deployment","id":148,"type":"h2","anchor":"testing-build-local","body":"Testing Build Local","heading":"Deployment"},{"pageID":"docs/deployment","id":149,"type":"p","anchor":"testing-build-local","body":"It is important to test build before deploying to a production. Docusaurus includes a docusaurus serve command to test build localy.","heading":"Deployment"},{"pageID":"docs/deployment","id":150,"type":"h2","anchor":"self-hosting","body":"Self Hosting","heading":"Deployment"},{"pageID":"docs/deployment","id":151,"type":"p","anchor":"self-hosting","body":"It is not the most performant solution","heading":"Deployment"},{"pageID":"docs/deployment","id":152,"type":"p","anchor":"self-hosting","body":"Docusaurus can be self hosted using docusaurus serve. Change port using --port and --host to change host.","heading":"Deployment"},{"pageID":"docs/deployment","id":153,"type":"h2","anchor":"deploying-to-github-pages","body":"Deploying to GitHub Pages","heading":"Deployment"},{"pageID":"docs/deployment","id":154,"type":"p","anchor":"deploying-to-github-pages","body":"Docusaurus provides an easy way to publish to GitHub Pages. Which is hosting that comes for free with every GitHub repository.","heading":"Deployment"},{"pageID":"docs/deployment","id":155,"type":"h3","anchor":"docusaurusconfigjs-settings","body":"docusaurus.config.js settings","heading":"Deployment"},{"pageID":"docs/deployment","id":156,"type":"p","anchor":"docusaurusconfigjs-settings","body":"First, modify your docusaurus.config.js and add the required params:","heading":"Deployment"},{"pageID":"docs/deployment","id":157,"type":"p","anchor":"docusaurusconfigjs-settings","body":"In case you want to use your custom domain for GitHub Pages, create a CNAME file in the static directory. Anything within the static directory will be copied to the root of the build directory for deployment.","heading":"Deployment"},{"pageID":"docs/deployment","id":158,"type":"p","anchor":"docusaurusconfigjs-settings","body":"You may refer to GitHub Pages' documentation User, Organization, and Project Pages for more details.","heading":"Deployment"},{"pageID":"docs/deployment","id":159,"type":"p","anchor":"docusaurusconfigjs-settings","body":"Example:","heading":"Deployment"},{"pageID":"docs/deployment","id":160,"type":"p","anchor":"docusaurusconfigjs-settings","body":"By default, GitHub Pages runs published files through Jekyll. Since Jekyll will discard any files that begin with _, it is recommended that you disable Jekyll by adding an empty file named .nojekyll file to your static directory.","heading":"Deployment"},{"pageID":"docs/deployment","id":161,"type":"h3","anchor":"environment-settings","body":"Environment settings","heading":"Deployment"},{"pageID":"docs/deployment","id":162,"type":"p","anchor":"environment-settings","body":"Specify the Git user as an environment variable.","heading":"Deployment"},{"pageID":"docs/deployment","id":163,"type":"p","anchor":"environment-settings","body":"There are two more optional parameters that are set as environment variables:","heading":"Deployment"},{"pageID":"docs/deployment","id":164,"type":"h3","anchor":"deploy","body":"Deploy","heading":"Deployment"},{"pageID":"docs/deployment","id":165,"type":"p","anchor":"deploy","body":"Finally, to deploy your site to GitHub Pages, run:","heading":"Deployment"},{"pageID":"docs/deployment","id":166,"type":"p","anchor":"deploy","body":"Bash","heading":"Deployment"},{"pageID":"docs/deployment","id":167,"type":"p","anchor":"deploy","body":"Windows","heading":"Deployment"},{"pageID":"docs/deployment","id":168,"type":"h3","anchor":"triggering-deployment-with-github-actions","body":"Triggering deployment with GitHub Actions","heading":"Deployment"},{"pageID":"docs/deployment","id":169,"type":"p","anchor":"triggering-deployment-with-github-actions","body":"GitHub Actions allow you to automate, customize, and execute your software development workflows right in your repository.","heading":"Deployment"},{"pageID":"docs/deployment","id":170,"type":"p","anchor":"triggering-deployment-with-github-actions","body":"This workflow assumes your documentation resided in documentation branch of your repository and your publishing source is configured for gh-pages branch.","heading":"Deployment"},{"pageID":"docs/deployment","id":171,"type":"h3","anchor":"triggering-deployment-with-travis-ci","body":"Triggering deployment with Travis CI","heading":"Deployment"},{"pageID":"docs/deployment","id":172,"type":"p","anchor":"triggering-deployment-with-travis-ci","body":"Continuous integration (CI) services are typically used to perform routine tasks whenever new commits are checked in to source control. These tasks can be any combination of running unit tests and integration tests, automating builds, publishing packages to NPM, and deploying changes to your website. All you need to do to automate the deployment of your website is to invoke the yarn deploy script whenever your website is updated. The following section covers how to do just that using Travis CI, a popular continuous integration service provider.","heading":"Deployment"},{"pageID":"docs/deployment","id":173,"type":"p","anchor":"triggering-deployment-with-travis-ci","body":"Now, whenever a new commit lands in master, Travis CI will run your suite of tests and if everything passes, your website will be deployed via the yarn deploy script.","heading":"Deployment"},{"pageID":"docs/deployment","id":174,"type":"h3","anchor":"using-azure-pipelines","body":"Using Azure Pipelines","heading":"Deployment"},{"pageID":"docs/deployment","id":175,"type":"h2","anchor":"deploying-to-netlify","body":"Deploying to Netlify","heading":"Deployment"},{"pageID":"docs/deployment","id":176,"type":"p","anchor":"deploying-to-netlify","body":"To deploy your Docusaurus 2 sites to Netlify, first make sure the following options are properly configured:","heading":"Deployment"},{"pageID":"docs/deployment","id":177,"type":"p","anchor":"deploying-to-netlify","body":"Then, create your site with Netlify.","heading":"Deployment"},{"pageID":"docs/deployment","id":178,"type":"p","anchor":"deploying-to-netlify","body":"While you set up the site, specify the build commands and directories as follows:","heading":"Deployment"},{"pageID":"docs/deployment","id":179,"type":"p","anchor":"deploying-to-netlify","body":"If you did not configure these build options, you may still go to \"Site settings\" -> \"Build and deploy\" after your site is created.","heading":"Deployment"},{"pageID":"docs/deployment","id":180,"type":"p","anchor":"deploying-to-netlify","body":"Once properly configured with the above options, your site should deploy and automatically redeploy upon merging to your deploy branch, which defaults to master.","heading":"Deployment"},{"pageID":"docs/deployment","id":181,"type":"p","anchor":"deploying-to-netlify","body":"Make sure to disable Netlify setting Pretty URLs to prevent lowercased URLs, unnecessary redirects and 404 errors.","heading":"Deployment"},{"pageID":"docs/deployment","id":182,"type":"h2","anchor":"deploying-to-vercel","body":"Deploying to Vercel","heading":"Deployment"},{"pageID":"docs/deployment","id":183,"type":"p","anchor":"deploying-to-vercel","body":"Deploying your Docusaurus project to Vercel will provide you with various benefits in the areas of performance and ease of use.","heading":"Deployment"},{"pageID":"docs/deployment","id":184,"type":"p","anchor":"deploying-to-vercel","body":"Most importantly, however, deploying a Docusaurus project only takes a couple of seconds:","heading":"Deployment"},{"pageID":"docs/deployment","id":185,"type":"p","anchor":"deploying-to-vercel","body":"That's all. Your docs will automatically be deployed.","heading":"Deployment"},{"pageID":"docs/deployment","id":186,"type":"p","anchor":"deploying-to-vercel","body":"Now you can connect your site to GitHub or GitLab to automatically receive a new deployment every time you push a commit.","heading":"Deployment"},{"pageID":"docs/deployment","id":187,"type":"h2","anchor":"deploying-to-render","body":"Deploying to Render","heading":"Deployment"},{"pageID":"docs/deployment","id":188,"type":"p","anchor":"deploying-to-render","body":"Render offers free static site hosting with fully managed SSL, custom domains, a global CDN and continuous auto-deploy from your Git repo. Deploy your app in just a few minutes by following these steps.","heading":"Deployment"},{"pageID":"docs/deployment","id":189,"type":"p","anchor":"deploying-to-render","body":"Create a new Web Service on Render, and give Render permission to access your Docusaurus repo.","heading":"Deployment"},{"pageID":"docs/deployment","id":190,"type":"p","anchor":"deploying-to-render","body":"Select the branch to deploy. The default is master.","heading":"Deployment"},{"pageID":"docs/deployment","id":191,"type":"p","anchor":"deploying-to-render","body":"Enter the following values during creation.","heading":"Deployment"},{"pageID":"docs/deployment","id":192,"type":"p","anchor":"deploying-to-render","body":"That's it! Your app will be live on your Render URL as soon as the build finishes.","heading":"Deployment"},{"pageID":"docs/deployment","id":193,"type":"h2","anchor":"deploying-to-surge","body":"Deploying to Surge","heading":"Deployment"},{"pageID":"docs/deployment","id":194,"type":"p","anchor":"deploying-to-surge","body":"Surge is a static web hosting platform, it is used to deploy your Docusaurus project from the command line in a minute. Deploying your project to Surge is easy and it is also free (including a custom domain and SSL).","heading":"Deployment"},{"pageID":"docs/deployment","id":195,"type":"p","anchor":"deploying-to-surge","body":"Deploy your app in a matter of seconds using surge with the following steps:","heading":"Deployment"},{"pageID":"docs/deployment","id":196,"type":"p","anchor":"deploying-to-surge","body":"First-time users of Surge would be prompted to create an account from the command line(happens only once).","heading":"Deployment"},{"pageID":"docs/deployment","id":197,"type":"p","anchor":"deploying-to-surge","body":"Confirm that the site you want to publish is in the build directory, a randomly generated subdomain *.surge.sh subdomain is always given(which can be edited).","heading":"Deployment"},{"pageID":"docs/deployment","id":198,"type":"h3","anchor":"using-your-domain","body":"Using your domain","heading":"Deployment"},{"pageID":"docs/deployment","id":199,"type":"p","anchor":"using-your-domain","body":"If you have a domain name you can deploy your site using surge to your domain using the command:","heading":"Deployment"},{"pageID":"docs/deployment","id":200,"type":"p","anchor":"using-your-domain","body":"Your site is now deployed for free at subdomain.surge.sh or yourdomain.com depending on the method you chose.","heading":"Deployment"},{"pageID":"docs/deployment","id":201,"type":"h3","anchor":"setting-up-cname-file","body":"Setting up CNAME file","heading":"Deployment"},{"pageID":"docs/deployment","id":202,"type":"p","anchor":"setting-up-cname-file","body":"Store your domain in a CNAME file for future deployments with the following command:","heading":"Deployment"},{"pageID":"docs/deployment","id":203,"type":"p","anchor":"setting-up-cname-file","body":"You can deploy any other changes in the future with the command surge.","heading":"Deployment"},{"pageID":"docs/design-principles","id":204,"type":"h1","anchor":"how-docusaurus-works","body":"Design Principles","heading":"Design Principles"},{"pageID":"docs/design-principles","id":205,"type":"p","anchor":"how-docusaurus-works","body":"This section is a work in progress.","heading":"Design Principles"},{"pageID":"docs/design-principles","id":206,"type":"h2","anchor":"how-docusaurus-works","body":"How Docusaurus works","heading":"Design Principles"},{"pageID":"docs/design-principles","id":207,"type":"p","anchor":"how-docusaurus-works","body":"We believe that as developers, knowing how a library works is helpful in allowing us to become better at using it. Hence we're dedicating effort into explaining the architecture and various components of Docusaurus with the hope that users reading it will gain a deeper understanding of the tool and be even more proficient in using it.","heading":"Design Principles"},{"pageID":"docs/docs-introduction","id":208,"type":"h1","anchor":"document-id","body":"Docs Introduction","heading":"Docs Introduction"},{"pageID":"docs/docs-introduction","id":209,"type":"p","anchor":"document-id","body":"The docs feature provides users with a way to organize Markdown files in a hierarchical format.","heading":"Docs Introduction"},{"pageID":"docs/docs-introduction","id":210,"type":"h2","anchor":"document-id","body":"Document ID","heading":"Docs Introduction"},{"pageID":"docs/docs-introduction","id":211,"type":"p","anchor":"document-id","body":"Every document has a unique id. By default, a document id is the name of the document (without the extension) relative to the root docs directory.","heading":"Docs Introduction"},{"pageID":"docs/docs-introduction","id":212,"type":"p","anchor":"document-id","body":"For example, greeting.md id is greeting and guide/hello.md id is guide/hello.","heading":"Docs Introduction"},{"pageID":"docs/docs-introduction","id":213,"type":"p","anchor":"document-id","body":"However, the last part of the id can be defined by user in the front matter. For example, if guide/hello.md's content is defined as below, its final id is guide/part1.","heading":"Docs Introduction"},{"pageID":"docs/docs-introduction","id":214,"type":"p","anchor":"document-id","body":"If you want more control over the last part of the document URL, it is possible to add a slug (defaults to the id).","heading":"Docs Introduction"},{"pageID":"docs/docs-introduction","id":215,"type":"h2","anchor":"home-page-docs","body":"Home page docs","heading":"Docs Introduction"},{"pageID":"docs/docs-introduction","id":216,"type":"p","anchor":"home-page-docs","body":"Using the homePageId property, you can create a home page of your docs. To do this, you can create a new document, especially for this purpose with the id as _index, or you could specify an existing document id.","heading":"Docs Introduction"},{"pageID":"docs/docs-introduction","id":217,"type":"p","anchor":"home-page-docs","body":"Given the example above, now when you navigate to the path /docs you will see that the document content with id is getting-started. This functionality also works for docs with versioning enabled. Importantly, with document serves as home docs page, it will not be available at its URL. Following the example above, this means that the docs/getting-started URL will be lead to a 404 error.","heading":"Docs Introduction"},{"pageID":"docs/docs-introduction","id":218,"type":"p","anchor":"home-page-docs","body":"The document id of _index is reserved exclusively for the home doc page, so it will not work as a standalone route. If left to the default, the page will not show a sidebar. If you wish to have a sidebar for this page, specify the document id that is listed in the sidebar file.","heading":"Docs Introduction"},{"pageID":"docs/docs-introduction","id":219,"type":"p","anchor":"home-page-docs","body":"The page docs that you created (eg. src/pages/docs.js) will take precedence over the route generated via the homePageId option.","heading":"Docs Introduction"},{"pageID":"docs/docs-introduction","id":220,"type":"h2","anchor":"sidebar","body":"Sidebar","heading":"Docs Introduction"},{"pageID":"docs/docs-introduction","id":221,"type":"p","anchor":"sidebar","body":"To generate a sidebar to your Docusaurus site, you need to define a file that exports a sidebar object and pass that into the @docusaurus/plugin-docs plugin directly or via @docusaurus/preset-classic.","heading":"Docs Introduction"},{"pageID":"docs/docs-introduction","id":222,"type":"h3","anchor":"sidebar-object","body":"Sidebar object","heading":"Docs Introduction"},{"pageID":"docs/docs-introduction","id":223,"type":"p","anchor":"sidebar-object","body":"A sidebar object is defined like this:","heading":"Docs Introduction"},{"pageID":"docs/docs-introduction","id":224,"type":"p","anchor":"sidebar-object","body":"Below is an example of a sidebar object. The key docs is the id of the sidebar (can be renamed to something else) and Getting Started is a category within the sidebar. greeting and doc1 are both sidebar item.","heading":"Docs Introduction"},{"pageID":"docs/docs-introduction","id":225,"type":"p","anchor":"sidebar-object","body":"Keep in mind that EcmaScript does not guarantee Object.keys({a,b}) === ['a','b'] (yet, this is generally true). If you don't want to rely on iteration order of JavaScript object keys for the category name, the following sidebar object is also equivalent of the above shorthand syntax.","heading":"Docs Introduction"},{"pageID":"docs/docs-introduction","id":226,"type":"p","anchor":"sidebar-object","body":"You can also have multiple sidebars for different Markdown files by adding more top-level keys to the exported object.","heading":"Docs Introduction"},{"pageID":"docs/docs-introduction","id":227,"type":"p","anchor":"sidebar-object","body":"Example:","heading":"Docs Introduction"},{"pageID":"docs/docs-introduction","id":228,"type":"p","anchor":"sidebar-item","body":"As the name implies, SidebarItem is an item defined in a Sidebar. There are a few types we support:","heading":"Docs Introduction"},{"pageID":"docs/docs-introduction","id":229,"type":"p","anchor":"doc","body":"Sidebar item type that links to a doc page. Example:","heading":"Docs Introduction"},{"pageID":"docs/docs-introduction","id":230,"type":"p","anchor":"doc","body":"Using just the Document ID is perfectly valid as well, the following is equivalent to the above:","heading":"Docs Introduction"},{"pageID":"docs/docs-introduction","id":231,"type":"p","anchor":"doc","body":"Note that using this type will bind the linked doc to current sidebar, this means that if you access doc1 page, the sidebar displayed will be the sidebar this item is on. For below case, doc1 is bounded to firstSidebar.","heading":"Docs Introduction"},{"pageID":"docs/docs-introduction","id":232,"type":"p","anchor":"link","body":"Sidebar item type that links to a non-document page. Example:","heading":"Docs Introduction"},{"pageID":"docs/docs-introduction","id":233,"type":"p","anchor":"ref","body":"Sidebar item type that links to doc without bounding it to the sidebar. Example:","heading":"Docs Introduction"},{"pageID":"docs/docs-introduction","id":234,"type":"p","anchor":"category","body":"This is used to add hierarchies to the sidebar:","heading":"Docs Introduction"},{"pageID":"docs/docs-introduction","id":235,"type":"p","anchor":"category","body":"As an example, here's how we created the subcategory for \"Docs\" under \"Guides\" in this site:","heading":"Docs Introduction"},{"pageID":"docs/docs-introduction","id":236,"type":"p","anchor":"category","body":"Note: it's possible to use the shorthand syntax to create nested categories:","heading":"Docs Introduction"},{"pageID":"docs/docs-introduction","id":237,"type":"p","anchor":"collapsible-categories","body":"For sites with a sizable amount of content, we support the option to expand/collapse a category to toggle the display of its contents. Categories are collapsible by default. If you want them to be always expanded, set themeConfig.sidebarCollapsible to false:","heading":"Docs Introduction"},{"pageID":"docs/docs-introduction","id":238,"type":"p","anchor":"expanded-categories-by-default","body":"For docs that have collapsible categories, you may want more fine-grain control over certain categories. If you want specific categories to be always expanded, you can set collapsed to false:","heading":"Docs Introduction"},{"pageID":"docs/docs-introduction","id":239,"type":"h2","anchor":"docs-only-mode","body":"Docs-only mode","heading":"Docs Introduction"},{"pageID":"docs/docs-introduction","id":240,"type":"p","anchor":"docs-only-mode","body":"If you only want the documentation feature, you can run your Docusaurus 2 site without a landing page and display your documentation page as the index page instead.","heading":"Docs Introduction"},{"pageID":"docs/docs-introduction","id":241,"type":"p","anchor":"docs-only-mode","body":"To enable docs-only mode, set the routeBasePath property of the docs object to the root of your site. Also, set the homePageId property to the ID of the document that you wish to show by default.","heading":"Docs Introduction"},{"pageID":"docs/docs-introduction","id":242,"type":"p","anchor":"docs-only-mode","body":"More details on functionality of home page for docs can be found in appropriate section.","heading":"Docs Introduction"},{"pageID":"docs/docs-introduction","id":243,"type":"p","anchor":"docs-only-mode","body":"Now, when visiting your site, it will show your initial document instead of a landing page.","heading":"Docs Introduction"},{"pageID":"docs/docs-introduction","id":244,"type":"p","anchor":"docs-only-mode","body":"You should delete the existing homepage at ./src/pages/index.js, or else there will be two files mapping to the same route!","heading":"Docs Introduction"},{"pageID":"docs/docs-introduction","id":245,"type":"p","anchor":"docs-only-mode","body":"There's also a \"blog-only mode\" for those who only want to use the blog feature of Docusaurus 2. You can use the same method detailed above. Follow the setup instructions on Blog-only mode.","heading":"Docs Introduction"},{"pageID":"docs/docusaurus-core","id":246,"type":"h1","anchor":"components","body":"Docusaurus Client API","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":247,"type":"p","anchor":"components","body":"Docusaurus provides some APIs on the clients that can be helpful to you when building your site.","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":248,"type":"h2","anchor":"components","body":"Components","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":249,"type":"h3","anchor":"head","body":"<Head/>","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":250,"type":"p","anchor":"head","body":"This reusable React component will manage all of your changes to the document head. It takes plain HTML tags and outputs plain HTML tags and is beginner-friendly. It is a wrapper around React Helmet.","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":251,"type":"p","anchor":"head","body":"Usage Example:","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":252,"type":"p","anchor":"head","body":"Nested or latter components will override duplicate usages:","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":253,"type":"p","anchor":"head","body":"Outputs","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":254,"type":"h3","anchor":"link","body":"<Link/>","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":255,"type":"p","anchor":"link","body":"This component enables linking to internal pages as well as a powerful performance feature called preloading. Preloading is used to prefetch resources so that the resources are fetched by the time the user navigates with this component. We use an IntersectionObserver to fetch a low-priority request when the <Link> is in the viewport and then use an onMouseOver event to trigger a high-priority request when it is likely that a user will navigate to the requested resource.","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":256,"type":"p","anchor":"link","body":"The component is a wrapper around react-router’s <Link> component that adds useful enhancements specific to Docusaurus. All props are passed through to react-router’s <Link> component.","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":257,"type":"p","anchor":"to-string","body":"The target location to navigate to. Example: /docs/introduction.","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":258,"type":"h3","anchor":"redirect","body":"<Redirect/>","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":259,"type":"p","anchor":"redirect","body":"Rendering a <Redirect> will navigate to a new location. The new location will override the current location in the history stack, like server-side redirects (HTTP 3xx) do. You can refer to React Router's Redirect documentation for more info on available props.","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":260,"type":"p","anchor":"redirect","body":"Example usage:","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":261,"type":"p","anchor":"redirect","body":"@docusaurus/router implements React Router and supports its features.","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":262,"type":"h3","anchor":"browseronly","body":"<BrowserOnly/>","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":263,"type":"p","anchor":"browseronly","body":"The <BrowserOnly> component accepts a children prop, a render function which will not be executed during the pre-rendering phase of the build process. This is useful for hiding code that is only meant to run in the browsers (e.g. where the window/document objects are being accessed). To improve SEO, you can also provide fallback content using the fallback prop, which will be prerendered until in the build process and replaced with the client-side only contents when viewed in the browser.","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":264,"type":"h2","anchor":"hooks","body":"Hooks","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":265,"type":"h3","anchor":"usedocusauruscontext","body":"useDocusaurusContext","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":266,"type":"p","anchor":"usedocusauruscontext","body":"React hook to access Docusaurus Context. Context contains siteConfig object from docusaurus.config.js, and some additional site metadata.","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":267,"type":"p","anchor":"usedocusauruscontext","body":"Usage example:","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":268,"type":"h3","anchor":"usebaseurl","body":"useBaseUrl","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":269,"type":"p","anchor":"usebaseurl","body":"React hook to automatically prepend baseUrl to a string automatically. This is particularly useful if you don't want to hardcode your config's baseUrl. We highly recommend you to use this.","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":270,"type":"p","anchor":"usebaseurl","body":"Example usage:","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":271,"type":"h3","anchor":"usebaseurlutils","body":"useBaseUrlUtils","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":272,"type":"p","anchor":"usebaseurlutils","body":"Sometimes useBaseUrl is not good enough. This hook return additional utils related to your site's base url.","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":273,"type":"h3","anchor":"useglobaldata","body":"useGlobalData()","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":274,"type":"p","anchor":"useglobaldata","body":"React hook to access Docusaurus global data created by all the plugins.","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":275,"type":"p","anchor":"useglobaldata","body":"Global data is namespaced by plugin name, and plugin id.","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":276,"type":"p","anchor":"useglobaldata","body":"Plugin id is only useful when a plugin is used multiple times on the same site. Each plugin instance is able to create its own global data.","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":277,"type":"p","anchor":"useglobaldata","body":"Usage example:","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":278,"type":"p","anchor":"useglobaldata","body":"Inspect your site's global data at ./docusaurus/globalData.json","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":279,"type":"h3","anchor":"useplugindatapluginname-string-pluginid-string","body":"usePluginData(pluginName: string, pluginId?: string)","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":280,"type":"p","anchor":"useplugindatapluginname-string-pluginid-string","body":"Access global data created by a specific plugin instance.","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":281,"type":"p","anchor":"useplugindatapluginname-string-pluginid-string","body":"This is the most convenient hook to access plugin global data, and should be used most of the time.","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":282,"type":"p","anchor":"useplugindatapluginname-string-pluginid-string","body":"pluginId is optional if you don't use multi-instance plugins.","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":283,"type":"p","anchor":"useplugindatapluginname-string-pluginid-string","body":"Usage example:","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":284,"type":"h3","anchor":"useallplugininstancesdatapluginname-string","body":"useAllPluginInstancesData(pluginName: string)","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":285,"type":"p","anchor":"useallplugininstancesdatapluginname-string","body":"Access global data created by a specific plugin. Given a plugin name, it returns the data of all the plugins instances of that name, by pluginId.","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":286,"type":"p","anchor":"useallplugininstancesdatapluginname-string","body":"Usage example:","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":287,"type":"h2","anchor":"modules","body":"Modules","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":288,"type":"h3","anchor":"executionenvironment","body":"ExecutionEnvironment","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus-core","id":289,"type":"p","anchor":"executionenvironment","body":"A module which exposes a few boolean variables to check the current rendering environment. Useful if you want to only run certain code on client/server or need to write server-side rendering compatible code.","heading":"Docusaurus Client API"},{"pageID":"docs/docusaurus.config.js","id":290,"type":"h1","anchor":"overview","body":"docusaurus.config.js","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":291,"type":"h2","anchor":"overview","body":"Overview","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":292,"type":"p","anchor":"overview","body":"docusaurus.config.js contains configurations for your site and is placed in the root directory of your site.","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":293,"type":"h2","anchor":"required-fields","body":"Required fields","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":294,"type":"h3","anchor":"title","body":"title","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":295,"type":"p","anchor":"title","body":"Title for your website.","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":296,"type":"h3","anchor":"favicon","body":"favicon","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":297,"type":"p","anchor":"favicon","body":"URL for site favicon. Example:","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":298,"type":"p","anchor":"favicon","body":"You can also use the favicon URL relative to the static directory of your site. For example, your site has the following directory structure:","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":299,"type":"p","anchor":"favicon","body":"So you can refer it like below:","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":300,"type":"h3","anchor":"url","body":"url","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":301,"type":"p","anchor":"url","body":"URL for your website. This can also be considered the top-level hostname. For example, https://facebook.github.io is the URL of https://facebook.github.io/metro/, and https://docusaurus.io is the URL for https://docusaurus.io. This field is related to the baseUrl field.","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":302,"type":"h3","anchor":"baseurl","body":"baseUrl","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":303,"type":"p","anchor":"baseurl","body":"Base URL for your site. This can also be considered the path after the host. For example, /metro/ is the baseUrl of https://facebook.github.io/metro/. For URLs that have no path, the baseUrl should be set to /. This field is related to the url field.","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":304,"type":"h2","anchor":"optional-fields","body":"Optional fields","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":305,"type":"h3","anchor":"onbrokenlinks","body":"onBrokenLinks","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":306,"type":"p","anchor":"onbrokenlinks","body":"The behavior of Docusaurus, when it detects any broken link.","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":307,"type":"p","anchor":"onbrokenlinks","body":"By default, it throws an error, to ensure you never ship any broken link, but you can lower this security if needed.","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":308,"type":"p","anchor":"onbrokenlinks","body":"The broken links detection is only available for a production build (docusaurus build).","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":309,"type":"h3","anchor":"tagline","body":"tagline","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":310,"type":"p","anchor":"tagline","body":"The tagline for your website.","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":311,"type":"h3","anchor":"organizationname","body":"organizationName","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":312,"type":"p","anchor":"organizationname","body":"The GitHub user or organization that owns the repository. Used by the deployment command.","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":313,"type":"h3","anchor":"projectname","body":"projectName","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":314,"type":"p","anchor":"projectname","body":"The name of the GitHub repository. Used by the deployment command.","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":315,"type":"h3","anchor":"githubhost","body":"githubHost","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":316,"type":"p","anchor":"githubhost","body":"The hostname of your server. Useful if you are using GitHub Enterprise.","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":317,"type":"h3","anchor":"themeconfig","body":"themeConfig","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":318,"type":"p","anchor":"themeconfig","body":"An object containing data needed by the theme you use.","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":319,"type":"p","anchor":"themeconfig","body":"For Docusaurus' default theme classic, we use themeConfig to customize your navbar and footer links:","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":320,"type":"p","anchor":"themeconfig","body":"Example:","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":321,"type":"h3","anchor":"plugins","body":"plugins","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":322,"type":"h3","anchor":"themes","body":"themes","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":323,"type":"h3","anchor":"presets","body":"presets","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":324,"type":"h3","anchor":"customfields","body":"customFields","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":325,"type":"p","anchor":"customfields","body":"Docusaurus guards docusaurus.config.js from unknown fields. To add a custom field, define it on customFields.","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":326,"type":"p","anchor":"customfields","body":"Attempting to add unknown field in the config will lead to error in build time:","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":327,"type":"h3","anchor":"scripts","body":"scripts","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":328,"type":"p","anchor":"scripts","body":"An array of scripts to load. The values can be either strings or plain objects of attribute-value maps. The <script> tags will be inserted in the HTML <head>.","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":329,"type":"p","anchor":"scripts","body":"Note that <script> added here are render-blocking so you might want to add async: true/defer: true to the objects.","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":330,"type":"p","anchor":"scripts","body":"Example:","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":331,"type":"h3","anchor":"stylesheets","body":"stylesheets","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":332,"type":"p","anchor":"stylesheets","body":"An array of CSS sources to load. The values can be either strings or plain objects of attribute-value maps. The <link> tags will be inserted in the HTML <head>.","heading":"docusaurus.config.js"},{"pageID":"docs/docusaurus.config.js","id":333,"type":"p","anchor":"stylesheets","body":"Example:","heading":"docusaurus.config.js"},{"pageID":"docs/installation","id":334,"type":"h1","anchor":"requirements","body":"Installation","heading":"Installation"},{"pageID":"docs/installation","id":335,"type":"p","anchor":"requirements","body":"Docusaurus is essentially a set of npm packages that can be installed over npm.","heading":"Installation"},{"pageID":"docs/installation","id":336,"type":"h2","anchor":"requirements","body":"Requirements","heading":"Installation"},{"pageID":"docs/installation","id":337,"type":"h2","anchor":"scaffold-project-website","body":"Scaffold project website","heading":"Installation"},{"pageID":"docs/installation","id":338,"type":"p","anchor":"scaffold-project-website","body":"The easiest way to install Docusaurus is to use the command line tool that helps you scaffold a skeleton Docusaurus website. You can run this command anywhere in a new empty repository or within an existing repository, it will create a new directory containing the scaffolded files.","heading":"Installation"},{"pageID":"docs/installation","id":339,"type":"p","anchor":"scaffold-project-website","body":"Example:","heading":"Installation"},{"pageID":"docs/installation","id":340,"type":"p","anchor":"scaffold-project-website","body":"If you do not specify name or template, it will prompt you for them. We recommend the classic template so that you can get started quickly and it contains features found in Docusaurus 1. The classic template contains @docusaurus/preset-classic which includes standard documentation, a blog, custom pages, and a CSS framework (with dark mode support). You can get up and running extremely quickly with the classic template and customize things later on when you have gained more familiarity with Docusaurus.","heading":"Installation"},{"pageID":"docs/installation","id":341,"type":"p","anchor":"scaffold-project-website","body":"[FB-Only]: If you are setting up a new Docusaurus website for a Facebook open source project, use the facebook template instead, which comes with some useful Facebook-specific defaults:","heading":"Installation"},{"pageID":"docs/installation","id":342,"type":"h2","anchor":"project-structure","body":"Project structure","heading":"Installation"},{"pageID":"docs/installation","id":343,"type":"p","anchor":"project-structure","body":"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/:","heading":"Installation"},{"pageID":"docs/installation","id":344,"type":"h3","anchor":"project-structure-rundown","body":"Project structure rundown","heading":"Installation"},{"pageID":"docs/installation","id":345,"type":"h2","anchor":"running-the-development-server","body":"Running the development server","heading":"Installation"},{"pageID":"docs/installation","id":346,"type":"p","anchor":"running-the-development-server","body":"To preview your changes as you edit the files, you can run a local development server that will serve your website and it will reflect the latest changes.","heading":"Installation"},{"pageID":"docs/installation","id":347,"type":"p","anchor":"running-the-development-server","body":"By default, a browser window will open at http://localhost:3000.","heading":"Installation"},{"pageID":"docs/installation","id":348,"type":"p","anchor":"running-the-development-server","body":"Congratulations! You have just created your first Docusaurus site! Browse around the site to see what's available.","heading":"Installation"},{"pageID":"docs/installation","id":349,"type":"h2","anchor":"build","body":"Build","heading":"Installation"},{"pageID":"docs/installation","id":350,"type":"p","anchor":"build","body":"Docusaurus is a modern static website generator so we need to build the website into a directory of static contents and put it on a web server so that it can be viewed. To build the website:","heading":"Installation"},{"pageID":"docs/installation","id":351,"type":"p","anchor":"build","body":"and contents will be generated within the /build directory, which can be copied to any static file hosting service like GitHub pages, Now or Netlify. Check out the docs on deployment for more details.","heading":"Installation"},{"pageID":"docs/installation","id":352,"type":"h2","anchor":"updating-your-docusaurus-version","body":"Updating your Docusaurus version","heading":"Installation"},{"pageID":"docs/installation","id":353,"type":"p","anchor":"updating-your-docusaurus-version","body":"There are many ways to update your Docusaurus version. One guaranteed way is to manually change the version number in package.json to the desired version. Note that all @docusaurus/-namespaced packages should be using the same version.","heading":"Installation"},{"pageID":"docs/installation","id":354,"type":"p","anchor":"updating-your-docusaurus-version","body":"Please update to the latest Docusaurus 2 version shown at the top of the page, not what is shown below.","heading":"Installation"},{"pageID":"docs/installation","id":355,"type":"p","anchor":"updating-your-docusaurus-version","body":"Then, in the directory containing package.json, run your package manager's install command:","heading":"Installation"},{"pageID":"docs/installation","id":356,"type":"p","anchor":"updating-your-docusaurus-version","body":"To check that that the update occurred successfully, run:","heading":"Installation"},{"pageID":"docs/installation","id":357,"type":"p","anchor":"updating-your-docusaurus-version","body":"You should see the correct version as output.","heading":"Installation"},{"pageID":"docs/installation","id":358,"type":"p","anchor":"updating-your-docusaurus-version","body":"Alternatively, if you are using Yarn, you can do:","heading":"Installation"},{"pageID":"docs/installation","id":359,"type":"h2","anchor":"problems","body":"Problems?","heading":"Installation"},{"pageID":"docs/installation","id":360,"type":"p","anchor":"problems","body":"Ask for help on Stack Overflow, on our GitHub repository or Twitter.","heading":"Installation"},{"pageID":"docs/lifecycle-apis","id":361,"type":"h1","anchor":"validateoptionsoptionsvalidate","body":"Lifecycle APIs","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":362,"type":"p","anchor":"validateoptionsoptionsvalidate","body":"This section is a work in progress.","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":363,"type":"p","anchor":"validateoptionsoptionsvalidate","body":"Lifecycle APIs are shared by Themes and Plugins.","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":364,"type":"h2","anchor":"validateoptionsoptionsvalidate","body":"validateOptions({options,validate})","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":365,"type":"p","anchor":"validateoptionsoptionsvalidate","body":"Return validated and normalized options for the plugin. This method is called before the plugin is initialized.You must return options since the returned options will be passed to plugin during intialization.","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":366,"type":"h3","anchor":"options","body":"options","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":367,"type":"p","anchor":"options","body":"validateOptions is called with options passed to plugin for validation and normalization.","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":368,"type":"h3","anchor":"validate","body":"validate","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":369,"type":"p","anchor":"validate","body":"validateOptions is called with validate function which takes a Joi schema and options as argument, returns validated and normalized options. validate will automatically handle error and validation config.","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":370,"type":"p","anchor":"validate","body":"Joi is recommended for validation and normalization of options.","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":371,"type":"p","anchor":"validate","body":"If you don't use Joi for validation you can throw an Error in case of invalid options and return options in case of success.","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":372,"type":"p","anchor":"validate","body":"You can also use ES modules style exports.","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":373,"type":"h2","anchor":"validatethemeconfigthemeconfigvalidate","body":"validateThemeConfig({themeConfig,validate})","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":374,"type":"p","anchor":"validatethemeconfigthemeconfigvalidate","body":"Return validated and normalized configuration for the theme.","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":375,"type":"h3","anchor":"themeconfig","body":"themeConfig","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":376,"type":"p","anchor":"themeconfig","body":"validateThemeConfig is called with themeConfig provided in docusaurus.config.js for validation and normalization.","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":377,"type":"h3","anchor":"validate-1","body":"validate","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":378,"type":"p","anchor":"validate-1","body":"validateThemeConfig is called with validate function which takes a Joi schema and themeConfig as argument, returns validated and normalized options. validate will automatically handle error and validation config.","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":379,"type":"p","anchor":"validate-1","body":"Joi is recommended for validation and normalization of theme config.","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":380,"type":"p","anchor":"validate-1","body":"If you don't use Joi for validation you can throw an Error in case of invalid options.","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":381,"type":"p","anchor":"validate-1","body":"You can also use ES modules style exports.","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":382,"type":"h2","anchor":"getpathstowatch","body":"getPathsToWatch()","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":383,"type":"p","anchor":"getpathstowatch","body":"Specifies the paths to watch for plugins and themes. The paths are watched by the dev server so that the plugin lifecycles are reloaded when contents in the watched paths change. Note that the plugins and themes modules are initially called with context and options from Node, which you may use to find the necessary directory information about the site.","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":384,"type":"p","anchor":"getpathstowatch","body":"Example:","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":385,"type":"h2","anchor":"async-loadcontent","body":"async loadContent()","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":386,"type":"p","anchor":"async-loadcontent","body":"Plugins should use this lifecycle to fetch from data sources (filesystem, remote API, headless CMS, etc) or doing some server processing.","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":387,"type":"p","anchor":"async-loadcontent","body":"For example, this plugin below return a random integer between 1 to 10 as content;","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":388,"type":"h2","anchor":"async-contentloadedcontent-actions","body":"async contentLoaded({content, actions})","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":389,"type":"p","anchor":"async-contentloadedcontent-actions","body":"Plugins should use the data loaded in loadContent and construct the pages/routes that consume the loaded data (optional).","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":390,"type":"h3","anchor":"content","body":"content","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":391,"type":"p","anchor":"content","body":"contentLoaded will be called after loadContent is done, the return value of loadContent() will be passed to contentLoaded as content.","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":392,"type":"h3","anchor":"actions","body":"actions","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":393,"type":"p","anchor":"actions","body":"actions contain two functions:","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":394,"type":"p","anchor":"actions","body":"Create a route to add to the website.","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":395,"type":"p","anchor":"actions","body":"A function to help you create static data (generally json or string), that you can provide to your routes as props.","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":396,"type":"p","anchor":"actions","body":"For example, this plugin below create a /friends page which display Your friends are: Yangshun, Sebastien:","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":397,"type":"p","anchor":"actions","body":"This function permits to create some global plugin data, that can be read from any page, including the pages created by other plugins, and your theme layout.","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":398,"type":"p","anchor":"actions","body":"This data become accessible to your client-side/theme code, through the useGlobalData and usePluginData","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":399,"type":"p","anchor":"actions","body":"One this data is created, you can access it with the global data hooks APIs","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":400,"type":"p","anchor":"actions","body":"Global data is... global: its size affects the loading time of all pages of your site, so try to keep it small.","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":401,"type":"p","anchor":"actions","body":"Prefer createData and page-specific data whenever possible.","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":402,"type":"p","anchor":"actions","body":"For example, this plugin below create a /friends page which display Your friends are: Yangshun, Sebastien:","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":403,"type":"h2","anchor":"async-routesloadedroutes","body":"async routesLoaded(routes)","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":404,"type":"p","anchor":"async-routesloadedroutes","body":"Plugins can modify the routes that were generated by all plugins. routesLoaded is called after contentLoaded hook.","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":405,"type":"h2","anchor":"configurewebpackconfig-isserver-utils","body":"configureWebpack(config, isServer, utils)","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":406,"type":"p","anchor":"configurewebpackconfig-isserver-utils","body":"Modifies the internal webpack config. If the return value is a JavaScript object, it will be merged into the final config using webpack-merge. If it is a function, it will be called and receive config as the first argument and an isServer flag as the argument argument.","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":407,"type":"h3","anchor":"config","body":"config","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":408,"type":"p","anchor":"config","body":"configureWebpack is called with config generated according to client/server build. You may treat this as the base config to be merged with.","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":409,"type":"h3","anchor":"isserver","body":"isServer","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":410,"type":"p","anchor":"isserver","body":"configureWebpack will be called both in server build and in client build. The server build receives true and the client build receives false as isServer.","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":411,"type":"h3","anchor":"utils","body":"utils","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":412,"type":"p","anchor":"utils","body":"The initial call to configureWebpack also receives a util object consists of three functions:","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":413,"type":"p","anchor":"utils","body":"You may use them to return your webpack configures conditionally.","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":414,"type":"p","anchor":"utils","body":"For example, this plugin below modify the webpack config to transpile .foo file.","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":415,"type":"h3","anchor":"merge-strategy","body":"Merge strategy","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":416,"type":"p","anchor":"merge-strategy","body":"We merge the Webpack configuration parts of plugins into the global Webpack config using webpack-merge.","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":417,"type":"p","anchor":"merge-strategy","body":"It is possible to specify the merge strategy. For example, if you want a webpack rule to be prepended instead of appended:","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":418,"type":"p","anchor":"merge-strategy","body":"Read the webpack-merge strategy doc for more details.","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":419,"type":"h2","anchor":"postbuildprops","body":"postBuild(props)","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":420,"type":"p","anchor":"postbuildprops","body":"Called when a (production) build finishes.","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":421,"type":"p","anchor":"postbuildprops","body":"Example:","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":422,"type":"h2","anchor":"extendclicli","body":"extendCli(cli)","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":423,"type":"p","anchor":"extendclicli","body":"Register an extra command to enhance the CLI of docusaurus. cli is commander object.","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":424,"type":"p","anchor":"extendclicli","body":"Example:","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":425,"type":"h2","anchor":"injecthtmltags","body":"injectHtmlTags()","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":426,"type":"p","anchor":"injecthtmltags","body":"Inject head and/or body HTML tags to Docusaurus generated HTML.","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":427,"type":"p","anchor":"injecthtmltags","body":"Example:","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":428,"type":"h2","anchor":"getthemepath","body":"getThemePath()","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":429,"type":"p","anchor":"getthemepath","body":"Returns the path to the directory where the theme components can be found. When your users calls swizzle, getThemePath is called and its returned path is used to find your theme components.","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":430,"type":"p","anchor":"getthemepath","body":"If you use the folder directory above, your getThemePath can be:","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":431,"type":"h2","anchor":"gettypescriptthemepath","body":"getTypeScriptThemePath()","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":432,"type":"p","anchor":"gettypescriptthemepath","body":"Similar to getThemePath(), it should return the path to the directory where the source code of TypeScript theme components can be found. Theme components under this path will not be resolved by Webpack. Therefore, it is not a replacement of getThemePath(). Instead, this path is purely for swizzling TypeScript theme components.","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":433,"type":"p","anchor":"gettypescriptthemepath","body":"If you want to support TypeScript component swizzling for your theme, you can make the path returned by getTypeScriptThemePath() be your source directory, and make path returned by getThemePath() be the compiled JavaScript output.","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":434,"type":"p","anchor":"gettypescriptthemepath","body":"Example:","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":435,"type":"h2","anchor":"getclientmodules","body":"getClientModules()","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":436,"type":"p","anchor":"getclientmodules","body":"Returns an array of paths to the modules that are to be imported in the client bundle. These modules are imported globally before React even renders the initial UI.","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":437,"type":"p","anchor":"getclientmodules","body":"As an example, to make your theme load a customCss object from options passed in by the user:","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":438,"type":"h2","anchor":"example","body":"Example","heading":"Lifecycle APIs"},{"pageID":"docs/lifecycle-apis","id":439,"type":"p","anchor":"example","body":"Here's a mind model for a presumptuous plugin implementation.","heading":"Lifecycle APIs"},{"pageID":"docs/markdown-features","id":440,"type":"h1","anchor":"markdown-headers","body":"Markdown Features","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":441,"type":"p","anchor":"markdown-headers","body":"Documentation is one of your product's interfaces with your users. A well-written and well-organized set of docs helps your users understand your product quickly. Our aligned goal here is to help your users find and understand the information they need, as quickly as possible.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":442,"type":"p","anchor":"markdown-headers","body":"Docusaurus 2 uses modern tooling to help you compose your interactive documentations with ease. You may embed React components, or build live coding blocks where your users may play with the code on the spot. Start sharing your eureka moments with the code your audience cannot walk away from. It is perhaps the most effective way of attracting potential users.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":443,"type":"p","anchor":"markdown-headers","body":"In this section, we'd like to introduce you to the tools we've picked that we believe will help you build powerful documentation. Let us walk you through with an example.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":444,"type":"p","anchor":"markdown-headers","body":"All the following content assumes you are using @docusaurus/preset-classic or @docusaurus/plugin-content-docs.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":445,"type":"p","anchor":"markdown-headers","body":"Markdown is a syntax that enables you to write formatted content in a readable syntax. The standard Markdown syntax is supported and we use MDX as the parsing engine, which can do much more than just parsing Markdown. More on that later.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":446,"type":"p","anchor":"markdown-headers","body":"Create a markdown file, greeting.md, and place it under the docs directory.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":447,"type":"p","anchor":"markdown-headers","body":"At the top of the file, specify id and title in the front matter, so that Docusaurus will pick them up correctly when generating your site.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":448,"type":"p","anchor":"markdown-headers","body":"This will render in the browser as follows:","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":449,"type":"h2","anchor":"markdown-headers","body":"Hello from Docusaurus","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":450,"type":"p","anchor":"markdown-headers","body":"Are you ready to create the documentation site for your open source project?","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":451,"type":"h3","anchor":"markdown-headers","body":"Headers","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":452,"type":"p","anchor":"markdown-headers","body":"will show up on the table of contents on the upper right","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":453,"type":"p","anchor":"markdown-headers","body":"So that your users will know what this page is all about without scrolling down or even without reading too much.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":454,"type":"h3","anchor":"markdown-headers","body":"Only h2 and h3 will be in the toc","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":455,"type":"p","anchor":"markdown-headers","body":"The headers are well-spaced so that the hierarchy is clear.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":456,"type":"h2","anchor":"markdown-headers","body":"Markdown headers","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":457,"type":"p","anchor":"markdown-headers","body":"Documents use the following markdown header fields that are enclosed by a line --- on either side:","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":458,"type":"p","anchor":"markdown-headers","body":"Example:","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":459,"type":"h2","anchor":"referencing-other-documents","body":"Referencing other documents","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":460,"type":"p","anchor":"referencing-other-documents","body":"If you want to reference another document file, you could use the name of the document you want to reference. Docusaurus will convert the file path to be the final website path (and remove the .md).","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":461,"type":"p","anchor":"referencing-other-documents","body":"For example, if you are in doc2.md and you want to reference doc1.md and folder/doc3.md:","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":462,"type":"p","anchor":"referencing-other-documents","body":"One benefit of this approach is that the links to external files will still work if you are viewing the file on GitHub.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":463,"type":"h2","anchor":"embedding-react-components-with-mdx","body":"Embedding React components with MDX","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":464,"type":"p","anchor":"embedding-react-components-with-mdx","body":"Docusaurus has built-in support for MDX, which allows you to write JSX within your Markdown files and render them as React components.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":465,"type":"p","anchor":"embedding-react-components-with-mdx","body":"Note 1: While both .md and .mdx files are parsed using MDX, some of the syntax are treated slightly differently. For the most accurate parsing and better editor support, we recommend using the .mdx extension for files containing MDX syntax. Let's rename the previous file to greeting.mdx.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":466,"type":"p","anchor":"embedding-react-components-with-mdx","body":"Note 2: Since all doc files are parsed using MDX, any HTML is treated as JSX. Therefore, if you need to inline-style a component, follow JSX flavor and provide style objects. This behavior is different from Docusaurus 1. See also Migrating from v1 to v2.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":467,"type":"p","anchor":"embedding-react-components-with-mdx","body":"Try this block here:","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":468,"type":"p","anchor":"embedding-react-components-with-mdx","body":"Notice how it renders both the markup from your React component and the Markdown syntax:","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":469,"type":"p","anchor":"embedding-react-components-with-mdx","body":"I can write Markdown alongside my JSX!","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":470,"type":"p","anchor":"embedding-react-components-with-mdx","body":"You can also import your own components defined in other files or third-party components installed via npm! Check out the MDX docs to see what other fancy stuff you can do with MDX.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":471,"type":"h3","anchor":"configuring-plugins","body":"Configuring plugins","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":472,"type":"p","anchor":"configuring-plugins","body":"You can expand the MDX functionalities, using plugins. An MDX plugin is usually a npm package, so you install them like other npm packages using npm. Docusaurus supports both Remark and Rehype plugins that work with MDX.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":473,"type":"p","anchor":"configuring-plugins","body":"First, install your Remark and Rehype plugins.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":474,"type":"p","anchor":"configuring-plugins","body":"For example:","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":475,"type":"p","anchor":"configuring-plugins","body":"Next, import the plugins:","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":476,"type":"p","anchor":"configuring-plugins","body":"Finally, add them to the @docusaurus/preset-classic options in docusaurus.config.js:","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":477,"type":"h3","anchor":"configuring-plugin-options","body":"Configuring plugin options","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":478,"type":"p","anchor":"configuring-plugin-options","body":"Some plugins can be configured and accept their own options. In that case, use the [plugin, pluginOptions] syntax, like so:","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":479,"type":"p","anchor":"configuring-plugin-options","body":"See more information in the MDX documentation.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":480,"type":"h2","anchor":"tabs","body":"Tabs","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":481,"type":"p","anchor":"tabs","body":"To show tabbed content within Markdown files, you can fall back on MDX. Docusaurus provides <Tabs> components out-of-the-box.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":482,"type":"p","anchor":"tabs","body":"will result in","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":483,"type":"h3","anchor":"syncing-tab-choices","body":"Syncing tab choices","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":484,"type":"p","anchor":"syncing-tab-choices","body":"You may want choices of the same kind of tabs to sync with each other. For example, you might want to provide different instructions for users on Windows vs users on macOS, and you want to changing all OS-specific instructions tabs in one click. To achieve that, you can give all related tabs the same groupId prop. Note that doing this will persist the choice in localStorage and all <Tab> instances with the same groupId will update automatically when the value of one of them is changed. Not that groupID are globally-namespaced.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":485,"type":"p","anchor":"syncing-tab-choices","body":"For all tab groups that have the same groupId, the possible values do not need to be the same. If one tab group with chooses an value that does not exist in another tab group with the same groupId, the tab group with the missing value won't change its tab. You can see that from the following example. Try to select Linux, and the above tab groups doesn't change.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":486,"type":"p","anchor":"syncing-tab-choices","body":"Tab choices with different groupIds will not interfere with each other:","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":487,"type":"h2","anchor":"calloutsadmonitions","body":"Callouts/admonitions","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":488,"type":"p","anchor":"calloutsadmonitions","body":"In addition to the basic Markdown syntax, we use remark-admonitions alongside MDX to add support for admonitions. Admonitions are wrapped by a set of 3 colons.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":489,"type":"p","anchor":"calloutsadmonitions","body":"Example:","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":490,"type":"p","anchor":"calloutsadmonitions","body":"The content and title can include markdown.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":491,"type":"p","anchor":"calloutsadmonitions","body":"Heads up! Here's a pro-tip.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":492,"type":"p","anchor":"calloutsadmonitions","body":"Useful information.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":493,"type":"p","anchor":"calloutsadmonitions","body":"Warning! You better pay attention!","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":494,"type":"p","anchor":"calloutsadmonitions","body":"Danger danger, mayday!","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":495,"type":"h3","anchor":"specifying-title","body":"Specifying title","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":496,"type":"p","anchor":"specifying-title","body":"You may also specify an optional title","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":497,"type":"p","anchor":"specifying-title","body":"The content and title can include Markdown.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":498,"type":"h2","anchor":"code-blocks","body":"Code blocks","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":499,"type":"p","anchor":"code-blocks","body":"Code blocks within documentation are super-powered 💪.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":500,"type":"h3","anchor":"code-title","body":"Code title","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":501,"type":"p","anchor":"code-title","body":"You can add a title to the code block by adding title key after the language (leave a space between them).","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":502,"type":"h3","anchor":"syntax-highlighting","body":"Syntax highlighting","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":503,"type":"p","anchor":"syntax-highlighting","body":"Code blocks are text blocks wrapped around by strings of 3 backticks. You may check out this reference for specifications of MDX.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":504,"type":"p","anchor":"syntax-highlighting","body":"Use the matching language meta string for your code block, and Docusaurus will pick up syntax highlighting automatically, powered by Prism React Renderer.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":505,"type":"p","anchor":"syntax-highlighting","body":"By default, the Prism syntax highlighting theme we use is Palenight. You can change this to another theme by passing theme field in prism as themeConfig in your docusaurus.config.js.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":506,"type":"p","anchor":"syntax-highlighting","body":"For example, if you prefer to use the dracula highlighting theme:","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":507,"type":"p","anchor":"syntax-highlighting","body":"By default, Docusaurus comes with this subset of commonly used languages.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":508,"type":"p","anchor":"syntax-highlighting","body":"To add syntax highlighting for any of the other Prism supported languages, define it in an array of additional languages.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":509,"type":"p","anchor":"syntax-highlighting","body":"For example, if you want to add highlighting for the powershell language:","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":510,"type":"p","anchor":"syntax-highlighting","body":"If you want to add highlighting for languages not yet supported by Prism, you can swizzle prism-include-languages:","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":511,"type":"p","anchor":"syntax-highlighting","body":"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:","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":512,"type":"p","anchor":"syntax-highlighting","body":"You can refer to Prism's official language definitions when you are writing your own language definitions.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":513,"type":"h3","anchor":"line-highlighting","body":"Line highlighting","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":514,"type":"p","anchor":"line-highlighting","body":"You can bring emphasis to certain lines of code by specifying line ranges after the language meta string (leave a space after the language).","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":515,"type":"p","anchor":"line-highlighting","body":"To accomplish this, Docusaurus adds the docusaurus-highlight-code-line class to the highlighted lines. You will need to define your own styling for this CSS, possibly in your src/css/custom.css with a custom background color which is dependent on your selected syntax highlighting theme. The color given below works for the default highlighting theme (Palenight), so if you are using another theme, you will have to tweak the color accordingly.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":516,"type":"p","anchor":"line-highlighting","body":"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 on their project details.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":517,"type":"p","anchor":"line-highlighting","body":"You can also use comments with highlight-next-line, highlight-start, and highlight-end to select which lines are highlighted.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":518,"type":"p","anchor":"line-highlighting","body":"Supported commenting syntax:","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":519,"type":"p","anchor":"line-highlighting","body":"If there's a syntax that is not currently supported, we are open to adding them! Pull requests welcome.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":520,"type":"h3","anchor":"interactive-code-editor","body":"Interactive code editor","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":521,"type":"p","anchor":"interactive-code-editor","body":"(Powered by React Live)","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":522,"type":"p","anchor":"interactive-code-editor","body":"You can create an interactive coding editor with the @docusaurus/theme-live-codeblock plugin.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":523,"type":"p","anchor":"interactive-code-editor","body":"First, add the plugin to your package.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":524,"type":"p","anchor":"interactive-code-editor","body":"You will also need to add the plugin to your docusaurus.config.js.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":525,"type":"p","anchor":"interactive-code-editor","body":"To use the plugin, create a code block with live attached to the language meta string.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":526,"type":"p","anchor":"interactive-code-editor","body":"The code block will be rendered as an interactive editor. Changes to the code will reflect on the result panel live.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":527,"type":"h2","anchor":"interactive-code-editor","body":"It is 6:08:30 pm.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":528,"type":"p","anchor":"interactive-code-editor","body":"It is not possible to import components directly from the react-live code editor, you have to define available imports upfront.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":529,"type":"p","anchor":"interactive-code-editor","body":"By default, all React imports are available. If you need more imports available, swizzle the react-live scope:","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":530,"type":"p","anchor":"interactive-code-editor","body":"The ButtonExample component is now available to use:","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":531,"type":"h3","anchor":"multi-language-support-code-blocks","body":"Multi-language support code blocks","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":532,"type":"p","anchor":"multi-language-support-code-blocks","body":"With MDX, you can easily create interactive components within your documentation, for example, to display code in multiple programming languages and switching between them using a tabs component.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":533,"type":"p","anchor":"multi-language-support-code-blocks","body":"Instead of implementing a dedicated component for multi-language support code blocks, we've implemented a generic Tabs component in the classic theme so that you can use it for other non-code scenarios as well.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":534,"type":"p","anchor":"multi-language-support-code-blocks","body":"The following example is how you can have multi-language code tabs in your docs. Note that the empty lines above and below each language block is intentional. This is a current limitation of MDX, you have to leave empty lines around Markdown syntax for the MDX parser to know that it's Markdown syntax and not JSX.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":535,"type":"p","anchor":"multi-language-support-code-blocks","body":"And you will get the following:","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":536,"type":"p","anchor":"multi-language-support-code-blocks","body":"You may want to implement your own <MultiLanguageCode /> abstraction if you find the above approach too verbose. We might just implement one in future for convenience.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":537,"type":"p","anchor":"multi-language-support-code-blocks","body":"If you have multiple of these multi-language code tabs, and you want to sync the selection across the tab instances, refer to the Syncing tab choices section.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":538,"type":"h2","anchor":"assets","body":"Assets","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":539,"type":"p","anchor":"assets","body":"Sometimes you want to link to static assets directly from markdown files, and it is convenient to co-locate the asset next to the markdown file using it.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":540,"type":"p","anchor":"assets","body":"We have setup Webpack loaders to handle most common file types, so that when you import a file, you get its url, and the asset is automatically copied to the output folder.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":541,"type":"p","anchor":"assets","body":"Let's imagine the following file structure:","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":542,"type":"h3","anchor":"image-assets","body":"Image assets","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":543,"type":"p","anchor":"image-assets","body":"You can use images by requiring them and using an image tag through MDX:","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":544,"type":"p","anchor":"image-assets","body":"The ES imports syntax also works:","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":545,"type":"p","anchor":"image-assets","body":"This results in displaying the image:","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":546,"type":"p","anchor":"image-assets","body":"","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":547,"type":"p","anchor":"image-assets","body":"If you are using @docusaurus/plugin-ideal-image, you need to use the dedicated image component, as documented.","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":548,"type":"h3","anchor":"common-assets","body":"Common assets","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":549,"type":"p","anchor":"common-assets","body":"In the same way, you can link to existing assets by requiring them and using the returned url in videos, links etc...","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":550,"type":"h3","anchor":"unknown-assets","body":"Unknown assets","heading":"Markdown Features"},{"pageID":"docs/markdown-features","id":551,"type":"p","anchor":"unknown-assets","body":"This require behavior is not supported for all file extensions, but as an escape hatch you can use the special Webpack syntax to force the file-loader to kick-in:","heading":"Markdown Features"},{"pageID":"docs/migrating-from-v1-to-v2","id":552,"type":"h1","anchor":"project-setup","body":"Migrating from v1 to v2","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":553,"type":"p","anchor":"project-setup","body":"This migration guide is targeted at Docusaurus users without translation and/or versioning features.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":554,"type":"p","anchor":"project-setup","body":"This doc guides you through migrating an existing Docusaurus 1 site to Docusaurus 2.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":555,"type":"p","anchor":"project-setup","body":"Your Docusaurus 1 site should have the following structure:","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":556,"type":"p","anchor":"project-setup","body":"After the migration, your Docusaurus 2 site could look like:","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":557,"type":"p","anchor":"project-setup","body":"You can use the migration command to take care of some of the migration chores.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":558,"type":"h2","anchor":"project-setup","body":"Project setup","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":559,"type":"h3","anchor":"packagejson","body":"package.json","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":560,"type":"p","anchor":"scoped-package-names","body":"In Docusaurus 2, we use scoped package names:","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":561,"type":"p","anchor":"scoped-package-names","body":"This provides a clear distinction between Docusaurus' official packages and community maintained packages. In another words, all Docusaurus' official packages are namespaced under @docusaurus/.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":562,"type":"p","anchor":"scoped-package-names","body":"Meanwhile, the default doc site functionalities provided by Docusaurus 1 are now provided by @docusaurus/preset-classic. Therefore, we need to add this dependency as well:","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":563,"type":"p","anchor":"scoped-package-names","body":"Please use the most recent Docusaurus 2 alpha version, which you can check out here (it's tagged next).","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":564,"type":"p","anchor":"cli-commands","body":"Meanwhile, CLI commands are renamed to docusaurus <command> (instead of docusaurus-command).","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":565,"type":"p","anchor":"cli-commands","body":"The \"scripts\" section of your package.json should be updated as follows:","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":566,"type":"p","anchor":"cli-commands","body":"A typical Docusaurus 2 package.json may look like this:","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":567,"type":"h3","anchor":"update-references-to-the-build-directory","body":"Update references to the build directory","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":568,"type":"p","anchor":"update-references-to-the-build-directory","body":"In Docusaurus 1, all the build artifacts are located within website/build/<PROJECT_NAME>.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":569,"type":"p","anchor":"update-references-to-the-build-directory","body":"In Docusaurus 2, it is now moved to just website/build. Make sure that you update your deployment configuration to read the generated files from the correct build directory.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":570,"type":"p","anchor":"update-references-to-the-build-directory","body":"If you are deploying to GitHub pages, make sure to run yarn deploy instead of yarn publish-gh-pages script.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":571,"type":"h3","anchor":"gitignore","body":".gitignore","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":572,"type":"p","anchor":"gitignore","body":"The .gitignore in your website should contain:","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":573,"type":"h3","anchor":"readme","body":"README","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":574,"type":"p","anchor":"readme","body":"The D1 website may have an existing README file. You can modify it to reflect the D2 changes, or copy the default Docusaurus v2 README.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":575,"type":"h2","anchor":"site-configurations","body":"Site configurations","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":576,"type":"h3","anchor":"docusaurusconfigjs","body":"docusaurus.config.js","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":577,"type":"p","anchor":"docusaurusconfigjs","body":"Rename siteConfig.js to docusaurus.config.js.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":578,"type":"p","anchor":"docusaurusconfigjs","body":"In Docusaurus 2, we split each functionality (blog, docs, pages) into plugins for modularity. Presets are bundles of plugins and for backward compatibility we built a @docusaurus/preset-classic preset which bundles most of the essential plugins present in Docusaurus 1.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":579,"type":"p","anchor":"docusaurusconfigjs","body":"Add the following preset configuration to your docusaurus.config.js.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":580,"type":"p","anchor":"docusaurusconfigjs","body":"We recommend moving the docs folder into the website folder and that is also the default directory structure in v2. Now supports Docusaurus project deployments out-of-the-box if the docs directory is within the website. It is also generally better for the docs to be within the website so that the docs and the rest of the website code are co-located within one website directory.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":581,"type":"p","anchor":"docusaurusconfigjs","body":"If you are migrating your Docusaurus v1 website, and there are pending documentation pull requests, you can temporarily keep the /docs folder to its original place, to avoid producing conflicts.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":582,"type":"p","anchor":"docusaurusconfigjs","body":"Refer to migration guide below for each field in siteConfig.js.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":583,"type":"h3","anchor":"updated-fields","body":"Updated fields","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":584,"type":"p","anchor":"baseurl-tagline-title-url-favicon-organizationname-projectname-githubhost-scripts-stylesheets","body":"No actions needed, these configuration fields were not modified.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":585,"type":"p","anchor":"colors","body":"Deprecated. We wrote a custom CSS framework for Docusaurus 2 called Infima which uses CSS variables for theming. The docs are not quite ready yet and we will update here when it is. To overwrite Infima's CSS variables, create your own CSS file (e.g. ./src/css/custom.css) and import it globally by passing it as an option to @docusaurus/preset-classic:","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":586,"type":"p","anchor":"colors","body":"Infima uses 7 shades of each color.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":587,"type":"p","anchor":"colors","body":"We recommend using ColorBox to find the different shades of colors for your chosen primary color.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":588,"type":"p","anchor":"colors","body":"Alteratively, use the following tool to generate the different shades for your website and copy the variables into src/css/custom.css.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":589,"type":"p","anchor":"primary_color","body":"Primary Color:","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":590,"type":"p","anchor":"primary_color","body":"Replace the variables in src/css/custom.css with these new variables.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":591,"type":"p","anchor":"footericon-copyright-ogimage-twitterimage-docssidenavcollapsible","body":"Site meta info such as assets, SEO, copyright info are now handled by themes. To customize them, use the themeConfig field in your docusaurus.config.js:","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":592,"type":"p","anchor":"headericon-headerlinks","body":"In Docusaurus 1, header icon and header links were root fields in siteConfig:","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":593,"type":"p","anchor":"headericon-headerlinks","body":"Now, these two fields are both handled by the theme:","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":594,"type":"p","anchor":"blogsidebarcount","body":"Deprecated. Pass it as a blog option to @docusaurus/preset-classic instead:","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":595,"type":"p","anchor":"cname","body":"Deprecated. Create a CNAME file in your static folder instead with your custom domain. Files in the static folder will be copied into the root of the build folder during execution of the build command.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":596,"type":"p","anchor":"customdocspath-docsurl-editurl-enableupdateby-enableupdatetime","body":"BREAKING: editUrl should point to (website) docusaurus project instead of docs directory.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":597,"type":"p","anchor":"customdocspath-docsurl-editurl-enableupdateby-enableupdatetime","body":"Deprecated. Pass it as an option to @docusaurus/preset-classic docs instead:","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":598,"type":"h3","anchor":"removed-fields","body":"Removed fields","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":599,"type":"p","anchor":"removed-fields","body":"The following fields are all deprecated, you may remove from your configuration file.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":600,"type":"p","anchor":"removed-fields","body":"We intend to implement many of the deprecated config fields as plugins in future. Help will be appreciated!","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":601,"type":"h2","anchor":"urls","body":"Urls","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":602,"type":"p","anchor":"urls","body":"In v1, all pages were available with or without the .html extension.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":603,"type":"p","anchor":"urls","body":"For example, these 2 pages exist:","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":604,"type":"p","anchor":"urls","body":"If cleanUrl was:","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":605,"type":"p","anchor":"urls","body":"In v2, by default, the canonical page is /installation, and not /installation.html.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":606,"type":"p","anchor":"urls","body":"If you had cleanUrl: false in v1, it's possible that people published links to /installation.html.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":607,"type":"p","anchor":"urls","body":"For SEO reasons, and avoiding breaking links, you should configure server-side redirect rules on your hosting provider.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":608,"type":"p","anchor":"urls","body":"As an escape hatch, you could use @docusaurus/plugin-client-redirects to create client-side redirects from /installation.html to /installation.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":609,"type":"p","anchor":"urls","body":"If you want to keep the .html extension as the canonical url of a page, docs can declare a slug: installation.html frontmatter.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":610,"type":"h2","anchor":"components","body":"Components","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":611,"type":"h3","anchor":"sidebar","body":"Sidebar","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":612,"type":"p","anchor":"sidebar","body":"In previous version, nested sidebar category is not allowed and sidebar category can only contain doc id. However, v2 allows infinite nested sidebar and we have many types of Sidebar Item other than document.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":613,"type":"p","anchor":"sidebar","body":"You'll have to migrate your sidebar if it contains category type. Rename subcategory to category and ids to items.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":614,"type":"h3","anchor":"footer","body":"Footer","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":615,"type":"p","anchor":"footer","body":"website/core/Footer.js is no longer needed. If you want to modify the default footer provided by Docusaurus, swizzle it:","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":616,"type":"p","anchor":"footer","body":"This will copy the current <Footer /> component used by the theme to a src/theme/Footer directory under the root of your site, you may then edit this component for customization.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":617,"type":"p","anchor":"footer","body":"Do not swizzle the Footer just to add the logo on the left. The logo is intentionally removed in v2 and moved to the bottom. Just configure the footer in docusaurus.config.js with themeConfig.footer:","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":618,"type":"h3","anchor":"pages","body":"Pages","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":619,"type":"p","anchor":"pages","body":"Please refer to creating pages to learn how Docusaurus 2 pages work. After reading that, notice that you have to move pages/en files in v1 to src/pages instead.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":620,"type":"p","anchor":"pages","body":"In Docusaurus v1, pages received the siteConfig object as props.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":621,"type":"p","anchor":"pages","body":"In Docusaurus v2, get the siteConfig object from useDocusaurusContext instead.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":622,"type":"p","anchor":"pages","body":"In v2, you have to apply the theme layout around each page. The Layout component takes metadata props (permalink is important, as it defines the canonical url of your page).","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":623,"type":"p","anchor":"pages","body":"CompLibrary is deprecated in v2, so you have to write your own React component or use Infima styles (Docs will be available soon, sorry about that! In the meanwhile, inspect the V2 website or view https://facebookincubator.github.io/infima/ to see what styles are available).","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":624,"type":"p","anchor":"pages","body":"You can migrate CommonJS to ES6 imports/exports.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":625,"type":"p","anchor":"pages","body":"Here's a typical Docusaurus v2 page:","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":626,"type":"p","anchor":"pages","body":"The following code could be helpful for migration of various pages:","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":627,"type":"h2","anchor":"content","body":"Content","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":628,"type":"h3","anchor":"remove-autogenerated_table_of_contents","body":"Remove AUTOGENERATED_TABLE_OF_CONTENTS","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":629,"type":"p","anchor":"remove-autogenerated_table_of_contents","body":"This feature is deprecated. You may read more about it in this issue. If you need the feature, use remark-toc instead and pass it to docs plugin's remarkPlugins option.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":630,"type":"h3","anchor":"update-markdown-syntax-to-be-mdx-compatible","body":"Update Markdown syntax to be MDX-compatible","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":631,"type":"p","anchor":"update-markdown-syntax-to-be-mdx-compatible","body":"In Docusaurus 2, the markdown syntax has been changed to MDX. Hence there might be some broken syntax in the existing docs which you would have to update. A common example is self-closing tags like <img> and <br> which are valid in HTML would have to be explicitly closed now ( <img/> and <br/>). All tags in MDX documents have to be valid JSX.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":632,"type":"p","anchor":"update-markdown-syntax-to-be-mdx-compatible","body":"Frontmatter is parsed by gray-matter. If your frontmatter use special characters like :, you now need to quote it: title: Part 1: my part1 title -> title: Part 1: \"my part1 title\".","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":633,"type":"p","anchor":"update-markdown-syntax-to-be-mdx-compatible","body":"Tips: You might want to use some online tools like HTML to JSX to make the migration easier.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":634,"type":"h3","anchor":"language-specific-code-tabs","body":"Language-specific code tabs","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":635,"type":"p","anchor":"language-specific-code-tabs","body":"Refer to the multi-language support code blocks section.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":636,"type":"h3","anchor":"front-matter","body":"Front matter","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":637,"type":"p","anchor":"front-matter","body":"The Docusaurus front matter fields for the blog have been changed from camelCase to snake_case to be consistent with the docs.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":638,"type":"p","anchor":"front-matter","body":"The fields authorFBID and authorTwitter have been deprecated. They are only used for generating the profile image of the author which can be done via the author_image_url field.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":639,"type":"h2","anchor":"test-your-site","body":"Test your site","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":640,"type":"p","anchor":"test-your-site","body":"After migration, your folder structure should look like this:","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":641,"type":"p","anchor":"test-your-site","body":"Start the development server and fix any errors:","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":642,"type":"h2","anchor":"migration-command","body":"Migration command","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":643,"type":"p","anchor":"migration-command","body":"The migration command automatically migrates your v1 website to a v2 website.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":644,"type":"p","anchor":"migration-command","body":"The migration command migrates:","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":645,"type":"p","anchor":"migration-command","body":"Manual tweaking is still required after using the migration command. You still need to migrate your footer, pages and content.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":646,"type":"p","anchor":"migration-command","body":"To use the migration command, follow these steps:","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":647,"type":"p","anchor":"migration-command","body":"Before using the migration command, ensure that /docs, /blog, /static, sidebars.json, siteConfig.js, package.json follow the structure shown at the start of this page.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":648,"type":"p","anchor":"migration-command","body":"To migrate your v1 website, run the migration command with the appropriate filesystem paths:","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":649,"type":"p","anchor":"options","body":"You can add option flags to the migration command to automatically migrate markdown content and pages to v2. It is likely that you will still need to make some manual changes to achieve your desired result.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":650,"type":"p","anchor":"options","body":"The migration of pages and MDX is still a work in progress.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":651,"type":"p","anchor":"options","body":"We recommend you to try to run the pages without these options, commit, and then try to run the migration again with the --page and --mdx options.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":652,"type":"p","anchor":"options","body":"This way, you'd be able to easily inspect and fix the diff.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":653,"type":"h2","anchor":"example-migration-prs","body":"Example migration PRs","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":654,"type":"p","anchor":"example-migration-prs","body":"You might want to refer to our migration PRs for Create React App and Flux as examples of how a migration for a basic Docusaurus v1 site can be done.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":655,"type":"h2","anchor":"support","body":"Support","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":656,"type":"p","anchor":"support","body":"For any questions, you can ask in the #docusaurus-1-to-2-migration Discord channel. Feel free to tag @yangshun in any migration PRs if you would like us to have a look.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":657,"type":"h2","anchor":"versioned-site","body":"Versioned Site","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":658,"type":"p","anchor":"versioned-site","body":"The versioning feature is a work in progress! Although we've implemented docs versioning since 2.0.0-alpha.37, we'd like to test it out for v2 users first before we recommend v1 users to migrate to v2. There are some changes in how v2 versioning works compared to v1. In the future, we might create a script to migrate your versioned docs easier. However, if you are adventurous enough to manually migrate, feel free to do so. Be warned though, the manual migration requires lot of work.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":659,"type":"p","anchor":"versioned-site","body":"Read up https://v2.docusaurus.io/blog/2018/09/11/Towards-Docusaurus-2#versioning first for problems in v1's approach.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":660,"type":"h3","anchor":"migrate-your-versioned_docs-front-matter","body":"Migrate your versioned_docs front matter","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":661,"type":"p","anchor":"migrate-your-versioned_docs-front-matter","body":"Unlike v1, The markdown header for each versioned doc is no longer altered by using version-${version}-${original_id} as the value for the actual id field. See scenario below for better explanation.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":662,"type":"p","anchor":"migrate-your-versioned_docs-front-matter","body":"For example, if you have a docs/hello.md.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":663,"type":"p","anchor":"migrate-your-versioned_docs-front-matter","body":"When you cut a new version 1.0.0, in Docusaurus v1, website/versioned_docs/version-1.0.0/hello.md looks like this:","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":664,"type":"p","anchor":"migrate-your-versioned_docs-front-matter","body":"In comparison, Docusaurus 2 website/versioned_docs/version-1.0.0/hello.md looks like this (exactly same as original)","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":665,"type":"p","anchor":"migrate-your-versioned_docs-front-matter","body":"Since we're going for snapshot and allow people to move (and edit) docs easily inside version. The id frontmatter is no longer altered and will remain the same. Internally, it is set as version-${version}/${id}.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":666,"type":"p","anchor":"migrate-your-versioned_docs-front-matter","body":"Essentially, here are the necessary changes in each versioned_docs file:","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":667,"type":"h3","anchor":"migrate-your-versioned_sidebars","body":"Migrate your versioned_sidebars","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":668,"type":"p","anchor":"migrate-your-versioned_sidebars","body":"Because in v1 there is a good chance someone created a new file with front matter id \"version-${version}-${id}\" that can conflict with versioned_docs id.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":669,"type":"p","anchor":"migrate-your-versioned_sidebars","body":"For example, Docusaurus 1 can't differentiate docs/xxx.md","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":670,"type":"p","anchor":"migrate-your-versioned_sidebars","body":"vs website/versioned_docs/version-1.0.0/hello.md","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":671,"type":"p","anchor":"migrate-your-versioned_sidebars","body":"Since we don't allow / in v1 & v2 for frontmatter, conflicts are less likely to occur.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":672,"type":"p","anchor":"migrate-your-versioned_sidebars","body":"So v1 users need to migrate their versioned_sidebars file","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":673,"type":"p","anchor":"migrate-your-versioned_sidebars","body":"Example versioned_sidebars/version-1.0.0-sidebars.json:","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":674,"type":"h3","anchor":"populate-your-versioned_sidebars-and-versioned_docs","body":"Populate your versioned_sidebars and versioned_docs","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":675,"type":"p","anchor":"populate-your-versioned_sidebars-and-versioned_docs","body":"In v2, we use snapshot approach for documentation versioning. Every versioned docs does not depends on other version. It is possible to have foo.md in version-1.0.0 but it doesn't exist in version-1.2.0. This is not possible in previous version due to Docusaurus v1 fallback functionality (https://docusaurus.io/docs/en/versioning#fallback-functionality).","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":676,"type":"p","anchor":"populate-your-versioned_sidebars-and-versioned_docs","body":"For example, if your versions.json looks like this in v1","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":677,"type":"p","anchor":"populate-your-versioned_sidebars-and-versioned_docs","body":"Docusaurus v1 creates versioned docs if and only if the doc content is different. Your docs structure might look like this if the only doc changed from v1.0.0 to v1.1.0 is hello.md.","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":678,"type":"p","anchor":"populate-your-versioned_sidebars-and-versioned_docs","body":"In v2, you have to populate the missing versioned_docs and versioned_sidebars (with the right frontmatter and id reference too).","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":679,"type":"h3","anchor":"convert-style-attributes-to-style-objects-in-mdx","body":"Convert style attributes to style objects in MDX","heading":"Migrating from v1 to v2"},{"pageID":"docs/migrating-from-v1-to-v2","id":680,"type":"p","anchor":"convert-style-attributes-to-style-objects-in-mdx","body":"Docusaurus 2 uses JSX for doc files. If you have any style attributes in your Docusaurus 1 docs, convert them to style objects, like this:","heading":"Migrating from v1 to v2"},{"pageID":"docs/next","id":681,"type":"h1","anchor":"disclaimer","body":"Introduction","heading":"Introduction"},{"pageID":"docs/next","id":682,"type":"h2","anchor":"disclaimer","body":"Disclaimer","heading":"Introduction"},{"pageID":"docs/next","id":683,"type":"p","anchor":"disclaimer","body":"It has been a year since we made the first alpha release of Docusaurus 2 and things have been pretty stable since then. Many of Facebook's new open source websites are using Docusaurus 2 now. At this point, we highly encourage you to use Docusaurus 2 over Docusaurus 1 for your new websites. For feedback and questions, chat with us on Discord 😉","heading":"Introduction"},{"pageID":"docs/next","id":684,"type":"p","anchor":"disclaimer","body":"You should use this if:","heading":"Introduction"},{"pageID":"docs/next","id":685,"type":"p","anchor":"disclaimer","body":"Do not use this if:","heading":"Introduction"},{"pageID":"docs/next","id":686,"type":"h2","anchor":"a-better-docusaurus-is-coming-to-town","body":"A better Docusaurus is coming to town","heading":"Introduction"},{"pageID":"docs/next","id":687,"type":"p","anchor":"a-better-docusaurus-is-coming-to-town","body":"Docusaurus 1 used to be a pure documentation site generator. In Docusaurus 2, we rebuilt it from the ground up, allowing for more customizability but preserved the best parts of Docusaurus 1 - easy to get started, versioned docs, and i18n (coming soon).","heading":"Introduction"},{"pageID":"docs/next","id":688,"type":"p","anchor":"a-better-docusaurus-is-coming-to-town","body":"Beyond that, Docusaurus 2 is a performant static site generator and can be used to create common content-driven websites (e.g. Documentation, Blogs, Product Landing and Marketing Pages, etc) extremely quickly.","heading":"Introduction"},{"pageID":"docs/next","id":689,"type":"p","anchor":"a-better-docusaurus-is-coming-to-town","body":"While our main focus will still be helping you get your documentations right and well, it is possible to build this any kind of website using Docusaurus 2 as it is just a React application. Docusaurus can now be used to build any website, not just documentation websites.","heading":"Introduction"},{"pageID":"docs/next","id":690,"type":"h2","anchor":"features","body":"Features","heading":"Introduction"},{"pageID":"docs/next","id":691,"type":"p","anchor":"features","body":"Docusaurus is built with high attention to your experience building your site and maintaining it with your collaborators and contributors.","heading":"Introduction"},{"pageID":"docs/next","id":692,"type":"p","anchor":"features","body":"Our shared goal — to help your users find what they need fast, and understand your products better. With the experience of Docusaurus 1, we share with you our best practices to help you build your doc site right and well.","heading":"Introduction"},{"pageID":"docs/next","id":693,"type":"p","anchor":"features","body":"Docusaurus 2 is born to be compassionately accessible to all your users, and lightning fast.","heading":"Introduction"},{"pageID":"docs/next","id":694,"type":"h2","anchor":"comparison-with-other-tools","body":"Comparison with other tools","heading":"Introduction"},{"pageID":"docs/next","id":695,"type":"p","anchor":"comparison-with-other-tools","body":"Across all static site generators, Docusaurus has a unique focus on doc sites and has out-of-the-box structure you need.","heading":"Introduction"},{"pageID":"docs/next","id":696,"type":"p","anchor":"comparison-with-other-tools","body":"We've also studied other main static site generators and would like to share our insights on the comparison, hopefully to help you navigate through the prismatic choices out there.","heading":"Introduction"},{"pageID":"docs/next","id":697,"type":"h3","anchor":"gatsby","body":"Gatsby","heading":"Introduction"},{"pageID":"docs/next","id":698,"type":"p","anchor":"gatsby","body":"Gatsby is packed with a lot of features, has a rich ecosystem of plugins and is capable of doing everything that Docusaurus does. Naturally, that comes at a cost of a higher learning curve. Gatsby does many things well and is suitable for building many types of websites. On the other hand, Docusaurus tries to do one thing super well - be the best tool for writing and publishing content.","heading":"Introduction"},{"pageID":"docs/next","id":699,"type":"p","anchor":"gatsby","body":"GraphQL is also pretty core to Gatsby, although you don't necessarily need GraphQL to build a Gatsby site. In most cases when building static websites, you won't need the flexibility that GraphQL provides.","heading":"Introduction"},{"pageID":"docs/next","id":700,"type":"p","anchor":"gatsby","body":"Many aspects of Docusaurus 2 were inspired by the best things about Gatsby and it's a great alternative.","heading":"Introduction"},{"pageID":"docs/next","id":701,"type":"h3","anchor":"gitbook","body":"GitBook","heading":"Introduction"},{"pageID":"docs/next","id":702,"type":"p","anchor":"gitbook","body":"GitBook has very clean design and has been used by many open source projects. With its focus shifting towards a commercial product rather than an open-source tool, many of its requirements no longer fit the needs as an open source project's documentation site. As a result, many have turned to other products. You may read about Redux's switch to Docusaurus here.","heading":"Introduction"},{"pageID":"docs/next","id":703,"type":"p","anchor":"gitbook","body":"Currently, GitBook is only free for open-source and non-profit teams. Docusaurus is free for everyone.","heading":"Introduction"},{"pageID":"docs/next","id":704,"type":"h3","anchor":"jekyll","body":"Jekyll","heading":"Introduction"},{"pageID":"docs/next","id":705,"type":"p","anchor":"jekyll","body":"Jekyll is one of the most mature static site generators around and has been a great tool to use — in fact, before Docusaurus, most of Facebook's Open Source websites are/were built on Jekyll! It is extremely simple to get started. We want to bring a similar developer experience as building a static site with Jekyll.","heading":"Introduction"},{"pageID":"docs/next","id":706,"type":"p","anchor":"jekyll","body":"In comparison with statically generated HTML and interactivity added using <script /> tags, Docusaurus sites are React apps. Using modern JavaScript ecosystem tooling, we hope to set new standards on doc sites performance, asset build pipeline and optimizations, and ease to setup.","heading":"Introduction"},{"pageID":"docs/next","id":707,"type":"h3","anchor":"vuepress","body":"VuePress","heading":"Introduction"},{"pageID":"docs/next","id":708,"type":"p","anchor":"vuepress","body":"VuePress has many similarities with Docusaurus - both focus heavily on content-centric website and provides tailored documentation features out of the box. However, VuePress is powered by Vue, while Docusaurus is powered by React. If you want a Vue-based solution, VuePress would be a decent choice.","heading":"Introduction"},{"pageID":"docs/next","id":709,"type":"h2","anchor":"staying-informed","body":"Staying informed","heading":"Introduction"},{"pageID":"docs/next","id":710,"type":"h2","anchor":"something-missing","body":"Something missing?","heading":"Introduction"},{"pageID":"docs/next","id":711,"type":"p","anchor":"something-missing","body":"If you find issues with the documentation or have suggestions on how to improve the documentation or the project in general, please file an issue for us, or send a tweet mentioning the @docusaurus Twitter account.","heading":"Introduction"},{"pageID":"docs/next","id":712,"type":"p","anchor":"something-missing","body":"For new feature requests, you can create a post on our Canny board, which is a handy tool for roadmapping and allows for sorting by upvotes, which gives the core team a better indicator of what features are in high demand, as compared to GitHub issues which are harder to triage. Refrain from making a Pull Request for new features (especially large ones) as someone might already be working on it or will be part of our roadmap. Talk to us first!","heading":"Introduction"},{"pageID":"docs/presets","id":713,"type":"h1","anchor":"using-presets","body":"Presets","heading":"Presets"},{"pageID":"docs/presets","id":714,"type":"p","anchor":"using-presets","body":"Presets are collections of plugins and themes.","heading":"Presets"},{"pageID":"docs/presets","id":715,"type":"h2","anchor":"using-presets","body":"Using presets","heading":"Presets"},{"pageID":"docs/presets","id":716,"type":"p","anchor":"using-presets","body":"A preset is usually a npm package, so you install them like other npm packages using npm.","heading":"Presets"},{"pageID":"docs/presets","id":717,"type":"p","anchor":"using-presets","body":"Then, add it in your site's docusaurus.config.js's presets option:","heading":"Presets"},{"pageID":"docs/presets","id":718,"type":"p","anchor":"using-presets","body":"To load presets from your local directory, specify how to resolve them:","heading":"Presets"},{"pageID":"docs/presets","id":719,"type":"h2","anchor":"presets---themes-and-plugins","body":"Presets -> themes and plugins","heading":"Presets"},{"pageID":"docs/presets","id":720,"type":"p","anchor":"presets---themes-and-plugins","body":"Presets in some way are a shorthand function to add plugins and themes to your docusaurus config. For example, you can specify a preset that includes the following themes and plugins,","heading":"Presets"},{"pageID":"docs/presets","id":721,"type":"p","anchor":"presets---themes-and-plugins","body":"then in your Docusaurus config, you may configure the preset instead:","heading":"Presets"},{"pageID":"docs/presets","id":722,"type":"p","anchor":"presets---themes-and-plugins","body":"This is equivalent of doing:","heading":"Presets"},{"pageID":"docs/presets","id":723,"type":"p","anchor":"presets---themes-and-plugins","body":"This is especially useful when some plugins and themes are intended to be used together.","heading":"Presets"},{"pageID":"docs/presets","id":724,"type":"h2","anchor":"official-presets","body":"Official presets","heading":"Presets"},{"pageID":"docs/presets","id":725,"type":"h3","anchor":"docusauruspreset-classic","body":"@docusaurus/preset-classic","heading":"Presets"},{"pageID":"docs/presets","id":726,"type":"p","anchor":"docusauruspreset-classic","body":"The classic preset that is usually shipped by default to new docusaurus website. It is a set of plugins and themes.","heading":"Presets"},{"pageID":"docs/presets","id":727,"type":"p","anchor":"docusauruspreset-classic","body":"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:","heading":"Presets"},{"pageID":"docs/presets","id":728,"type":"p","anchor":"docusauruspreset-classic","body":"In addition to these plugins and themes, @docusaurus/theme-classic adds remark-admonitions as a remark plugin to @docusaurus/plugin-content-blog and @docusaurus/plugin-content-docs.","heading":"Presets"},{"pageID":"docs/presets","id":729,"type":"p","anchor":"docusauruspreset-classic","body":"The admonitions key will be passed as the options to remark-admonitions. Passing false will prevent the plugin from being added to MDX.","heading":"Presets"},{"pageID":"docs/resources","id":730,"type":"h1","anchor":"videos","body":"Awesome Resources","heading":"Awesome Resources"},{"pageID":"docs/resources","id":731,"type":"p","anchor":"videos","body":"A curated list of interesting Docusaurus community projects.","heading":"Awesome Resources"},{"pageID":"docs/resources","id":732,"type":"h2","anchor":"videos","body":"Videos","heading":"Awesome Resources"},{"pageID":"docs/resources","id":733,"type":"h2","anchor":"articles","body":"Articles","heading":"Awesome Resources"},{"pageID":"docs/resources","id":734,"type":"h2","anchor":"showcase","body":"Showcase","heading":"Awesome Resources"},{"pageID":"docs/resources","id":735,"type":"p","anchor":"showcase","body":"See the showcase.","heading":"Awesome Resources"},{"pageID":"docs/resources","id":736,"type":"h2","anchor":"official-plugins","body":"Official plugins","heading":"Awesome Resources"},{"pageID":"docs/resources","id":737,"type":"h2","anchor":"community-plugins","body":"Community plugins","heading":"Awesome Resources"},{"pageID":"docs/resources","id":738,"type":"h2","anchor":"enterprise-usage","body":"Enterprise usage","heading":"Awesome Resources"},{"pageID":"docs/search","id":739,"type":"h1","anchor":"using-algolia-docsearch","body":"Search","heading":"Search"},{"pageID":"docs/search","id":740,"type":"p","anchor":"using-algolia-docsearch","body":"Docusaurus' own @docusaurus/preset-classic supports a search integration.","heading":"Search"},{"pageID":"docs/search","id":741,"type":"p","anchor":"using-algolia-docsearch","body":"There are two main options, you can use Algolia DocSearch or bring in your own SearchBar component.","heading":"Search"},{"pageID":"docs/search","id":742,"type":"h2","anchor":"using-algolia-docsearch","body":"Using Algolia DocSearch","heading":"Search"},{"pageID":"docs/search","id":743,"type":"p","anchor":"using-algolia-docsearch","body":"Algolia DocSearch works by crawling the content of your website every 24 hours and putting all the content in an Algolia index. This content is then queried directly from your front-end using the Algolia API. Note that your website needs to be publicly available for this to work (i.e., not behind a firewall). The service is free.","heading":"Search"},{"pageID":"docs/search","id":744,"type":"h3","anchor":"connecting-algolia","body":"Connecting Algolia","heading":"Search"},{"pageID":"docs/search","id":745,"type":"p","anchor":"connecting-algolia","body":"To connect your docs with Algolia, add an algolia field in your themeConfig. Apply for DocSearch to get your Algolia index and API key.","heading":"Search"},{"pageID":"docs/search","id":746,"type":"p","anchor":"connecting-algolia","body":"The searchParameters option used to be named algoliaOptions in Docusaurus v1.","heading":"Search"},{"pageID":"docs/search","id":747,"type":"h3","anchor":"styling-your-algolia-search","body":"Styling your Algolia search","heading":"Search"},{"pageID":"docs/search","id":748,"type":"p","anchor":"styling-your-algolia-search","body":"By default, DocSearch comes with a fine-tuned theme that was designed for accessibility, making sure that colors and contrasts respect standards.","heading":"Search"},{"pageID":"docs/search","id":749,"type":"p","anchor":"styling-your-algolia-search","body":"Still, you can reuse the Infima CSS variables from Docusaurus to style DocSearch by editing the /src/css/custom.css file.","heading":"Search"},{"pageID":"docs/search","id":750,"type":"h3","anchor":"customizing-the-algolia-search-behavior","body":"Customizing the Algolia search behavior","heading":"Search"},{"pageID":"docs/search","id":751,"type":"p","anchor":"customizing-the-algolia-search-behavior","body":"Algolia DocSearch supports a list of options that you can pass to the algolia field in the docusaurus.config.js file.","heading":"Search"},{"pageID":"docs/search","id":752,"type":"h3","anchor":"editing-the-algolia-search-component","body":"Editing the Algolia search component","heading":"Search"},{"pageID":"docs/search","id":753,"type":"p","anchor":"editing-the-algolia-search-component","body":"If you prefer to edit the Algolia search React component, swizzle the SearchBar component in @docusaurus/theme-search-algolia:","heading":"Search"},{"pageID":"docs/search","id":754,"type":"h2","anchor":"using-your-own-search","body":"Using your own search","heading":"Search"},{"pageID":"docs/search","id":755,"type":"p","anchor":"using-your-own-search","body":"To use your own search, swizzle the SearchBar component in @docusaurus/theme-classic","heading":"Search"},{"pageID":"docs/search","id":756,"type":"p","anchor":"using-your-own-search","body":"This will create a src/themes/SearchBar file in your project folder. Restart your dev server and edit the component, you will see that Docusaurus uses your own SearchBar component now.","heading":"Search"},{"pageID":"docs/search","id":757,"type":"p","anchor":"using-your-own-search","body":"Notes: You can alternatively swizzle from Algolia SearchBar and create your own search component from there.","heading":"Search"},{"pageID":"docs/static-assets","id":758,"type":"h1","anchor":"referencing-your-static-asset","body":"Static Assets","heading":"Static Assets"},{"pageID":"docs/static-assets","id":759,"type":"p","anchor":"referencing-your-static-asset","body":"In general, every website needs assets: images, stylesheets, favicons and etc. In such cases, you can create a directory named static at the root of your project. Every file you put into that directory will be copied into the the root of the generated build folder with the directory hierarchy preserved. E.g. if you add a file named sun.jpg to the static folder, it’ll be copied to build/sun.jpg.","heading":"Static Assets"},{"pageID":"docs/static-assets","id":760,"type":"p","anchor":"referencing-your-static-asset","body":"This means that if the site's baseUrl is /, an image in /static/img/docusaurus_keytar.svg is available at /img/docusaurus_keytar.svg.","heading":"Static Assets"},{"pageID":"docs/static-assets","id":761,"type":"h2","anchor":"referencing-your-static-asset","body":"Referencing your static asset","heading":"Static Assets"},{"pageID":"docs/static-assets","id":762,"type":"p","anchor":"referencing-your-static-asset","body":"You can reference assets from the static folder in your code. You could use hardcoded absolute paths, i.e. starting with a slash /, but remember to include the baseUrl if it is not /. However, this will break if you change your baseUrl in the config.","heading":"Static Assets"},{"pageID":"docs/static-assets","id":763,"type":"p","anchor":"referencing-your-static-asset","body":"A better way would be to use the useBaseUrl utility function which appends the baseUrl to paths for you.","heading":"Static Assets"},{"pageID":"docs/static-assets","id":764,"type":"h3","anchor":"jsx-example","body":"JSX example","heading":"Static Assets"},{"pageID":"docs/static-assets","id":765,"type":"p","anchor":"jsx-example","body":"You can also import SVG images, which will be transformed into React components.","heading":"Static Assets"},{"pageID":"docs/static-assets","id":766,"type":"h3","anchor":"markdown-example","body":"Markdown example","heading":"Static Assets"},{"pageID":"docs/static-assets","id":767,"type":"p","anchor":"markdown-example","body":"Thanks to MDX, you can also use useBaseUrl utility function in Markdown files! You'd have to use <img> tags instead of the Markdown image syntax though. The syntax is exactly the same as in JSX.","heading":"Static Assets"},{"pageID":"docs/static-assets","id":768,"type":"p","anchor":"markdown-example","body":"You could also just use Markdown image syntax, but you would have to manually maintain the image paths yourself and isn't recommended.","heading":"Static Assets"},{"pageID":"docs/static-assets","id":769,"type":"h3","anchor":"caveats","body":"Caveats","heading":"Static Assets"},{"pageID":"docs/static-assets","id":770,"type":"p","anchor":"caveats","body":"Keep in mind that:","heading":"Static Assets"},{"pageID":"docs/styling-layout","id":771,"type":"h1","anchor":"traditional-css","body":"Styling and Layout","heading":"Styling and Layout"},{"pageID":"docs/styling-layout","id":772,"type":"h2","anchor":"traditional-css","body":"Traditional CSS","heading":"Styling and Layout"},{"pageID":"docs/styling-layout","id":773,"type":"p","anchor":"traditional-css","body":"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.","heading":"Styling and Layout"},{"pageID":"docs/styling-layout","id":774,"type":"p","anchor":"traditional-css","body":"Any CSS you write within that file will be available globally and can be referenced directly using string literals. This is the most traditional approach to writing CSS and is fine for small websites that do not have much customization.","heading":"Styling and Layout"},{"pageID":"docs/styling-layout","id":775,"type":"h2","anchor":"styling-your-site-with-infima","body":"Styling your site with Infima","heading":"Styling and Layout"},{"pageID":"docs/styling-layout","id":776,"type":"p","anchor":"styling-your-site-with-infima","body":"@docusaurus/preset-classic uses 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.","heading":"Styling and Layout"},{"pageID":"docs/styling-layout","id":777,"type":"p","anchor":"styling-your-site-with-infima","body":"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.","heading":"Styling and Layout"},{"pageID":"docs/styling-layout","id":778,"type":"p","anchor":"styling-your-site-with-infima","body":"Infima uses 7 shades of each color. We recommend using ColorBox to find the different shades of colors for your chosen primary color.","heading":"Styling and Layout"},{"pageID":"docs/styling-layout","id":779,"type":"p","anchor":"styling-your-site-with-infima","body":"Alternatively, use the following tool to generate the different shades for your website and copy the variables into /src/css/custom.css.","heading":"Styling and Layout"},{"pageID":"docs/styling-layout","id":780,"type":"p","anchor":"primary_color","body":"Primary Color:","heading":"Styling and Layout"},{"pageID":"docs/styling-layout","id":781,"type":"p","anchor":"primary_color","body":"Replace the variables in src/css/custom.css with these new variables.","heading":"Styling and Layout"},{"pageID":"docs/styling-layout","id":782,"type":"h2","anchor":"styling-approaches","body":"Styling approaches","heading":"Styling and Layout"},{"pageID":"docs/styling-layout","id":783,"type":"p","anchor":"styling-approaches","body":"A Docusaurus site is a single-page React application. You can style it the way you style React apps.","heading":"Styling and Layout"},{"pageID":"docs/styling-layout","id":784,"type":"p","anchor":"styling-approaches","body":"There are a few approaches/frameworks which will work, depending on your preferences and the type of website you are trying to build. Websites that are highly interactive and behave more like web apps will benefit from a more modern styling approaches that co-locate styles with the components. Component styling can also be particularly useful when you wish to customize or swizzle a component.","heading":"Styling and Layout"},{"pageID":"docs/styling-layout","id":785,"type":"h3","anchor":"global-styles","body":"Global styles","heading":"Styling and Layout"},{"pageID":"docs/styling-layout","id":786,"type":"p","anchor":"global-styles","body":"This is the most traditional way of styling that most developers (including non-front end developers) would be familiar with.","heading":"Styling and Layout"},{"pageID":"docs/styling-layout","id":787,"type":"p","anchor":"global-styles","body":"Assuming you are using @docusaurus/preset-classic and /src/css/custom.css was passed in to the preset config, styles inside that file would be available globally.","heading":"Styling and Layout"},{"pageID":"docs/styling-layout","id":788,"type":"h3","anchor":"css-modules","body":"CSS modules","heading":"Styling and Layout"},{"pageID":"docs/styling-layout","id":789,"type":"p","anchor":"css-modules","body":"To style your components using CSS Modules, name your stylesheet files with the .module.css suffix (e.g. welcome.module.css). webpack will load such CSS files as CSS modules and you have to reference the class names from the imported CSS module (as opposed to using plain strings). This is similar to the convention used in Create React App.","heading":"Styling and Layout"},{"pageID":"docs/styling-layout","id":790,"type":"p","anchor":"css-modules","body":"The class names which will be processed by webpack into a globally unique class name during build.","heading":"Styling and Layout"},{"pageID":"docs/styling-layout","id":791,"type":"h3","anchor":"css-in-js","body":"CSS-in-JS","heading":"Styling and Layout"},{"pageID":"docs/styling-layout","id":792,"type":"p","anchor":"css-in-js","body":"This section is a work in progress. Welcoming PRs.","heading":"Styling and Layout"},{"pageID":"docs/styling-layout","id":793,"type":"h3","anchor":"sassscss","body":"Sass/SCSS","heading":"Styling and Layout"},{"pageID":"docs/styling-layout","id":794,"type":"p","anchor":"sassscss","body":"To use Sass/SCSS as your CSS preprocessor, install the unofficial Docusaurus 2 plugin docusaurus-plugin-sass. This plugin works for both global styles and the CSS modules approach:","heading":"Styling and Layout"},{"pageID":"docs/styling-layout","id":795,"type":"p","anchor":"global-styles-using-sassscss","body":"You can now set the customCss property of @docusaurus/preset-classic to point to your Sass/SCSS file:","heading":"Styling and Layout"},{"pageID":"docs/styling-layout","id":796,"type":"p","anchor":"modules-using-sassscss","body":"Name your stylesheet files with the .module.scss suffix (e.g. welcome.module.scss) instead of .css. Webpack will use sass-loader to preprocess your stylesheets and load them as CSS modules.","heading":"Styling and Layout"},{"pageID":"docs/support","id":797,"type":"h1","anchor":"stack-overflow","body":"Support","heading":"Support"},{"pageID":"docs/support","id":798,"type":"p","anchor":"stack-overflow","body":"Docusaurus has a community of thousands of developers.","heading":"Support"},{"pageID":"docs/support","id":799,"type":"p","anchor":"stack-overflow","body":"On this page we've listed some Docusaurus-related communities that you can be a part of; see the other pages in this section for additional online and in-person learning materials.","heading":"Support"},{"pageID":"docs/support","id":800,"type":"p","anchor":"stack-overflow","body":"Before participating in Docusaurus' communities, please read our Code of Conduct. We have adopted the Contributor Covenant and we expect that all community members adhere to the guidelines within.","heading":"Support"},{"pageID":"docs/support","id":801,"type":"h2","anchor":"stack-overflow","body":"Stack Overflow","heading":"Support"},{"pageID":"docs/support","id":802,"type":"p","anchor":"stack-overflow","body":"Stack Overflow is a popular forum to ask code-level questions or if you're stuck with a specific error. Read through the existing questions tagged with docusaurus or ask your own!","heading":"Support"},{"pageID":"docs/support","id":803,"type":"h2","anchor":"discussion-forums","body":"Discussion forums","heading":"Support"},{"pageID":"docs/support","id":804,"type":"p","anchor":"discussion-forums","body":"There are many online forums which are a great place for discussion about best practices and application architecture as well as the future of Docusaurus. If you have an answerable code-level question, Stack Overflow is usually a better fit.","heading":"Support"},{"pageID":"docs/support","id":805,"type":"h2","anchor":"feature-requests","body":"Feature requests","heading":"Support"},{"pageID":"docs/support","id":806,"type":"p","anchor":"feature-requests","body":"For new feature requests, you can create a post on our Canny board, which is a handy tool for roadmapping and allows for sorting by upvotes, which gives the core team a better indicator of what features are in high demand, as compared to GitHub issues which are harder to triage. Refrain from making a Pull Request for new features (especially large ones) as someone might already be working on it or will be part of our roadmap. Talk to us first!","heading":"Support"},{"pageID":"docs/support","id":807,"type":"h2","anchor":"news","body":"News","heading":"Support"},{"pageID":"docs/support","id":808,"type":"p","anchor":"news","body":"For the latest news about Docusaurus, follow @docusaurus on Twitter and the official Docusaurus blog on this website.","heading":"Support"},{"pageID":"docs/team","id":809,"type":"h1","anchor":"active-team","body":"Team","heading":"Team"},{"pageID":"docs/team","id":810,"type":"h2","anchor":"active-team","body":"Active Team","heading":"Team"},{"pageID":"docs/team","id":811,"type":"h3","anchor":"active-team","body":"Alexey Pyltsyn","heading":"Team"},{"pageID":"docs/team","id":812,"type":"h3","anchor":"active-team","body":"Fanny Vieira","heading":"Team"},{"pageID":"docs/team","id":813,"type":"h3","anchor":"active-team","body":"Joel Marcey","heading":"Team"},{"pageID":"docs/team","id":814,"type":"h3","anchor":"active-team","body":"Yangshun Tay","heading":"Team"},{"pageID":"docs/team","id":815,"type":"h2","anchor":"honorary-alumni","body":"Honorary Alumni","heading":"Team"},{"pageID":"docs/team","id":816,"type":"h3","anchor":"honorary-alumni","body":"Endilie Yacop Sucipto","heading":"Team"},{"pageID":"docs/team","id":817,"type":"h3","anchor":"honorary-alumni","body":"Wei Gao","heading":"Team"},{"pageID":"docs/team","id":818,"type":"h2","anchor":"acknowledgements","body":"Acknowledgements","heading":"Team"},{"pageID":"docs/team","id":819,"type":"p","anchor":"acknowledgements","body":"Docusaurus was originally created by Joel Marcey. Today, Docusaurus has a few hundred open source contributors. We’d like to recognize a few people who have made significant contributions to Docusaurus and its documentation in the past and have helped maintain them over the years:","heading":"Team"},{"pageID":"docs/theme-classic","id":820,"type":"h1","anchor":"common","body":"@docusaurus/theme-classic","heading":"@docusaurus/theme-classic"},{"pageID":"docs/theme-classic","id":821,"type":"p","anchor":"common","body":"This section is a work in progress.","heading":"@docusaurus/theme-classic"},{"pageID":"docs/theme-classic","id":822,"type":"h2","anchor":"common","body":"Common","heading":"@docusaurus/theme-classic"},{"pageID":"docs/theme-classic","id":823,"type":"h3","anchor":"color-mode---dark-mode","body":"Color mode - dark mode","heading":"@docusaurus/theme-classic"},{"pageID":"docs/theme-classic","id":824,"type":"p","anchor":"color-mode---dark-mode","body":"The classic theme provides by default light and dark mode support, with a navbar switch for the user.","heading":"@docusaurus/theme-classic"},{"pageID":"docs/theme-classic","id":825,"type":"p","anchor":"color-mode---dark-mode","body":"It is possible to customize the color mode support with the following configuration:","heading":"@docusaurus/theme-classic"},{"pageID":"docs/theme-classic","id":826,"type":"p","anchor":"color-mode---dark-mode","body":"With respectPrefersColorScheme: true, the defaultMode is overridden by user system preferences.","heading":"@docusaurus/theme-classic"},{"pageID":"docs/theme-classic","id":827,"type":"p","anchor":"color-mode---dark-mode","body":"If you only want to support one color mode, you likely want to ignore user system preferences.","heading":"@docusaurus/theme-classic"},{"pageID":"docs/theme-classic","id":828,"type":"h3","anchor":"meta-image","body":"Meta image","heading":"@docusaurus/theme-classic"},{"pageID":"docs/theme-classic","id":829,"type":"p","anchor":"meta-image","body":"You can configure a default image that will be used for your meta tag, in particular og:image and twitter:image.","heading":"@docusaurus/theme-classic"},{"pageID":"docs/theme-classic","id":830,"type":"h3","anchor":"announcement-bar","body":"Announcement bar","heading":"@docusaurus/theme-classic"},{"pageID":"docs/theme-classic","id":831,"type":"p","anchor":"announcement-bar","body":"Sometimes you want to announce something in your website. Just for such a case, you can add an announcement bar. This is a non-fixed and dismissable panel above the navbar.","heading":"@docusaurus/theme-classic"},{"pageID":"docs/theme-classic","id":832,"type":"h2","anchor":"hooks","body":"Hooks","heading":"@docusaurus/theme-classic"},{"pageID":"docs/theme-classic","id":833,"type":"h3","anchor":"usethemecontext","body":"useThemeContext","heading":"@docusaurus/theme-classic"},{"pageID":"docs/theme-classic","id":834,"type":"p","anchor":"usethemecontext","body":"React hook to access theme context. This context contains functions for setting light and dark mode and boolean property, indicating which mode is currently in use.","heading":"@docusaurus/theme-classic"},{"pageID":"docs/theme-classic","id":835,"type":"p","anchor":"usethemecontext","body":"Usage example:","heading":"@docusaurus/theme-classic"},{"pageID":"docs/theme-classic","id":836,"type":"p","anchor":"usethemecontext","body":"The component calling useThemeContext must be a child of the Layout component.","heading":"@docusaurus/theme-classic"},{"pageID":"docs/theme-classic","id":837,"type":"h2","anchor":"navbar","body":"Navbar","heading":"@docusaurus/theme-classic"},{"pageID":"docs/theme-classic","id":838,"type":"h3","anchor":"navbar-title--logo","body":"Navbar title & logo","heading":"@docusaurus/theme-classic"},{"pageID":"docs/theme-classic","id":839,"type":"p","anchor":"navbar-title--logo","body":"You can add a logo and title to the navbar via themeConfig.navbar. Logo can be placed in static folder. Logo URL is set to base URL of your site by default. Although you can specify your own URL for the logo, if it is an external link, it will open in a new tab. In addition, you can override a value for the target attribute of logo link, it can come in handy if you are hosting docs website in a subdirectory of your main website, and in which case you probably do not need a link in the logo to the main website will open in a new tab.","heading":"@docusaurus/theme-classic"},{"pageID":"docs/theme-classic","id":840,"type":"p","anchor":"navbar-title--logo","body":"To improve dark mode support, you can also set a different logo for this mode.","heading":"@docusaurus/theme-classic"},{"pageID":"docs/theme-classic","id":841,"type":"h3","anchor":"navbar-items","body":"Navbar items","heading":"@docusaurus/theme-classic"},{"pageID":"docs/theme-classic","id":842,"type":"p","anchor":"navbar-items","body":"You can add items to the navbar via themeConfig.navbar.items.","heading":"@docusaurus/theme-classic"},{"pageID":"docs/theme-classic","id":843,"type":"p","anchor":"navbar-items","body":"By default, Navbar items are regular links (internal or external).","heading":"@docusaurus/theme-classic"},{"pageID":"docs/theme-classic","id":844,"type":"p","anchor":"navbar-items","body":"React Router should automatically apply active link styling to links, but you can use activeBasePath in edge cases. For cases in which a link should be active on several different paths (such as when you have multiple doc folders under the same sidebar), you can use activeBaseRegex. activeBaseRegex is a more flexible alternative to activeBasePath and takes precedence over it -- Docusaurus parses it into a regular expression that is tested against the current URL.","heading":"@docusaurus/theme-classic"},{"pageID":"docs/theme-classic","id":845,"type":"p","anchor":"navbar-items","body":"Outbound (external) links automatically get target=\"_blank\" rel=\"noopener noreferrer\" attributes.","heading":"@docusaurus/theme-classic"},{"pageID":"docs/theme-classic","id":846,"type":"h3","anchor":"navbar-dropdown","body":"Navbar dropdown","heading":"@docusaurus/theme-classic"},{"pageID":"docs/theme-classic","id":847,"type":"p","anchor":"navbar-dropdown","body":"Navbar items can also be dropdown items by specifying the items, an inner array of navbar items.","heading":"@docusaurus/theme-classic"},{"pageID":"docs/theme-classic","id":848,"type":"h3","anchor":"navbar-docs-version-dropdown","body":"Navbar docs version dropdown","heading":"@docusaurus/theme-classic"},{"pageID":"docs/theme-classic","id":849,"type":"p","anchor":"navbar-docs-version-dropdown","body":"If you use docs with versioning, this special navbar item type that will render a dropdown with all your site's available versions. The user will be able to switch from one version to another, while staying on the same doc (as long as the doc id is constant across versions).","heading":"@docusaurus/theme-classic"},{"pageID":"docs/theme-classic","id":850,"type":"h3","anchor":"navbar-docs-version","body":"Navbar docs version","heading":"@docusaurus/theme-classic"},{"pageID":"docs/theme-classic","id":851,"type":"p","anchor":"navbar-docs-version","body":"If you use docs with versioning, this special navbar item type will link to the active/browsed version of your doc (depends on the current url), and fallback to the latest version.","heading":"@docusaurus/theme-classic"},{"pageID":"docs/theme-classic","id":852,"type":"h3","anchor":"auto-hide-sticky-navbar","body":"Auto-hide sticky navbar","heading":"@docusaurus/theme-classic"},{"pageID":"docs/theme-classic","id":853,"type":"p","anchor":"auto-hide-sticky-navbar","body":"You can enable this cool UI feature that automatically hides the navbar when a user starts scrolling down the page, and show it again when the user scrolls up.","heading":"@docusaurus/theme-classic"},{"pageID":"docs/theme-classic","id":854,"type":"h2","anchor":"codeblock","body":"CodeBlock","heading":"@docusaurus/theme-classic"},{"pageID":"docs/theme-classic","id":855,"type":"p","anchor":"codeblock","body":"Docusaurus uses Prism React Renderer to highlight code blocks.","heading":"@docusaurus/theme-classic"},{"pageID":"docs/theme-classic","id":856,"type":"h3","anchor":"theme","body":"Theme","heading":"@docusaurus/theme-classic"},{"pageID":"docs/theme-classic","id":857,"type":"p","anchor":"theme","body":"By default, we use Palenight as syntax highlighting theme. You can specify a custom theme from the list of available themes. If you want to use a different syntax highlighting theme when the site is in dark mode, you may also do so.","heading":"@docusaurus/theme-classic"},{"pageID":"docs/theme-classic","id":858,"type":"p","anchor":"theme","body":"If you use the line highlighting Markdown syntax, you might need to specify a different highlight background color for the dark mode syntax highlighting theme. Refer to the docs for guidance.","heading":"@docusaurus/theme-classic"},{"pageID":"docs/theme-classic","id":859,"type":"h3","anchor":"default-language","body":"Default language","heading":"@docusaurus/theme-classic"},{"pageID":"docs/theme-classic","id":860,"type":"p","anchor":"default-language","body":"You can set a default language for code blocks if no language is added after the opening triple backticks (i.e. ```). Note that a valid language name must be passed, e.g.:","heading":"@docusaurus/theme-classic"},{"pageID":"docs/typescript-support","id":861,"type":"h1","anchor":"setup","body":"TypeScript Support","heading":"TypeScript Support"},{"pageID":"docs/typescript-support","id":862,"type":"h2","anchor":"setup","body":"Setup","heading":"TypeScript Support"},{"pageID":"docs/typescript-support","id":863,"type":"p","anchor":"setup","body":"Docusaurus supports writing and using TypeScript theme components. To start using TypeScript, add @docusaurus/module-type-aliases to your project:","heading":"TypeScript Support"},{"pageID":"docs/typescript-support","id":864,"type":"p","anchor":"setup","body":"Then add tsconfig.json to your project root with following content:","heading":"TypeScript Support"},{"pageID":"docs/typescript-support","id":865,"type":"p","anchor":"setup","body":"Docusaurus doesn't use this tsconfig.json to compile your TypeScript. It is added just for a nicer Editor experience, although you can choose to run tsc --noEmit to type check your code for yourself.","heading":"TypeScript Support"},{"pageID":"docs/typescript-support","id":866,"type":"p","anchor":"setup","body":"Then add types.d.ts in your src folder with the following content:","heading":"TypeScript Support"},{"pageID":"docs/typescript-support","id":867,"type":"p","anchor":"setup","body":"This file makes TypeScript recognize various Docusaurus specific webpack aliases like @theme, @docusaurus, @generated.","heading":"TypeScript Support"},{"pageID":"docs/typescript-support","id":868,"type":"p","anchor":"setup","body":"Now you can start writing TypeScript theme components.","heading":"TypeScript Support"},{"pageID":"docs/typescript-support","id":869,"type":"h2","anchor":"swizzling-typescript-theme-components","body":"Swizzling TypeScript theme components","heading":"TypeScript Support"},{"pageID":"docs/typescript-support","id":870,"type":"p","anchor":"swizzling-typescript-theme-components","body":"For themes that supports TypeScript theme components, you can add the --typescript flag to the end of swizzling command to get TypeScript source code. For example, the following command will generate index.tsx and styles.module.css into src/theme/Footer.","heading":"TypeScript Support"},{"pageID":"docs/typescript-support","id":871,"type":"p","anchor":"swizzling-typescript-theme-components","body":"At this moment, the only official Docusaurus theme that supports TypeScript theme components is @docusaurus/theme-classic. If you are a Docusaurus theme package author who wants to add TypeScript support, see the Lifecycle APIs docs.","heading":"TypeScript Support"},{"pageID":"docs/using-plugins","id":872,"type":"h1","anchor":"installing-a-plugin","body":"Plugins","heading":"Plugins"},{"pageID":"docs/using-plugins","id":873,"type":"p","anchor":"installing-a-plugin","body":"Plugins are the building blocks of features in a Docusaurus 2 site. Each plugin handles its own individual feature. Plugins may work and be distributed as part of bundle via presets.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":874,"type":"h2","anchor":"installing-a-plugin","body":"Installing a plugin","heading":"Plugins"},{"pageID":"docs/using-plugins","id":875,"type":"p","anchor":"installing-a-plugin","body":"A plugin is usually a npm package, so you install them like other npm packages using npm.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":876,"type":"p","anchor":"installing-a-plugin","body":"Then you add it in your site's docusaurus.config.js's plugins option:","heading":"Plugins"},{"pageID":"docs/using-plugins","id":877,"type":"p","anchor":"installing-a-plugin","body":"Docusaurus can also load plugins from your local directory, you can do something like the following:","heading":"Plugins"},{"pageID":"docs/using-plugins","id":878,"type":"h2","anchor":"configuring-plugins","body":"Configuring plugins","heading":"Plugins"},{"pageID":"docs/using-plugins","id":879,"type":"p","anchor":"configuring-plugins","body":"For the most basic usage of plugins, you can provide just the plugin name or the absolute path to the plugin.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":880,"type":"p","anchor":"configuring-plugins","body":"However, plugins can have options specified by wrapping the name and an options object in an array inside your config. This style is usually called Babel Style.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":881,"type":"p","anchor":"configuring-plugins","body":"Example:","heading":"Plugins"},{"pageID":"docs/using-plugins","id":882,"type":"h2","anchor":"multi-instance-plugins-and-plugin-ids","body":"Multi-instance plugins and plugin ids","heading":"Plugins"},{"pageID":"docs/using-plugins","id":883,"type":"p","anchor":"multi-instance-plugins-and-plugin-ids","body":"It is possible to use multiple times the same plugin, on the same Docusaurus website.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":884,"type":"p","anchor":"multi-instance-plugins-and-plugin-ids","body":"In this case, you it is required to assign a unique id to each plugin instance.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":885,"type":"p","anchor":"multi-instance-plugins-and-plugin-ids","body":"By default, the plugin id is default.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":886,"type":"h2","anchor":"plugins-design","body":"Plugins design","heading":"Plugins"},{"pageID":"docs/using-plugins","id":887,"type":"p","anchor":"plugins-design","body":"Docusaurus' implementation of the plugins system provides us with a convenient way to hook into the website's lifecycle to modify what goes on during development/build, which involves (but not limited to) extending the webpack config, modifying the data being loaded and creating new components to be used in a page.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":888,"type":"h2","anchor":"creating-plugins","body":"Creating plugins","heading":"Plugins"},{"pageID":"docs/using-plugins","id":889,"type":"p","anchor":"creating-plugins","body":"A plugin is a module which exports a function that takes two parameters and returns an object when executed.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":890,"type":"h3","anchor":"module-definition","body":"Module definition","heading":"Plugins"},{"pageID":"docs/using-plugins","id":891,"type":"p","anchor":"module-definition","body":"The exported modules for plugins are called with two parameters: context and options and returns a JavaScript object with defining the lifecycle APIs.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":892,"type":"p","anchor":"module-definition","body":"For example if you have a reference to a local folder such as this in your docusaurus.config.js:","heading":"Plugins"},{"pageID":"docs/using-plugins","id":893,"type":"p","anchor":"module-definition","body":"Then in the folder my-plugin you can create an index.js such as this","heading":"Plugins"},{"pageID":"docs/using-plugins","id":894,"type":"p","anchor":"module-definition","body":"The my-plugin folder could also be a fully fledged package with it's own package.json and a src/index.js file for example","heading":"Plugins"},{"pageID":"docs/using-plugins","id":895,"type":"p","anchor":"context","body":"context is plugin-agnostic and the same object will be passed into all plugins used for a Docusaurus website. The context object contains the following fields:","heading":"Plugins"},{"pageID":"docs/using-plugins","id":896,"type":"p","anchor":"options","body":"options are the second optional parameter when the plugins are used. options are plugin-specific and are specified by users when they use them in docusaurus.config.js. Alternatively, if preset contains the plugin, the preset will then be in charge of passing the correct options into the plugin. It is up to individual plugin to define what options it takes.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":897,"type":"p","anchor":"return-value","body":"The returned object value should implement the lifecycle APIs.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":898,"type":"h2","anchor":"official-plugins","body":"Official plugins","heading":"Plugins"},{"pageID":"docs/using-plugins","id":899,"type":"p","anchor":"official-plugins","body":"Find the list of official Docusaurus plugins here.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":900,"type":"h3","anchor":"docusaurusplugin-content-blog","body":"@docusaurus/plugin-content-blog","heading":"Plugins"},{"pageID":"docs/using-plugins","id":901,"type":"p","anchor":"docusaurusplugin-content-blog","body":"Provides the Blog feature and is the default blog plugin for Docusaurus.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":902,"type":"p","anchor":"docusaurusplugin-content-blog","body":"Installation","heading":"Plugins"},{"pageID":"docs/using-plugins","id":903,"type":"p","anchor":"docusaurusplugin-content-blog","body":"If you have installed @docusaurus/preset-classic, you don't need to install it as a dependency. You can also configure it through the classic preset options instead of doing it like below.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":904,"type":"h3","anchor":"docusaurusplugin-content-docs","body":"@docusaurus/plugin-content-docs","heading":"Plugins"},{"pageID":"docs/using-plugins","id":905,"type":"p","anchor":"docusaurusplugin-content-docs","body":"Provides the Docs functionality and is the default docs plugin for Docusaurus.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":906,"type":"p","anchor":"docusaurusplugin-content-docs","body":"Installation","heading":"Plugins"},{"pageID":"docs/using-plugins","id":907,"type":"p","anchor":"docusaurusplugin-content-docs","body":"If you have installed @docusaurus/preset-classic, you don't need to install it as a dependency. You can also configure it through the classic preset options instead of doing it like below.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":908,"type":"h3","anchor":"docusaurusplugin-content-pages","body":"@docusaurus/plugin-content-pages","heading":"Plugins"},{"pageID":"docs/using-plugins","id":909,"type":"p","anchor":"docusaurusplugin-content-pages","body":"The default pages plugin for Docusaurus. The classic template ships with this plugin with default configurations. This plugin provides creating pages functionality.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":910,"type":"p","anchor":"docusaurusplugin-content-pages","body":"Installation","heading":"Plugins"},{"pageID":"docs/using-plugins","id":911,"type":"p","anchor":"docusaurusplugin-content-pages","body":"If you have installed @docusaurus/preset-classic, you don't need to install it as a dependency. You can also configure it through the classic preset options instead of doing it like below.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":912,"type":"h3","anchor":"docusaurusplugin-google-analytics","body":"@docusaurus/plugin-google-analytics","heading":"Plugins"},{"pageID":"docs/using-plugins","id":913,"type":"p","anchor":"docusaurusplugin-google-analytics","body":"The default Google Analytics plugin. It is a JavaScript library for measuring how users interact with your website.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":914,"type":"p","anchor":"docusaurusplugin-google-analytics","body":"Installation","heading":"Plugins"},{"pageID":"docs/using-plugins","id":915,"type":"p","anchor":"docusaurusplugin-google-analytics","body":"If you have installed @docusaurus/preset-classic, you don't need to install it as a dependency.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":916,"type":"p","anchor":"docusaurusplugin-google-analytics","body":"Configuration","heading":"Plugins"},{"pageID":"docs/using-plugins","id":917,"type":"h3","anchor":"docusaurusplugin-google-gtag","body":"@docusaurus/plugin-google-gtag","heading":"Plugins"},{"pageID":"docs/using-plugins","id":918,"type":"p","anchor":"docusaurusplugin-google-gtag","body":"The default Global Site Tag (gtag.js) plugin. It is a JavaScript tagging framework and API that allows you to send event data to Google Analytics, Google Ads, and Google Marketing Platform. This section describes how to configure a Docusaurus site to enable global site tag for Google Analytics.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":919,"type":"p","anchor":"docusaurusplugin-google-gtag","body":"Installation","heading":"Plugins"},{"pageID":"docs/using-plugins","id":920,"type":"p","anchor":"docusaurusplugin-google-gtag","body":"If you have installed @docusaurus/preset-classic, you don't need to install it as a dependency.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":921,"type":"p","anchor":"docusaurusplugin-google-gtag","body":"Configuration","heading":"Plugins"},{"pageID":"docs/using-plugins","id":922,"type":"h3","anchor":"docusaurusplugin-sitemap","body":"@docusaurus/plugin-sitemap","heading":"Plugins"},{"pageID":"docs/using-plugins","id":923,"type":"p","anchor":"docusaurusplugin-sitemap","body":"This plugin creates sitemap for your site so that search engine crawlers can crawl your site more accurately.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":924,"type":"p","anchor":"docusaurusplugin-sitemap","body":"Installation","heading":"Plugins"},{"pageID":"docs/using-plugins","id":925,"type":"p","anchor":"docusaurusplugin-sitemap","body":"If you have installed @docusaurus/preset-classic, you don't need to install it as a dependency. You can also configure it through the classic preset options instead of doing it like below.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":926,"type":"h3","anchor":"docusaurusplugin-ideal-image","body":"@docusaurus/plugin-ideal-image","heading":"Plugins"},{"pageID":"docs/using-plugins","id":927,"type":"p","anchor":"docusaurusplugin-ideal-image","body":"Docusaurus Plugin to generate an almost ideal image (responsive, lazy-loading, and low quality placeholder) in the production builds.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":928,"type":"p","anchor":"docusaurusplugin-ideal-image","body":"Modify your docusaurus.config.js","heading":"Plugins"},{"pageID":"docs/using-plugins","id":929,"type":"p","anchor":"usage","body":"This plugin supports the PNG, GIF and JPG formats only.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":930,"type":"h3","anchor":"docusaurusplugin-client-redirects","body":"@docusaurus/plugin-client-redirects","heading":"Plugins"},{"pageID":"docs/using-plugins","id":931,"type":"p","anchor":"docusaurusplugin-client-redirects","body":"Docusaurus Plugin to generate client-side redirects.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":932,"type":"p","anchor":"docusaurusplugin-client-redirects","body":"This plugin will write additional HTML pages to your static site, that redirects the user to your existing Docusaurus pages with JavaScript.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":933,"type":"p","anchor":"docusaurusplugin-client-redirects","body":"This plugin only create redirects for the production build.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":934,"type":"p","anchor":"docusaurusplugin-client-redirects","body":"It is better to use server-side redirects whenever possible.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":935,"type":"p","anchor":"docusaurusplugin-client-redirects","body":"Before using this plugin, you should look if your hosting provider doesn't offer this feature.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":936,"type":"p","anchor":"docusaurusplugin-client-redirects","body":"Installation","heading":"Plugins"},{"pageID":"docs/using-plugins","id":937,"type":"p","anchor":"docusaurusplugin-client-redirects","body":"Configuration","heading":"Plugins"},{"pageID":"docs/using-plugins","id":938,"type":"p","anchor":"docusaurusplugin-client-redirects","body":"Main usecase: you have /myDocusaurusPage, and you want to redirect to this page from /myDocusaurusPage.html:","heading":"Plugins"},{"pageID":"docs/using-plugins","id":939,"type":"p","anchor":"docusaurusplugin-client-redirects","body":"Second usecase: you have /myDocusaurusPage.html, and you want to redirect to this page from /myDocusaurusPage.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":940,"type":"p","anchor":"docusaurusplugin-client-redirects","body":"For custom redirect logic, provide your own createRedirects function.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":941,"type":"p","anchor":"docusaurusplugin-client-redirects","body":"Let's imagine you change the url of an existing page, you might want to make sure the old url still works:","heading":"Plugins"},{"pageID":"docs/using-plugins","id":942,"type":"p","anchor":"docusaurusplugin-client-redirects","body":"It's possible to use a function to create the redirects for each existing path:","heading":"Plugins"},{"pageID":"docs/using-plugins","id":943,"type":"p","anchor":"docusaurusplugin-client-redirects","body":"Finally, it's possible to use all options at the same time:","heading":"Plugins"},{"pageID":"docs/using-plugins","id":944,"type":"h3","anchor":"docusaurusplugin-pwa","body":"@docusaurus/plugin-pwa","heading":"Plugins"},{"pageID":"docs/using-plugins","id":945,"type":"p","anchor":"docusaurusplugin-pwa","body":"Docusaurus Plugin to add PWA support using Workbox. This plugin generates a Service Worker in production build only, and allows you to create fully PWA-compliant documentation site with offline and installation support.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":946,"type":"p","anchor":"docusaurusplugin-pwa","body":"Create a PWA manifest at ./static/manifest.json.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":947,"type":"p","anchor":"docusaurusplugin-pwa","body":"Modify docusaurus.config.js with a minimal PWA config, like:","heading":"Plugins"},{"pageID":"docs/using-plugins","id":948,"type":"p","anchor":"progressive-web-app","body":"Having a service worker installed is not enough to make your application a PWA. You'll need to at least include a Web App Manifest and have the correct tags in <head> (Options > pwaHead).","heading":"Plugins"},{"pageID":"docs/using-plugins","id":949,"type":"p","anchor":"progressive-web-app","body":"After deployment, you can use Lighthouse to run an audit on your site.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":950,"type":"p","anchor":"progressive-web-app","body":"For a more exhaustive list of what it takes for your site to be a PWA, refer to the PWA Checklist","heading":"Plugins"},{"pageID":"docs/using-plugins","id":951,"type":"p","anchor":"app-installation-support","body":"If your browser supports it, you should be able to install a Docusaurus site as an app.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":952,"type":"p","anchor":"app-installation-support","body":"","heading":"Plugins"},{"pageID":"docs/using-plugins","id":953,"type":"p","anchor":"offline-mode-precaching","body":"We enable users to browse a Docusaurus site offline, by using service-worker precaching.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":954,"type":"h3","anchor":"what-is-precaching","body":"What is Precaching?","heading":"Plugins"},{"pageID":"docs/using-plugins","id":955,"type":"p","anchor":"what-is-precaching","body":"One feature of service workers is the ability to save a set of files to the cache when the service worker is installing. This is often referred to as \"precaching\", since you are caching content ahead of the service worker being used.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":956,"type":"p","anchor":"what-is-precaching","body":"The main reason for doing this is that it gives developers control over the cache, meaning they can determine when and how long a file is cached as well as serve it to the browser without going to the network, meaning it can be used to create web apps that work offline.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":957,"type":"p","anchor":"what-is-precaching","body":"Workbox takes a lot of the heavy lifting out of precaching by simplifying the API and ensuring assets are downloaded efficiently.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":958,"type":"p","anchor":"what-is-precaching","body":"By default, offline mode is enabled when the site is installed as an app. See the offlineModeActivationStrategies option for details.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":959,"type":"p","anchor":"what-is-precaching","body":"After the site has been precached, the service worker will serve cached responses for later visits. When a new build is deployed along with a new service worker, the new one will begin installing and eventually move to a waiting state. During this waiting state, a reload popup will show and ask the user to reload the page for new content. Until the user either clears the application cache or clicks the reload button on the popup, the service worker will continue serving the old content.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":960,"type":"p","anchor":"what-is-precaching","body":"Offline mode / precaching requires downloading all the static assets of the site ahead of time, and can consume unnecessary bandwidth. It may not be a good idea to activate it for all kind of sites.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":961,"type":"p","anchor":"debug","body":"Turn debug mode on:","heading":"Plugins"},{"pageID":"docs/using-plugins","id":962,"type":"p","anchor":"offlinemodeactivationstrategies","body":"Strategies used to turn the offline mode on:","heading":"Plugins"},{"pageID":"docs/using-plugins","id":963,"type":"p","anchor":"offlinemodeactivationstrategies","body":"Use this carefully: some users may not like to be forced to use the offline mode.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":964,"type":"p","anchor":"injectmanifestconfig","body":"Workbox options to pass to workbox.injectManifest(). This gives you control over which assets will be precached, and be available offline.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":965,"type":"p","anchor":"reloadpopup","body":"Module path to reload popup component. This popup is rendered when a new service worker is waiting to be installed, and we suggest a reload to the user.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":966,"type":"p","anchor":"reloadpopup","body":"Passing false will disable the popup, but this is not recommended: users won't have a way to get up-to-date content.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":967,"type":"p","anchor":"reloadpopup","body":"A custom component can be used, as long as it accepts onReload as a prop. The onReload callback should be called when the reload button is clicked. This will tell the service worker to install the waiting service worker and reload the page.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":968,"type":"p","anchor":"reloadpopup","body":"The default theme includes an implementation for the reload popup and uses Infima Alerts.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":969,"type":"p","anchor":"reloadpopup","body":"","heading":"Plugins"},{"pageID":"docs/using-plugins","id":970,"type":"p","anchor":"pwahead","body":"Array of objects containing tagName and key-value pairs for attributes to inject into the <head> tag. Technically you can inject any head tag through this, but it's ideally used for tags to make your site PWA compliant. Here's a list of tag to make your app fully compliant:","heading":"Plugins"},{"pageID":"docs/using-plugins","id":971,"type":"p","anchor":"swcustom","body":"Useful for additional Workbox rules. You can do whatever a service worker can do here, and use the full power of workbox libraries. The code is transpiled, so you can use modern ES6+ syntax here.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":972,"type":"p","anchor":"swcustom","body":"For example, to cache files from external routes:","heading":"Plugins"},{"pageID":"docs/using-plugins","id":973,"type":"p","anchor":"swcustom","body":"The module should have a default function export, and receives some params.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":974,"type":"p","anchor":"swregister","body":"Adds an entry before the Docusaurus app so that registration can happen before the app runs. The default registerSW.js file is enough for simple registration.","heading":"Plugins"},{"pageID":"docs/using-plugins","id":975,"type":"p","anchor":"swregister","body":"Passing false will disable registration entirely.","heading":"Plugins"},{"pageID":"docs/using-themes","id":976,"type":"h1","anchor":"using-themes","body":"Themes","heading":"Themes"},{"pageID":"docs/using-themes","id":977,"type":"p","anchor":"using-themes","body":"Like plugins, themes are designed to add functionality to your Docusaurus site. As a good rule of thumb, themes are mostly focused on client-side, where plugins are more focused on server-side functionalities. Themes are also designed to be replace-able with other themes.","heading":"Themes"},{"pageID":"docs/using-themes","id":978,"type":"h2","anchor":"using-themes","body":"Using themes","heading":"Themes"},{"pageID":"docs/using-themes","id":979,"type":"p","anchor":"using-themes","body":"To use themes, specify the themes in your docusaurus.config.js. You may use multiple themes:","heading":"Themes"},{"pageID":"docs/using-themes","id":980,"type":"h2","anchor":"theme-components","body":"Theme components","heading":"Themes"},{"pageID":"docs/using-themes","id":981,"type":"p","anchor":"theme-components","body":"Most of the time, theme is used to provide a set of React components, e.g. Navbar, Layout, Footer.","heading":"Themes"},{"pageID":"docs/using-themes","id":982,"type":"p","anchor":"theme-components","body":"Users can use these components in their code by importing them using the @theme webpack alias:","heading":"Themes"},{"pageID":"docs/using-themes","id":983,"type":"p","anchor":"theme-components","body":"The alias @theme can refer to a few directories, in the following priority:","heading":"Themes"},{"pageID":"docs/using-themes","id":984,"type":"p","anchor":"theme-components","body":"Given the following structure","heading":"Themes"},{"pageID":"docs/using-themes","id":985,"type":"p","anchor":"theme-components","body":"website/src/theme/Navbar.js takes precedence whenever @theme/Navbar is imported. This behavior is called component swizzling. In iOS, method swizzling is the process of changing the implementation of an existing selector (method). In the context of a website, component swizzling means providing an alternative component that takes precedence over the component provided by the theme.","heading":"Themes"},{"pageID":"docs/using-themes","id":986,"type":"p","anchor":"theme-components","body":"Themes are for providing UI components to present the content. Most content plugins need to be paired with a theme in order to be actually useful. The UI is a separate layer from the data schema, so it makes it easy to swap out the themes for other designs (i.e., Bootstrap).","heading":"Themes"},{"pageID":"docs/using-themes","id":987,"type":"p","anchor":"theme-components","body":"For example, a Docusaurus blog consists of a blog plugin and a blog theme.","heading":"Themes"},{"pageID":"docs/using-themes","id":988,"type":"p","anchor":"theme-components","body":"And if you want to use Bootstrap styling, you can swap out the theme with theme-blog-bootstrap (fictitious non-existing theme):","heading":"Themes"},{"pageID":"docs/using-themes","id":989,"type":"p","anchor":"theme-components","body":"The content plugin remains the same and the only thing you need to change is the theme.","heading":"Themes"},{"pageID":"docs/using-themes","id":990,"type":"h2","anchor":"swizzling-theme-components","body":"Swizzling theme components","heading":"Themes"},{"pageID":"docs/using-themes","id":991,"type":"p","anchor":"swizzling-theme-components","body":"We would like to discourage swizzling of components until we've minimally reached a Beta stage. The components APIs have been changing rapidly and are likely to keep changing until we reach Beta. Stick with the default appearance for now if possible to save yourself some potential pain in future.","heading":"Themes"},{"pageID":"docs/using-themes","id":992,"type":"p","anchor":"swizzling-theme-components","body":"Docusaurus Themes' components are designed to be replaceable. To make it easier for you, we created a command for you to replace theme components called swizzle.","heading":"Themes"},{"pageID":"docs/using-themes","id":993,"type":"p","anchor":"swizzling-theme-components","body":"To swizzle a component for a theme, run the following command in your doc site:","heading":"Themes"},{"pageID":"docs/using-themes","id":994,"type":"p","anchor":"swizzling-theme-components","body":"As an example, to swizzle the <Footer /> component in @docusaurus/theme-classic for your site, run:","heading":"Themes"},{"pageID":"docs/using-themes","id":995,"type":"p","anchor":"swizzling-theme-components","body":"This will copy the current <Footer /> component used by the theme to a src/theme/Footer directory under the root of your site, which is where Docusaurus will look for swizzled components. Docusaurus will then use swizzled component in place of the original one from the theme.","heading":"Themes"},{"pageID":"docs/using-themes","id":996,"type":"p","anchor":"swizzling-theme-components","body":"Although we highly discourage swizzling of all components, if you wish to do that, run:","heading":"Themes"},{"pageID":"docs/using-themes","id":997,"type":"p","anchor":"swizzling-theme-components","body":"Note: You need to restart your webpack dev server in order for Docusaurus to know about the new component.","heading":"Themes"},{"pageID":"docs/using-themes","id":998,"type":"h2","anchor":"official-themes-by-docusaurus","body":"Official themes by Docusaurus","heading":"Themes"},{"pageID":"docs/using-themes","id":999,"type":"h3","anchor":"docusaurustheme-classic","body":"@docusaurus/theme-classic","heading":"Themes"},{"pageID":"docs/using-themes","id":1000,"type":"p","anchor":"docusaurustheme-classic","body":"The classic theme for Docusaurus. You can refer to classic theme configuration for more details on the configuration.","heading":"Themes"},{"pageID":"docs/using-themes","id":1001,"type":"p","anchor":"docusaurustheme-classic","body":"If you have installed @docusaurus/preset-classic, you don't need to install it as a dependency.","heading":"Themes"},{"pageID":"docs/using-themes","id":1002,"type":"h3","anchor":"docusaurustheme-search-algolia","body":"@docusaurus/theme-search-algolia","heading":"Themes"},{"pageID":"docs/using-themes","id":1003,"type":"p","anchor":"docusaurustheme-search-algolia","body":"This theme provides a @theme/SearchBar component that integrates with Algolia DocSearch easily. Combined with @docusaurus/theme-classic, it provides a very easy search integration. You can read more on search documentation.","heading":"Themes"},{"pageID":"docs/using-themes","id":1004,"type":"p","anchor":"docusaurustheme-search-algolia","body":"This theme also adds search page available at /search path with OpenSearch support.","heading":"Themes"},{"pageID":"docs/using-themes","id":1005,"type":"p","anchor":"docusaurustheme-search-algolia","body":"If you have installed @docusaurus/preset-classic, you don't need to install it as a dependency.","heading":"Themes"},{"pageID":"docs/using-themes","id":1006,"type":"h3","anchor":"docusaurustheme-live-codeblock","body":"@docusaurus/theme-live-codeblock","heading":"Themes"},{"pageID":"docs/using-themes","id":1007,"type":"p","anchor":"docusaurustheme-live-codeblock","body":"This theme provides a @theme/CodeBlock component that is powered by react-live. You can read more on interactive code editor documentation.","heading":"Themes"},{"pageID":"docs/using-themes","id":1008,"type":"h2","anchor":"themes-design","body":"Themes design","heading":"Themes"},{"pageID":"docs/using-themes","id":1009,"type":"p","anchor":"themes-design","body":"While themes share the exact same lifecycle methods with plugins, their implementations can look very different from those of plugins based on themes' designed objectives.","heading":"Themes"},{"pageID":"docs/using-themes","id":1010,"type":"p","anchor":"themes-design","body":"Themes are designed to complete the build of your Docusaurus site and supply the components used by your site, plugins, and the themes themselves. So a typical theme implementation would look like a src/index.js file that hooks it up to the lifecycle methods. Most likely they would not use loadContent, which plugins would use. And it is typically accompanied by a src/theme directory full of components.","heading":"Themes"},{"pageID":"docs/using-themes","id":1011,"type":"p","anchor":"themes-design","body":"To summarize:","heading":"Themes"},{"pageID":"docs/using-themes","id":1012,"type":"h2","anchor":"writing-customized-docusaurus-themes","body":"Writing customized Docusaurus themes","heading":"Themes"},{"pageID":"docs/using-themes","id":1013,"type":"p","anchor":"writing-customized-docusaurus-themes","body":"A Docusaurus theme normally includes an index.js file where you hook up to the lifecycle methods, alongside with a theme/ directory of components. A typical Docusaurus theme folder looks like this:","heading":"Themes"},{"pageID":"docs/using-themes","id":1014,"type":"p","anchor":"writing-customized-docusaurus-themes","body":"There are two lifecycle methods that are essential to theme implementation:","heading":"Themes"},{"pageID":"docs/using-themes","id":1015,"type":"p","anchor":"writing-customized-docusaurus-themes","body":"These lifecycle method are not essential but recommended:","heading":"Themes"},{"pageID":"docs/versioning","id":1016,"type":"h1","anchor":"directory-structure","body":"Versioning","heading":"Versioning"},{"pageID":"docs/versioning","id":1017,"type":"p","anchor":"directory-structure","body":"You can use the version script to create a new documentation version based on the latest content in the docs directory. That specific set of documentation will then be preserved and accessible even as the documentation in the docs directory changes moving forward.","heading":"Versioning"},{"pageID":"docs/versioning","id":1018,"type":"p","anchor":"directory-structure","body":"Think about it before starting to version your documentation - it can become difficult for contributors to help improve it!","heading":"Versioning"},{"pageID":"docs/versioning","id":1019,"type":"p","anchor":"directory-structure","body":"Most of the time, you don't need versioning as it will just increase your build time, and introduce complexity to your codebase. Versioning is best suited for websites with high-traffic and rapid changes to documentation between versions. If your documentation rarely changes, don't add versioning to your documentation.","heading":"Versioning"},{"pageID":"docs/versioning","id":1020,"type":"p","anchor":"directory-structure","body":"To better understand how versioning works and see if it suits your needs, you can read on below.","heading":"Versioning"},{"pageID":"docs/versioning","id":1021,"type":"h2","anchor":"directory-structure","body":"Directory structure","heading":"Versioning"},{"pageID":"docs/versioning","id":1022,"type":"p","anchor":"directory-structure","body":"The table below explains how a versioned file maps to its version and the generated URL.","heading":"Versioning"},{"pageID":"docs/versioning","id":1023,"type":"h3","anchor":"tagging-a-new-version","body":"Tagging a new version","heading":"Versioning"},{"pageID":"docs/versioning","id":1024,"type":"p","anchor":"tagging-a-new-version","body":"When tagging a new version, the document versioning mechanism will:","heading":"Versioning"},{"pageID":"docs/versioning","id":1025,"type":"h2","anchor":"files","body":"Files","heading":"Versioning"},{"pageID":"docs/versioning","id":1026,"type":"h3","anchor":"creating-new-files","body":"Creating new files","heading":"Versioning"},{"pageID":"docs/versioning","id":1027,"type":"p","anchor":"creating-new-files","body":"Master docs","heading":"Versioning"},{"pageID":"docs/versioning","id":1028,"type":"p","anchor":"creating-new-files","body":"Older docs","heading":"Versioning"},{"pageID":"docs/versioning","id":1029,"type":"h3","anchor":"linking-files","body":"Linking files","heading":"Versioning"},{"pageID":"docs/versioning","id":1030,"type":"h2","anchor":"versions","body":"Versions","heading":"Versioning"},{"pageID":"docs/versioning","id":1031,"type":"p","anchor":"versions","body":"Each directory in versioned_docs/ will represent a documentation version.","heading":"Versioning"},{"pageID":"docs/versioning","id":1032,"type":"h3","anchor":"updating-an-existing-version","body":"Updating an existing version","heading":"Versioning"},{"pageID":"docs/versioning","id":1033,"type":"p","anchor":"updating-an-existing-version","body":"You can update multiple docs versions at the same time because each directory in versioned_docs/ represents specific routes when published.","heading":"Versioning"},{"pageID":"docs/versioning","id":1034,"type":"p","anchor":"updating-an-existing-version","body":"Example: When you change any file in versioned_docs/version-2.6/, it will only affect the docs for version 2.6.","heading":"Versioning"},{"pageID":"docs/versioning","id":1035,"type":"h3","anchor":"deleting-an-existing-version","body":"Deleting an existing version","heading":"Versioning"},{"pageID":"docs/versioning","id":1036,"type":"p","anchor":"deleting-an-existing-version","body":"You can delete/remove versions as well.","heading":"Versioning"},{"pageID":"docs/versioning","id":1037,"type":"p","anchor":"deleting-an-existing-version","body":"Example:","heading":"Versioning"},{"pageID":"docs/versioning","id":1038,"type":"h2","anchor":"recommended-practices","body":"Recommended practices","heading":"Versioning"},{"pageID":"docs/versioning","id":1039,"type":"h3","anchor":"version-your-documentation-only-when-needed","body":"Version your documentation only when needed","heading":"Versioning"},{"pageID":"docs/versioning","id":1040,"type":"p","anchor":"version-your-documentation-only-when-needed","body":"For example, you are building a documentation for your npm package foo and you are currently in version 1.0.0. You then release a patch version for a minor bug fix and it's now 1.0.1.","heading":"Versioning"},{"pageID":"docs/versioning","id":1041,"type":"p","anchor":"version-your-documentation-only-when-needed","body":"Should you cut a new documentation version 1.0.1? You probably shouldn't. 1.0.1 and 1.0.0 docs shouldn't differ according to semver because there are no new features!. Cutting a new version for it will only just create unnecessary duplicated files.","heading":"Versioning"},{"pageID":"docs/versioning","id":1042,"type":"h3","anchor":"keep-the-number-of-versions-small","body":"Keep the number of versions small","heading":"Versioning"},{"pageID":"docs/versioning","id":1043,"type":"p","anchor":"keep-the-number-of-versions-small","body":"As a good rule of thumb, try to keep the number of your versions below 10. It is very likely that you will have a lot of obsolete versioned documentation that nobody even reads anymore. For example, Jest is currently in version 24.9, and only maintains several latest documentation version with the lowest being 22.X. Keep it small 😊","heading":"Versioning"},{"pageID":"docs/versioning","id":1044,"type":"h3","anchor":"use-absolute-import-within-the-docs","body":"Use absolute import within the docs","heading":"Versioning"},{"pageID":"docs/versioning","id":1045,"type":"p","anchor":"use-absolute-import-within-the-docs","body":"Don't use relative paths import within the docs. Because when we cut a version the paths no longer work (the nesting level is different, among other reasons). You can utilize the @site alias provided by docusaurus, that points to the website directory. Example:","heading":"Versioning"}] | |||
| } | ||
| return rank(fuse.search(term)); | ||
| }; | ||
| } |
There was a problem hiding this comment.
All this looks not ideal to me.
We need a way to "preload" the search engine as soon as the user hover the search bar, even before the first keystroke.
We should only fetch the data once, and initialize FuseJS once, not on
We should rely on FuseJS scoring/orderi,ng
There was a problem hiding this comment.
Oh didn't see but you set the fuse engine in context so it does not re-execute, not fan of how it's done but. seems to work not too bad 👍
| } | ||
| return rank(fuse.search(term)); | ||
| }; | ||
| } |
There was a problem hiding this comment.
This part is not ideal
We should be able to preload the search engine so that it starts loading as soon as the user hover or focus the text input.
We should fetch the data, and init fuse only once
We should rely on FuseJS scoring/ordering, not computing a score ourselves
|
|
||
| import scrap from './scrapper'; | ||
|
|
||
| import glob from 'glob'; |
There was a problem hiding this comment.
Why not use Globby, as we already use it in other places ?
|
Added a few comments here and there but would have to try the code more in depth to understand how all this works :) The POC looks fine but not sure the search results are very good ;p
|
|
@slorber I got very different results. |
added 2 commits
August 12, 2020 16:01
|
Hmm, I think there is a plugin for that already: https://github.com/cmfcmf/docusaurus-search-local 🙂 |
|
This one doesn't provide UI. It would be official and maintained by the docusaurus team. |
It provides the simple UI (you can also PR in there and implement the custom/alternative design). Also the design you trying to mimic has been created by Algolia not the Docusaurs.
It depends on the approach, if you consider this as good or bad news. 🙂 I'm just bit skeptical about reimplementing the same feature multiple times or judging the plugin quality based on the "official" label (or demoting the 3rd part plugins quality). Wouldn't this approach leads to implementing all plugins in the official repository? (Which will negate the whole idea about the plugins and flexibility in V2?) Or how to choose which plugins should be official and which can be developed by community and still concern as viable for the Docusaurs users? |
|
@Simek Official doesn't mean anything is superior but it will have close functionality to the existing search plugin. This is a plugin that can be used by any other theme to build on it. |
|
As for PRs to other community plugins, this plugin does scrapping and rating very differently which is more inspired by docsearch. This plugin provides a hook that can be used in any plugin anywhere in the docusaurus application. |
|
closing it |
3 tasks
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Motivation
Create search plugin without the use of any service.
Have you read the Contributing Guidelines on pull requests?
Yes
Test Plan
Will add