poc: Cloud Manager Github Pages Docs

[bnussman-akamai]

Description 📝

Tip

The site is deployed at https://bnussman-akamai.github.io/manager/ for the sake of testing this

• Uses Vitepress to build a docs site from our existing docs folder 🗂️
• Proof of concept as an alternative to @abailly-akamai 's POC: [M3-7538] - Cloud Manager GH Pages Docs #9960
• Just wanted to give this a try and see how it felt. Not saying it's the right solution for our docs site, just wanted to feel out / let the team feel out the option

Pros of this approach ✅

• Integrated with our monorepo, meaning yarn && yarn docs is all you need to start a local dev server (easier to onboard)
• Uses file-based routing so that we don't have to put explicit metadata at the top of each .md file 📂
• Keeps us within the Typescript / Vite ecosystem
• Although we care more about functionality than looks, this looks more modern and has dark mode 🌑

Cons of this approach ❌

• Adds a significant amount of node_modules (could cause slower install times) (this explains the diff) 🐌
  • Installing these dependencies can't easily be skipped if we include this in our monorepo as far as I know
  • While we should consider this a con, it could be less of a problem when we migrate from yarn to pnpm or bun install
• Might not be worth the added maintenance and overheard 😕

Preview 📷

How to test 🧪

Deployed

• Visit https://bnussman-akamai.github.io/manager/

Locally

• Check out this PR
• Run yarn in the repo's root to ensure your dependencies are good to go
• Run yarn docs
• Go to http://localhost:5173/manager/

As an Author I have considered 🤔

• 👀 Doing a self review
• ❔ Our contribution guidelines
• 🤏 Splitting feature into small PRs
• ➕ Adding a changeset
• 🧪 Providing/Improving test coverage
• 🔐 Removing all sensitive information from the code and PR description
• 🚩 Using a feature flag to protect the release
• 👣 Providing comprehensive reproduction steps
• 📑 Providing or updating our documentation
• 🕛 Scheduling a pair reviewing session
• 📱 Providing mobile support
• ♿ Providing accessibility support

[mjac0bs]

Thanks for putting together this POC to compare.

When comparing between the vitepress and jekyl versions of docs, this one definitely gives us a much friendlier UX out of the box, which is really nice!

As far as the cons:

Adds a significant amount of node_modules (could cause slower install times)

Slower by some amount of seconds for install, which we don't need to do very often, is not the biggest deal, imo.

maintenance

Making sure all these new packages stay up to date and any security issues are resolved feels like a bigger pain point here. That's a lot of vue stuff we wouldn't otherwise need.

While we should consider this a con, it could be less of a problem when we migrate from yarn to pnpm or bun install

With pnpm or bun, can we skip these dependencies? Or is there something else (speed?) that would make this a different experience with alternative package managers?

[abailly-akamai]

@mjac0bs or @bnussman can we maybe use npx to bypass installing local deps? vitepress supports it

[bnussman-akamai]

@abailly-akamai That's a good idea, but I think we'd have to drop the vitepress-sidebar dependency and manually populate the sidebar if we want to run vitepress directly? Thoughts?

[abailly-akamai]

@bnussman I took a super quick npx stab at it and i am feeling pretty good about it so far. Basically just with a config file in the current /docs dir + the index.md file we get pretty much the same result.

As far as the sidebar, since we can populate it from the config file, we could write a simple script that aggregates the development-guide files and generates our links. Just want to make sure we wanna take that route before writing it.

[bnussman-akamai]

That's great news @abailly-akamai I think I'm happy with that direction.

Maybe we could even copy-paste vitepress-sidebar as needed

[bnussman-akamai]

Closing in favor of #10027. We will continue to use Vitepress, but we will just run it with npx/bunx to keep the monorepo lightweight