diff --git a/website/docs/TEMPLATE.md b/website/docs/TEMPLATE.md deleted file mode 100644 index 8a78d92ad1..0000000000 --- a/website/docs/TEMPLATE.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -id: TODO -title: TODO ---- - - -#### References - -- TODO diff --git a/website/docs/plugins.md b/website/docs/advanced-plugins.md similarity index 96% rename from website/docs/plugins.md rename to website/docs/advanced-plugins.md index 7736586d11..6ebf9a49f0 100644 --- a/website/docs/plugins.md +++ b/website/docs/advanced-plugins.md @@ -1,5 +1,5 @@ --- -id: plugins +id: advanced-plugins title: Plugins --- @@ -11,7 +11,7 @@ Docusaurus Plugins are very similar to [Gatsby Plugins](https://www.gatsbyjs.org In most cases, plugins are there to fetch data and create routes. A plugin could take in components as part of its options and to act as the wrapper for the page. -## Lifecycle methods +## Lifecycle Methods @@ -26,11 +26,13 @@ For example, the in docusaurus-plugin-content-docs: In contentLoaded, for each doc Markdown file, a route is created: /doc/installation, /doc/getting-started, etc. --> -## How to create plugins +## How to Create Plugins + +_This section is a work in progress._ -## Official plugins +## Official Plugins ### `@docusaurus/plugin-content-blog` @@ -175,7 +177,7 @@ module.exports = { ### `@docusaurus/plugin-content-gtag` - +_This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640)._ ### `@docusaurus/plugin-content-sitemap` diff --git a/website/docs/advanced-presets.md b/website/docs/advanced-presets.md new file mode 100644 index 0000000000..b21907588e --- /dev/null +++ b/website/docs/advanced-presets.md @@ -0,0 +1,17 @@ +--- +id: advanced-presets +title: Presets +--- + +_This section is a work in progress._ + + diff --git a/website/docs/advanced-themes.md b/website/docs/advanced-themes.md new file mode 100644 index 0000000000..be1a9ed7cd --- /dev/null +++ b/website/docs/advanced-themes.md @@ -0,0 +1,21 @@ +--- +id: advanced-themes +title: Themes +--- + +_This section is a work in progress._ + + diff --git a/website/docs/analytics.md b/website/docs/analytics.md deleted file mode 100644 index 2de49940b6..0000000000 --- a/website/docs/analytics.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -id: analytics -title: Adding Analytics ---- - -TODO: Talk about using Google analytics and Google gtag plugins and how to track using your own plugins. diff --git a/website/docs/plugins-api.md b/website/docs/api-plugins.md similarity index 97% rename from website/docs/plugins-api.md rename to website/docs/api-plugins.md index ef373da4f7..c6f5ee6ceb 100644 --- a/website/docs/plugins-api.md +++ b/website/docs/api-plugins.md @@ -119,7 +119,3 @@ module.exports = function(context, opts) { }; }; ``` - -#### References - -- https://v1.vuepress.vuejs.org/plugin/option-api.html diff --git a/website/docs/api-themes.md b/website/docs/api-themes.md new file mode 100644 index 0000000000..e2729235c8 --- /dev/null +++ b/website/docs/api-themes.md @@ -0,0 +1,18 @@ +--- +id: themes +title: Themes +--- + +_This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640)._ + + diff --git a/website/docs/assets.md b/website/docs/assets.md deleted file mode 100644 index 6907238819..0000000000 --- a/website/docs/assets.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -id: assets -title: Using Assets ---- - -TODO: Talk about how to include static assets within pages and docs. - -### Images - -TODO: How to include images in the website and reference them from pages and docs. - -### Videos - -TODO: Show how to easily embed YouTube videos. - -#### References - -- https://v1.vuepress.vuejs.org/guide/assets.html -- https://www.gatsbyjs.org/docs/images-and-files/ diff --git a/website/docs/blog.md b/website/docs/blog.md index cebc94f324..2f9c6c849b 100644 --- a/website/docs/blog.md +++ b/website/docs/blog.md @@ -3,8 +3,15 @@ id: blog title: Blog --- -TODO: Explain how to add a blog and using the blog plugin. +_This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640)._ -#### References + diff --git a/website/docs/configuration.md b/website/docs/configuration.md index b70f2e16f2..0fedac5f20 100644 --- a/website/docs/configuration.md +++ b/website/docs/configuration.md @@ -19,32 +19,45 @@ However, it can be helpful if you have a high-level understanding of how the con The configurations can be categorized into: -- [Site meta](#site-meta) -- [Deployment configurations](#deployment-configurations) -- [Theme configurations, plugins, and presets](#theme-plugins-and-presets-configurations) -- [Custom configurations](#custom-configurations) +- [Site Metadata](#site-metadata) +- [Deployment Configurations](#deployment-configurations) +- [Theme Configurations, Plugins, and Presets](#theme-plugins-and-presets-configurations) +- [Custom Configurations](#custom-configurations) -### Site meta +### Site Metadata -Site meta contains the essential meta information such as titles and `favicon`. +Site metadata contains the essential global metadata such as titles and `favicon`. -They are used by your site app in a number of places such as your site's title and headings, browser tab icon, and SEO. +They are used by your website in a number of places such as your site's title and headings, browser tab icon, social sharing (Facebook, Twitter) information and for search engine optimization (SEO). -### Deployment configurations +### Deployment Configurations -Deployment configurations are used when you deploy your site with Docusaurus' deploy command. The related fields are: +Deployment configurations are used when you deploy your site with Docusaurus' `deploy` command. The related fields are: -You may also check the doc for [Deployment](deployment.md) for more information about the fields. +You may also check the [Deployment docs](deployment.md) for more information about the fields. -### Theme, plugins, and presets configurations +### Themes, Plugins, and Presets Configurations - +_This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640)._ -### Custom configurations + + +### Custom Configurations Docusaurus guards `docusaurus.config.js` from unknown fields. To add a custom field, define it on `customFields` @@ -60,7 +73,7 @@ module.exports = { }; ``` -## Accessing configuration from your site +## Accessing Configuration From Your Site Your configuration object will be made available to all the components of your site. And you may access them via context as `siteConfig`: @@ -73,6 +86,7 @@ const Layout = props => { const context = useDocusaurusContext(); const {siteConfig = {}} = context; const {title, tagline, seo} = siteConfig; + return ( @@ -84,3 +98,5 @@ const Layout = props => { ); }; ``` + +> 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`. diff --git a/website/docs/contributing.md b/website/docs/contributing.md new file mode 100644 index 0000000000..16f672711d --- /dev/null +++ b/website/docs/contributing.md @@ -0,0 +1,17 @@ +--- +id: contributing +title: Contributing +--- + +_This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640)._ + + diff --git a/website/docs/creating-pages.md b/website/docs/creating-pages.md index 0d239760a4..a838865691 100644 --- a/website/docs/creating-pages.md +++ b/website/docs/creating-pages.md @@ -9,7 +9,7 @@ In this section, we will learn about creating ad-hoc pages in Docusaurus using R -In the `pages` directory, create a file called `hello.js` with the following contents: +In the `src/pages` directory, create a file called `hello.js` with the following contents: ```jsx import React from 'react'; diff --git a/website/docs/deployment.md b/website/docs/deployment.md index d33a10a645..83bc6824a9 100644 --- a/website/docs/deployment.md +++ b/website/docs/deployment.md @@ -17,7 +17,7 @@ You can deploy your site to static site hosting services such as [GitHub Pages]( Docusaurus provides a easy way to publish to GitHub Pages. -### `docusaurus.config.js` settings +### `docusaurus.config.js` Settings First, modify your `docusaurus.config.js` and add the required params: @@ -65,7 +65,7 @@ There are two more optional parameters that are set as environment variables: Finally, to deploy your site to GitHub Pages, run: ```bash -GIT_USER=[yourGitHubUserName] yarn run deploy +GIT_USER= yarn run deploy ``` + +## Deployment with Netlify + +_This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640)._ diff --git a/website/docs/design-principles.md b/website/docs/design-principles.md index a487918090..34aac073b8 100644 --- a/website/docs/design-principles.md +++ b/website/docs/design-principles.md @@ -3,14 +3,28 @@ id: design-principles title: Design Principles --- -- Easy to learn but most things are still achievable by users, even if it takes them more code and more time to write. No abstractions beat bad abstractions, and we don't want users to have to hack around the wrong abstractions. Mandatory talk: Minimal API Surface Area -- Users won't feel overwhelmed when looking at the directory of a D2 project. It just makes sense and is easy to build on top of. Gatsby projects have a ton of config files - `gatsby-config.js`, `gatsby-node.js`, `gatsby-client.js`, which can look intimidating to beginners. -- We should not lock in our users to use our plugins or our CSS. Certain lower-level infra level stuff like React Loadable, React Router are fine, but not higher level ones, such as choice of Markdown engines, CSS frameworks, CSS methodology. -- The separations of concerns between each layer of our stack should be clear - well-abstracted and modular. +_This section is a work in progress._ -TODO: Explain the principles that guide the development of Docusaurus. +- Easy to learn but most things are still achievable by users, even if it takes them more code and more time to write. Not having abstractions is better than having the wrong abstractions, and we don't want users to have to hack around the wrong abstractions. Mandatory talk - [Minimal API Surface Area](https://www.youtube.com/watch?v=4anAwXYqLG8) +- Intuitive project structure - users will not feel overwhelmed when looking at the project directory of a Docusaurus project. It should look intuitive and easy to build on top of. +- The separations of concerns between each layer of our stack (content/theming/styling) should be clear - well-abstracted and modular. +- Sensible defaults - Common and popular performance optimizations and configurations will be done for users but they are given the option to override them. +- No vendor-lock in - Users are not required to use the default plugins or CSS, although they are highly encouraged to. Certain lower-level infra level stuff like React Loadable, React Router are fine, but not higher level ones, such as choice of Markdown engines, CSS frameworks, CSS methodology. -#### References +## How Docusaurus Works + + +We believe that as devlopers, 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. + + diff --git a/website/docs/docusaurus-core.md b/website/docs/docusaurus-core.md index cad05dd0b6..21ffacd161 100644 --- a/website/docs/docusaurus-core.md +++ b/website/docs/docusaurus-core.md @@ -3,8 +3,14 @@ id: docusaurus-core title: Docusaurus Core --- -TODO: Mention Docusaurus core APIs here, such as ``, ``, `prefetch`, etc. +_This section is a work in progress._ -#### References + diff --git a/website/docs/docusaurus.config.js.md b/website/docs/docusaurus.config.js.md index ce82314d43..c19e60e7ec 100644 --- a/website/docs/docusaurus.config.js.md +++ b/website/docs/docusaurus.config.js.md @@ -12,7 +12,7 @@ title: docusaurus.config.js `docusaurus.config.js` contains configurations for your site and is placed in the root directory of your site. -## Required fields +## Required Fields ### `title` @@ -95,13 +95,13 @@ module.exports = { }; ``` -## Optional fields +## Optional Fields ### `organizationName` - Type: `string` -The GitHub user or organization that owns the repository. +The GitHub user or organization that owns the repository. Used by the deployment command. ```js // docusaurus.config.js @@ -115,7 +115,7 @@ module.exports = { - Type: `string` -The name of the GitHub repository. +The name of the GitHub repository. Used by the deployment command. ```js // docusaurus.config.js @@ -214,7 +214,7 @@ Docusaurus guards `docusaurus.config.js` from unknown fields. To add a custom fi module.exports = { customFields: { admin: 'endi', - superman: 'lol' + superman: 'lol', }, }; ``` diff --git a/website/docs/how-docusaurus-works.md b/website/docs/how-docusaurus-works.md deleted file mode 100644 index 114d748d3b..0000000000 --- a/website/docs/how-docusaurus-works.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -id: TODO -title: TODO ---- - -We believe that as devlopers, 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. - -TODO: Elaborate more. - -#### References - -- https://www.gatsbyjs.org/docs/behind-the-scenes/ diff --git a/website/docs/how-to-contribute.md b/website/docs/how-to-contribute.md deleted file mode 100644 index b940968798..0000000000 --- a/website/docs/how-to-contribute.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -id: how-to-contribute -title: How to Contribute ---- - -TODO: Basically mirror the `CONTRIBUTING.md` that we have. - -#### References - -- https://reactjs.org/docs/how-to-contribute.html diff --git a/website/docs/introduction.md b/website/docs/introduction.md index bb61b3d905..7b3ba07234 100644 --- a/website/docs/introduction.md +++ b/website/docs/introduction.md @@ -18,7 +18,7 @@ This is a **very early and incomplete alpha release** of Docusaurus 2. We are ma - :x: You need a full production-ready solution (try [Docusaurus 1](https://docusaurus.io/) instead) - :x: You prefer not to work with potential breaking changes and/or features not yet working properly as we improve it during alpha period -## The next Docusaurus is coming to town +## The Next Docusaurus is Coming to Town Docusaurus @@ -70,7 +70,7 @@ We've also studied other main static site generators and would like to share our ### Gatsby -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 tries to do many things well, while Docusaurus tries to do one thing super well - be the best tool for writing and publishing content. +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. 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. @@ -78,7 +78,7 @@ Many aspects of Docusaurus 2 were inspired by the best things about Gatsby and i ### GitBook -Gitbook has very clean slate 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 doc site. As a result, many have to turn to other products. [You may read about Redux's switch to Docusaurus here](https://github.com/reduxjs/redux/issues/3161). +Gitbook has very clean slate 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 doc site. As a result, many have to turn to other products. You may read about Redux's switch to Docusaurus [here](https://github.com/reduxjs/redux/issues/3161). Currently, Gitbook is only free for open-source and non-profit teams. Docusaurus is free for everyone. diff --git a/website/docs/writing-docs.mdx b/website/docs/markdown-features.mdx similarity index 82% rename from website/docs/writing-docs.mdx rename to website/docs/markdown-features.mdx index c20e331ec5..d106e90608 100644 --- a/website/docs/writing-docs.mdx +++ b/website/docs/markdown-features.mdx @@ -1,8 +1,14 @@ --- -id: writing-docs -title: Writing Docs +id: markdown-features +title: Markdown Features --- + + 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 easily as possible. 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. @@ -11,7 +17,7 @@ In this section, we'd like to introduce you to the tools we've picked that we be **Note:** All the following content assumes you are using `docusaurus-preset-classic`. -## Using Markdown +--- Markdown is a syntax that enables you to write formatted content in an easy-to-use syntax. The [standard Markdown syntax](https://daringfireball.net/projects/markdown/syntax) is supported and we use [MDX](https://mdxjs.com/) as the parsing engine, which can do much more than just parsing Markdown. More on that later. @@ -84,45 +90,7 @@ The headers are well-spaced so that the hierarchy is clear. -## Sidebar - -To generate a sidebar to your Docusaurus site, you need to define a file that exports a JS module and pass that into `docusaurus-plugin-docs` directly or via the `docusaurus-preset-classic`. If you are using the classic preset, you can find the `sidebars.js` under the root directory already created for you, so you may edit it directly for customization. - - - -```bash -website # root directory of your site -├── docs -│   └── greeting.md -├── docusaurus.config.js -├── sidebars.js -. -``` - -To add a doc to the sidebar, add the `id` specified in the frontmatter of the doc into its category. - -```diff -module.exports = { - docs: { -+ "Getting started": ["greeting"], - "Docusaurus": ["doc1"], - "First Category": ["doc2"], - "Second Category": ["doc3"], - } -}; -``` - -The `docs` key in the file is just the name of that particular sidebar hierarchy, and can be renamed to something else. You can have multiple sidebars for different Markdown files by adding more top-level keys to the exported object. - - - - - -## Embedding React Components +### Embedding React Components Docusaurus has built-in support for [MDX](https://mdxjs.com), which allows you to write JSX within your Markdown files and render them as React components. @@ -173,7 +141,7 @@ I can write **Markdown** alongside my _JSX_! You can also import your own components defined in other files or third-party components installed via npm! Check out the [MDX docs](https://mdxjs.com/) to see what other fancy stuff you can do with MDX. -## Syntax Highlighting +### Syntax Highlighting Code blocks are text blocks wrapped around by strings of 3 backticks. You may check out [this reference](https://github.com/mdx-js/specification) for specifications of MDX. @@ -191,7 +159,7 @@ console.log('Every repo must come with a mascot.'); **Work in Progress** Currently the Prism theme we use is [Night Owl](https://github.com/FormidableLabs/prism-react-renderer/blob/master/themes/nightOwl.js). We will support customized theme in a future version. -## Interactive Coding Editor +### Interactive Coding Editor (Powered by [React Live](https://github.com/FormidableLabs/react-live)) diff --git a/website/docs/markdown.md b/website/docs/markdown.md deleted file mode 100644 index 6e307b1608..0000000000 --- a/website/docs/markdown.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -id: markdown -title: Markdown Features ---- - - -#### References - -- TODO diff --git a/website/docs/presets.md b/website/docs/presets.md deleted file mode 100644 index 8055db4525..0000000000 --- a/website/docs/presets.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -id: presets -title: Presets ---- - -TODO: Explain what presets are. - -## Using Presets - -TODO: How to use presets and build your own ones to share with others. - -## Official Presets - -TODO: List them out and explain. - -#### References - -- https://babeljs.io/docs/en/presets diff --git a/website/docs/reaching-users.md b/website/docs/reaching-users.md new file mode 100644 index 0000000000..8ed5c28887 --- /dev/null +++ b/website/docs/reaching-users.md @@ -0,0 +1,48 @@ +--- +id: reaching-users +title: Reaching Users +--- + +## Search + +_This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640)._ + + + +## SEO + +_This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640)._ + + + +## Analytics + +_This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640)._ + + diff --git a/website/docs/search.md b/website/docs/search.md deleted file mode 100644 index 9204547dfe..0000000000 --- a/website/docs/search.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -id: search -title: Adding Search ---- - -TODO: Talk about how to add Algolia search and offline search via the search plugin (TBD). - -#### References - -- https://docusaurus.io/docs/en/search diff --git a/website/docs/sidebar.md b/website/docs/sidebar.md new file mode 100644 index 0000000000..835ff24ea3 --- /dev/null +++ b/website/docs/sidebar.md @@ -0,0 +1,45 @@ +--- +id: sidebar +title: Sidebar +--- + +To generate a sidebar to your Docusaurus site, you need to define a file that exports a JS module and pass that into `docusaurus-plugin-docs` directly or via the `docusaurus-preset-classic`. If you are using the classic preset, you can find the `sidebars.js` under the root directory already created for you, so you may edit it directly for customization. + + + +```bash +website # root directory of your site +├── docs +│   └── greeting.md +├── docusaurus.config.js +├── sidebars.js +. +``` + +To add a doc to the sidebar, add the `id` specified in the frontmatter of the doc into its category. + +```diff +module.exports = { + docs: { ++ "Getting started": ["greeting"], + "Docusaurus": ["doc1"], + "First Category": ["doc2"], + "Second Category": ["doc3"], + } +}; +``` + +The `docs` key in the file is just the name of that particular sidebar hierarchy, and can be renamed to something else. You can have multiple sidebars for different Markdown files by adding more top-level keys to the exported object. + +## Subcategories + +_This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640)._ + + diff --git a/website/docs/static-assets.md b/website/docs/static-assets.md new file mode 100644 index 0000000000..55688c1114 --- /dev/null +++ b/website/docs/static-assets.md @@ -0,0 +1,17 @@ +--- +id: static-assets +title: Static Assets +--- + +_This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640)._ + +A "how-to" guide on including static assets within pages and docs. + + diff --git a/website/docs/styling-layout.md b/website/docs/styling-layout.md index c09f248d29..61d5452151 100644 --- a/website/docs/styling-layout.md +++ b/website/docs/styling-layout.md @@ -3,17 +3,40 @@ id: styling-layout title: Styling and Layout --- -## Styling your site with Infima +## Traditional CSS -The classic template of Docusaurus uses [Infima](https://infima-dev.netlify.com/) as the underlying styling framework. Infima provides powerful and flexible layout and styling for content-centric websites. For more details of Infima, check out [Infima docs](https://infima-dev.netlify.com/). +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. -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 `custom.css` file under your site's `/css` directory: +```diff +// docusaurus.config.js +module.exports = { + // ... + presets: [ + [ + '@docusaurus/preset-classic', + { ++ theme: { ++ customCss: require.resolve('./src/css/custom.css'), ++ }, + }, + ], + ], +}; +``` + +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. + +## Styling your Site with Infima + +`@docusaurus/preset-classic` uses [Infima CSS](https://infima-dev.netlify.com/) as the underlying styling framework. Infima provides powerful and flexible layout and styling suitable for content-centric websites. For more details of Infima, check out [Infima docs](https://infima-dev.netlify.com/). + +When you `init` your Docusaurus 2 project, the website will be generated with basic Infima stylesheets and default styling. You may customize the styling by editing the `src/css/custom.css` file. ```css /** - * /css/custom.css - * You can override the default Infima variables here. - * this is not a complete list of --ifm- variables + * src/css/custom.css + * You can override the default Infima variables here. + * Note: this is not a complete list of --ifm- variables. */ :root { --ifm-color-primary: #25c2a0; @@ -28,27 +51,69 @@ When you `init` your Docusaurus 2 project, the website will be generated with ba -## Styling your components +## Styling Approaches -Your whole Docusaurus 2 site is a React app. Any styling that works with React will work with your site. +A Docusaurus site is a single-page React application. You can style it the way you style React apps. -Component styling can be particularly useful when you wish to customize or swizzle a component. And there are a few frameworks we recommend that work particularly well with components. +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. -### With CSS Modules +### Global Styles -To style your components using CSS Modules, name your stylesheets as `xxx.module.css`. The build step will pick up such files as CSS Module stylesheets. Then, you may get the generated class names from the module: +This is the most traditional way of styling that most developers (including non-front end developers) would be familiar with. -```js -import styles from './styles.module.css'; +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. -export default () => ( -
-

