😎 Get swag for migrating websites to Docusaurus 2!

Tip: This is a task that requires at least a few hours of commitment (can be more, depending on the website) and it targeted at people who want to learn more about Docusaurus and Open Source.

Docusaurus 2 has reached a mature alpha stage. We want to help some existing Docusaurus 1 sites migrate to Docusaurus 2. We’ve done this ourselves for Create React App (PR) and Flux (PR). But just the few of us isn’t enough. We need your help.

We have shortlisted the following sites using Docusaurus 1 which we want to migrate to Docusaurus 2: https://docs.google.com/spreadsheets/d/18SWTklRJVvOTOQEStTo8LXBc78ZMFdbdwp2EEJK5q8g/edit?usp=sharing).

Instructions

• You should be somewhat familiar with using Docusaurus before attempting the task. Otherwise, you can follow our Docusaurus 1 tutorial and Docusaurus 2 Getting Started
• Comment below to get dibs on the website you’re interested in helping to migrate. Make sure it’s not already claimed
• Find the GitHub repo to the website you want to claim
• File an issue on the GitHub project with the following details

Issue Title:

Migrate Website to Docusaurus 2 Alpha

Issue Body:

Hi there! The Docusaurus team is currently developing Docusaurus 2 and are almost done with an MVP that doesn't include translations and versioning features, which means there's feature parity with your website's current usage of Docusaurus.

Docusaurus 2 brings about many improvements:

- Client-side rendering with prerendering (site renders without JavaScript!)
- More flexible appearance - Customizable layouts, CSS modules, etc
- Embeddable interactive React components within markdown via MDX

I will be helping you migrate and be the POC throughout the migration process. Let me know what you think!

cc @yangshun @wgao19 

• If the project maintainer gives the green light, then go ahead and start the migration process

Pre-Migration

• Navigate to every page of the website and see if there’s anything special about the page (e.g. importing extra scripts)
• Look at the docs files to do a sanity check that the user didn’t add anything that Docusaurus 2 doesn’t support (e.g. custom markdown syntax)
• If there are any unsupported things, you can check back with us or ping us in the #docusaurus-1-to-2-migration Discord channel

Migration

• Follow the v1 to v2 migration guide here
• You should look at the website/siteConfig.js and address every field (either migrate it or remove it (but take note of it))
• There will probably be syntax issues in their Markdown docs that is not compatible with with Docusaurus 2’s MDX parser. Most of them should be easy to fix
• v2 uses a different CSS framework and it is not necessary to make the landing page components look exactly like v1 (referring to the call-to-action button and the footer). Most importantly is contents, then the layout. Fine-grain differences in visual appearance of individual components is acceptable and probably intended
• Do not swizzle the Footer just to add the logo on the left. The logo is intentionally removed in v2. Just configure the footer via the docusaurus.config.js’s themeConfig.footer properties.
• As long as you have the same contents you should be good
• The following code could be helpful for migration of various pages
  • Index page - Flux (recommended), Docusaurus 2, Hermes,
  • Help/Support page - Docusaurus 2, Flux
• For Docusaurus 2, we built a CSS framework called Infima. More guidance on styling can be found here
• You might want to refer to our PRs for Create React App and Flux as examples of how a migration for a basic Docusaurus v1 site can be done

Post-Migration

• Check the project’s CI to update the path of the build directory (generated files are in build/ instead of build/{projectName} in v2)
• Navigate to every page, checking for broken links and broken images
• Check that the index page and doc page look fine on mobile
• Make a PR.
  • At the minimum, you should include some screenshots
  • If possible, you can try to host the built website somewhere using hosting services like Now or GitHub pages. This step is important in giving project owners the confidence that the migration doesn’t break anything. They can click around and try the shiny migrated Docusaurus 2 website
  • List down features that were removed (due to Docusaurus 2 not supporting or whatever other reasons there may be)
  • Tag @yangshun in the PR you create, and link it to this issue so we can better track the open migration PRs
• PR gets approved and merged by project maintainer(s)
• ???
• Profit!

Thank You!

We’ll be sending Facebook Open Source stickers to contributors who successfully complete migrate a website. If you migrate 3 websites, we’ll send you a Docusaurus plushie!

P.S. Hacktoberfest is going on now and you could get a fancy free t-shirt by submitting PRs!

For any questions regarding the migration, either comment below or ask in our #docusaurus-1-to-2-migration Discord channel (preferred).

---

I’ll check in with you every once in a while on the progress. Note that it’s totally ok to unclaim a website for any reason, we understand 😊

P.S. If there’s a Docusaurus 1 website not listed here, it means we don’t have the bandwidth to support the migration. You are free to initiate a migration issue on other projects but support from the Docusaurus core team will be limited as we prioritize supporting our own projects.

[yangshun]

Hi all, as this point we have migrated most of the websites we want to and those which haven’t been migrated are not highly used and as a result not high priority. We will have another wave of migration work when we have shipped versioning and translations. Thank you everyone!

[yangshun]

@Croftyland Thanks for your enthusiasm! In general we prefer that you do one at a time so that you have a better idea of how doing one is like, and don’t end up overcommitting. It’s fine for now but feel free to let us know if it’s too much and you would like to put some websites “up for grabs”.

@AMashoshyna Definitely!

@ahmadalfy Of course! That’ll be challenging! P.S. Nice to see you again

@imazik Thanks but it has been claimed by @AMashoshyna. There are many others. Find another one?

@sshhdaniella Absolutely!