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