😎 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

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

[dtaylorbrown]

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 😃

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?

[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: #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-Chandel7]

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.

[davidjgoss]

I'm keen to have a go at migrating https://ax.dev/ using the migration CLI, can I claim that one?

[slorber]

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

[davidjgoss]

@slorber thanks, I'll ask them

[yangshun]

I think we're done with this issue!

[singhankit62000]

Hey I'd like to migrate https://hhvm.github.io/hack-codegen/

[codewithpom]

@yangshun Is this still active so I can help.

[slorber]

No this is not an active issue anymore.

[sonujangra27]

is it still active?

[yangshun]

Nope, the issue is closed.

…

On Wed, 2 Nov 2022, 8:51 pm sonujangra27, ***@***.***> wrote: is it still active? — Reply to this email directly, view it on GitHub <#1834 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAKBCHKVRGGYPFEXVRLB7K3WGJPTLANCNFSM4JABVJYA> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[Nihat217716]

Comment