Migration to docusaurus

[alvarolorentedev]

Description

minimumcd.webm

Fixes #323

[netlify]

✅ Deploy Preview for minimumcd ready!

Name	Link
🔨 Latest commit	8b4f656
🔍 Latest deploy log	https://app.netlify.com/sites/minimumcd/deploys/64d7f3096dd56a0007639aff
😎 Deploy Preview	https://deploy-preview-324--minimumcd.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[bdfinst]

Fun fact, I'm in the middle of converting my company's docs site from Docusaurus to Hugo to eliminate the vulnerabilities in React.
What do you see as the advantage to this large a change?

[alvarolorentedev]

hello @bdfinst thanks for the comment, I opened a discussion in #323.

From my perspective, here are my thoughts:

• The current look and feel is quite outdated and the website is not really welcoming to be consumed. Docusaurus (infima) will allow us to be more up to date.
• React is as well-known language in the industry, so there is a smaller learning curve for contribution. I have tried to fight multiple times with the templating model of hugo and is complex.
• React also allows more dynamic content to be created inside the page, and it also has many libraries we could use to animate for example CICD proceses, or even show maturity models.
• The maintenance of templates in Hugo tends to be low, and only a few that are paid products are heavily maintained and act upon contributions (I have tried to contribute to some, and the release cycle varies a lot).
• Hugo you depend a lot on individual conventions in templates, so if we ever are to move out of the current template it is almost a rewrite as a template dominates the content structure.

Toward your concerns, React is a very active project many companies depend on, it will probably be taken care of sooner than later, and actually, we will get Dependabot to notify us abut those vulnerabilities.
I have seen the opposite of you this last year, I have seen 2 companies ditch Hugo in favour of docusaurus.

[bdfinst]

1. Look and feel: I'd be open to migrating to Google's Docsy or the theme I'm building for my company, which is a fork of Docsy. That would be a much less intrusive change.
2. I'm not sure how comfortable the rest of the core team is with React, but I've been developing in it for several years. My company is converting from Docusaurus due to the toil of keeping up with React CVEs in secure environments. Not an issue here, but it's the reason I mentioned it.
3. Hugo also allows for dynamic content within the page. I've been building shortcodes for the same for the last week to extend those features in my company's fork of Docsy. :) What dynamic content do you think is missing from MinCD?
4. I've had a PR open on Docsy for the past three weeks, so I get where you're coming from. Since the underlying tech is Hugo itself, unless something is broken in the theme, there's very little maintenance required. With Docusaurus, you need to keep dependencies current.
5. I've migrated between Hugo templates before. It's not a huge problem. My personal site and a few other sites I administer are also Hugo. In fact, i migrated my personal site from an older theme to my company's theme and only needed to modify some custom templates I'd created, not the documentation.

[alvarolorentedev]

The base tradeoff of generic static code generators like Hugo/Jekyll/Hexo/... is that the driving factor of the site is not the site itself, but the theme behind it. While It's true, it's possible to create short codes, those short codes are just HTML snipped that are resolved at compile time with small support for JS (no real complexity is allowed).

I have worked and migrated from Docsy before, Personally my opinion is more than changing a few configurations there is not too much control over the content of the page, specially the landing or any intermediate page you want to create navigation for. For example, to actually do some real modifications, you had to fork and create your own theme.

Answering your question about dynamic content missing in minimal CD, if we were in docusaurus/astro/... we could, for example, use a library like react flow to generate dynamic content showing how TBD works that will be engaging similar to this kafka visualization from softwaremill.

With this in mind, we can push collaborations of the bigger community if we use a mainstream language that allows development by anyone without a new learning curve. If we stick to Hugo, the issue is that community and that knowledge is more siloed & complex.

We need to take in count that the end goal of this group is to create engagement in the community to push forward CD if we can create more dinamic and engagement materia with things like react flow & also grow the capability for others to create easier the engagement material is a win win.

Getting back to the main point of this PR docusaurus helps us:

• Create more engaging content (essential for growing a community).
• Reduce the entrance learning curve for collaboration (essential for OS).

[bdfinst]

This seems like a huge lift for a hypothetical PR for an animated TBD workflow. Do you have one you're wanting to add?

If someone wants to flex their artistic muscles, this would be a lot less code and would align with the minimalism we get so many compliments on.

[alvarolorentedev]

@bdfinst I have given a few more reasons, it is up to you and the rest of the group to decide if this makes sense.

The resume of why I think this is as good move are:

• Docusaurus is Website-centric.
  • No need to modify a template to later modify the content.
• Docusaurus uses mainstream technology.
  • It improves the capability for people to contribute.
  • Extensive documentation
  • Extensive ecosystem
  • Frequent updates and security patches.
• Docusaurus is better maintained than any of the templates of generic systems.
• Docusaurus has a great integration for search with algolia that enables our users to get better access to our documentation.

Again, this is not about flexing artistically or hypotheticals. It's about using a technology that has stagnated for the last 2 years with a small community (Hugo) vs another that still growing and has large adoption (React). At the end, both compile markdowns into HTML, but one is more flexible and extensible than the other.

Overall, this PR is about community engagement and capabilities to become part of the group and collaborate.

[alvarolorentedev]

also playing with 2 new possible logos

[alvarolorentedev]

[bdfinst]

I've used Docusaurus, Gatsby, Jekyll, and Hugo quite a bit.

"No need to modify a template to later modify the content."
I find this confusing. It's Markdown.

"Docusaurus uses mainstream technology."
Go is pretty mainstream. It's been around for over a decade. In addition, Hugo has more contributors than Docusaurus, so it's hard to argue that the latter is better supported.

"It improves the capability for people to contribute."
All contributions to date have been Markdown. All static site generators have the same user experience where that's concerned.

"Extensive documentation"
https://gohugo.io/documentation/

"Extensive ecosystem"
They all do.

"Frequent updates and security patches."
No security patches are required for Hugo. I just created a Docusaurus site and got the following

added 1112 packages, and audited 1113 packages in 34s

204 packages are looking for funding
  run `npm fund` for details

22 vulnerabilities (4 moderate, 18 high)

This is what I get on the current site

added 128 packages, and audited 129 packages in 1s

40 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities

It's also significantly faster to build the current site locally. I'm in the process of replacing Docusaurus with Hugo at work so I'm feeling the pain of the build time difference there.

"Docusaurus is better maintained than any of the templates of generic systems."
The current template requires no maintenance.

"Docusaurus has a great integration for search with algolia that enables our users to get better access to our documentation."

Many site generators do

There are a couple of significant problems with this PR.

1. It doesn't add missing features.
2. The main feature, the content, cannot be code reviewed.

The structure of the main page has been optimized to ensure that any changes to the core content that people are signing on that they agree with have easily verifiable changes. That's why the signature, contributor, and other additional content on the main page are generated from other resources rather than simply part of the main page. This PR destroys that traceability.

I understand you prefer React, but the fact that there are many React developers is not a huge deal for goals of this project. I've talked to the rest of the team and they are also a bit confused about the value. We do appreciate the enthusiasm and would love help with the content, but we don't think this particular PR is in the best interests of the project goals.

[alvarolorentedev]

If those are your thoughts we are not going to get anywhere, and i dont feel this is my place to cooperate when there is 0 reflection and all is being defensive.
So best of luck.

[bdfinst]

If those are your thoughts we are not going to get anywhere, and i dont feel this is my place to cooperate when there is 0 reflection and all is being defensive. So best of luck.

Get more experience with open-source contributions. Go convert Docusaurus to Angular and see what they say. ;)

Also, since we are maintaining the site, changes that make that experience objectively worse don't help.

[alvarolorentedev]

btw...not sure if you noticed, but you compare apples with pears 😛. A node project vs the broken link checker and the MD linter 🤷 (hugo is in go so its not going to be checked against npm cve)

[bdfinst]

Hugo is a dev dependency, so there are no CVEs. This is an apples-to-apples comparison.

To reiterate:

1. The PR removes traceability of the valuable part of the project, the content. Considering the care we take to maintain that traceability, that immediately removes any possible value from this PR.
2. Making it easier for a React developer to modify the infrastructure doesn't make it easier to improve the content.
3. Docusaurus requires more maintenance toil than Hugo. Since that toil falls on the core team and not you, trying to ram this down our throats isn't good behavior.

Collaboration doesn't consist of trying to bully people into accepting your PR.
Do you understand the irony of making a PR like this to something like MinimumCD?
It's not small. It's not evolutionary. It adds features that aren't needed but that require extra maintenance.
To add to that, the theme you picked is still beta.