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

Open
yangshun opened this issue Oct 12, 2019 · 33 comments
Labels

Comments

@yangshun
Copy link
Member

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

Experienced Level

Beginner Level

Non-Docusaurus

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 @endiliey @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
  • 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 and @endiliey 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

This comment has been minimized.

@AMashoshyna

This comment has been minimized.

Copy link

@AMashoshyna AMashoshyna commented Oct 12, 2019

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

@ahmadalfy

This comment has been minimized.

Copy link
Contributor

@ahmadalfy ahmadalfy commented Oct 12, 2019

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

@imazik

This comment has been minimized.

Copy link

@imazik imazik commented Oct 12, 2019

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

@sshhdaniella

This comment has been minimized.

Copy link

@sshhdaniella sshhdaniella commented Oct 12, 2019

@yangshun

This comment has been minimized.

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!

@diegowifi

This comment has been minimized.

Copy link

@diegowifi diegowifi commented Oct 12, 2019

Hi @yangshun

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

@yangshun

This comment has been minimized.

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

This comment has been minimized.

Copy link
Contributor

@ThakurKarthik ThakurKarthik commented Oct 13, 2019

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

@ozgunbal

This comment has been minimized.

Copy link

@ozgunbal ozgunbal commented Oct 13, 2019

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

This comment has been minimized.

Copy link

@lzhuor lzhuor commented Oct 13, 2019

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

@yangshun

This comment has been minimized.

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!

@jesuslerma

This comment has been minimized.

Copy link

@jesuslerma jesuslerma commented Oct 14, 2019

Hi @yangshun

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

@dnafication

This comment has been minimized.

Copy link

@dnafication dnafication commented Oct 15, 2019

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

@yangshun

This comment has been minimized.

Copy link
Member Author

@yangshun yangshun commented Oct 15, 2019

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

This comment has been minimized.

Copy link

@dnafication dnafication commented Oct 15, 2019

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

@yangshun

This comment has been minimized.

Copy link
Member Author

@yangshun yangshun commented Oct 16, 2019

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

This comment has been minimized.

Copy link

@Croftyland Croftyland commented Oct 16, 2019

Hi @yangshun,

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

@Croftyland

This comment has been minimized.

Copy link

@Croftyland Croftyland commented Oct 16, 2019

@yangshun

This comment has been minimized.

Copy link
Member Author

@yangshun yangshun commented Oct 16, 2019

@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

This comment has been minimized.

Copy link

@Croftyland Croftyland commented Oct 17, 2019

@yangshun I have mentioned you on issues

If everything is fine and merged, will do next site

@ozgunbal

This comment has been minimized.

Copy link

@ozgunbal ozgunbal commented Oct 18, 2019

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

@dnafication

This comment has been minimized.

Copy link

@dnafication dnafication commented Oct 22, 2019

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.

facebook-github-bot added a commit to facebookincubator/profilo that referenced this issue Oct 24, 2019
Summary:
- Live version: https://build.ozgunbal.now.sh/
- I only removed github star counts below `Get Started` button at v1:
![image](https://user-images.githubusercontent.com/16080180/66868638-60d9b200-efa6-11e9-9e58-a8638b93d04e.png)
It can be added if it's necessary but IMHO, doesn't look good with new theme.
- Hey, yangshun and endiliey . You can check it when you're available.
- This PR related to #46 and facebook/docusaurus#1834
Pull Request resolved: #47

Differential Revision: D18064160

Pulled By: BurntBrunch

fbshipit-source-id: 70b67a519455f3072246373661966e0bd6f84c36
@brkn brkn referenced this issue Oct 27, 2019
3 of 3 tasks complete
@mishal23

This comment has been minimized.

Copy link

@mishal23 mishal23 commented Oct 27, 2019

@yangshun

This comment has been minimized.

Copy link
Member Author

@yangshun yangshun commented Oct 28, 2019

@mishal23 definitely! Thank you!

@yangshun

This comment has been minimized.

Copy link
Member Author

@yangshun yangshun commented Oct 28, 2019

@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

This comment has been minimized.

Copy link
Contributor

@mesaugat mesaugat commented Oct 30, 2019

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

@Hardik500

This comment has been minimized.

Copy link

@Hardik500 Hardik500 commented Oct 31, 2019

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

@MathewtheCoder

This comment has been minimized.

Copy link

@MathewtheCoder MathewtheCoder commented Nov 3, 2019

@yangshun

This comment has been minimized.

Copy link
Member Author

@yangshun yangshun commented Nov 3, 2019

@Hardik500 sure thing!
@MathewtheCoder yep go ahead!

@BrandonPessman

This comment has been minimized.

Copy link

@BrandonPessman BrandonPessman commented Nov 4, 2019

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

@yangshun

This comment has been minimized.

Copy link
Member Author

@yangshun yangshun commented Nov 4, 2019

@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

This comment has been minimized.

Copy link

@phacks phacks commented Nov 6, 2019

Hi everyone! Not sure if that counts as a proper contribution, but I wrote the documentation for my company鈥檚 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鈥攖his part of the dev experience could be streamlined. Happy to help if you need any!

@endiliey endiliey removed the hacktoberfest label Nov 13, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
You can鈥檛 perform that action at this time.