forked from facebook/docusaurus
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: create Docusaurus v2.2.0 release docs + changelog + release blo…
…g post (facebook#8265)
- Loading branch information
Showing
97 changed files
with
18,857 additions
and
1 deletion.
There are no files selected for viewing
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
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
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,123 @@ | ||
| --- | ||
| title: Docusaurus 2.2 | ||
| authors: [slorber] | ||
| tags: [release] | ||
| image: ./img/social-card.png | ||
| date: 2022-10-29 | ||
| --- | ||
|
|
||
| We are happy to announce **Docusaurus 2.2**. | ||
|
|
||
| The upgrade should be easy: as explained in our [release process documentation](/community/release-process), minor versions respect [Semantic Versioning](https://semver.org/). | ||
|
|
||
|  | ||
|
|
||
| <!--truncate--> | ||
|
|
||
| ## Highlights | ||
|
|
||
| ### Mermaid diagrams | ||
|
|
||
| In [#7490](https://github.com/facebook/docusaurus/pull/7490), we added support for Mermaid diagrams. This fills the gap between GitHub Flavored Markdown which also [added support recently](https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/). You can create Mermaid diagrams using Markdown code blocks: | ||
|
|
||
| ````md | ||
| ```mermaid | ||
| sequenceDiagram | ||
| participant Alice | ||
| participant Bob | ||
| Alice->>John: Hello John, how are you? | ||
| loop Health check | ||
| John->>John: Fight against hypochondria | ||
| end | ||
| Note right of John: Rational thoughts <br/>prevail! | ||
| John-->>Alice: Great! | ||
| John->>Bob: How about you? | ||
| Bob-->>John: Jolly good! | ||
| ``` | ||
| ```` | ||
|
|
||
| ````mdx-code-block | ||
| import BrowserWindow from '@site/src/components/BrowserWindow'; | ||
| <BrowserWindow> | ||
| ```mermaid | ||
| sequenceDiagram | ||
| participant Alice | ||
| participant Bob | ||
| Alice->>John: Hello John, how are you? | ||
| loop Health check | ||
| John->>John: Fight against hypochondria | ||
| end | ||
| Note right of John: Rational thoughts <br/>prevail! | ||
| John-->>Alice: Great! | ||
| John->>Bob: How about you? | ||
| Bob-->>John: Jolly good! | ||
| ``` | ||
| </BrowserWindow> | ||
| ```` | ||
|
|
||
| Make sure to check the [documentation](/docs/markdown-features/diagrams), and the [more advanced examples](/tests/pages/diagrams) | ||
|
|
||
| ### Config `headTags` | ||
|
|
||
| In [#8151](https://github.com/facebook/docusaurus/pull/8151), we added the ability to apply arbitrary HTML `<head>` tags to all pages of your site. | ||
|
|
||
| ```js title="docusaurus.config.js" | ||
| module.exports = { | ||
| headTags: [ | ||
| { | ||
| tagName: 'link', | ||
| attributes: { | ||
| rel: 'icon', | ||
| href: '/img/docusaurus.png', | ||
| }, | ||
| }, | ||
| ], | ||
| }; | ||
| ``` | ||
|
|
||
| ### Accessibility | ||
|
|
||
| We did several accessibility improvements: | ||
|
|
||
| - [#8207](https://github.com/facebook/docusaurus/pull/8207): improves keyboard navigation for mobile drawer hamburger button | ||
| - [#8161](https://github.com/facebook/docusaurus/pull/8161): improves keyboard navigation for tabs | ||
| - [#8204](https://github.com/facebook/docusaurus/pull/8204): makes the skip to content button support progressive enhancement | ||
| - [#8174](https://github.com/facebook/docusaurus/pull/8174): improves screen reader announcement when toggling between light/dark mode | ||
|
|
||
| ### Developer Experience | ||
|
|
||
| We made validation stricter and improved error messages: | ||
|
|
||
| - [#8234](https://github.com/facebook/docusaurus/pull/8234): in case of doc processing failure, prints the problematic markdown file path in the error message | ||
| - [#8192](https://github.com/facebook/docusaurus/pull/8192) and [#8159](https://github.com/facebook/docusaurus/pull/8159): validates `siteConfig.url` more strictly and with better error message | ||
| - [#8066](https://github.com/facebook/docusaurus/pull/8066): makes config `url` and `baseUrl` fail-safe and less sensitive to the presence or absence of a leading or trailing slash | ||
|
|
||
| ### Translations | ||
|
|
||
| We completed the default theme translation support for multiple languages: | ||
|
|
||
| - 🇹🇷 [#8105](https://github.com/facebook/docusaurus/pull/8105): completes Turkish translations | ||
| - 🇷🇺 [#8253](https://github.com/facebook/docusaurus/pull/8253): completes Russian translations | ||
| - 🇫🇷 [#8243](https://github.com/facebook/docusaurus/pull/8243): completes French translations | ||
| - 🇯🇵 [#8075](https://github.com/facebook/docusaurus/pull/8075): completes Japanese translations | ||
|
|
||
| :::tip | ||
|
|
||
| Completing theme translations is an [ongoing effort](https://github.com/facebook/docusaurus/issues/3526) and an easy way to contribute to Docusaurus. We add new theme features regularly, for which we often [need new translations](https://github.com/facebook/docusaurus/issues/3526). | ||
|
|
||
| ::: | ||
|
|
||
| ## Other changes | ||
|
|
||
| Other notable changes include: | ||
|
|
||
| - [#8210](https://github.com/facebook/docusaurus/pull/8210): the `docusaurus swizzle` CLI has a new `--config` option | ||
| - [#8109](https://github.com/facebook/docusaurus/pull/8109): mobile navigation performance optimizations, prefetch resources earlier | ||
| - [#8059](https://github.com/facebook/docusaurus/pull/8059): versions/locales navbar dropdowns preserve hash and querystring on navigation | ||
| - [#8227](https://github.com/facebook/docusaurus/pull/8227): the client redirect plugin preserves hash and querystring on redirect | ||
|
|
||
| Check the **[2.2.0 changelog entry](/changelog/2.2.0)** for an exhaustive list of changes. |
28 changes: 28 additions & 0 deletions
28
website/versioned_docs/version-2.2.0/advanced/architecture.md
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,28 @@ | ||
| --- | ||
| description: How Docusaurus works to build your app | ||
| --- | ||
|
|
||
| # Architecture | ||
|
|
||
| ```mdx-code-block | ||
| import Tabs from '@theme/Tabs'; | ||
| import TabItem from '@theme/TabItem'; | ||
| import Zoom from 'react-medium-image-zoom'; | ||
| ``` | ||
|
|
||
| <Zoom> | ||
|
|
||
|  | ||
|
|
||
| </Zoom> | ||
|
|
||
| This diagram shows how Docusaurus works to build your app. Plugins each collect their content and emit JSON data; themes provide layout components which receive the JSON data as route modules. The bundler bundles all the components and emits a server bundle and a client bundle. | ||
|
|
||
| Although you (either plugin authors or site creators) are writing JavaScript all the time, bear in mind that the JS is actually run in different environments: | ||
|
|
||
| - All plugin lifecycle methods are run in Node. Therefore, until we support ES Modules in our codebase, plugin source code must be provided as CommonJS that can be `require`'d. | ||
| - The theme code is built with Webpack. They can be provided as ESM—following React conventions. | ||
|
|
||
| Plugin code and theme code never directly import each other: they only communicate through protocols (in our case, through JSON temp files and calls to `addRoute`). A useful mental model is to imagine that the plugins are not written in JavaScript, but in another language like Rust. The only way to interact with plugins for the user is through `docusaurus.config.js`, which itself is run in Node (hence you can use `require` and pass callbacks as plugin options). | ||
|
|
||
| During bundling, the config file itself is serialized and bundled, allowing the theme to access config options like `themeConfig` or `baseUrl` through [`useDocusaurusContext()`](../docusaurus-core.md#useDocusaurusContext). However, the `siteConfig` object only contains **serializable values** (values that are preserved after `JSON.stringify()`). Functions, regexes, etc. would be lost on the client side. The `themeConfig` is designed to be entirely serializable. |
Oops, something went wrong.