mirror of
https://github.com/facebook/docusaurus.git
synced 2025-05-03 20:27:20 +02:00
refactor(v2): point blog plugin path to v1's blog directory
This commit is contained in:
Yangshun Tay
parent
95ca07a646
commit
b13e468b16
5 changed files with 4 additions and 414 deletions
|
|
@ -1,158 +0,0 @@
|
|||
---
|
||||
title: Introducing Docusaurus
|
||||
author: Joel Marcey
|
||||
authorURL: http://twitter.com/JoelMarcey
|
||||
authorFBID: 611217057
|
||||
authorTwitter: JoelMarcey
|
||||
---
|
||||
|
||||
|
||||
|
||||
We are very happy to introduce [Docusaurus](https://github.com/facebook/Docusaurus) to help you manage one or many open source websites.
|
||||
|
||||
We created [Docusaurus](https://docusaurus.io) for the following reasons:
|
||||
|
||||
1. To put the focus on writing good documentation instead of worrying about the infrastructure of a website.
|
||||
1. To provide features that many of our open source websites need like blog support, search and versioning.
|
||||
1. To make it easy to push updates, new features, and bug fixes to everyone all at once.
|
||||
1. And, finally, to provide a consistent look and feel across all of our open source projects.
|
||||
|
||||
<!--truncate-->
|
||||
|
||||
Docusaurus is a tool designed to make it easy for teams to publish documentation websites without having to worry about the infrastructure and design details. At its core, all a user has to provide are documentation files written in markdown, customization of a provided home page written in React, and a few configuration modifications. Docusaurus handles the rest by providing default styles, site formatting, and simple document navigation. Getting started is easy, as users can [install](https://docusaurus.io/docs/en/installation.html) it using `npm` or `yarn` via a simple initialization script that [creates a working example website out of the box](https://docusaurus.io/docs/en/site-preparation.html).
|
||||
|
||||
Docusaurus also provides core website and documentation features out-of-the-box including [blog support](https://docusaurus.io/docs/en/blog.html), [internationalization](https://docusaurus.io/docs/en/translation.html), [search](https://docusaurus.io/docs/en/search.html), and [versioning](https://docusaurus.io/docs/en/versioning.html). While some projects may not require any of these features, enabling them is generally a matter of updating configuration options instead of having to add the infrastructure from the ground up. As more features get added to Docusaurus, users just can easily update to the latest version. This can be done by simply running npm or yarn update and updating configuration options. Users or teams will no longer need to manually rework their entire website infrastructure each time a new feature gets added.
|
||||
|
||||
## The Birth of docusaurus
|
||||
|
||||
|
||||
|
||||
When Facebook first started their open source program, many teams implemented a custom website for each of their open source projects. This approach presented challenges when the open source program team was asked to help the project teams improve their documentation. Since each site was unique, adding basic infrastructure such as a blog, consistent navigation, search, etc. became challenging undertakings.
|
||||
|
||||
The open source team tried to help mitigate this problem by coming up with a standard template, based on Jekyll, that could be used as a starting point for a project website. We asked our new projects to manually copy our template source to their repo, write their docs, and publish. This template approach was adopted by most of open source projects launched; some existing projects even converted their custom website implementations to the new template as well.
|
||||
|
||||
The problem with the "copy the template to your repo" approach is that, even though the platform is consistent, pushing updates becomes unmaintainable across an entire suite of projects already using the template. This is because we lost control of the template after a project copied it to their repo. Projects were free to modify the template as desired and apply their own project-specific features to it. So while projects share the same site generation platform, they have now diverted enough where they cannot take advantage of the new features we have added to the template over time. There was no easy way we could ask all current projects to "copy" a new version of the template since it might break their existing site or remove features that they have added on their own. Instead, we would have to apply the updates manually to each project one-by-one. This became very problematic when projects started asking for our team for internationalization support within the template, requiring low-level changes to how the template was structured and generated.
|
||||
|
||||
So we started thinking about what we could do to help mitigate the challenge of keeping sites updated and consistent across our entire portfolio. We also wanted multiple projects to share the same site generation software. We wanted them to start out with the same template, and yet have the flexibility to customize and adapt their site theme to suit their needs. They should be able to extend and customize their site, but when we update the underlying infrastructure with fixes and features, the project should be able update simply and without any breaking changes.
|
||||
|
||||
Docusaurus was born!
|
||||
|
||||
At Facebook, Docusaurus allows us to quickly get different projects up and running with documentation websites, especially for teams who don't have much experience with web development or primarily want a basic site to showcase their project. Docusaurus already supports sites needing more advanced features like internationalization for Jest and versioning for React Native. As different projects request new features for their sites, they are added to Docusaurus and simultaneously provided to all projects! All together, this ends up greatly reducing the work needed to maintain different sites for different projects. Our teams are able to focus on keeping their projects healthier by spending more time adding features, fixing bugs, and writing documentation.
|
||||
|
||||
## Getting Up and Running
|
||||
|
||||
|
||||
|
||||
At its core, we wanted sites running Docusaurus to be simple to use. With one [installation](https://docusaurus.io/docs/en/installation.html) command and some simple [configuration](https://docusaurus.io/docs/en/site-preparation.html), you can actually have a default running website.
|
||||
|
||||
When you run `docusaurus-init`, you will see a structure similar to:
|
||||
|
||||
```bash
|
||||
root-of-repo
|
||||
├── docs-examples-from-docusaurus
|
||||
│ ├── doc1.md
|
||||
│ ├── doc2.md
|
||||
│ ├── doc3.md
|
||||
│ ├── exampledoc4.md
|
||||
│ └── exampledoc5.md
|
||||
├── website
|
||||
│ ├── blog-examples-from-docusaurus
|
||||
│ │ ├── 2016-03-11-blog-post.md
|
||||
│ │ └── 2017-04-10-blog-post-two.md
|
||||
│ ├── core
|
||||
│ │ └── Footer.js
|
||||
│ ├── node_modules
|
||||
│ ├── package.json
|
||||
│ ├── pages
|
||||
│ ├── sidebars.json
|
||||
│ ├── siteConfig.js
|
||||
│ └── static
|
||||
```
|
||||
|
||||
With the exception of node_modules and package.json, all the directories and files you see are where you customize and add content to your Docusaurus-based website. The docs folder is where you add your markdown that represents your documentation; the blog folder is where you add your markdown for your [blog posts](https://docusaurus.io/docs/en/blog.html); `siteConfig.js` is where you make most of the [customizations](https://docusaurus.io/docs/en/site-config.html) for your site; `sidebars.json` is where you maintain the layout and content of the [sidebar](https://docusaurus.io/docs/en/navigation.html) for your documentation; the `pages` folder is where you add [custom](https://docusaurus.io/docs/en/custom-pages.html) pages for your site; the `static` folder is where all of your static assets go (e.g., CSS stylesheets and images); and the `core` folder is where you can customize core components of the site, in this case the footer.
|
||||
|
||||
## How does Docusaurus work?
|
||||
|
||||
Docusaurus is written primarily in JavaScript and [React](https://facebook.github.io/react), replacing Jekyll which we used in the old template. We use [Remarkable](https://github.com/jonschlinkert/remarkable) for our markdown rendering and [highlight.js](https://highlightjs.org/) for our code block syntax highlighting. The core of Docusaurus' functionality is in the [lib directory](https://github.com/facebookexperimental/Docusaurus/tree/master/lib) of the [Docusaurus repo](https://github.com/facebook/Docusaurus/). The general structure looks like:
|
||||
|
||||
```bash
|
||||
root-of-Docusaurus
|
||||
├── lib
|
||||
│ ├── core
|
||||
│ ├── server
|
||||
│ │ ├── generate.js
|
||||
│ │ ├── server.js
|
||||
│ │ └── ...and more files
|
||||
│ ├── static
|
||||
│ ├── build-files.js
|
||||
│ ├── copy-examples.js
|
||||
│ ├── generate-feed.js
|
||||
│ ├── publish-gh-pages.js
|
||||
│ ├── rename-version.js
|
||||
│ ├── start-server.js
|
||||
│ ├── versions.js
|
||||
│ └── write-translations.js
|
||||
```
|
||||
|
||||
The key files here are build-files.js and start-server.js. There are many similarities between these two files: `build-files.js` is used to build the physical artifacts for serving by an external web server. `start-server.js` is used to run the Docusaurus server and locally test your site. Both go through the following general process to take all of the markdown and configuration to create a runnable website:
|
||||
|
||||
1. Process your website settings in `siteConfig.js`
|
||||
1. Read the document metadata that exists in all the markdown files in your docs directory.
|
||||
1. Create a table of contents for your documents based upon the ids extracted from the metadata.
|
||||
1. Convert the markdown to HTML, including doing link replacement.
|
||||
1. These files will go in a build/docs directory of the compiled site, and any translated versions will go into a language specific folder within the build/docs folder.
|
||||
1. Repeat 1-3 for blog posts.
|
||||
1. The blog file will go in a build/blog directory of the compiled site.
|
||||
1. Read the main.css file and concatenate any user-defined css into master css file that will be in the build/css directory of the compiled site.
|
||||
1. Copy images into an build/img directory of the compiled site.
|
||||
1. Take any custom pages that were added to the pages folder of the site and compile/copy those into the root build directory of the compiled site. Any translated versions will go into a language specific folder within build.
|
||||
1. Create CNAME and sitemap.xml files and add those to build.
|
||||
|
||||
Note that this process does not take into full account how translations or versioning works. The underlying details of those features will be saved for future blog posts.
|
||||
|
||||
The final structure of your compiled site will look similar to:
|
||||
|
||||
```bash
|
||||
build
|
||||
├── website
|
||||
│ ├── CNAME
|
||||
│ ├── blog
|
||||
│ ├── css
|
||||
│ ├── docs
|
||||
│ ├── en
|
||||
│ ├── help.html # custom page
|
||||
│ ├── img
|
||||
│ ├── index.html # landing page
|
||||
│ ├── sitemap.xml
|
||||
│ └── users.html # custom page
|
||||
```
|
||||
|
||||
## Community
|
||||
|
||||
|
||||
|
||||
We welcome your [contributions](https://github.com/facebook/Docusaurus/blob/master/CONTRIBUTING.md) to Docusaurus, whether you want to use it for your own site, you want to [contribute](https://github.com/facebook/Docusaurus/blob/master/CONTRIBUTING.md) to the Docusaurus core or just have questions. Follow us on [GitHub](https://github.com/facebook/Docusaurus) and [Twitter](https://twitter.com/docusaurus).
|
||||
|
||||
## Acknowledgements
|
||||
|
||||
Docusaurus wouldn't exist without the work of the rest of the core Docusaurus team: [Eric Nakagawa](http://twitter.com/ericnakagawa), [Hector Ramos](https://twitter.com/hectorramos), [Eric Vicenti](https://twitter.com/EricVicenti) and [Frank Li](https://github.com/deltice) — a former intern at Facebook who implemented the core technology and features.
|
||||
|
||||
Special thanks also goes out to our earliest [adopters](https://docusaurus.io/en/users.html) of Docusaurus:
|
||||
|
||||
- [BuckleScript](https://bucklescript.github.io/)
|
||||
- [FastText](https://fasttext.cc)
|
||||
- [Jest](https://jestjs.io)
|
||||
- [Make It Open](http://makeitopen.com)
|
||||
- [Prettier](https://prettier.io/)
|
||||
- [Reason-react](https://reasonml.github.io/reason-react/)
|
||||
- [React Native](https://facebook.github.io/react-native/)
|
||||
- [Relay](https://facebook.github.io/relay/)
|
||||
|
||||
Without their dedication to creating or migrating their websites over to the platform, we would have not have been in the position where we are today.
|
||||
|
||||
## Resources
|
||||
|
||||
- [Read our documentation](https://docusaurus.io)
|
||||
- [Follow our Twitter feed](https://twitter.com/docusaurus)
|
||||
- [Follow us on GitHub](https://github.com/facebook/Docusaurus)
|
||||
- [About Slash, the Docusaurus mascot](https://docusaurus.io/about-slash.html)
|
||||
|
|
@ -1,121 +0,0 @@
|
|||
---
|
||||
title: How I Converted Profilo to Docusaurus in Under 2 Hours
|
||||
author: Christine Abernathy
|
||||
authorURL: http://twitter.com/abernathyca
|
||||
authorFBID: 1424840234
|
||||
authorTwitter: abernathyca
|
||||
---
|
||||
|
||||
> *“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.”*
|
||||
>
|
||||
> *— Note sent to the Profilo team*
|
||||
|
||||
|
||||
This is the story of the rather short journey it took to create the [Profilo](https://facebookincubator.github.io/profilo/) website using Docusaurus.
|
||||
|
||||
Profilo, an Android library for collecting performance traces from production, [was announced](https://code.fb.com/android/profilo-understanding-app-performance-in-the-wild/) earlier this year. The project was [published on GitHub](https://github.com/facebookincubator/profilo/tree/802042f90f990998a272387e371b893af52465b8) with a less than [a handful or Markdown files](https://github.com/facebookincubator/profilo/tree/802042f90f990998a272387e371b893af52465b8/docs) to describe its functionality and no website to showcase any branding and highlight the logo. The task at hand was to turn these existing docs and logo into a website.
|
||||
|
||||
<!--truncate-->
|
||||
|
||||
In general, when creating a website with Docusaurus you do the following:
|
||||
|
||||
1. Generate a template website using Docusaurus scripts.
|
||||
1. Customize the generated template files for your desired site colors and your project configuration (ex: website and GitHub links).
|
||||
1. Create the website content:
|
||||
1. Add your docs and any supporting assets.
|
||||
1. Customize the default landing page provided by Docusaurus to suit your needs.
|
||||
1. Configure the default site navigation file.
|
||||
1. Publish the website and set up how it will be published for future changes.
|
||||
|
||||
Given I had pre-existing Markdown files, I didn't have to generate the core content but simply make sure that Docusaurus could process the files by adding the expected metadata to them. Most of the work would therefore consist of customizing the defaults provided by Docusaurus.
|
||||
|
||||
## Overview of Steps Taken
|
||||
|
||||
Here's an overview of the steps taken to convert to a website. I'll discuss some of the design aspects in a later section.
|
||||
|
||||
**Design and colors:**
|
||||
|
||||
1. Got all the desired logo formats from designer. I had to create the *.favicon* one.
|
||||
1. Worked out some passable primary and secondary website colors using the http://paletton.com/ tools - very handy!
|
||||
|
||||
**Initial website setup:**
|
||||
|
||||
1. Forked the [Profilo project](https://github.com/facebookincubator/profilo/) on GitHub and created a local clone of the fork to set up the website.
|
||||
1. Created the initial Docusaurus website using the [installation instructions](https://docusaurus.io/docs/en/installation.html).
|
||||
1. Deleted the `docs-examples-from-docusaurus` and `website/blog-examples-from-docusaurus` folders as these would not be needed. Profilo had existing docs we could use and there was no need for blogs at this time.
|
||||
|
||||
**Content creation:**
|
||||
|
||||
1. Added metadata to the existing Markdown files found in the `docs` folder, for example:
|
||||
|
||||
+---
|
||||
+id: architecture
|
||||
+title: Architecture
|
||||
+sidebar_label: Architecture
|
||||
+---
|
||||
|
||||
1. Added the logo assets to the `website/static/img` folder.
|
||||
1. Modified `website/pages/en/index.js`, the landing page, to highlight Profilo features.
|
||||
1. Modified `website/core/Footer.js`, the footer, to simplify it for Profilo.
|
||||
1. Edited `website/siteConfig.js` (website configuration file) to specify the previously chosen primary and secondary colors.
|
||||
1. Modified `website/sidebars.json` that specifies the sidebar navigation. Listed all the docs and customized it based on the metadata added to the Markdown files.
|
||||
1. Edited the website configuration file to specify the GitHub properties, logo images, header links, and the website link.
|
||||
1. Tested the website locally throughout this phase. (I ran `yarn start` from the `website` folder to start the server.)
|
||||
|
||||
**Feedback and review changes:**
|
||||
|
||||
1. Sent a [pull request](https://github.com/facebookincubator/profilo/pull/6) to the project.
|
||||
1. Updated the colors after the designer rightly gasped at the ones I had chosen (IANAD).
|
||||
1. Updated the colors and updated the PR.
|
||||
1. The PR was then accepted and [merged](https://github.com/facebookincubator/profilo/commit/6ad033aaf5a7d54e6d842f45a5bccd051a8e45ad). Yay!
|
||||
|
||||
**Website publishing:**
|
||||
|
||||
1. Pushed the first website version by running the Docusaurus publish script from the command line:
|
||||
|
||||
USE_SSH=true \
|
||||
GIT_USER=caabernathy \
|
||||
CURRENT_BRANCH=master \
|
||||
yarn run publish-gh-pages
|
||||
|
||||
1. Configured Circle CI using the [provided Docusaurus instructions](https://docusaurus.io/docs/en/publishing.html#automating-deployments-using-continuous-integration). There were 2 PRs for this, [the first](https://github.com/facebookincubator/profilo/pull/8)for the initial config and [the second](https://github.com/facebookincubator/profilo/pull/12) to make sure Circle CI only triggered for changes in the master branch (thanks Joel Marcey!).
|
||||
|
||||
The final website was published on https://facebookincubator.github.io/profilo/. It had taken 1.5 hours to get to the initial PR stage and another half an hour or so to respond to review feedback and publish the website.
|
||||
|
||||
## Design
|
||||
|
||||
Here's what the initial website looked like when the first pull request was sent out:
|
||||
|
||||
|
||||
|
||||
Most of the time in the content creation was spent picking colors that worked reasonably well with the given logo. These colors were a good jumping off point for designer feedback. I used Photoshop to sample various portions of the logo.
|
||||
|
||||
|
||||
|
||||
I then took the RGB representation of the color and set it as the baseline color on [Paletton](http://paletton.com/). The website then gave me various color options to try on the website by editing the Docusaurus website configuration file.
|
||||
|
||||
|
||||
|
||||
The selected primary and secondary colors were a good jumping off point for designer feedback.
|
||||
|
||||
There were also modifications made to the default website generated by Docusaurus. These changes were mainly around simplifying the footer and creating a customized landing page for Profilo that listed the project's features.
|
||||
|
||||
Here's what the final website looked like:
|
||||
|
||||
|
||||
|
||||
This is an example page showing the core content, in this case the Getting Started page:
|
||||
|
||||
|
||||
|
||||
This also shows the sidebar structure that was set up through editing `website/sidebars.json`.
|
||||
|
||||
Lastly, I didn't have to worry about handling responsive design. You get this out of the box with Docusaurus!
|
||||
|
||||
|
||||
|
||||
## Final Thoughts
|
||||
|
||||
The Profilo engineers were happy to see that they didn't have to change their workflow to update existing content. They were able to continue working with Markdown files. This will still be true in the future if new docs are added, although there may be some config changes needed if the sidebar navigation needs to be updated.
|
||||
|
||||
The infrastructure provided by Docusaurus made it easy to convert Markdown files into a working website. Even though the project had only three docs, this gave Profilo a more professional look. So, it was well worth the short time investment to get it done.
|
||||
|
|
@ -1,135 +0,0 @@
|
|||
---
|
||||
title: Towards Docusaurus 2
|
||||
author: Endilie Yacop Sucipto
|
||||
authorTitle: Maintainer of Docusaurus
|
||||
authorURL: https://github.com/endiliey
|
||||
authorImageURL: https://avatars1.githubusercontent.com/u/17883920?s=460&v=4
|
||||
authorTwitter: endiliey
|
||||
---
|
||||
|
||||
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/).
|
||||
|
||||
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 🎉.
|
||||
|
||||
<!--truncate-->
|
||||
|
||||
## Introduction
|
||||
|
||||
It all started with this [RFC issue](https://github.com/facebook/Docusaurus/issues/789) opened by [Yangshun](https://github.com/yangshun) towards the end of June 2018.
|
||||
|
||||
<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>
|
||||
|
||||
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.
|
||||
|
||||
## Infrastructure
|
||||
|
||||
### Content
|
||||
|
||||
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 `dangerouslySetInnerHTML` 😱.
|
||||
|
||||
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.
|
||||
|
||||
For Docusaurus 2, we will be using [webpack](https://webpack.js.org/) 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, **during build time we will create a server-rendered version of the app** and render the corresponding HTML. A Docusaurus site will be essentially an isomorphic/universal application. This approach is heavily inspired by [Gatsby](https://github.com/gatsbyjs/gatsby).
|
||||
|
||||
### Versioning
|
||||
|
||||
If you have been using Docusaurus for a while, you might notice that Docusaurus creates versioned docs **if and only if** the docs content are **different**.
|
||||
|
||||
For example, if we have `docs/hello.md`:
|
||||
|
||||
```text
|
||||
---
|
||||
id: hello
|
||||
title: hello
|
||||
---
|
||||
Hello world !
|
||||
```
|
||||
|
||||
And **we cut version 1.0.0,** Docusaurus will create `versioned_docs/version-1.0.0/hello.md`:
|
||||
|
||||
```text
|
||||
---
|
||||
id: version-1.0.0-hello
|
||||
title: hello
|
||||
original_id: hello
|
||||
---
|
||||
Hello world !
|
||||
```
|
||||
|
||||
However, if there are no changes to `hello.md` when cutting v2.0.0, Docusaurus will not create any versioned docs for that document. In other words, `versioned_docs/version-2.0.0/hello.md` will not exist.
|
||||
|
||||
This can be very confusing for users; if they want to edit the v2.0.0 docs, they have to edit `versioned_docs/version-1.0.0/hello.md` or manually add `versioned_docs/version-2.0.0/hello.md`. This could potentially lead to unwanted bugs. Here is a [real scenario in Jest](https://github.com/facebook/jest/pull/6758#issuecomment-408274413).
|
||||
|
||||
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 [renaming docs breaks links in old versions](https://github.com/facebook/Docusaurus/issues/845).
|
||||
|
||||
For Docusaurus 2, **every time we cut a new version, we will instead take a snapshot of all the docs**. 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.
|
||||
|
||||
### Translation
|
||||
|
||||
Docusaurus allows for easy translation functionality by using [Crowdin](https://crowdin.com/). Documentation files written in English are uploaded to Crowdin for translation by users within a community. We always assumed that **English** 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.
|
||||
|
||||
For Docusaurus 2, **we will not assume English is the default language**. When a user enables internationalization, they have to set a default language in `siteConfig.js`. We will then assume that all the files in `docs` are written in that language.
|
||||
|
||||
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.
|
||||
|
||||
## Customizability
|
||||
|
||||
### Layout
|
||||
|
||||
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.
|
||||
|
||||
For Docusaurus 2, **layout and styling should be controlled by the user**. Docusaurus will handle the content generation, routing, translation, and versioning. Inspired by [create-react-app](https://github.com/facebook/create-react-app) and [VuePress](https://vuepress.vuejs.org/), Docusaurus will still provide a default theme, which the user can eject from, for further layout and styling customization. This means that it is very possible for the user to even change the HTML meta by using [React Helmet](https://github.com/nfl/react-helmet). Community-based themes are also very possible. This approach of allowing users to be in charge of layout and styling is taken by most static site generators.
|
||||
|
||||
### Markdown
|
||||
|
||||
Our markdown parsing is currently powered by [Remarkable](https://github.com/jonschlinkert/remarkable). What if the user wants to use [markdown-it](https://github.com/markdown-it/markdown-it) or even [MDX](https://github.com/mdx-js/mdx)? And then there is an issue of which syntax highlighter to use, (e.g: [Prism](https://prismjs.com/) vs [Highlight.js](https://highlightjs.org/)). We should leave these choices open to the user.
|
||||
|
||||
For Docusaurus 2, **users can eject and choose their own markdown parser**. It does not matter if they want to use another markdown parser such as [Remark](https://github.com/remarkjs/remark), or even their own in-house markdown parser. As a rule of thumb, the user has to provide a React component, in which we will provide a children props containing the *RAW string of markdown*. By default, we will use Remarkable for the markdown parser and Highlight.js for the syntax highlighting. The default parser could still change in the future as we're still experimenting with different markdown parsers.
|
||||
|
||||
### Search
|
||||
|
||||
Our core search functionality is based on [Algolia](https://www.algolia.com/). There are requests by users to be able to use different search offerings, such as `lunrjs` for offline search.
|
||||
|
||||
I personally like Algolia and we have a great experience working with them. They are very responsive; we can easily submit a pull request to Algolia since their `DocSearch` is open source. For example, I recently submitted [this PR that enables DocSearch to scrape alternate languages in sitemap](https://github.com/algolia/docsearch-scraper/pull/387).
|
||||
|
||||
For Docusaurus 2, **we will allow users to customize the search box**. Users simply need to eject from the default theme and modify the Search UI (a React component). However, we will still use Algolia in the default theme.
|
||||
|
||||
## Stability
|
||||
|
||||
Software is never going to be perfect, but we want Docusaurus to not break as we add new features. When Docusaurus was first released, it did not have any strong automated test suites. As a result, there were a lot of regressions not caught early. Although we have recently added a lot of tests, the test coverage is still relatively low.
|
||||
|
||||
For Docusaurus 2, **we are adding tests as we develop** 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.
|
||||
|
||||
## Frequently Asked Questions
|
||||
|
||||
### Will there be any breaking changes?
|
||||
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 **minimize the number of breaking changes** 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 **major rewrite and re-architecting** of the codebase.
|
||||
|
||||
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 `siteConfig.js` and we plan to keep it as lean as possible. For example, the `cleanUrl` siteConfig will be deprecated as all the URL for Docusaurus 2 sites will be without the `.html` suffix.
|
||||
|
||||
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 [Discord](https://discord.gg/docusaurus) or [Twitter](https://twitter.com/docusaurus) for questions and help.
|
||||
|
||||
|
||||
### When is the release of Docusaurus 2?
|
||||
|
||||
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.
|
||||
|
||||
One thing that I would like to share is that while Docusaurus is part of [Facebook Open Source](https://opensource.fb.com/) 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 [NTU Singapore](https://twitter.com/NTUsg), 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, **we want to make it as awesome as possible**.
|
||||
|
||||
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](https://github.com/facebook/Docusaurus). When that time arrives, I encourage everyone to look into it and hopefully contribute in some way. Before then, please stay tuned 😉!
|
||||
|
||||
## Final Thoughts
|
||||
|
||||
Docusaurus has had a large impact on the open source community as seen from the [many popular projects](https://docusaurus.io/en/users) 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.
|
||||
|
||||
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.
|
||||
|
||||
We also want to let people know that **due to work on Docusaurus 2, we will be less likely to accept new features/major changes on Docusaurus 1.**
|
||||
|
||||
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 [Docusaurus on Open Collective](https://opencollective.com/Docusaurus).
|
||||
|
||||
> If you are sponsoring our work on [Open Collective](https://opencollective.com/Docusaurus), we'll personally offer you a helping hand for maintenance and upgrading of Docusaurus website.
|
||||
|
||||
Lastly, if you haven't done so already, click the **star** and **watch** button on [GitHub](https://github.com/facebook/Docusaurus), and follow us on [Twitter](https://twitter.com/docusaurus).
|
||||
|
||||
<script async src="//cdn.embedly.com/widgets/platform.js" charset="UTF-8"></script>
|
||||
|
|
@ -34,6 +34,7 @@ module.exports = {
|
|||
name: 'docusaurus-content-blog',
|
||||
options: {
|
||||
include: ['*.md', '*.mdx'],
|
||||
path: '../v1/website/blog',
|
||||
},
|
||||
},
|
||||
],
|
||||
|
|
|
|||
|
|
@ -13,6 +13,7 @@ async function genRoutesConfig({
|
|||
pagesMetadatas = [],
|
||||
contentsStore = {},
|
||||
}) {
|
||||
// Docs.
|
||||
const {docsUrl, baseUrl} = siteConfig;
|
||||
function genDocsRoute(metadata) {
|
||||
const {permalink, source} = metadata;
|
||||
|
|
@ -45,6 +46,7 @@ async function genRoutesConfig({
|
|||
.join(',')}],
|
||||
}`;
|
||||
|
||||
// Pages.
|
||||
function genPagesRoute(metadata) {
|
||||
const {permalink, source} = metadata;
|
||||
return `
|
||||
|
|
@ -66,6 +68,7 @@ async function genRoutesConfig({
|
|||
}`;
|
||||
}
|
||||
|
||||
// Blog.
|
||||
function genBlogRoute(metadata) {
|
||||
const {permalink, source} = metadata;
|
||||
if (metadata.isBlogPage) {
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue