Documentation engine build

This is a rework to host the MongoDB Query Language documentation in a structured manner. This rework also shows how to host the articles as Markdown and landing page(s) as YAML. This makes it easier for others to contribute to your documentation without requiring knowledge of Next.js internals.

This prototype also heavily uses static rendering, so the HTML files are generated at compilation, and HTML is served client side. This allows the site to have SEO metadata set on a per-page basis, titles set on a per-page basis, and deep linking to specific articles.

Preview

Here's a preview of the site auto-published to GitHub Pages:

• https://seesharprun-documentdb-prototype.github.io/docs
• https://seesharprun-documentdb-prototype.github.io/docs/reference
• https://seesharprun-documentdb-prototype.github.io/docs/reference/command
• https://seesharprun-documentdb-prototype.github.io/docs/reference/command/aggregation
• https://seesharprun-documentdb-prototype.github.io/docs/reference/command/aggregation/count
• https://seesharprun-documentdb-prototype.github.io/docs/reference/command/aggregation/count#examples
• https://seesharprun-documentdb-prototype.github.io/docs/quickstart
• https://seesharprun-documentdb-prototype.github.io/docs/postgresql/functions
• https://seesharprun-documentdb-prototype.github.io/docs/architecture

Changes in this PoC

• Latest version of Next.js
  • Switched to Turbopack
  • Stripped out unused files
  • Configured Next.js for fast refresh in local dev
  • Configured static HTML file export for caching/SEO performance
• Updated blog posts list to data-driven
  • Created YAML file for community blog posts
  • Created validation schema file
  • Read YAML file to generate blog posts
• Switched documentation to static content
  • Use Markdown for documentation to make contribution easier
  • Transform Markdown to HTML
  • Allow custom layouts like the "coming-soon" page for architecture
• Added structured language reference files
  • Add 2 sample YAML files
  • Transform and serve YAML
• Universal reference and documentation enhancements
  • Anchor tags for H2 and H3 elements
  • Served as vanilla HTML for caching
  • Serve unique titles and metadata descriptions for SEO optimization
  • Serve unique URIs for bookmarks
• Rework CD workflow
  • Use minimal permissions
  • Rename
• Create CI workflow
  • Check reference YAML against schema
  • Check blog YAML against schema
• SEO/GEO
  • Add meta tags for various pages
  • Add social media cards via meta tags
  • Influence search result cards via meta tags

Contribution endpoints

How you can use this

Feel free to pick this PR apart, re-use ideas, and close it when you're done.

Looking forward

This PR opens up the possibility of using the structured operator/command files as part of a CI/CD workflow. You could easily host DocumentDB's container as a sidecar in a GitHub action and actually run each example command to verify it works on a scheduled and per-PR basis. We can also use AI and other tools to review the examples and perform operations like streamlining the samples to be similar across all documentation.