Docusaurus: 😎 Get swag for migrating websites to Docusaurus 2!

[yangshun]

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

[Croftyland]

Hi, I will take

1. https://callstack.github.io/react-native-testing-library/
2. https://libspectrum.io
3. https://phyre.ai

[AMashoshyna]

Hi, can I please take https://testing-library.com/?

[ahmadalfy]

I would love to claim https://facebook.github.io/watchman/

[shovanmaity]

hi can I please take -
https://testing-library.com/

[sshhdaniella]

Hi, I would love to do: https://facebookincubator.github.io/fbt/

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

[diegowifi]

Hi @yangshun

I would like to migrate https://pybowler.io/

[yangshun]

@diegowifi Sure thing, it's yours!

[ThakurKarthik]

Hi @yangshun can i take https://fbredex.com/ . This will be my first issue for open source ! <3

[ozgunbal]

Hi @yangshun I posted migration request to https://facebook.github.io/react-360/ . I'm waiting green light from them :smiley:

Edit: After trial of local migration, I decided to help for https://www.fbidb.io/ and https://facebookincubator.github.io/profilo/ , too.

[lzhuor]

Hi @yangshun, may I take https://fasttext.cc/blog/ ? Thank you.

[yangshun]

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

[jesuslerma]

Hi @yangshun

I would like to migrate https://www.fbidb.io

[dnafication]

Hi @yangshun I would like to work on https://myrocks.io/
Is there any specific timeline to complete this?

[yangshun]

Hey @dnafication, no there's no strict timeline, but the sooner the better. We will ask you about your progress and may reassign to someone else if if we see that there's no progress/response. This happens very often in Open Source 😥

[dnafication]

Thanks for the quick reply @yangshun
I did reach out to the repo owners and opened an issue with the text provided by you. Awaiting their response. https://github.com/facebook/mysql-5.6/issues/1054

[yangshun]

Hi folks helping out with the migration, please note that you don't have to make the v2 landing page look exactly the same as v1, unless you've been requested by the maintainer to do so.

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

[Croftyland]

Hi @yangshun,

All sites, which were taken, are done and pull requested. Only got problem with https://libspectrum.io/ due to protected branches

[Croftyland]

Can I take https://pyre-check.org/?

[yangshun]

@Croftyland could you tag this issue in your PRs so that we can better track them? Yes if you've completed the rest, feel free to take Pyre Check. For Pyre they have some ASCII cinema embed which you can follow how Hydra embeds it.

[Croftyland]

@yangshun I have mentioned you on issues

If everything is fine and merged, will do next site

[ozgunbal]

@yangshun I can start another migration. https://github.com/facebookincubator/profilo/issues/46 is currently waiting for review. I am available for new challenge. Is https://facebook.github.io/react-360/ good to start?

[dnafication]

Thanks for the quick reply @yangshun
I did reach out to the repo owners and opened an issue with the text provided by you. Awaiting their response. facebook/mysql-5.6#1054

Hi @yangshun I have not got any response from the maintainers of the myrocks.io yet. I can pick up another one in the mean time. I already managed to work on 50% of their site as it was a bit small.

[mishal23]

Can I try https://fbinfer.com/?

[yangshun]

@mishal23 definitely! Thank you!

[yangshun]

@ozgunbal sure you could do React 360 too.

@dnafication After looking into the project deeper, I think myrocks.io isn't a good project to work on as their website haven't been update in more than a year. Feel free to pick another small one if there are any available.

[mesaugat]

If anyone wants to let go of any claimed "Beginner Level" website, I can pick it up. 🙂

[Hardik500]

Can I take https://frescolib.org/ ?

[MathewtheCoder]

Can I take https://pyre-check.org/ ? @yangshun

[yangshun]

@Hardik500 sure thing!
@MathewtheCoder yep go ahead!

[BrandonPessman]

I would be interested in doing https://draftjs.org/ If it hasn't been grabbed! @yangshun

[yangshun]

@BrandonPessman go ahead! Just a note to change the index page to load draft js from npm via require/import instead of the current scripts approach!

[phacks]

