mirror of
https://github.com/facebook/docusaurus.git
synced 2025-05-17 19:16:58 +02:00
Website Deployment Script
parent
37374701ee
commit
4dc3a4d09e
5 changed files with 36 additions and 36 deletions
|
|
@ -1,4 +1,4 @@
|
|||
<!DOCTYPE html><html lang="en"><head><meta charSet="utf-8"/><meta http-equiv="X-UA-Compatible" content="IE=edge"/><title>Towards Docusaurus 2 · Docusaurus</title><meta name="viewport" content="width=device-width"/><meta name="generator" content="Docusaurus"/><meta name="description" content="Docusaurus was [officially announced](https://docusaurus.io/blog/2017/12/14/introducing-docusaurus) over nine months ago as a way to easily build open source documentation website. Since then, it has amassed ~8,600 GitHub Stars and is used by many popular open source projects such as [React Native](https://facebook.github.io/react-native/), [Babel](https://babeljs.io/), [Jest](https://jestjs.io/), [Reason](https://reasonml.github.io/) and [Prettier](https://prettier.io/)."/><meta name="docsearch:language" content="en"/><meta property="og:title" content="Towards Docusaurus 2 · Docusaurus"/><meta property="og:type" content="website"/><meta property="og:url" content="https://docusaurus.io/blog/2018/09/11/Towards-Docusaurus-2"/><meta property="og:description" content="Docusaurus was [officially announced](https://docusaurus.io/blog/2017/12/14/introducing-docusaurus) over nine months ago as a way to easily build open source documentation website. Since then, it has amassed ~8,600 GitHub Stars and is used by many popular open source projects such as [React Native](https://facebook.github.io/react-native/), [Babel](https://babeljs.io/), [Jest](https://jestjs.io/), [Reason](https://reasonml.github.io/) and [Prettier](https://prettier.io/)."/><meta property="og:image" content="https://docusaurus.io/img/docusaurus.png"/><meta name="twitter:card" content="summary"/><meta name="twitter:image" content="https://docusaurus.io/img/docusaurus.png"/><link rel="shortcut icon" href="/img/docusaurus.ico"/><link rel="stylesheet" href="https://cdn.jsdelivr.net/docsearch.js/1/docsearch.min.css"/><link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/atom-one-dark.min.css"/><link rel="alternate" type="application/atom+xml" href="https://docusaurus.io/blog/atom.xml" title="Docusaurus Blog ATOM Feed"/><link rel="alternate" type="application/rss+xml" href="https://docusaurus.io/blog/feed.xml" title="Docusaurus Blog RSS Feed"/><script>
|
||||
<!DOCTYPE html><html lang="en"><head><meta charSet="utf-8"/><meta http-equiv="X-UA-Compatible" content="IE=edge"/><title>Towards Docusaurus 2 · Docusaurus</title><meta name="viewport" content="width=device-width"/><meta name="generator" content="Docusaurus"/><meta name="description" content="Docusaurus was [officially announced](https://docusaurus.io/blog/2017/12/14/introducing-docusaurus) over nine months ago as a way to easily build open source documentation websites. Since then, it has amassed over 8,600 GitHub Stars, and is used by many popular open source projects such as [React Native](https://facebook.github.io/react-native/), [Babel](https://babeljs.io/), [Jest](https://jestjs.io/), [Reason](https://reasonml.github.io/) and [Prettier](https://prettier.io/)."/><meta name="docsearch:language" content="en"/><meta property="og:title" content="Towards Docusaurus 2 · Docusaurus"/><meta property="og:type" content="website"/><meta property="og:url" content="https://docusaurus.io/blog/2018/09/11/Towards-Docusaurus-2"/><meta property="og:description" content="Docusaurus was [officially announced](https://docusaurus.io/blog/2017/12/14/introducing-docusaurus) over nine months ago as a way to easily build open source documentation websites. Since then, it has amassed over 8,600 GitHub Stars, and is used by many popular open source projects such as [React Native](https://facebook.github.io/react-native/), [Babel](https://babeljs.io/), [Jest](https://jestjs.io/), [Reason](https://reasonml.github.io/) and [Prettier](https://prettier.io/)."/><meta property="og:image" content="https://docusaurus.io/img/docusaurus.png"/><meta name="twitter:card" content="summary"/><meta name="twitter:image" content="https://docusaurus.io/img/docusaurus.png"/><link rel="shortcut icon" href="/img/docusaurus.ico"/><link rel="stylesheet" href="https://cdn.jsdelivr.net/docsearch.js/1/docsearch.min.css"/><link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/atom-one-dark.min.css"/><link rel="alternate" type="application/atom+xml" href="https://docusaurus.io/blog/atom.xml" title="Docusaurus Blog ATOM Feed"/><link rel="alternate" type="application/rss+xml" href="https://docusaurus.io/blog/feed.xml" title="Docusaurus Blog RSS Feed"/><script>
|
||||
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
|
||||
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
|
||||
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
|
||||
|
|
@ -51,17 +51,17 @@
|
|||
};
|
||||
}
|
||||
});
|
||||
</script></nav></div><div class="container mainContainer postContainer blogContainer"><div class="wrapper"><div class="lonePost"><div class="post"><header class="postHeader"><h1 class="postHeaderTitle"><a href="/blog/2018/09/11/Towards-Docusaurus-2">Towards Docusaurus 2</a></h1><p class="post-meta">September 11, 2018</p><div class="authorBlock"><p class="post-authorName"><a href="https://github.com/endiliey" target="_blank" rel="noreferrer noopener">Endilie Yacop Sucipto</a>Maintainer of Docusaurus</p><div class="authorPhoto authorPhotoBig"><a href="https://github.com/endiliey" target="_blank" rel="noreferrer noopener"><img src="https://avatars1.githubusercontent.com/u/17883920?s=460&v=4" alt="Endilie Yacop Sucipto"/></a></div></div></header><div><span><p>Docusaurus was <a href="https://docusaurus.io/blog/2017/12/14/introducing-docusaurus">officially announced</a> over nine months ago as a way to easily build open source documentation website. Since then, it has amassed ~8,600 GitHub Stars and is used by many popular open source projects such as <a href="https://facebook.github.io/react-native/">React Native</a>, <a href="https://babeljs.io/">Babel</a>, <a href="https://jestjs.io/">Jest</a>, <a href="https://reasonml.github.io/">Reason</a> and <a href="https://prettier.io/">Prettier</a>.</p>
|
||||
<p>There is a saying that the very best software is constantly evolving, and the very worst isn't. In case you are not aware, we've been planning and working on Docusaurus 2 🎉.</p>
|
||||
</script></nav></div><div class="container mainContainer postContainer blogContainer"><div class="wrapper"><div class="lonePost"><div class="post"><header class="postHeader"><h1 class="postHeaderTitle"><a href="/blog/2018/09/11/Towards-Docusaurus-2">Towards Docusaurus 2</a></h1><p class="post-meta">September 11, 2018</p><div class="authorBlock"><p class="post-authorName"><a href="https://github.com/endiliey" target="_blank" rel="noreferrer noopener">Endilie Yacop Sucipto</a>Maintainer of Docusaurus</p><div class="authorPhoto authorPhotoBig"><a href="https://github.com/endiliey" target="_blank" rel="noreferrer noopener"><img src="https://avatars1.githubusercontent.com/u/17883920?s=460&v=4" alt="Endilie Yacop Sucipto"/></a></div></div></header><div><span><p>Docusaurus was <a href="https://docusaurus.io/blog/2017/12/14/introducing-docusaurus">officially announced</a> over nine months ago as a way to easily build open source documentation websites. Since then, it has amassed over 8,600 GitHub Stars, and is used by many popular open source projects such as <a href="https://facebook.github.io/react-native/">React Native</a>, <a href="https://babeljs.io/">Babel</a>, <a href="https://jestjs.io/">Jest</a>, <a href="https://reasonml.github.io/">Reason</a> and <a href="https://prettier.io/">Prettier</a>.</p>
|
||||
<p>There is a saying that the very best software is constantly evolving, and the very worst is not. In case you are not aware, we have been planning and working on the next version of Docusaurus 🎉.</p>
|
||||
<!--truncate-->
|
||||
<h2><a class="anchor" aria-hidden="true" id="introduction"></a><a href="#introduction" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Introduction</h2>
|
||||
<p>It all started with this <a href="https://github.com/facebook/Docusaurus/issues/789">RFC issue</a> opened by <a href="https://github.com/yangshun">Yangshun</a> nearing the end of June 2018.</p>
|
||||
<p>It all started with this <a href="https://github.com/facebook/Docusaurus/issues/789">RFC issue</a> opened by <a href="https://github.com/yangshun">Yangshun</a> towards the end of June 2018.</p>
|
||||
<blockquote class="embedly-card"><h4><a href="https://github.com/facebook/Docusaurus/issues/789">[RFC] Docusaurus v2 · Issue #789 · facebook/Docusaurus</a></h4><p>These are some of the problems I'm seeing in Docusaurus now and also how we can address them in v2. A number of the ideas here were inspired by VuePress and other static site generators. In the current static site generators ecosystem, t...</p></blockquote>
|
||||
<p>Since most of the problems are already mentioned in the issue, I will only go through some of the problems Docusaurus 1 faces and how we are going to address them in Docusaurus 2.</p>
|
||||
<p>Most of the suggested improvements are mentioned in the issue; I will provide details on some of issues in Docusaurus 1 and how we are going to address them in Docusaurus 2.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="infrastructure"></a><a href="#infrastructure" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Infrastructure</h2>
|
||||
<h3><a class="anchor" aria-hidden="true" id="content"></a><a href="#content" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Content</h3>
|
||||
<p>A Docusaurus 1 website is, in fact, built into a bunch of static HTML pages. Despite using React, we were not fully utilizing the features React offered, such as component state which allows for dynamic and interactive pages. React was only used as a templating engine for static content and interactivity has to be added through script tags and <code>dangerouslySetInnerHTML</code> 😱.</p>
|
||||
<p>In addition, there isn't any easy way to change how Docusaurus loads content. For example, adding CSS preprocessors such as Sass and Less was not supported natively and involved many user hacks of adding custom scripts.</p>
|
||||
<p>A Docusaurus 1 website is, in fact, built into a bunch of static HTML pages. Despite using React, we were not fully utilizing the features React offered, such as component state, which allows for dynamic and interactive pages. React was only used as a templating engine for static content and interactivity has to be added through script tags and <code>dangerouslySetInnerHTML</code> 😱.</p>
|
||||
<p>In addition, there is not an easy way to change how Docusaurus loads content. For example, adding CSS preprocessors such as Sass and Less was not supported natively and involved many user hacks of adding custom scripts.</p>
|
||||
<p>For Docusaurus 2, we will be using <a href="https://webpack.js.org/">webpack</a> as a module bundler and we are changing the way we serve content. Adding CSS preprocessors will be as easy as adding a webpack loader. Instead of a pure static HTML, <strong>during build time we will create a server-rendered version of the app</strong> and render the corresponding HTML. A Docusaurus site will be essentially an isomorphic/universal application. This approach is heavily inspired by <a href="https://github.com/gatsbyjs/gatsby">Gatsby</a>.</p>
|
||||
<h3><a class="anchor" aria-hidden="true" id="versioning"></a><a href="#versioning" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Versioning</h3>
|
||||
<p>If you have been using Docusaurus for a while, you might notice that Docusaurus creates versioned docs <strong>if and only if</strong> the docs content are <strong>different</strong>.</p>
|
||||
|
|
@ -81,13 +81,13 @@ original_id: hello
|
|||
Hello world !
|
||||
</code></pre>
|
||||
<p>However, if there are no changes to <code>hello.md</code> when cutting v2.0.0, Docusaurus will not create any versioned docs for that document. In other words, <code>versioned_docs/version-2.0.0/hello.md</code> will not exist.</p>
|
||||
<p>This is very confusing for users, if they want to edit the v2.0.0 docs, they have to edit <code>versioned_docs/version-1.0.0/hello.md</code> or manually add <code>versioned_docs/version-2.0.0/hello.md</code>. Here is a <a href="https://github.com/facebook/jest/pull/6758#issuecomment-408274413">real scenario in Jest</a>. This could potentially lead to unwanted bugs.</p>
|
||||
<p>In addition, this adds complexity within the codebase as we require a mechanism for version fallbacks. And during build time, Docusaurus has to replace the linking to the correct version. This is also the cause of <a href="https://github.com/facebook/Docusaurus/issues/845">renaming docs breaks links in old versions</a>.</p>
|
||||
<p>This can be very confusing for users; if they want to edit the v2.0.0 docs, they have to edit <code>versioned_docs/version-1.0.0/hello.md</code> or manually add <code>versioned_docs/version-2.0.0/hello.md</code>. This could potentially lead to unwanted bugs. Here is a <a href="https://github.com/facebook/jest/pull/6758#issuecomment-408274413">real scenario in Jest</a>.</p>
|
||||
<p>In addition, this adds complexity within the codebase as we require a mechanism for version fallbacks. And during build time, Docusaurus has to replace the linking to the correct version. This is also the cause of a bug where <a href="https://github.com/facebook/Docusaurus/issues/845">renaming docs breaks links in old versions</a>.</p>
|
||||
<p>For Docusaurus 2, <strong>every time we cut a new version, we will instead take a snapshot of all the docs</strong>. We will not require the content of a document to have changed. This is a space complexity trade-off for a better developer and user experience. We will use more space for better separation of concerns and guaranteed correctness.</p>
|
||||
<h3><a class="anchor" aria-hidden="true" id="translation"></a><a href="#translation" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Translation</h3>
|
||||
<p>Docusaurus allows for easy translation functionality by using <a href="https://crowdin.com/">Crowdin</a>. Documentation files written in English are uploaded to Crowdin for translation by users within a community. We always assumed that <strong>English</strong> is the default language, but this might not be the case for all users. We have seen plenty of non-English open source projects using Docusaurus.</p>
|
||||
<p>For Docusaurus 2, <strong>we will not assume English is the default language</strong>. When a user enables internationalization, they have to set a default language in <code>siteConfig.js</code>. We will then assume that all the files in <code>docs</code> are written in that language.</p>
|
||||
<p>In addition, after working on the MVP of Docusaurus 2, I realized that it is possible not to use Crowdin for translations, so we might need to add an additional workflow to enable that scenario. However, we will still strongly recommend people use Crowdin for easier integration.</p>
|
||||
<p>In addition, after working on the MVP of Docusaurus 2, I realized that it is possible not to use Crowdin for translations. Thus, we might need to add an additional workflow to enable that scenario. However, we will still strongly recommend people use Crowdin for easier integration.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="customizability"></a><a href="#customizability" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Customizability</h2>
|
||||
<h3><a class="anchor" aria-hidden="true" id="layout"></a><a href="#layout" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Layout</h3>
|
||||
<p>The current state of Docusaurus is that it is in charge of the entire layout and styling, unintentionally making it very hard for users to customize their site's appearance to their wishes.</p>
|
||||
|
|
@ -104,15 +104,15 @@ Hello world !
|
|||
<p>For Docusaurus 2, <strong>we are adding tests as we develop</strong> since we are going for a fresh rewrite. Hence, I believe that it should be more stable than ever and it should be harder to break things compared to Docusaurus 1.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="frequently-asked-questions"></a><a href="#frequently-asked-questions" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Frequently Asked Questions</h2>
|
||||
<h3><a class="anchor" aria-hidden="true" id="will-there-be-any-breaking-changes"></a><a href="#will-there-be-any-breaking-changes" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Will there be any breaking changes?</h3>
|
||||
<p>If you've read the post up until to this point, you should be able to notice that there will be breaking changes. While we will try to <strong>minimize the number of breaking changes</strong> and make it backward compatible as much as possible, we believe that some breaking changes are required. This is mostly due to <strong>major rewrite and re-architecture</strong> for Docusaurus 2.</p>
|
||||
<p>The exact list of breaking changes are not totally known yet as development is not 100% finalized. However, one thing that I'll highlight is that we will deprecate a lot of options in <code>siteConfig.js</code> and we plan to keep it as lean as possible. For example, the <code>cleanUrl</code> siteConfig will be deprecated as all the URL for Docusaurus 2 site will be without <code>.html</code> suffix.</p>
|
||||
<p>If you've read the post up until to this point, you should be able to notice that there will be breaking changes. While we will try to <strong>minimize the number of breaking changes</strong> and make it backward compatible as much as possible, we believe that some breaking changes are required. This is mostly due to Docusaurus 2 being a <strong>major rewrite and re-architecting</strong> of the codebase.</p>
|
||||
<p>The exact list of breaking changes is not totally known yet as development is not 100% finalized. However, one thing that I will highlight is that we will deprecate a lot of options in <code>siteConfig.js</code> and we plan to keep it as lean as possible. For example, the <code>cleanUrl</code> siteConfig will be deprecated as all the URL for Docusaurus 2 sites will be without the <code>.html</code> suffix.</p>
|
||||
<p>Our goal is that most sites should be able to upgrade to Docusaurus 2 without a lot of pain. We will also include a migration guide when we release Docusaurus 2. When the times come, feel free to ping us on <a href="https://discord.gg/docusaurus">Discord</a> or <a href="https://twitter.com/docusaurus">Twitter</a> for questions and help.</p>
|
||||
<h3><a class="anchor" aria-hidden="true" id="when-is-the-release-of-docusaurus-2"></a><a href="#when-is-the-release-of-docusaurus-2" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>When is the release of Docusaurus 2?</h3>
|
||||
<p>As of now, we do not have an exact date planned for the release. I personally estimate that we might be able to release an alpha version in the next one to two months, but this is of course just an estimate.</p>
|
||||
<p>As of now, we do not have an exact date planned for the release. I personally estimate that we might be able to release an alpha version in the next one to two months, but this is, of course, just an estimate.</p>
|
||||
<p>One thing that I would like to share is that while Docusaurus is part of <a href="https://opensource.fb.com/">Facebook Open Source</a> and most of the team are Facebook employees, the maintenance and development work is mostly done outside of normal working hours. I am currently a final year undergraduate student at <a href="https://twitter.com/NTUsg">NTU Singapore</a>, so I had to juggle between doing my coursework, my final year project and maintaining/developing Docusaurus. However, that does not mean that we do not want to make Docusaurus better. In fact, <strong>we want to make it as awesome as possible</strong>.</p>
|
||||
<p>For now, the actual Docusaurus 2 work is still hosted in a private repository. In the near future, we will move them into the public repository. When that time arrives, I encourage everyone to look into it and hopefully, contribute in some way. Before that, please stay tuned 😉!</p>
|
||||
<p>For now, the actual Docusaurus 2 work is still hosted in a private repository. In the near future, we will move them into the <a href="https://github.com/facebook/Docusaurus">public repository</a>. When that time arrives, I encourage everyone to look into it and hopefully contribute in some way. Before then, please stay tuned 😉!</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="final-thoughts"></a><a href="#final-thoughts" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Final Thoughts</h2>
|
||||
<p>Docusaurus has had a large impact on the open source community as seen from the <a href="https://docusaurus.io/en/users">many popular projects</a> which use Docusaurus for documentation. In order to move faster in the future, we are taking the opportunity to fix some core problems with Docusaurus 1 and striving to make Docusaurus better for everyone. In fact, it is safe to say that Docusaurus 2 is not just a plan anymore; the work on it has started and, hopefully, we will be able to see it materialize in the near future.</p>
|
||||
<p>Docusaurus has had a large impact on the open source community as seen from the <a href="https://docusaurus.io/en/users">many popular projects</a> which use Docusaurus for documentation. In order to move faster in the future, we are taking the opportunity to fix some core problems with Docusaurus 1 and striving to make Docusaurus better for everyone. In fact, it is safe to say that Docusaurus 2 is not just a plan any longer; the work on it has started and, hopefully, we will be able to see it materialize in the near future.</p>
|
||||
<p>Docusaurus' mission has always been to make it really easy for you to get a website with documentation up and running out of the box. That mission does not change with Docusaurus 2.</p>
|
||||
<p>We also want to let people know that <strong>due to work on Docusaurus 2, we will be less likely to accept new features/major changes on Docusaurus 1.</strong></p>
|
||||
<p>If you are using Docusaurus, you are part of our community; keep letting us know how we can make Docusaurus better for you. If you appreciate the work we're doing, you can support <a href="https://opencollective.com/Docusaurus">Docusaurus on Open Collective</a>.</p>
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
<!DOCTYPE html><html lang="en"><head><meta charSet="utf-8"/><meta http-equiv="X-UA-Compatible" content="IE=edge"/><title>Towards Docusaurus 2 · Docusaurus</title><meta name="viewport" content="width=device-width"/><meta name="generator" content="Docusaurus"/><meta name="description" content="Docusaurus was [officially announced](https://docusaurus.io/blog/2017/12/14/introducing-docusaurus) over nine months ago as a way to easily build open source documentation website. Since then, it has amassed ~8,600 GitHub Stars and is used by many popular open source projects such as [React Native](https://facebook.github.io/react-native/), [Babel](https://babeljs.io/), [Jest](https://jestjs.io/), [Reason](https://reasonml.github.io/) and [Prettier](https://prettier.io/)."/><meta name="docsearch:language" content="en"/><meta property="og:title" content="Towards Docusaurus 2 · Docusaurus"/><meta property="og:type" content="website"/><meta property="og:url" content="https://docusaurus.io/blog/2018/09/11/Towards-Docusaurus-2"/><meta property="og:description" content="Docusaurus was [officially announced](https://docusaurus.io/blog/2017/12/14/introducing-docusaurus) over nine months ago as a way to easily build open source documentation website. Since then, it has amassed ~8,600 GitHub Stars and is used by many popular open source projects such as [React Native](https://facebook.github.io/react-native/), [Babel](https://babeljs.io/), [Jest](https://jestjs.io/), [Reason](https://reasonml.github.io/) and [Prettier](https://prettier.io/)."/><meta property="og:image" content="https://docusaurus.io/img/docusaurus.png"/><meta name="twitter:card" content="summary"/><meta name="twitter:image" content="https://docusaurus.io/img/docusaurus.png"/><link rel="shortcut icon" href="/img/docusaurus.ico"/><link rel="stylesheet" href="https://cdn.jsdelivr.net/docsearch.js/1/docsearch.min.css"/><link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/atom-one-dark.min.css"/><link rel="alternate" type="application/atom+xml" href="https://docusaurus.io/blog/atom.xml" title="Docusaurus Blog ATOM Feed"/><link rel="alternate" type="application/rss+xml" href="https://docusaurus.io/blog/feed.xml" title="Docusaurus Blog RSS Feed"/><script>
|
||||
<!DOCTYPE html><html lang="en"><head><meta charSet="utf-8"/><meta http-equiv="X-UA-Compatible" content="IE=edge"/><title>Towards Docusaurus 2 · Docusaurus</title><meta name="viewport" content="width=device-width"/><meta name="generator" content="Docusaurus"/><meta name="description" content="Docusaurus was [officially announced](https://docusaurus.io/blog/2017/12/14/introducing-docusaurus) over nine months ago as a way to easily build open source documentation websites. Since then, it has amassed over 8,600 GitHub Stars, and is used by many popular open source projects such as [React Native](https://facebook.github.io/react-native/), [Babel](https://babeljs.io/), [Jest](https://jestjs.io/), [Reason](https://reasonml.github.io/) and [Prettier](https://prettier.io/)."/><meta name="docsearch:language" content="en"/><meta property="og:title" content="Towards Docusaurus 2 · Docusaurus"/><meta property="og:type" content="website"/><meta property="og:url" content="https://docusaurus.io/blog/2018/09/11/Towards-Docusaurus-2"/><meta property="og:description" content="Docusaurus was [officially announced](https://docusaurus.io/blog/2017/12/14/introducing-docusaurus) over nine months ago as a way to easily build open source documentation websites. Since then, it has amassed over 8,600 GitHub Stars, and is used by many popular open source projects such as [React Native](https://facebook.github.io/react-native/), [Babel](https://babeljs.io/), [Jest](https://jestjs.io/), [Reason](https://reasonml.github.io/) and [Prettier](https://prettier.io/)."/><meta property="og:image" content="https://docusaurus.io/img/docusaurus.png"/><meta name="twitter:card" content="summary"/><meta name="twitter:image" content="https://docusaurus.io/img/docusaurus.png"/><link rel="shortcut icon" href="/img/docusaurus.ico"/><link rel="stylesheet" href="https://cdn.jsdelivr.net/docsearch.js/1/docsearch.min.css"/><link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/atom-one-dark.min.css"/><link rel="alternate" type="application/atom+xml" href="https://docusaurus.io/blog/atom.xml" title="Docusaurus Blog ATOM Feed"/><link rel="alternate" type="application/rss+xml" href="https://docusaurus.io/blog/feed.xml" title="Docusaurus Blog RSS Feed"/><script>
|
||||
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
|
||||
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
|
||||
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
|
||||
|
|
@ -51,17 +51,17 @@
|
|||
};
|
||||
}
|
||||
});
|
||||
</script></nav></div><div class="container mainContainer postContainer blogContainer"><div class="wrapper"><div class="lonePost"><div class="post"><header class="postHeader"><h1 class="postHeaderTitle"><a href="/blog/2018/09/11/Towards-Docusaurus-2">Towards Docusaurus 2</a></h1><p class="post-meta">September 11, 2018</p><div class="authorBlock"><p class="post-authorName"><a href="https://github.com/endiliey" target="_blank" rel="noreferrer noopener">Endilie Yacop Sucipto</a>Maintainer of Docusaurus</p><div class="authorPhoto authorPhotoBig"><a href="https://github.com/endiliey" target="_blank" rel="noreferrer noopener"><img src="https://avatars1.githubusercontent.com/u/17883920?s=460&v=4" alt="Endilie Yacop Sucipto"/></a></div></div></header><div><span><p>Docusaurus was <a href="https://docusaurus.io/blog/2017/12/14/introducing-docusaurus">officially announced</a> over nine months ago as a way to easily build open source documentation website. Since then, it has amassed ~8,600 GitHub Stars and is used by many popular open source projects such as <a href="https://facebook.github.io/react-native/">React Native</a>, <a href="https://babeljs.io/">Babel</a>, <a href="https://jestjs.io/">Jest</a>, <a href="https://reasonml.github.io/">Reason</a> and <a href="https://prettier.io/">Prettier</a>.</p>
|
||||
<p>There is a saying that the very best software is constantly evolving, and the very worst isn't. In case you are not aware, we've been planning and working on Docusaurus 2 🎉.</p>
|
||||
</script></nav></div><div class="container mainContainer postContainer blogContainer"><div class="wrapper"><div class="lonePost"><div class="post"><header class="postHeader"><h1 class="postHeaderTitle"><a href="/blog/2018/09/11/Towards-Docusaurus-2">Towards Docusaurus 2</a></h1><p class="post-meta">September 11, 2018</p><div class="authorBlock"><p class="post-authorName"><a href="https://github.com/endiliey" target="_blank" rel="noreferrer noopener">Endilie Yacop Sucipto</a>Maintainer of Docusaurus</p><div class="authorPhoto authorPhotoBig"><a href="https://github.com/endiliey" target="_blank" rel="noreferrer noopener"><img src="https://avatars1.githubusercontent.com/u/17883920?s=460&v=4" alt="Endilie Yacop Sucipto"/></a></div></div></header><div><span><p>Docusaurus was <a href="https://docusaurus.io/blog/2017/12/14/introducing-docusaurus">officially announced</a> over nine months ago as a way to easily build open source documentation websites. Since then, it has amassed over 8,600 GitHub Stars, and is used by many popular open source projects such as <a href="https://facebook.github.io/react-native/">React Native</a>, <a href="https://babeljs.io/">Babel</a>, <a href="https://jestjs.io/">Jest</a>, <a href="https://reasonml.github.io/">Reason</a> and <a href="https://prettier.io/">Prettier</a>.</p>
|
||||
<p>There is a saying that the very best software is constantly evolving, and the very worst is not. In case you are not aware, we have been planning and working on the next version of Docusaurus 🎉.</p>
|
||||
<!--truncate-->
|
||||
<h2><a class="anchor" aria-hidden="true" id="introduction"></a><a href="#introduction" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Introduction</h2>
|
||||
<p>It all started with this <a href="https://github.com/facebook/Docusaurus/issues/789">RFC issue</a> opened by <a href="https://github.com/yangshun">Yangshun</a> nearing the end of June 2018.</p>
|
||||
<p>It all started with this <a href="https://github.com/facebook/Docusaurus/issues/789">RFC issue</a> opened by <a href="https://github.com/yangshun">Yangshun</a> towards the end of June 2018.</p>
|
||||
<blockquote class="embedly-card"><h4><a href="https://github.com/facebook/Docusaurus/issues/789">[RFC] Docusaurus v2 · Issue #789 · facebook/Docusaurus</a></h4><p>These are some of the problems I'm seeing in Docusaurus now and also how we can address them in v2. A number of the ideas here were inspired by VuePress and other static site generators. In the current static site generators ecosystem, t...</p></blockquote>
|
||||
<p>Since most of the problems are already mentioned in the issue, I will only go through some of the problems Docusaurus 1 faces and how we are going to address them in Docusaurus 2.</p>
|
||||
<p>Most of the suggested improvements are mentioned in the issue; I will provide details on some of issues in Docusaurus 1 and how we are going to address them in Docusaurus 2.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="infrastructure"></a><a href="#infrastructure" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Infrastructure</h2>
|
||||
<h3><a class="anchor" aria-hidden="true" id="content"></a><a href="#content" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Content</h3>
|
||||
<p>A Docusaurus 1 website is, in fact, built into a bunch of static HTML pages. Despite using React, we were not fully utilizing the features React offered, such as component state which allows for dynamic and interactive pages. React was only used as a templating engine for static content and interactivity has to be added through script tags and <code>dangerouslySetInnerHTML</code> 😱.</p>
|
||||
<p>In addition, there isn't any easy way to change how Docusaurus loads content. For example, adding CSS preprocessors such as Sass and Less was not supported natively and involved many user hacks of adding custom scripts.</p>
|
||||
<p>A Docusaurus 1 website is, in fact, built into a bunch of static HTML pages. Despite using React, we were not fully utilizing the features React offered, such as component state, which allows for dynamic and interactive pages. React was only used as a templating engine for static content and interactivity has to be added through script tags and <code>dangerouslySetInnerHTML</code> 😱.</p>
|
||||
<p>In addition, there is not an easy way to change how Docusaurus loads content. For example, adding CSS preprocessors such as Sass and Less was not supported natively and involved many user hacks of adding custom scripts.</p>
|
||||
<p>For Docusaurus 2, we will be using <a href="https://webpack.js.org/">webpack</a> as a module bundler and we are changing the way we serve content. Adding CSS preprocessors will be as easy as adding a webpack loader. Instead of a pure static HTML, <strong>during build time we will create a server-rendered version of the app</strong> and render the corresponding HTML. A Docusaurus site will be essentially an isomorphic/universal application. This approach is heavily inspired by <a href="https://github.com/gatsbyjs/gatsby">Gatsby</a>.</p>
|
||||
<h3><a class="anchor" aria-hidden="true" id="versioning"></a><a href="#versioning" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Versioning</h3>
|
||||
<p>If you have been using Docusaurus for a while, you might notice that Docusaurus creates versioned docs <strong>if and only if</strong> the docs content are <strong>different</strong>.</p>
|
||||
|
|
@ -81,13 +81,13 @@ original_id: hello
|
|||
Hello world !
|
||||
</code></pre>
|
||||
<p>However, if there are no changes to <code>hello.md</code> when cutting v2.0.0, Docusaurus will not create any versioned docs for that document. In other words, <code>versioned_docs/version-2.0.0/hello.md</code> will not exist.</p>
|
||||
<p>This is very confusing for users, if they want to edit the v2.0.0 docs, they have to edit <code>versioned_docs/version-1.0.0/hello.md</code> or manually add <code>versioned_docs/version-2.0.0/hello.md</code>. Here is a <a href="https://github.com/facebook/jest/pull/6758#issuecomment-408274413">real scenario in Jest</a>. This could potentially lead to unwanted bugs.</p>
|
||||
<p>In addition, this adds complexity within the codebase as we require a mechanism for version fallbacks. And during build time, Docusaurus has to replace the linking to the correct version. This is also the cause of <a href="https://github.com/facebook/Docusaurus/issues/845">renaming docs breaks links in old versions</a>.</p>
|
||||
<p>This can be very confusing for users; if they want to edit the v2.0.0 docs, they have to edit <code>versioned_docs/version-1.0.0/hello.md</code> or manually add <code>versioned_docs/version-2.0.0/hello.md</code>. This could potentially lead to unwanted bugs. Here is a <a href="https://github.com/facebook/jest/pull/6758#issuecomment-408274413">real scenario in Jest</a>.</p>
|
||||
<p>In addition, this adds complexity within the codebase as we require a mechanism for version fallbacks. And during build time, Docusaurus has to replace the linking to the correct version. This is also the cause of a bug where <a href="https://github.com/facebook/Docusaurus/issues/845">renaming docs breaks links in old versions</a>.</p>
|
||||
<p>For Docusaurus 2, <strong>every time we cut a new version, we will instead take a snapshot of all the docs</strong>. We will not require the content of a document to have changed. This is a space complexity trade-off for a better developer and user experience. We will use more space for better separation of concerns and guaranteed correctness.</p>
|
||||
<h3><a class="anchor" aria-hidden="true" id="translation"></a><a href="#translation" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Translation</h3>
|
||||
<p>Docusaurus allows for easy translation functionality by using <a href="https://crowdin.com/">Crowdin</a>. Documentation files written in English are uploaded to Crowdin for translation by users within a community. We always assumed that <strong>English</strong> is the default language, but this might not be the case for all users. We have seen plenty of non-English open source projects using Docusaurus.</p>
|
||||
<p>For Docusaurus 2, <strong>we will not assume English is the default language</strong>. When a user enables internationalization, they have to set a default language in <code>siteConfig.js</code>. We will then assume that all the files in <code>docs</code> are written in that language.</p>
|
||||
<p>In addition, after working on the MVP of Docusaurus 2, I realized that it is possible not to use Crowdin for translations, so we might need to add an additional workflow to enable that scenario. However, we will still strongly recommend people use Crowdin for easier integration.</p>
|
||||
<p>In addition, after working on the MVP of Docusaurus 2, I realized that it is possible not to use Crowdin for translations. Thus, we might need to add an additional workflow to enable that scenario. However, we will still strongly recommend people use Crowdin for easier integration.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="customizability"></a><a href="#customizability" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Customizability</h2>
|
||||
<h3><a class="anchor" aria-hidden="true" id="layout"></a><a href="#layout" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Layout</h3>
|
||||
<p>The current state of Docusaurus is that it is in charge of the entire layout and styling, unintentionally making it very hard for users to customize their site's appearance to their wishes.</p>
|
||||
|
|
@ -104,15 +104,15 @@ Hello world !
|
|||
<p>For Docusaurus 2, <strong>we are adding tests as we develop</strong> since we are going for a fresh rewrite. Hence, I believe that it should be more stable than ever and it should be harder to break things compared to Docusaurus 1.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="frequently-asked-questions"></a><a href="#frequently-asked-questions" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Frequently Asked Questions</h2>
|
||||
<h3><a class="anchor" aria-hidden="true" id="will-there-be-any-breaking-changes"></a><a href="#will-there-be-any-breaking-changes" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Will there be any breaking changes?</h3>
|
||||
<p>If you've read the post up until to this point, you should be able to notice that there will be breaking changes. While we will try to <strong>minimize the number of breaking changes</strong> and make it backward compatible as much as possible, we believe that some breaking changes are required. This is mostly due to <strong>major rewrite and re-architecture</strong> for Docusaurus 2.</p>
|
||||
<p>The exact list of breaking changes are not totally known yet as development is not 100% finalized. However, one thing that I'll highlight is that we will deprecate a lot of options in <code>siteConfig.js</code> and we plan to keep it as lean as possible. For example, the <code>cleanUrl</code> siteConfig will be deprecated as all the URL for Docusaurus 2 site will be without <code>.html</code> suffix.</p>
|
||||
<p>If you've read the post up until to this point, you should be able to notice that there will be breaking changes. While we will try to <strong>minimize the number of breaking changes</strong> and make it backward compatible as much as possible, we believe that some breaking changes are required. This is mostly due to Docusaurus 2 being a <strong>major rewrite and re-architecting</strong> of the codebase.</p>
|
||||
<p>The exact list of breaking changes is not totally known yet as development is not 100% finalized. However, one thing that I will highlight is that we will deprecate a lot of options in <code>siteConfig.js</code> and we plan to keep it as lean as possible. For example, the <code>cleanUrl</code> siteConfig will be deprecated as all the URL for Docusaurus 2 sites will be without the <code>.html</code> suffix.</p>
|
||||
<p>Our goal is that most sites should be able to upgrade to Docusaurus 2 without a lot of pain. We will also include a migration guide when we release Docusaurus 2. When the times come, feel free to ping us on <a href="https://discord.gg/docusaurus">Discord</a> or <a href="https://twitter.com/docusaurus">Twitter</a> for questions and help.</p>
|
||||
<h3><a class="anchor" aria-hidden="true" id="when-is-the-release-of-docusaurus-2"></a><a href="#when-is-the-release-of-docusaurus-2" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>When is the release of Docusaurus 2?</h3>
|
||||
<p>As of now, we do not have an exact date planned for the release. I personally estimate that we might be able to release an alpha version in the next one to two months, but this is of course just an estimate.</p>
|
||||
<p>As of now, we do not have an exact date planned for the release. I personally estimate that we might be able to release an alpha version in the next one to two months, but this is, of course, just an estimate.</p>
|
||||
<p>One thing that I would like to share is that while Docusaurus is part of <a href="https://opensource.fb.com/">Facebook Open Source</a> and most of the team are Facebook employees, the maintenance and development work is mostly done outside of normal working hours. I am currently a final year undergraduate student at <a href="https://twitter.com/NTUsg">NTU Singapore</a>, so I had to juggle between doing my coursework, my final year project and maintaining/developing Docusaurus. However, that does not mean that we do not want to make Docusaurus better. In fact, <strong>we want to make it as awesome as possible</strong>.</p>
|
||||
<p>For now, the actual Docusaurus 2 work is still hosted in a private repository. In the near future, we will move them into the public repository. When that time arrives, I encourage everyone to look into it and hopefully, contribute in some way. Before that, please stay tuned 😉!</p>
|
||||
<p>For now, the actual Docusaurus 2 work is still hosted in a private repository. In the near future, we will move them into the <a href="https://github.com/facebook/Docusaurus">public repository</a>. When that time arrives, I encourage everyone to look into it and hopefully contribute in some way. Before then, please stay tuned 😉!</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="final-thoughts"></a><a href="#final-thoughts" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Final Thoughts</h2>
|
||||
<p>Docusaurus has had a large impact on the open source community as seen from the <a href="https://docusaurus.io/en/users">many popular projects</a> which use Docusaurus for documentation. In order to move faster in the future, we are taking the opportunity to fix some core problems with Docusaurus 1 and striving to make Docusaurus better for everyone. In fact, it is safe to say that Docusaurus 2 is not just a plan anymore; the work on it has started and, hopefully, we will be able to see it materialize in the near future.</p>
|
||||
<p>Docusaurus has had a large impact on the open source community as seen from the <a href="https://docusaurus.io/en/users">many popular projects</a> which use Docusaurus for documentation. In order to move faster in the future, we are taking the opportunity to fix some core problems with Docusaurus 1 and striving to make Docusaurus better for everyone. In fact, it is safe to say that Docusaurus 2 is not just a plan any longer; the work on it has started and, hopefully, we will be able to see it materialize in the near future.</p>
|
||||
<p>Docusaurus' mission has always been to make it really easy for you to get a website with documentation up and running out of the box. That mission does not change with Docusaurus 2.</p>
|
||||
<p>We also want to let people know that <strong>due to work on Docusaurus 2, we will be less likely to accept new features/major changes on Docusaurus 1.</strong></p>
|
||||
<p>If you are using Docusaurus, you are part of our community; keep letting us know how we can make Docusaurus better for you. If you appreciate the work we're doing, you can support <a href="https://opencollective.com/Docusaurus">Docusaurus on Open Collective</a>.</p>
|
||||
|
|
|
|||
|
|
@ -14,8 +14,8 @@
|
|||
<link href="https://docusaurus.io/blog/2018/09/11/Towards-Docusaurus-2.html">
|
||||
</link>
|
||||
<updated>2018-09-11T06:00:00Z</updated>
|
||||
<summary type="html"><![CDATA[<p>Docusaurus was <a href="https://docusaurus.io/blog/2017/12/14/introducing-docusaurus">officially announced</a> over nine months ago as a way to easily build open source documentation website. Since then, it has amassed ~8,600 GitHub Stars and is used by many popular open source projects such as <a href="https://facebook.github.io/react-native/">React Native</a>, <a href="https://babeljs.io/">Babel</a>, <a href="https://jestjs.io/">Jest</a>, <a href="https://reasonml.github.io/">Reason</a> and <a href="https://prettier.io/">Prettier</a>.</p>
|
||||
<p>There is a saying that the very best software is constantly evolving, and the very worst isn't. In case you are not aware, we've been planning and working on Docusaurus 2 🎉.</p>
|
||||
<summary type="html"><![CDATA[<p>Docusaurus was <a href="https://docusaurus.io/blog/2017/12/14/introducing-docusaurus">officially announced</a> over nine months ago as a way to easily build open source documentation websites. Since then, it has amassed over 8,600 GitHub Stars, and is used by many popular open source projects such as <a href="https://facebook.github.io/react-native/">React Native</a>, <a href="https://babeljs.io/">Babel</a>, <a href="https://jestjs.io/">Jest</a>, <a href="https://reasonml.github.io/">Reason</a> and <a href="https://prettier.io/">Prettier</a>.</p>
|
||||
<p>There is a saying that the very best software is constantly evolving, and the very worst is not. In case you are not aware, we have been planning and working on the next version of Docusaurus 🎉.</p>
|
||||
]]></summary>
|
||||
<author>
|
||||
<name>Endilie Yacop Sucipto</name>
|
||||
|
|
|
|||
|
|
@ -18,8 +18,8 @@
|
|||
<link>https://docusaurus.io/blog/2018/09/11/Towards-Docusaurus-2.html</link>
|
||||
<guid>https://docusaurus.io/blog/2018/09/11/Towards-Docusaurus-2.html</guid>
|
||||
<pubDate>Tue, 11 Sep 2018 06:00:00 GMT</pubDate>
|
||||
<description><![CDATA[<p>Docusaurus was <a href="https://docusaurus.io/blog/2017/12/14/introducing-docusaurus">officially announced</a> over nine months ago as a way to easily build open source documentation website. Since then, it has amassed ~8,600 GitHub Stars and is used by many popular open source projects such as <a href="https://facebook.github.io/react-native/">React Native</a>, <a href="https://babeljs.io/">Babel</a>, <a href="https://jestjs.io/">Jest</a>, <a href="https://reasonml.github.io/">Reason</a> and <a href="https://prettier.io/">Prettier</a>.</p>
|
||||
<p>There is a saying that the very best software is constantly evolving, and the very worst isn't. In case you are not aware, we've been planning and working on Docusaurus 2 🎉.</p>
|
||||
<description><![CDATA[<p>Docusaurus was <a href="https://docusaurus.io/blog/2017/12/14/introducing-docusaurus">officially announced</a> over nine months ago as a way to easily build open source documentation websites. Since then, it has amassed over 8,600 GitHub Stars, and is used by many popular open source projects such as <a href="https://facebook.github.io/react-native/">React Native</a>, <a href="https://babeljs.io/">Babel</a>, <a href="https://jestjs.io/">Jest</a>, <a href="https://reasonml.github.io/">Reason</a> and <a href="https://prettier.io/">Prettier</a>.</p>
|
||||
<p>There is a saying that the very best software is constantly evolving, and the very worst is not. In case you are not aware, we have been planning and working on the next version of Docusaurus 🎉.</p>
|
||||
]]></description>
|
||||
</item>
|
||||
<item>
|
||||
|
|
|
|||
|
|
@ -51,8 +51,8 @@
|
|||
};
|
||||
}
|
||||
});
|
||||
</script></nav></div><div class="container mainContainer postContainer blogContainer"><div class="wrapper"><div class="posts"><div class="post"><header class="postHeader"><h1 class="postHeaderTitle"><a href="/blog/2018/09/11/Towards-Docusaurus-2">Towards Docusaurus 2</a></h1><p class="post-meta">September 11, 2018</p><div class="authorBlock"><p class="post-authorName"><a href="https://github.com/endiliey" target="_blank" rel="noreferrer noopener">Endilie Yacop Sucipto</a>Maintainer of Docusaurus</p><div class="authorPhoto authorPhotoBig"><a href="https://github.com/endiliey" target="_blank" rel="noreferrer noopener"><img src="https://avatars1.githubusercontent.com/u/17883920?s=460&v=4" alt="Endilie Yacop Sucipto"/></a></div></div></header><article class="post-content"><div><span><p>Docusaurus was <a href="https://docusaurus.io/blog/2017/12/14/introducing-docusaurus">officially announced</a> over nine months ago as a way to easily build open source documentation website. Since then, it has amassed ~8,600 GitHub Stars and is used by many popular open source projects such as <a href="https://facebook.github.io/react-native/">React Native</a>, <a href="https://babeljs.io/">Babel</a>, <a href="https://jestjs.io/">Jest</a>, <a href="https://reasonml.github.io/">Reason</a> and <a href="https://prettier.io/">Prettier</a>.</p>
|
||||
<p>There is a saying that the very best software is constantly evolving, and the very worst isn't. In case you are not aware, we've been planning and working on Docusaurus 2 🎉.</p>
|
||||
</script></nav></div><div class="container mainContainer postContainer blogContainer"><div class="wrapper"><div class="posts"><div class="post"><header class="postHeader"><h1 class="postHeaderTitle"><a href="/blog/2018/09/11/Towards-Docusaurus-2">Towards Docusaurus 2</a></h1><p class="post-meta">September 11, 2018</p><div class="authorBlock"><p class="post-authorName"><a href="https://github.com/endiliey" target="_blank" rel="noreferrer noopener">Endilie Yacop Sucipto</a>Maintainer of Docusaurus</p><div class="authorPhoto authorPhotoBig"><a href="https://github.com/endiliey" target="_blank" rel="noreferrer noopener"><img src="https://avatars1.githubusercontent.com/u/17883920?s=460&v=4" alt="Endilie Yacop Sucipto"/></a></div></div></header><article class="post-content"><div><span><p>Docusaurus was <a href="https://docusaurus.io/blog/2017/12/14/introducing-docusaurus">officially announced</a> over nine months ago as a way to easily build open source documentation websites. Since then, it has amassed over 8,600 GitHub Stars, and is used by many popular open source projects such as <a href="https://facebook.github.io/react-native/">React Native</a>, <a href="https://babeljs.io/">Babel</a>, <a href="https://jestjs.io/">Jest</a>, <a href="https://reasonml.github.io/">Reason</a> and <a href="https://prettier.io/">Prettier</a>.</p>
|
||||
<p>There is a saying that the very best software is constantly evolving, and the very worst is not. In case you are not aware, we have been planning and working on the next version of Docusaurus 🎉.</p>
|
||||
</span></div><div class="read-more"><a class="button" href="/blog/2018/09/11/Towards-Docusaurus-2">Read More</a></div></article></div><div class="post"><header class="postHeader"><h1 class="postHeaderTitle"><a href="/blog/2018/04/30/How-I-Converted-Profilo-To-Docusaurus">How I Converted Profilo to Docusaurus in Under 2 Hours</a></h1><p class="post-meta">April 30, 2018</p><div class="authorBlock"><p class="post-authorName"><a href="http://twitter.com/abernathyca" target="_blank" rel="noreferrer noopener">Christine Abernathy</a></p><div class="authorPhoto"><a href="http://twitter.com/abernathyca" target="_blank" rel="noreferrer noopener"><img src="https://graph.facebook.com/1424840234/picture/?height=200&width=200" alt="Christine Abernathy"/></a></div></div></header><article class="post-content"><div><span><blockquote>
|
||||
<p><em>“Joel and I were discussing having a website and how it would have been great to launch with it. So I challenged myself to add Docusaurus support. It took just over an hour and a half. I'm going to send you a PR with the addition so you can take a look and see if you like it. Your workflow for adding docs wouldn't be much different from editing those markdown files.”</em></p>
|
||||
<p><em>— Note sent to the Profilo team</em></p>
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue