diff --git a/packages/docusaurus/src/server/loadSetup.ts b/packages/docusaurus/src/server/loadSetup.ts deleted file mode 100644 index f148c0c9c2..0000000000 --- a/packages/docusaurus/src/server/loadSetup.ts +++ /dev/null @@ -1,25 +0,0 @@ -/** - * Copyright (c) 2017-present, Facebook, Inc. - * - * This source code is licensed under the MIT license found in the - * LICENSE file in the root directory of this source tree. - */ - -import path from 'path'; -import {load} from './index'; -import {Props} from '@docusaurus/types'; - -// Helper methods to setup dummy/fake projects -export const loadSetup = async (name: string): Promise => { - const fixtures = path.join(__dirname, '__tests__', '__fixtures__'); - const simpleSite = path.join(fixtures, 'simple-site'); - const customSite = path.join(fixtures, 'custom-site'); - - switch (name) { - case 'custom': - return load(customSite); - case 'simple': - default: - return load(simpleSite); - } -}; diff --git a/website/docs/analytics.md b/website/docs/analytics.md deleted file mode 100644 index da3e850d76..0000000000 --- a/website/docs/analytics.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -id: analytics -title: Analytics -keywords: - - docusaurus - - analytics ---- - -This page describes how to configure a Docusaurus site to enable Google's libraries and SDKs for tracking. - -## `@docusaurus/plugin-google-analytics` - -[Google's analytics.js library](https://developers.google.com/analytics/devguides/collection/analyticsjs/) is a JavaScript library for measuring how users interact with your website. This section explains how to configure a Docusaurus site to enable Google Analytics. - -If you generalized your site using Docusaurus' classic template, you may enable the analytics plugin directly by specifying the Google Analytics tracking id via the `themeConfig` field: - -```js -// docusaurus.config.js -module.exports = { - themeConfig: { - googleAnalytics: { - trackingID: 'UA-142857148-5', - }, - }, -}; -``` - -To learn how to manually set up the Google Analytics plugin for Docusaurus sites not generated from the classic template, refer to [Advanced Guides: Plugins – `@docusaurus/plugin-google-analytics`](advanced-plugins.md#docusaurusplugin-google-analytics). - -## `@docusaurus/plugin-google-gtag` - -Google's [Global Site Tag (gtag.js)](https://developers.google.com/analytics/devguides/collection/gtagjs/) 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. - -If you generalized your site using Docusaurus' classic template, you may enable the gtag plugin directly by specifying the gtag tracking id via the `themeConfig` field: - -```js -// docusaurus.config.js -module.exports = { - themeConfig: { - gtag: { - trackingID: 'UA-142857148-5', - }, - }, -}; -``` - -To learn how to manually set up the gtag plugin for Docusaurus sites not generated from the classic template, refer to [Advanced Guides: Plugins – `@docusaurus/plugin-google-gtag`](advanced-plugins.md#docusaurusplugin-google-gtag). diff --git a/website/docs/contributing.md b/website/docs/contributing.md index dccc096b94..1923103510 100644 --- a/website/docs/contributing.md +++ b/website/docs/contributing.md @@ -19,7 +19,7 @@ Facebook has adopted a Code of Conduct that we expect project participants to ad 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: - Start using Docusaurus 2! Go through the [Getting Started](installation.md) guides. Does everything work as expected? If not, we're always looking for improvements. Let us know by [opening an issue](#reporting-new-issues). -- Look through the [v2.0 issues](https://github.com/facebook/docusaurus/labels/2.x). If you find an issue you would like to fix, [open a pull request](#your-first-pull-request). Issues tagged as [_Good first issue_](https://github.com/facebook/docusaurus/labels/Good%20first%20issue) are a good place to get started. +- Look through the [v2.0 issues](https://github.com/facebook/docusaurus/labels/v2). If you find an issue you would like to fix, [open a pull request](#your-first-pull-request). Issues tagged as [_Good first issue_](https://github.com/facebook/docusaurus/labels/Good%20first%20issue) are a good place to get started. - Help us making the docs better. File an issue if you find anything that is confusing or can be improved. We also have [an umbrella issue for v2 docs](https://github.com/facebook/docusaurus/issues/1640) where we are planning and working on all v2 docs. You may adopt a doc piece there to work on. - Take a look at the [features requested](https://github.com/facebook/docusaurus/labels/enhancement) by others in the community and consider opening a pull request if you see something you want to work on. @@ -48,7 +48,7 @@ We use [GitHub Issues](https://github.com/facebook/docusaurus/issues) for our pu If you have questions about using Docusaurus, contact the Docusaurus Twitter account at [@docusaurus](https://twitter.com/docusaurus), and we will do our best to answer your questions. -You can also file issues as [feature requests or enhancements](https://github.com/facebook/docusaurus/labels/feature%20request). If you see anything you'd like to be implemented, create an issue with [feature template](https://raw.githubusercontent.com/facebook/docusaurus/master/.github/ISSUE_TEMPLATE/feature.md) +You can also file issues as [feature requests or enhancements](https://github.com/facebook/docusaurus/labels/feature). If you see anything you'd like to be implemented, create an issue with [feature template](https://raw.githubusercontent.com/facebook/docusaurus/master/.github/ISSUE_TEMPLATE/feature.md) ### Reporting security bugs diff --git a/website/docs/seo.md b/website/docs/seo.md deleted file mode 100644 index 895ac04efb..0000000000 --- a/website/docs/seo.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -id: seo -title: SEO -keywords: - - docusaurus - - seo ---- - -Docusaurus takes care of both site level SEO and page specific SEO based on the content of your site. - -Site SEO helps users reach your site. Page specific SEO helps your users find answers to their questions quickly. - -## Site level SEO - -Docusaurus' classic theme generates the essential meta tags for SEO using the site meta information you provide in `docusaurus.config.js`. For site level SEO to work correctly, make sure that you provide the following fields correctly: - -```js -// docusaurus.config.js -module.exports = { - /** - * the following two fields are used for title as well as image alt - * - `${title} · ${tagline}` - * - `Image for ${title} · ${tagline}` - */ - title: 'Docusaurus', - tagline: 'Easy to Maintain Open Source Documentation Websites', - /** - * The following fields are used for `og:image` and `twitter:image` - */ - baseUrl: '/', - siteUrl: 'https://docusaurus.io', - themeConfig: { - /** - * relative to your site's "static" directory - * cannot be svg - */ - image: 'img/docusaurus.png', - }, -}; -``` - -## Document Page specific SEO - -To add SEO to your doc, use the following fields in your doc's front matter: - -```yaml ---- -keywords: - - docs - - docusaurus -description: How do I find you when I cannot solve this problem -image: https://i.imgur.com/mErPwqL.png ---- - -``` - -### `keywords` - -- Type: `string[]` - -You may provide an array of keywords in a bullet list. Consider putting searchable terms that summarizes key information of the page to help your users find the correct page. - -### `description` - -- Type: `string` - -If you provide a description to this page, we will use this description for SEO. - -Consider putting key information about this page, error messages, searchable terms, etc., inside description to help your users land on your doc page. - -### `image` - -- Type: `string` - -`image` is used by search engines and Twitter for a cover or thumbnail image when displaying the link to your post. - -Note that the file of this image cannot be SVG. - -## Customize SEO - -To add customized SEO, use the `Head` component from `@docusaurus/Head`. - -Example: - -```js -import Head from '@docusaurus/Head'; - -const MySEO = () => ( - <> - - - - -); -``` diff --git a/website/docs/theme-classic.md b/website/docs/theme-classic.md index 9eb6a26959..b02a931dd1 100644 --- a/website/docs/theme-classic.md +++ b/website/docs/theme-classic.md @@ -11,6 +11,31 @@ title: "@docusaurus/theme-classic" To remove the ability to switch on dark mode, there is an option `themeConfig.disableDarkMode`, which is implicitly set to `false`. +```js +// docusaurus.config.js +module.exports = { + themeConfig: { + disableDarkMode: false, +} +``` + +### Meta image + +You can configure a default image that will be used for your meta tag, in particular `og:image` and `twitter:image`; + +```js +// docusaurus.config.js +module.exports = { + themeConfig: { + /** + * relative to your site's "static" directory + * cannot be svg + * can be external url too + */ + image: 'img/docusaurus.png', +} +``` + ## Navbar ### Navbar Title & Logo diff --git a/website/docs/using-plugins.md b/website/docs/using-plugins.md index ba0bd00c2e..db5df7b41a 100644 --- a/website/docs/using-plugins.md +++ b/website/docs/using-plugins.md @@ -129,7 +129,15 @@ Find the list of official Docusaurus plugins [here](https://github.com/facebook/ ### `@docusaurus/plugin-content-blog` -Provides the [Blog](blog.md) feature and is the default blog plugin for Docusaurus. The classic template ships with this plugin with default configurations. +Provides the [Blog](blog.md) feature and is the default blog plugin for Docusaurus. + +**Installation** + +```bash npm2yarn +npm install --save @docusaurus/plugin-content-blog +``` + +> 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](presets.md#docusauruspreset-classic) instead of doing it like below. ```js // docusaurus.config.js @@ -185,7 +193,15 @@ module.exports = { ### `@docusaurus/plugin-content-docs` -Provides the [Docs](markdown-features.mdx) functionality and is the default docs plugin for Docusaurus. The classic template ships with this plugin with default configurations. +Provides the [Docs](markdown-features.mdx) functionality and is the default docs plugin for Docusaurus. + +**Installation** + +```bash npm2yarn +npm install --save @docusaurus/plugin-content-docs +``` + +> 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](presets.md#docusauruspreset-classic) instead of doing it like below. ```js // docusaurus.config.js @@ -242,6 +258,14 @@ module.exports = { The default pages plugin for Docusaurus. The classic template ships with this plugin with default configurations. This plugin provides [creating pages](creating-pages.md) functionality. +**Installation** + +```bash npm2yarn +npm install --save @docusaurus/plugin-content-pages +``` + +> 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](presets.md#docusauruspreset-classic) instead of doing it like below. + ```js // docusaurus.config.js module.exports = { @@ -269,7 +293,7 @@ module.exports = { ### `@docusaurus/plugin-google-analytics` -The default [Google Analytics](https://developers.google.com/analytics/devguides/collection/analyticsjs/) plugin. +The default [Google Analytics](https://developers.google.com/analytics/devguides/collection/analyticsjs/) plugin. It is a JavaScript library for measuring how users interact with your website. **Installation** @@ -277,6 +301,8 @@ The default [Google Analytics](https://developers.google.com/analytics/devguides npm install --save @docusaurus/plugin-google-analytics ``` +> If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency. + **Configuration** ```js @@ -293,7 +319,7 @@ module.exports = { ### `@docusaurus/plugin-google-gtag` -The default [Global Site Tag (gtag.js)](https://developers.google.com/analytics/devguides/collection/gtagjs/) plugin. +The default [Global Site Tag (gtag.js)](https://developers.google.com/analytics/devguides/collection/gtagjs/) 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. **Installation** @@ -301,6 +327,8 @@ The default [Global Site Tag (gtag.js)](https://developers.google.com/analytics/ npm install --save @docusaurus/plugin-google-gtag ``` +> If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency. + **Configuration** ```js @@ -317,7 +345,15 @@ module.exports = { ### `@docusaurus/plugin-sitemap` -The classic template ships with this plugin. This plugin creates sitemap for your site so that search engine crawlers can crawl your site more accurately. +This plugin creates sitemap for your site so that search engine crawlers can crawl your site more accurately. + +**Installation** + +```bash npm2yarn +npm install --save @docusaurus/plugin-sitemap +``` + +> 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](presets.md#docusauruspreset-classic) instead of doing it like below. ```js // docusaurus.config.js diff --git a/website/docs/using-themes.md b/website/docs/using-themes.md index 7a3d5d8e8c..6dbe8ac79c 100644 --- a/website/docs/using-themes.md +++ b/website/docs/using-themes.md @@ -96,9 +96,33 @@ This will copy the current `