Hi everyone! Not sure if that counts as a proper contribution, but I wrote the documentation for my company’s latest Open Source project (Falco, an automatic and easy-to-use WebPageTest runner to run performance testing against your websites), on Docusaurus V2 : https://getfal.co/.

Loved the experience, although using Infima involved a lot of inspecting the styles of the demo site elements—this part of the dev experience could be streamlined. Happy to help if you need any!

[smorimoto]

Can I take https://fbinfer.com? Related issue seems not to have been updated for a long time.

[smorimoto]

@yangshun Done!

[yangshun]

@diegowifi, @BrandonPessman, @lzhuor, @sshhdaniella, @Hardik500, @ozgunbal, @AMashoshyna, @ahmadalfy - checking in with you regarding the progress. Let me know if you are blocked so that we can step in to help, or if you're unable to proceed we can free it up for others.

[diegowifi]

Hi @yangshun I finished the Bowler transition to v2, there is just an issue with the footer, could you help me with that? We could keep this conversation in the discord channel 😄

[yangshun]

@diegowifi thanks! Please make a PR to the Bowler repo and we can discuss from there

[ozgunbal]

@yangshun I'm on it. I had given a break due to my other works, but I returned to this subject.

[Hardik500]

@yangshun I am currently preparing for my exams. So if you want you can free it for others.

[ozgunbal]

@yangshun What's the recent situation of migration in total? I couldn't open the google sheet above due to permission request.

Is there any help needed for another site?

[shivangna]

^ Seconded, @yangshun it would be great to get access to the google sheet link (I'm running into similar permission issues)

[BrandonPessman]

@yangshun Feel free to give mine up to someone if you need to. Unfortunately, I've been swamped with projects and studying for finals. I probably won't be able to tackle it for another few weeks.

[mesaugat]

Can I take https://fasttext.cc/ or https://reason-native.com/ ? @yangshun

[yangshun]

@mesaugat Reason Native is more actively developed, you can have that.

@BrandonPessman Sure, I'll do that. All the best for finals!

@shivangna Apologies, I have set the right access

[yangshun]

@ozgunbal would love your help with fbt website if possible 😄

[ozgunbal]

@yangshun you can assign fbt to me 👍

[theaupoulat]

Possible to take gulp or fastText ?

[yangshun]

@ozgunbal done, thank you!

@theaupoulat Sure, how about fastText?

Many thanks guys!

[theaupoulat]

sure !

[hookabidoo]

Hi, can I try with gulp please ?

[shivangna]

@yangshun can I take logDevice?

[yangshun]

@hookabidoo Yes sure

@shivangna Go ahead

@Croftyland @ozgunbal @aswathkk @imbsky could you guys PM me your address on Discord (yangshun#8663)? I would like to send out the swag 😎

[saadpasta]

Hye @yangshun can I take this one https://frescolib.org/ 😀

[michizhou]

Hey @yangshun is it alright if I take this one: https://facebook.github.io/watchman/ ?
Also what is the status of https://frescolib.org/ and the other websites that are on hold? Will they available for migration anytime soon? Will there be additional websites that need to be migrated in the future? Please let me know. Thanks!

[mohamedsgap]

Hi @yangshun Is it still possible to contribute to this issue ? If so I gonna wok on Flipper and migrate it to Docusaurus 2!

[sreetamdas]

Hey @yangshun is https://facebook.github.io/watchman still up for grabs? Would like to take it up

[prma85]

Hey @yangshun I was going to comment that I can do the https://facebook.github.io/watchman
But @sreetamdas already want to do it.
I could do https://frescolib.org/docs/, but I am wondering if the multi-language support is something already implemented for v2 🤔

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

[fanny]

Done facebook/watchman#787

[imrishabh18]

@yangshun Is any migration still left ?

[shujathkhan]

Hey @yangshun is https://ax.dev still up for grabs? Would like to take it up

[JapneetSingh5]

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

[slorber]

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: https://github.com/facebook/docusaurus/issues/3035

[HeroicHitesh]

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

[slorber]

@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

[vj-codes]

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

[slorber]

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

[Piyush-Chandel]

I would like take https://github.com/hhvm/hacklang.org ... should i take ?

[slorber]

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.