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’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Migrate Website to Docusaurus 2 #2146

Closed
12 of 18 tasks
teikjun opened this issue Aug 14, 2020 · 9 comments
Closed
12 of 18 tasks

Migrate Website to Docusaurus 2 #2146

teikjun opened this issue Aug 14, 2020 · 9 comments

Comments

@teikjun
Copy link
Contributor

teikjun commented Aug 14, 2020

Description

Hi there! The Docusaurus team is currently developing Docusaurus 2, which now has feature parity with React Native'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

@darshkpatel and I will be helping to migrate and be the POC throughout the migration process.

You can view the test site here: https://reactnative-v2.netlify.app/docs/

We're keeping track of our progress in #2139.

To do list

  • Run migration CLI
  • Remove unused versions
  • remove from /versioned_docs, /versioned_sidebar, versions.json, docusaurus.config.js
  • Fix build errors from all versioned_docs and current docs
  • close all unclosed tags, remove invalid tags (handled by Backwards compatible docs fixes for docusaurus upgrade #2158)
  • for any invalid JSX outside codeblocks, enclose them in codeblocks (handled by Backwards compatible docs fixes for docusaurus upgrade #2158)
  • use MDX compatible syntax: change class to className, change style="..." to style={{...}}.
  • Fix other build errors
  • Fix url-loader issue by adding it as dependency in root directory ( as a hack )
  • Fix errors in blog
  • Migrate navbar items
  • Migrate footer items
  • Migrate pages for help, showcase, version
  • replace CompLibrary, siteConfig and other deprecated things with appropriate substitutes
  • In docusaurus.config.js, set preset-classic's pages.path to be 'pages/en'
  • Migrate CSS for pages and docs
  • Use CSS modules to limit scope of CSS (global CSS can affect theme components)
  • Remove incompatible CSS and fix bugs
  • Move assets (handled by move image assets from docs to statics folder #2157)
  • Move /docs/assets into /static/docs/assets
  • Move missing images from /blog/assets into /static/blog/assets
  • Migrate landing page
  • Fix CSS bugs in landing page 🔨
  • Customize Prism setup and SnackPlayer using remarkablePlugins
  • Fix SnackPlayer bug
  • Fix custom CSS components in docs
  • Fix tabbed items in docs
  • Replace quotes with admonitions in docs
  • Add redirects for moved/renamed docs

Legends:

🔨 - in progress

  • - complete

Note: We'll add a more detailed log of changes after completing each item

@gedeagas
Copy link
Contributor

Awesome !!

@Simek
Copy link
Collaborator

Simek commented Aug 16, 2020

@teikjun Can we track the progress back in #2139 or in this issue instead of MLH repository to be more transparent for the community and make it easier to interact and discuss about the changes?

@Simek Simek linked a pull request Aug 16, 2020 that will close this issue
22 tasks
@teikjun
Copy link
Contributor Author

teikjun commented Aug 16, 2020

@Simek Sure! We'll track the progress in #2139, I've updated the link in the issue

@darshkpatel
Copy link
Contributor

Should we support theme switching? or should I force default to the light theme? v2 supports defaulting to user's system preference too

Screenshot 2020-08-18 at 12 29 36 PM
Screenshot 2020-08-18 at 12 29 41 PM

PS: Links look weird due to a CSS bug, we're working on it.

@Simek
Copy link
Collaborator

Simek commented Aug 18, 2020

@darshkpatel I think that you should focus on the content and functionality (ex. SnackPlayer, Prism config, content tabs, non versioned pages, manual redirects for removed pages etc.), due to restricted time of MLH project. Fine tuning design, adding back custom design tweaks (like platform labels) and correcting typography might be a lengthy process.

Generally I would like to see the Dark Mode, but I have not discuss about this with @rachelnabors yet.

P.S. I'm experiencing issue with the disappearing content (after a while) on the page linked in the first post. Is it a known issue?
Annotation 2020-08-18 114502

P.S.2 The second (and biggest problem in my eyes) is that currently doc files migration destroyed the GIT changes history (files were removed and than added back instead of moving them within the repository - using git mv). This results is that all content is being attributed to the one person, example:

@Simek Simek pinned this issue Aug 18, 2020
@rachelnabors
Copy link
Contributor

Please implement the theme switcher—we can handle the design tweaks necessary to make it work. But focus on the functionality: inline toggles for examples and notes.

It would be best if we could keep the contribution records with git mv as that information is used for attribution purposes on the page. Please retain it.

Thank you!

@darshkpatel
Copy link
Contributor

darshkpatel commented Aug 18, 2020

P.S. I'm experiencing issue with the disappearing content (after a while) on the page linked in the first post. Is it a known issue?

Thanks for pointing it out! Weren't aware of it since it doesn't occur while running the dev server. Will add to ToDo

@slorber
Copy link
Contributor

slorber commented Aug 19, 2020

That looks quite nice already!

Also see the content disappear, that's what I reported you @rachelnabors , this seems to be related to React hydration as it only happens on first page load, not navigation => https://react-native-v2.netlify.app/docs/

I also think having the theme switcher is great and it seems to work quite nicely already.

Looks like the code blocks highlighting does not work, but I suspect this is because we don't integrate properly the embedded Snack player iframe.

About git, you are totally right, and I was pretty sure this would be a problem for many large v1 website like this one. The migration cli we made is a first version, there are still many things that can be improved, but preserving git history is probably the most critical one. facebook/docusaurus#3103
We'll try to figure out how to preserve it

I also think that for now we should try to see how to add the missing features like the Snack Player etc. Once these are done, we'd have a better idea of how hard it will be to complete this migration project.

@slorber
Copy link
Contributor

slorber commented Sep 2, 2020

Can be closed in favor in the new migration fork: react-native-website-migration#7

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

6 participants