Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

馃槑 Get swag for migrating websites to Docusaurus 2! #1834

yangshun opened this issue Oct 12, 2019 · 77 comments

馃槑 Get swag for migrating websites to Docusaurus 2! #1834

yangshun opened this issue Oct 12, 2019 · 77 comments


Copy link

@yangshun yangshun commented Oct 12, 2019

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:


  • 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


  • 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


  • 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
  • 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


  • 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.

Copy link

@Croftyland Croftyland commented Oct 12, 2019

Copy link

@AMashoshyna AMashoshyna commented Oct 12, 2019

Hi, can I please take

Copy link

@ahmadalfy ahmadalfy commented Oct 12, 2019

I would love to claim

Copy link

@shovanmaity shovanmaity commented Oct 12, 2019

hi can I please take -

Copy link

@dtaylorbrown dtaylorbrown commented Oct 12, 2019

Copy link
Member Author

@yangshun yangshun commented Oct 12, 2019

@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!

Copy link

@diegowifi diegowifi commented Oct 12, 2019

Hi @yangshun

I would like to migrate

Copy link
Member Author

@yangshun yangshun commented Oct 12, 2019

@diegowifi Sure thing, it's yours!

@yangshun yangshun changed the title 馃専 Help us migrate websites to Docusaurus 2! 馃専 Get swag for migrating websites to Docusaurus 2! Oct 12, 2019
@yangshun yangshun changed the title 馃専 Get swag for migrating websites to Docusaurus 2! 馃槑 Get swag for migrating websites to Docusaurus 2! Oct 12, 2019
Copy link

@ThakurKarthik ThakurKarthik commented Oct 13, 2019

Hi @yangshun can i take . This will be my first issue for open source ! <3

Copy link

@ozgunbal ozgunbal commented Oct 13, 2019

Hi @yangshun I posted migration request to . I'm waiting green light from them 馃槂

Edit: After trial of local migration, I decided to help for and , too.

Copy link

@lzhuor lzhuor commented Oct 13, 2019

Hi @yangshun, may I take ? Thank you.

Copy link
Member Author

@yangshun yangshun commented Oct 13, 2019

@ThakurKarthik Great, welcome to open source! Do note that migration work is non-trivial and could be overwhelming to people who are new to open source

@ozgunbal Sure thing, thanks! I recommend you just take one first though.

@lzhuor Do you mean the entire site or just the blog? Either way, sure!

Copy link

@jesuslerma jesuslerma commented Oct 14, 2019

Hi @yangshun

I would like to migrate

Copy link

@dnafication dnafication commented Oct 15, 2019

Hi @yangshun I would like to work on
Is there any specific timeline to complete this?

@yangshun yangshun unpinned this issue Feb 24, 2020
Copy link
Member Author

@yangshun yangshun commented Feb 24, 2020

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!

facebook-github-bot added a commit to facebook/metro that referenced this issue Mar 11, 2020

Part of facebook/docusaurus#1834
Closes #525

Migrated documentation of metro to `docusaurus 2`

Website can be previewed here

In order for the publish ci to pass, `GIT_USER` needs to be set to someone with publish access in the ci config.

**Test plan**
cd website
yarn start

cc: yangshun
Pull Request resolved: #527

Reviewed By: rubennorte

Differential Revision: D20384283

Pulled By: cpojer

fbshipit-source-id: 4b7f20b0668038bad2232529970456801836b57c
Copy link

@fanny fanny commented Mar 13, 2020

facebook-github-bot added a commit to facebook/idb that referenced this issue Mar 13, 2020
Thank you for sending the PR! We appreciate you spending the time to work on these changes.

Help us understand your motivation by explaining why you decided to make this change.

You can learn more about contributing to `idb` here:

Happy contributing!


## Motivation

Migrates idb website to Docusaurus v2. This [issue](facebook/docusaurus#1834) has more information. Additionally, there are some doc fixes.

Fixes #564
Pull Request resolved: #582

Test Plan:
Try it out here:

v2 screenshot:
![Screen Shot 2020-02-22 at 11 13 06 AM](

## Related PRs


/cc yangshun

Reviewed By: lawrencelomax

Differential Revision: D20065823

Pulled By: scottilee

fbshipit-source-id: 47618972c56202caf5e720fdb9b15855d8160775
Copy link

@imrishabh18 imrishabh18 commented Apr 2, 2020

@yangshun Is any migration still left ?

Copy link

@shujathkhan shujathkhan commented May 18, 2020

Hey @yangshun is still up for grabs? Would like to take it up

Copy link

@JapneetSingh5 JapneetSingh5 commented Jul 9, 2020

Hi @yangshun, I'm currently working on migrating to v2. Are the stickers and your guidance still up for grabs? :p

Copy link

@slorber slorber commented Jul 10, 2020

Hey all, and @JapneetSingh5

We are working on a migration cli for v1->v2 migration, if you want to try it, get in touch

If you still have a v1 site to migrate, report it here: #3035

Copy link

@HeroicHitesh HeroicHitesh commented Jul 10, 2020

@slorber I am interested in contributing. Where and how can I start the migration work?

Copy link

@slorber slorber commented Jul 10, 2020

@HeroicHitesh as we are working on a migration cli, it's not worth migrating sites manually anymore. If you want to contribute to some other parts, we can get in touch on Discord

Copy link

@vj-codes vj-codes commented Aug 20, 2020

@slorber Anything still left?I would love to contribute!

Copy link

@slorber slorber commented Aug 20, 2020

Hi @vj-codes

We have many v1 sites left to migrate but they are rather complex ones. We are currently working on ReactNative website, and later this will likely be Jest. These sites are complex and will help us understand what features in v2 are missing.

I don't know exactly which easy v1 sites easy to migrate are left but if you find one or if someone ask for help here on Discord, don't hesitate ;)

Note, a first version of the migration cli has been published, but there are improvements that can be made

Copy link

@Piyush-Codes7 Piyush-Codes7 commented Nov 24, 2020

I would like take ... should i take ?

Copy link

@slorber slorber commented Nov 24, 2020

Hi @piyush-chandel

I can't tell. myself if Hacklang is interested to migrate to Docusaurus 2 so it is a good idea to ask them first.
It looks to me this is a highly customized v1 site, and it does not look like an easy one to migrate.

Copy link

@davidjgoss davidjgoss commented Jan 1, 2021

I'm keen to have a go at migrating using the migration CLI, can I claim that one?

Copy link

@slorber slorber commented Jan 4, 2021

@davidjgoss I think the excel is a bit outdated and not easy to tell if this site is good to be migrated without reaching to the maintainers.

Copy link

@davidjgoss davidjgoss commented Jan 5, 2021

@slorber thanks, I'll ask them

Copy link
Member Author

@yangshun yangshun commented May 29, 2021

I think we're done with this issue!

@yangshun yangshun closed this May 29, 2021
Copy link

@singhankit62000 singhankit62000 commented Jun 16, 2021

Hey I'd like to migrate

Copy link

@codewithpom codewithpom commented Nov 12, 2021

@yangshun Is this still active so I can help.

Copy link

@slorber slorber commented Nov 12, 2021

No this is not an active issue anymore.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet