Docs Site v2

[kamranayub]

Working issue for thinking about the next version of the docs site.

Context

The current website is built on a custom Gatsby.js site, with support for MDX and API reference links (using a custom plugin). It is also built with Semantic UI styles.

Objective

We would like to better organize the documentation site and make it more example-rich, along with a refreshed homepage and onboarding experience.

Goals

• Accessible and mobile-friendly documentation
• Organize docs under the Diátaxis system
• Frictionless and contributor-friendly DX
• Simpler CI/CD workflow with a smoother Typedoc integration
• Integrated with API reference docs
• Integration of compiled, interactive examples
• Product analytics to understand usage patterns
• Support for natively-integrated interactive tutorials

Non-Goals

• Restricted editing access
• Complicated local DX
• Expensive hosting
• Maintenance-heavy upgrades

Pain Points

Here's what sucks about the current implementation:

• Typedoc upgrades are totally manual and need to be coordinated across the core repo and this docs repo
• The docs area is entirely custom and isn't on parity accessibility-wise with something like Docusaurus
• API docs are separately built in a custom workflow and requires convoluted orchestration scripts
• Creating examples is done in the core repo with Storybook, or manually with snippets in this repo (it's not unified or consistent)
• Managing package dependency upgrades is annoying

Ideas

• Docusaurus maintains React support with MDX
  • Typedoc through docusaurus-plugin-typedoc-api (example)
  • Supports API docs linking
  • Supports Posthog for analytics
• We could update the theme to be based off https://github.com/hasura/gatsby-gitbook-starter
  • Worth noting: Hasura switched to Docusaurus v2 😄
• We could switch to hosting on something like Mintlify
  • But this will (likely) restrict who can contribute.
  • And we are at the mercy of the platform
  • GitBooks is free for OSS teams but it may not be as customizable as we'd like

Decisions

1. What framework or library should be used to build the docs?
2. What provider should be used to host the site?
3. Should we consolidate docs into the core excalibur repo?

Related

excaliburjs/Excalibur#2770

[kamranayub]

Proposed Decisions

Migrate to Docusaurus v2

Adopting a plugin to support Typedoc.

Pros

• Maintains React and MDX support
• Eliminates the need to maintain custom source/transformer plugins for Typedoc
• Simplifies CI/CD workflow
• Simplifies contributor workflow
• Provides more docs-centric features out-of-the-box and through future upgrades

Cons

• Does not support SSR
  • Mitigation: We can leverage Cloudflare Pages Functions for any dynamic rendering, or Docusaurus plugins for static generation.
• No integrated course or tutorial experience. I do not see any templates/plugins for building step-wise interactive tutorials like Storybook Tutorials or Cypress Guides (both of those are custom-built), nor has anyone created a Docusaurus plugin for something like Medusa's Recipes or learning path experience.

Host through Cloudflare Pages

Using a centralized shared excalibur.js organization account.

Pros

• Cloudflare provides a generous free plan, with deploy previews and unlimited traffic
• Cloudflare provides an upgrade path to adopt Functions or Workers as-needed with storage solutions like D1, R2, and Durable Objects.

Cons

• The CI/CD is separately managed from GitHub Actions
• With many contributors over time, we may run into the 500 build limit (~60 builds/mo currently, however, over half are dependabot PRs)

Consolidate to excalibur repo

Given that we only created this repo due to constraints with GitHub Pages, it makes sense to re-evaluate.

Pros

• Shared dependencies -- no more TypeScript version dancing between repos
• Code lives next to docs -- guarantees compiled examples are against repo code
• Discussions and issues can be created for docs vs. linked from separate repo
• Simpler CI/CD workflow, no more cross-repo orchestration. Current solution clones and builds excalibur repo anyway.
• Simpler PR workflow, everything happens in one place

Cons

• Bloats repo, feeling like a monorepo
  • Mitigation: If everything is under a site or content or docs folder, it may be less of an issue. We could take this time to reorganize the file tree as well.
• Cloning will take longer. There are submodules we use here that would move. We commit a lot more files.
• Bloats local and CI build commands (non-goal: worse DX)
  • Mitigation: We could adopt a tool like Nx or Turborepo to try and simplify the build toolchain. It should not increase CI build time, as Cloudflare would handle docs build.
• Old versioned docs may be harder
  • Current solution can clone all the tags to build. We may need to figure out a different solution for those, or maybe it's fine but needs to be in a temp directory.

[eonarheim]

@kamranayub I'm 100% on board with the proposal.

I think cloudflare pages is worth a try, I think there are a lot of advantages merging docs into the main repo as you say. It definitely feels like it's worth it considering the drift we have to deal with.

Another advantage of doing a new thing in the main repo, is we can do side by side deployments of gh pages and cloudflare until we are ready to cutover DNS.

cc @chrisk-7777