Hello!

-
My doc
-
-); +```css +/* src/css/custom.css */ +.purple-text { + color: rebeccapurple; +} ``` -### With CSS-in-JS Frameworks +```jsx +function MyComponent() { + return ( +
+

Purple Heading!

+
+ ); +} +``` -This section is a work in progress. [Welcoming PRs](https://github.com/facebook/Docusaurus/pulls). +### CSS Modules + +To style your components using [CSS Modules](https://github.com/css-modules/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](https://facebook.github.io/create-react-app/docs/adding-a-css-modules-stylesheet). + +```css +/* styles.module.css */ +.main { + padding: 12px; +} + +.heading { + font-weight: bold; +} + +.contents { + color: #ccc; +} +``` + +```jsx +import styles from './styles.module.css'; + +function MyComponent() { + return ( +
+

Hello!

+
Lorem Ipsum
+
+ ); +} +``` + +The class names which will be processed by webpack into a globally unique class name during build. + +### CSS-in-JS + +_This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640)._ diff --git a/website/docs/themes.md b/website/docs/themes.md deleted file mode 100644 index a7782995e4..0000000000 --- a/website/docs/themes.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -id: themes -title: Themes ---- - -TODO: Explain what themes are. - -## What are Themes for? - -TODO - -## How to Create Themes - -TODO - -## Official Themes - -TODO - -#### References - -- https://v1.vuepress.vuejs.org/theme/ diff --git a/website/docs/using-plugins.md b/website/docs/using-plugins.md index 12a627e6e1..40b42f773f 100644 --- a/website/docs/using-plugins.md +++ b/website/docs/using-plugins.md @@ -5,38 +5,46 @@ title: Using Plugins -Plugins are the building blocks for Docusaurus 2 sites' features. Each plugin handles its own individual feature. Plugins may work together as [presets](./presets.md). +Plugins are the building blocks which add features to a Docusaurus 2 site. Each plugin handles its own individual feature. Plugins may work be bundled together and distributed via [presets](advanced-presets.md). -Docusaurus 2 provides a few essential plugins such as [sitemap](#docusaurus-plugin-content-sitemap), [analytics](#docusaurus-plugin-content-analytics). And you may write your own plugins for customized features. +Docusaurus 2 provides a few essential plugins such as [Google Analytics](#docusaurus-plugin-content-analytics) and [Sitemap](#docusaurus-plugin-content-sitemap). You may also write your own plugins for customized features. -In this doc, we talk about how to use plugins with Docusaurus' official plugins. To learn about the design implementation and how to write your own plugins, check out [Advanced Guides: Plugins](./plugins.md). For API reference, check out [API Reference: Plugins]('./plugins-api.md). +In this doc, we talk about how to use plugins with Docusaurus' official plugins. To learn about the design implementation and how to write your own plugins, check out [Advanced Guides: Plugins](advanced-plugins.md). For API reference, check out [API Reference: Plugins](api-plugins.md). -## Using plugins +## Using Plugins To use a plugin, add the plugin to the `plugins` field of your `docusaurus.config.js`. -For some plugins, providing just the plugin name is sufficient. For plugins that require options, specify the plugin in a `['plugin-name', options]` array. +For the most basic usage of plugins, you can providing just the plugin name or the absolute path to the plugin. For plugins that require options, specify the plugin as an array where the first value is the plugin name/path and second value is an options object, e.g. `['plugin-name', { path: 'foo/bar' }]` array. ```js // docusaurus.config.js module.exports = { plugins: [ + // Basic usage. '@docusaurus/plugin-google-analytics', - ['@docusaurus/plugin-sitemap', opts.sitemap], + + // With options object. + [ + '@docusaurus/plugin-sitemap', + { + cacheTime: 600 * 1000, + }, + ], ], }; ``` -## Passing options to Docusaurus plugins +## Passing Options to Docusaurus Plugins Within Preset -Docusaurus' classic template is scaffolded with the classic preset, which in turn includes the following official plugins. You may read more about the configurations of these plugins in our [Advanced Guides: Plugins](./plugins.md). +Docusaurus' classic template is scaffolded with the classic preset, which in turn includes the following official plugins. You may read more about the configurations of these plugins in our [Advanced Guides: Plugins](advanced-plugins.md). - `@docusaurus/plugin-content-blog` - `@docusaurus/plugin-content-docs` - `@docusaurus/plugin-content-pages` -- `@docusaurus/plugin-content-analytics` -- `@docusaurus/plugin-content-gtag` -- `@docusaurus/plugin-content-sitemap` +- `@docusaurus/plugin-google-analytics` +- `@docusaurus/plugin-google-gtag` +- `@docusaurus/plugin-sitemap` If you initialized your site using the classic template, you do not have to specify them individually in your `docusaurus.config.js`. To provide the neccesary fields to certain plugins, i.e. `trackingID` of `@docusaurus/plugin-content-analytics`, pass them in the preset field. @@ -47,15 +55,19 @@ module.exports = { [ '@docusaurus/preset-classic', { + // Will be passed to @docusaurus/plugin-content-docs. docs: { sidebarPath: require.resolve('./sidebars.js'), }, + // Will be passed to @docusaurus/theme-classic. theme: { customCss: require.resolve('./src/css/custom.css'), }, + // Will be passed to @docusaurus/plugin-google-analytics. googleAnalytics: { trackingID: 'UA-000000-2', }, + ... }, ], ], diff --git a/website/docs/using-themes.md b/website/docs/using-themes.md index fe01bf4938..77176b2f35 100644 --- a/website/docs/using-themes.md +++ b/website/docs/using-themes.md @@ -3,8 +3,26 @@ id: using-themes title: Using Themes --- -TODO: Give a high-level overview about themes and what they can be used for. +_This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640)._ -#### References + diff --git a/website/sidebars.js b/website/sidebars.js index 3edbe3ecb7..ffa68c8f62 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -1,4 +1,4 @@ -/** +/* * Copyright (c) 2017-present, Facebook, Inc. * * This source code is licensed under the MIT license found in the @@ -7,30 +7,36 @@ module.exports = { docs: { - 'Getting Started': [ + Docusaurus: [ 'introduction', - 'installation', - 'creating-pages', - 'writing-docs', - 'deployment', + /*'motivation', */ 'design-principles', + 'contributing', ], + 'Getting Started': ['installation', 'configuration'], Guides: [ - 'assets', - 'markdown', + 'creating-pages', 'styling-layout', + { + type: 'category', + label: 'Docs', + items: ['markdown-features', 'sidebar', 'static-assets'], + }, + 'blog', + 'reaching-users', 'using-plugins', 'using-themes', - 'search', - 'analytics', - 'configuration', + 'deployment', + ], + 'Advanced Guides': [ + 'advanced-plugins', + 'advanced-themes', + 'advanced-presets', ], - 'Advanced Guides': ['blog', 'plugins', 'themes', 'presets'], 'API Reference': [ 'cli', 'docusaurus-core', 'docusaurus.config.js', 'plugins-api', ], - Contributing: ['how-to-contribute', 'motivation', 'design-principles'], }, };