GRO-683 - 1 - Add astro, example page, make astro+jekyll live side by side (temporarily)

.github/workflows/test.yml

@@ -18,6 +18,10 @@ jobs:
         with:
           bundler-cache: true # runs 'bundle install' and caches installed gems automatically
           cache-version: 0
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+      - name: Install js dependencies
+        run: bun install --frozen-lockfile
       - name: Build the Jekyll Site
         env:
           JEKYLL_ENV: production

.gitignore

@@ -1,9 +1,20 @@
 /node_modules/
 .DS_Store
 .idea
+.vscode
 *.log
 tmp/
 /htmlproofer.out
 /.clj-kondo/
 /.lsp/
 /_site/
+
+# Astro build output
+dist/
+
+# generated types
+.astro/
+
+# environment variables
+.env
+.env.production

.prettierrc

@@ -0,0 +1,7 @@
+{
+  "plugins": [
+    "@ianvs/prettier-plugin-sort-imports",
+    "prettier-plugin-astro"
+  ],
+  "trailingComma": "all"
+}

AGENTS.md

@@ -0,0 +1,22 @@
+## Development
+
+When starting the dev server, use background mode:
+
+```
+astro dev --background
+```
+
+Manage the background server with `astro dev stop`, `astro dev status`, and `astro dev logs`.
+
+## Documentation
+
+Full documentation: https://docs.astro.build
+
+Consult these guides before working on related tasks:
+
+- [Adding pages, dynamic routes, or middleware](https://docs.astro.build/en/guides/routing/)
+- [Working with Astro components](https://docs.astro.build/en/basics/astro-components/)
+- [Using React, Vue, Svelte, or other framework components](https://docs.astro.build/en/guides/framework-components/)
+- [Adding or managing content](https://docs.astro.build/en/guides/content-collections/)
+- [Adding styles or using Tailwind](https://docs.astro.build/en/guides/styling/)
+- [Supporting multiple languages](https://docs.astro.build/en/guides/internationalization/)

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

_includes/learn/left-nav.html

@@ -1,4 +1,4 @@
-{% assign cleanPageURL = page.url | replace: '/index' '' %}
+{% assign cleanPageURL = page.url | replace: '/index', '' %}
 
 {% for category in include.categories %}
   <h5>{{category.name}}</h5>

_includes/schema-markup.html

@@ -31,4 +31,4 @@
     ]
   }
 </script>
-{% assign page.schema_markup_added = true %} {% endunless %}
+{% endunless %}

_plugins/astro_build_plugin.rb

@@ -0,0 +1,11 @@
+Jekyll::Hooks.register :site, :post_write do |site|
+  next if site.config['serving']
+
+  build_astro = "bun run build"
+
+  raise "Astro build failed" unless system(build_astro)
+
+  shuffle_directories = "rsync -a dist/* _site && rm -rf dist"
+
+  raise "Astro sitemap rename / sync failed" unless system("#{shuffle_directories}")
+end

amplify.yml

@@ -3,15 +3,18 @@ frontend:
   phases:
     preBuild:
       commands:
-        - sudo yum install -y xz
+        - sudo yum install -y xz rsync
         - rvm install 3.3.2
         - rvm use 3.3.2
         - gem install bundler -v 2.5.22
         - bundle _2.5.22_ config set --local path 'vendor/bundle'
         - bundle _2.5.22_ install
+        - curl -fsSL https://bun.sh/install | bash
+        - export PATH="$HOME/.bun/bin:$PATH"
+        - bun ci
     build:
       commands:
-        - JEKYLL_ENV=production NODE_ENV=production bundle _2.5.22_ exec jekyll build
+        - export JEKYLL_ENV=$([ "$AWS_BRANCH" = "master" ] && echo "production" || echo "staging") && export NODE_ENV=$JEKYLL_ENV && bundle exec jekyll build
   artifacts:
     baseDirectory: _site
     files:

astro.config.mjs

@@ -0,0 +1,5 @@
+// @ts-check
+import { defineConfig } from 'astro/config';
+
+// https://astro.build/config
+export default defineConfig({});

package.json

@@ -13,6 +13,13 @@
     "url": "https://github.com/metabase/metabase/issues"
   },
   "scripts": {
+    "build": "astro build",
+    "check": "bun lint-scripts && bun fmt:check && bun ts",
+    "dev": "concurrently 'bundle exec jekyll serve --incremental --port=4002' 'wait-on http://localhost:4002 -i 1000 && astro dev'",
+    "preview": "astro preview",
+    "fmt": "prettier --write \"src/**/*.{ts,astro}\"",
+    "fmt:check": "prettier --check \"src/**/*.{ts,astro}\"",
+    "ts": "astro check",
     "lint-scripts": "eslint .",
     "lint-scripts-fix": "eslint . --fix",
     "lint-styles": "stylelint '**/*.scss' --quiet && stylelint '**/*.css' --quiet",
@@ -58,21 +65,30 @@
     "yamljs": "^0.2.3"
   },
   "devDependencies": {
+    "@astrojs/check": "^0.9.9",
     "@html-eslint/eslint-plugin": "^0.13.2",
     "@html-eslint/parser": "^0.13.2",
+    "@ianvs/prettier-plugin-sort-imports": "^4.7.1",
     "@linthtml/linthtml": "^0.8.6",
     "@linthtml/linthtml-config-recommended": "^0.1.0",
+    "@types/yamljs": "^0.2.34",
+    "astro": "^7.0.9",
+    "concurrently": "^10.0.3",
     "eslint": "^8.29.0",
     "eslint-plugin-frontmatter": "^0.0.8",
     "eslint-plugin-markdown": "^2.2.1",
     "eslint-plugin-mdx": "^2.0.0",
     "eslint-plugin-react": "^7.30.0",
+    "liquidjs": "^10.27.2",
     "markdownlint-cli": "^0.33.0",
-    "prettier": "^1.18.2",
+    "prettier": "^3.9.5",
+    "prettier-plugin-astro": "^0.14.1",
     "semver": "^7.7.2",
     "stylelint": "^14.9.0",
     "stylelint-config-standard-scss": "^4.0.0",
-    "stylelint-order": "^5.0.0"
+    "stylelint-order": "^5.0.0",
+    "typescript": "^6.0.3",
+    "wait-on": "^9.0.10"
   },
   "resolutions": {
     "graceful-fs": "^4.2.9"

src/components/LiquidInclude.astro

@@ -0,0 +1,25 @@
+---
+import fs from "node:fs";
+import path from "node:path";
+import type { LiquidRenderer } from "@/lib/liquid/liquidRenderer";
+
+const INCLUDES_ROOT = path.join(process.cwd(), "_includes");
+
+// Astro equivalent of Jekyll's `{% include %}` tag. Extra props are passed
+// through as `include.*` inside the partial, just like Jekyll:
+//   {% include foo.html param="x" %}  ->  <LiquidInclude src="foo.html" param="x" />
+interface Props {
+  lq: LiquidRenderer;
+  src: string;
+  [param: string]: unknown;
+}
+
+const { lq, src, ...params } = Astro.props;
+
+const html = await lq.render(
+  fs.readFileSync(path.join(INCLUDES_ROOT, src), "utf-8"),
+  { include: params },
+);
+---
+
+<Fragment set:html={html} />

src/content.config.ts

@@ -0,0 +1,10 @@
+import { defineCollection } from "astro:content";
+import { glob } from "astro/loaders";
+
+const examples = defineCollection({
+  loader: glob({
+    pattern: ["src/example-collection/**/*.md"],
+  }),
+});
+
+export const collections = { examples };

src/example-collection/example-doc.md

@@ -0,0 +1,52 @@
+---
+version: v0.62
+has_magic_breadcrumbs: true
+show_category_breadcrumb: true
+show_title_breadcrumb: true
+layout: new-docs
+no_index_no_follow: true
+---
+
+# Example markdown astro page
+
+## Liquid include examples
+
+{% include plans-blockquote.html feature="Authenticated embeds" sdk=true is_plural=true%}
+
+{% include youtube.html id='yTRzCQeTmO8' %}
+
+{% include beta-blockquote.html %}
+
+## Custom include_file examples
+
+Whole file (remove snippet comments):
+
+```js
+{% include_file "{{ dirname }}/sdk/snippets/next-js/app-router-authentication-api-route.ts" %}
+```
+
+Specific snippet:
+
+```js
+{% include_file "{{ dirname }}/sdk/snippets/authentication/auth-config-base.tsx" snippet="example" %}
+```
+
+## Miscellaneous cases
+
+### Inline attribute lists
+
+```
+[Metabase Expert](/partners/){:target="_blank"}
+```
+
+gets rendered as [Metabase Expert](/partners/){:target="_blank"}.
+
+### Inline code snippet
+
+Inline backticks like `this` get rendered as inline code with no copy button.
+
+### Responsive tables
+
+The columns should stack on small screens.
+
+{% include_file "{{ dirname }}/sdk/api/snippets/ParameterChangePayload.md" snippet="properties" %}

src/layouts/DefaultNewLayout.astro

@@ -0,0 +1,47 @@
+---
+import LiquidInclude from "@/components/LiquidInclude.astro";
+import { getLiquidRenderer } from "@/lib/liquid/liquidRenderer";
+
+type Props = {
+  page: Record<string, unknown>;
+  dirname: string;
+};
+
+const { page, dirname } = Astro.props;
+
+const lq = getLiquidRenderer({ page, dirname });
+---
+
+<!doctype html>
+<html prefix="og: https://ogp.me/ns#" lang="en-US">
+  <LiquidInclude lq={lq} src="head.html" />
+
+  <body>
+    <LiquidInclude lq={lq} src="shared-chrome/header.html" />
+
+    <div>
+      <slot />
+    </div>
+
+    <LiquidInclude lq={lq} src="shared-chrome/footer.html" />
+    <script is:inline type="text/javascript" src="/js/contentloaded.min.js"
+    ></script>
+    <script is:inline type="text/javascript" src="/js/lightbox.js"></script>
+    <script is:inline type="text/javascript" src="/js/documentation.js"
+    ></script>
+    <script is:inline type="text/javascript" src="/js/blog.js"></script>
+    <script is:inline type="text/javascript" src="/js/syntax-highlight.js"
+    ></script>
+
+    {
+      Astro.url.pathname.includes("/docs/") &&
+        Astro.url.pathname.includes("embedding") && (
+          <script
+            is:inline
+            type="text/javascript"
+            src="/js/docs/checkpoints.js"
+          />
+        )
+    }
+  </body>
+</html>

src/layouts/NewDocsLayout.astro

@@ -0,0 +1,91 @@
+---
+import LiquidInclude from "@/components/LiquidInclude.astro";
+import { getLiquidRenderer } from "@/lib/liquid/liquidRenderer";
+import DefaultNewLayout from "./DefaultNewLayout.astro";
+
+type Props = {
+  page: {
+    category: string;
+  };
+  dirname: string;
+};
+
+const { page, dirname } = Astro.props;
+
+/* Do not show breadcrumb on home page */
+const parts = Astro.url.pathname.split("/");
+const showBreadcrumb =
+  parts[1] == "docs" && parts.length == 4 && parts[3] === "index.html";
+
+const lq = getLiquidRenderer({ page, dirname });
+---
+
+<DefaultNewLayout page={page} dirname={dirname}>
+  <div class="bootstrap">
+    <div class="learn docs blog-post MB-Page">
+      <LiquidInclude lq={lq} src="docs/left-sidebar.html" domain="docs" />
+
+      <article class="learn__post learn__article">
+        <LiquidInclude
+          lq={lq}
+          src="learn/top-bar.html"
+          domain="docs"
+          show_breadcrumb="show_breadcrumb"
+        />
+
+        <div class="learn__post__content">
+          {!showBreadcrumb && <LiquidInclude lq={lq} src="docs_version.html" />}
+
+          <LiquidInclude lq={lq} src="docs/blockquotes.html" />
+
+          <slot />
+
+          <div>
+            <div class="widget-separator"></div>
+            {
+              page.category !== "Cloud" && (
+                <p>
+                  Read docs for other{" "}
+                  <a href="/docs/all">versions of Metabase</a>.
+                </p>
+              )
+            }
+          </div>
+        </div>
+
+        <div class="learn__right-sidebar">
+          <div id="sub-navigation-content">
+            {/* Is populated via js */}
+          </div>
+          <LiquidInclude
+            lq={lq}
+            src="shared/was-this-helpful-widget.html"
+            should_add_propose_a_change_dialog="true"
+          />
+        </div>
+      </article>
+    </div>
+  </div>
+
+  <script
+    is:inline
+    type="text/javascript"
+    src="/js/new-docs-version-selector.js"></script>
+  <script is:inline type="text/javascript" src="/js/new-docs-anchor-links.js"
+  ></script>
+  <script
+    is:inline
+    type="text/javascript"
+    src="/js/new-docs-code-snippet-copy.js"></script>
+  <script is:inline type="text/javascript" src="/js/new-docs-table-overflow.js"
+  ></script>
+  <script is:inline type="text/javascript" src="/js/image-zoom.js"></script>
+  <script is:inline type="text/javascript" src="/js/learn/left-sidebar.js"
+  ></script>
+  <script is:inline type="text/javascript" src="/js/docs/right-sidebar.js"
+  ></script>
+  <script is:inline type="text/javascript" src="/js/position-feedback-widget.js"
+  ></script>
+
+  <script is:inline src="/js/use-custom-header-checkout-link.js"></script>
+</DefaultNewLayout>