Migrate the Magma website from v1 to v2

[JoelMarcey]

📚 Documentation

The Magma team would like their site migrated from Docusaurus v1 to v2.

https://magma.github.io/magma/

Have you read the Contributing Guidelines on issues?

Yes

[JoelMarcey]

cc @lisa761

[JoelMarcey]

cc @jaredmullane

[slorber]

What I see:

• Sources at https://github.com/magma/magma/tree/master/docs/docusaurus
• Site is versioned, using incremental doc updates
• No translations
• Not too much CSS
• Custom pages exist but they seem unused (ie we only use md docs)
• Need to redirect the .html extension

Notes and questions:

• Where is the ./docs folder for master docs?
• The existing navbar tries to look like the main Magma site, might need some custom CSS to achieve (not the std Docusaurus layout)
• Why is there a docker config? (the prod site seems to be deployed by Netlify)

That does not look like a site too complex to migrate.

@jaredmullane can you please give us some additional details about your expectations (ie what is good enough for you to be deployed in production, what should be kept or ditched?)

@lisa761 can you please see with MLH if you can fork this repo?
I'd also like to have access to that I can configure a temporary Netlify deployment and push to the fork to help you.

[jaredmullane]

Hi @slorber, thanks for the help! The master docs are kept under themagma/docs/readmes/ folder and the versioned docs are kept separate. The Docker config is I believe related to the create_docusaurus_website.sh file which runs a local version of docusaurus using Docker.

It would be great if we could add a lightweight homepage like Flux (https://facebook.github.io/flux/) but in terms of the documentation side there is nothing major to ditch. We can always add those changes on our side as well on as we are planning on reorganizing our Docusaurus page next month. Thanks again.

[slorber]

Thanks

Why are the docs in /readmes, that looks quite unusual 😅

Do you use Docker in dev or you just run yarn start?

It would be great if we could add a lightweight homepage like Flux (https://facebook.github.io/flux/)

Actually, you have a homepage already but you "overwrite" it with a JS redirect here: https://github.com/magma/magma/blob/master/docs/docusaurus/static/index.html

The Flux homepage is basically the default Docusaurus homepage so it shouldn't be too hard to set this up 😆

in terms of the documentation side there is nothing major to ditch

Yes we don't plan to remove any doc, I was just wondering what particular v1 site features you really care about or whatever.

What we could do is just do the bare v1-v2 migration, deploy a preview, ask for feedbacks and you tell us what's missing (or even commit to the PR directly if you want to contribute to the migration effort)

[jaredmullane]

Why are the docs in /readmes, that looks quite unusual 😅

I am not sure on this one. The docusaurus was set up before I began working on the product.

Do you use Docker in dev or you just run yarn start?

I believe the Docker portion is just to run it in dev. My sense is we should just do npm run serve or yarn.

What we could do is just do the bare v1-v2 migration, deploy a preview, ask for feedbacks and you tell us what's missing (or even commit to the PR directly if you want to contribute to the migration effort)

That would be great. Thanks again!

[jaredmullane]

Just want to double check, is there anything else you need from our side @slorber? Thanks again for all the help and hope that you have a great weekend. :)

[jaredmullane]

I have been going through the migration process on my own, however, when I run 'yarn start' I am getting an error message related to duplicate titles for all my docs. Use either a frontmatter title or a markdown title, not both.

Have you @slorber encountered that issue before? Thanks!

[slorber]

sorry for the delay @jaredmullane , unfortunately I didn't have time to help you and the MLH session is already reaching its end.

If you have a public Github branch I can help you there (If you give me write access) or review the code.

Use either a frontmatter title or a markdown title, not both.

This is a new warning that we introduced recently. In alpha.73 there's an env variable to disable it. We may simply remove it if it becomes annoying for too many users.

This warning is emitted when a markdown doc contains multiple h1 headings:

# My Doc Title

lorem ipsum

# My Second Doc Title

lorem ipsum

Doing so is a bad practice that you should rather avoid.

Asked the community here: https://twitter.com/sebastienlorber/status/1379416531235405832

If you want to keep this double title pattern in your docs, I'm curious to understand your motivations.

[jaredmullane]

No worries @slorber! It is strange because the files being flagged but that error message only have one title (see below). Could be something with the versioned docs. I will keep messing around with it.

The repo that I am trying to migrate is Magma with my branch here. Definitely appreciate any insight or help and hope that you have a great weekend!

[slorber]

Hi @jaredmullane

On this url, I still see a Docusaurus v1 website: https://github.com/jaredmullane/magma/tree/docusaurus-migration/docs/docusaurus

Have you pushed your initial migration work for me to take a look? How can I help exactly?

The error Use either a frontmatter title or a markdown title, not both. has been removed in alpha74 as it was more annoying than helpful. Just need to upgrade the dependencies again to get it removed.

It was due to having duplicate top-level titles in both md + frontmatter, for example:

---
id: version-1.0.1-testing
sidebar_label: Testing
title: Testing in Orchestrator
hide_title: true
original_id: testing
---
# Testing in Orchestrator

[jaredmullane]

Hey @slorber

I forgot to push the latest to that branch but should be good now at that link above. Sorry for that! That should contain the initial migration work I have started. I am just trying to migrate it fully to v2.

[slorber]

Hey,

I've opened a PR to your fork, fixing a few migration issues for you: jaredmullane/magma#24

Will add inline comments so that you understand the changes

[jaredmullane]

Can't thank you enough @slorber for all the help!! Really appreciate all the support :)

[slorber]

Thanks :) Let me know if you have any question or if you are stuck with the migration

[jaredmullane]

I had created a new repo here where I have updated our migration. We ended up having to change some of the versioned docs but otherwise it works. We are able to successfully deploy the website (v2-website folder is the new folder), however the only issue now is our docs, versioned docs, and sidebars don't deploy. Does anything look off in our docusaurus.config.js file to you? Thanks so much again for the help!

[slorber]

however the only issue now is our docs, versioned docs, and sidebars don't deploy

I don't understand what you mean sorry 😅

Does anything look off in our docusaurus.config.js file to you?

Not sure what to look for as. I don't understand the problem.

However I see that you reverted some config changes that I did on purpose here: https://github.com/jaredmullane/magma/pull/24/files

cf your current config not using the new docsVersionDropdown navbar item:

https://github.com/jaredmullane/docu_2/blob/master/v2-website/docusaurus.config.js#L65

[shanku9]

Hello @slorber , thanks for looking. We still have 2 pending issues:

1. Website home page not found. It goes to http://localhost:3000/docs/basics/introduction.html vs http://localhost:3000/docs/basics/introduction
2. All the images are broken. Do we have to move them to a different location?
   See attached

[slorber]

@shanku9

---

About the .html suffix, the best would be to setup server-side redirects (better for SEO) but this is out of the scope of Docusaurus (server features depends on your host).

As a good enough solution, we have a @docusaurus/plugin-client-redirects that can help you redirect /xyz.html to /xyz. It only works in production (test with yarn build && yarn serve), not yarn start.

If you have incoming links to your doc with the .html extension, I'd rather remove that extension

---

For the broken images, I don't know, afaik they were not broken in my PR here so wonder what you changed?
https://github.com/jaredmullane/magma/pull/24/files

It would be much more convenient for me to inspect a prod build where I can see/inspect the problem you have, as you just have to give me an url.
You can signup to Netlify in 5min and it's very easy to host a site here, for free: just drag&drop the website/build folder.
Ideally, wire your Git repo so that I'm sure the deployment I see is in sync with the code I see on Github.