Migrate the site infrastructure to Jaspr and Jaspr Content (#12548)

**Staged:**
https://flutter-docs-prod--pr12548-feat-jaspr-migration-kz7c0jfj.web.app/

Migrates the site from being built with JS/TS, Node, and 11ty to being
built with purely Dart, [Jaspr](https://jaspr.site/), and [Jaspr
Content](https://docs.jaspr.site/content).

---

As part of this work, the `dash_site` bash script has been removed from
the root of the repository.

After the removal, you can access the site tooling, including building
and staging with `dart run dash_site <command>` from anywhere within the
repository workspace. If you still want a shorter command, you can add
an alias for `dart run dash_site` in your shell, such as `dst`.

---

**Staged:**
https://flutter-docs-prod--pr12548-feat-jaspr-migration-kz7c0jfj.web.app/

Resolves #12405
Fixes #12590

---------

Co-authored-by: Kilian Schulte <[email protected]>
Co-authored-by: Kilian Schulte <[email protected]>

Author: parlough

.github/dependabot.yml

@@ -11,21 +11,11 @@ updates:
       - "auto.dependencies"
       - "auto.github-action"
       - "lang.yaml"
-  - package-ecosystem: "npm"
-    directory: "/"
-    schedule:
-      interval: "daily"
-    allow:
-      - dependency-type: "production"
-    labels:
-      - "auto.dependencies"
-      - "auto.npm"
-      - "lang.javascript"
   - package-ecosystem: "pub"
     versioning-strategy: "increase-if-necessary"
     directories:
       - "/"
-      - "/tool/flutter_site"
+      - "/tool/dash_site"
     schedule:
       interval: "daily"
     labels:

.github/workflows/test.yml

@@ -13,9 +13,6 @@ on:
 # Declare default permissions as read only.
 permissions: read-all
 
-env:
-  NODE_VERSION: 22
-
 jobs:
   test:
     name: Analyze and test code examples
@@ -41,13 +38,13 @@ jobs:
         run: dart pub get
         continue-on-error: ${{ matrix.experimental }}
       - name: Check Dart code formatting
-        run: dart run flutter_site format-dart --check
+        run: dart run dash_site format-dart --check
         continue-on-error: ${{ matrix.experimental }}
       - name: Analyze Dart code
-        run: dart run flutter_site analyze-dart
+        run: dart run dash_site analyze-dart
         continue-on-error: ${{ matrix.experimental }}
       - name: Run Dart tests
-        run: dart run flutter_site test-dart
+        run: dart run dash_site test-dart
         continue-on-error: ${{ matrix.experimental }}
 
   excerpts:
@@ -62,24 +59,15 @@ jobs:
       - name: Fetch Dart dependencies
         run: dart pub get
       - name: Check if excerpts are up to date
-        run: dart run flutter_site refresh-excerpts --fail-on-update --dry-run
+        run: dart run dash_site refresh-excerpts --fail-on-update --dry-run
         continue-on-error: ${{ matrix.experimental }}
 
   linkcheck:
     name: Build site and check links
     runs-on: ubuntu-latest
+    timeout-minutes: 30
     steps:
       - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8
-      - name: Enable Corepack
-        run: npm i -g corepack@latest && corepack enable
-      - uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903
-        with:
-          node-version: ${{ env.NODE_VERSION }}
-          cache: 'pnpm'
-      - name: Setup pnpm
-        run: corepack install
-      - name: Install node dependencies
-        run: pnpm install --frozen-lockfile
       - uses: dart-lang/setup-dart@e51d8e571e22473a2ddebf0ef8a2123f0ab2c02c
         with:
           sdk: beta
@@ -88,11 +76,11 @@ jobs:
       - name: Install firebase-tools
         run: curl -sL https://firebase.tools | bash
       - name: Build site
-        run: dart run flutter_site build
+        run: dart run dash_site build
       - name: Check for broken Markdown link references
-        run: dart run flutter_site check-link-references
+        run: dart run dash_site check-link-references
       - name: Check for broken internal links
-        run: dart run flutter_site check-links
+        run: dart run dash_site check-links
 
   firebase-validate:
     name: Validate Firebase configuration
@@ -106,4 +94,4 @@ jobs:
       - name: Fetch Dart dependencies
         run: dart pub get
       - name: Validate the firebase.json file
-        run: dart run flutter_site verify-firebase-json
+        run: dart run dash_site verify-firebase-json

.idx/dev.nix

@@ -6,8 +6,8 @@
 
   # Use https://search.nixos.org/packages to find packages
   packages = [
-    pkgs.nodejs_22
-    pkgs.pnpm
+  # Node is included for deploying to Firebase.
+    pkgs.nodejs_24
   ];
 
   # Sets environment variables in the workspace
@@ -24,7 +24,7 @@
       enable = true;
       previews = {
         web = {
-          command = ["./dash_site" "serve"];
+          command = ["dart" "run" "dash_site" "serve"];
           manager = "web";
           env = {
             # Environment variables to set for your server
@@ -38,12 +38,11 @@
     workspace = {
       # Runs when a workspace is first created
       onCreate = {
-        pnpm-install = "pnpm install";
+        dart-pub-get = "dart pub get";
       };
       # Runs when the workspace is (re)started
       onStart = {
-        # Example: start a background task to watch and re-build backend code
-        # watch-backend = "npm run watch-backend";
+        dart-pub-get = "dart pub get";
       };
     };
   };

.nvmrc

@@ -5,10 +5,10 @@
 # [Flutter][] documentation website
 
 The [documentation site][Flutter] for the [Flutter framework][],
-built with [Eleventy][] and hosted on [Firebase][].
+built with [Jaspr][] and hosted on [Firebase][].
 
 [Flutter framework]: https://flutter.dev
-[Eleventy]: https://11ty.dev/
+[Jaspr]: https://jaspr.site
 [Firebase]: https://firebase.google.com/
 
 [Build Status]: https://github.com/flutter/website/workflows/build/badge.svg
@@ -88,12 +88,9 @@ enable an edit-refresh cycle.
 
 ### Get the prerequisites
 
-Install the following tools to build and develop the site:
+To build and develop the site, you'll need to
+install the latest stable release of Flutter, which includes Dart.
 
-#### Flutter
-
-The latest stable release of Flutter, which includes Dart,
-is required to build the site and run its tooling.
 If you don't have Flutter or need to update, follow the
 instructions at [Install Flutter][] or [Upgrading Flutter][].
 
@@ -107,28 +104,6 @@ flutter --version
 [Install Flutter]: https://docs.flutter.dev/get-started
 [Upgrading Flutter]: https://docs.flutter.dev/release/upgrade
 
-#### Node.js
-
-The **latest** stable LTS release of Node.js is required to build the site.
-If you don't have Node.js or need to update, download your
-computer's corresponding version and follow the instructions
-from the [Node.js download archive][].
-If you prefer, you can use a version manager such as [nvm][],
-and run `nvm install` from the repository's root directory.
-
-If you already have Node installed, verify it's available on your path
-and already the latest stable version _(currently `22.14` or later)_:
-
-```console
-node --version
-```
-
-If your version is out of date,
-follow the update instructions for how you originally installed it.
-
-[Node.js download archive]: https://nodejs.org/en/download/
-[nvm]: https://github.com/nvm-sh/nvm
-
 ### Clone this repo
 
 If you're not a member of the Flutter organization,
@@ -164,103 +139,53 @@ following the instructions in [Get the prerequisites](#get-the-prerequisites).
    dart pub get
    ```
 
-3. _Optional:_ We recommend you use `pnpm`, but you can also use `npm`.
-   Install `pnpm`, an alternative, efficient package manager for
-   npm packages. If you already have `pnpm`, verify you have the
-   latest stable version.
-
-   ```console
-   node --version
-   ```
-
-   If you don't already have `pnpm` installed, we recommend
-   using [`corepack`][] to install and manage `pnpm` versions,
-   since `corepack` is bundled with most installations of
-   Node. If you installed `node` using Homebrew, you'll need
-   to install corepack separately:
-
-   ```console
-   brew install corepack
-   ```
-
-   If you haven't used `corepack` before, you'll need to
-   first enable it with `corepack enable`.
-   Then, to install the correct `pnpm` version, from the
-   root directory of the repository, run `corepack install`:
-
-   ```console
-   corepack enable;
-   corepack install
-   ```
-
-   To install [`pnpm`][] without using `corepack`, you
-   can use your preferred [installation method][pnpm-install].
-
-5. _(optional)_ Once you have `pnpm` installed and setup,
-   fetch the site's npm dependencies using `pnpm install`.
-   We highly recommend you use `pnpm`, but you can also use `npm`.
-
-   ```console
-   pnpm install
-   ```
-
-   Rerun `pnpm install` whenever you incorporate the
-   latest changes to the `main` branch or if you
-   experience dependency or import errors when building the site.
-
-6. From the root directory, run the `dash_site` tool to
+3. From the root directory, run the `dash_site` tool to
    validate your setup and learn about the available commands.
 
-   ```console
-   ./dash_site --help
+   ```terminal
+   dart run dash_site --help
    ```
 
-7. From the root directory, serve the site locally.
+4. From the root directory, serve the site locally.
 
-   ```console
-   ./dash_site serve
+   ```terminal
+   dart run dash_site serve
    ```
 
    This command generates and serves the site on a
    local port that's printed to your terminal.
 
-8. View your changes in the browser by navigating to <http://localhost:4000>.
+5. View your changes in the browser by navigating to <http://localhost:8080>.
 
-   Note the port might be different if `4000` is taken.
+   Note the port might be different if `8080` is taken.
 
-   If you want to check the raw, generated HTML output and structure,
-   view the `_site` directory in a file explorer or an IDE.
-
-9. Make your changes to the local repo.
+6. Make your changes to the local repo.
 
+   To view your changes in the browser,
+   you'll need to refresh the page.
    The site should automatically rebuild on most changes, but if
    something doesn't update, exit the process and rerun the command.
-   Improvements to this functionality are planned.
-   Please open a new issue to track the issue if this occurs.
 
-10. Commit your changes to the branch and submit your PR.
+7. Commit your changes to the branch and submit your PR.
 
    If your change is large, or you'd like to test it,
    consider [validating your changes](#validate-your-changes).
 
 > [!TIP]
 > To find additional commands that you can run,
-> run `./dash_site --help` from the repository's root directory.
-
-[`corepack`]: https://nodejs.org/api/corepack.html
-[`pnpm`]: https://pnpm.io/
-[pnpm-install]: https://pnpm.io/installation
+> run `dart run dash_site --help` from the repository's root directory.
 
 ## Validate your changes
 
 ### Check documentation and example code
 
-If you've made changes to the code in the `/examples` or `/tool` directories,
+If you've made changes to the code in
+the `/examples`, `/site`, or `/tool` directories,
 commit your work, then run the following command to
 verify it is up to date and matches the site standards.
 
-```console
-./dash_site check-all
+```terminal
+dart run dash_site check-all
 ```
 
 If this script reports any errors or warnings,
@@ -286,53 +211,9 @@ how the snippets are copied from the `.dart` files.
 
 To resolve this error and update the Markdown snippets to match,
 from the root of the `website` directory,
-run `./dash_site refresh-excerpts`.
+run `dart run dash_site refresh-excerpts`.
 
 To learn more about creating, editing, and using code excerpts,
 check out the [excerpt updater package documentation][].
 
 [excerpt updater package documentation]: https://github.com/dart-lang/site-shared/tree/main/pkgs/excerpter#readme
-
-## [Optional] Deploy to a staging site
-
-Submitted pull requests can be automatically staged
-by a site maintainer.
-If you'd like to stage the site yourself though,
-you can build a full version and upload it to Firebase.
-
-1. If you don't already have a Firebase project,
-
-  - Navigate to the [Firebase Console](https://console.firebase.google.com)
-    and create your own Firebase project (for example, `flutter-dev-staging`).
-
-  - Head back to your local terminal and verify that you're logged in.
-
-    ```console
-    npm exec -- firebase-tools login
-    ```
-
-  - Ensure that your project exists and activate that project:
-
-    ```console
-    npm exec -- firebase-tools projects:list
-    npm exec -- firebase-tools use <your-project>
-    ```
-
-2. From the root directory of the repository, build the site:
-
-   ```console
-   ./dash_site build
-   ```
-
-   This builds the site and copies it to your local `_site` directory.
-   If that directory previously existed, it will be replaced.
-
-3. Deploy to your activated Firebase project's default hosting site:
-
-   ```console
-   npm exec -- firebase-tools deploy --only hosting
-   ```
-
-4. Navigate to your PR on GitHub and include the link of the staged version.
-   Do consider adding a reference to the commit you staged,
-   so that reviewers know if any further changes have been made.

README.md

@@ -2,15 +2,15 @@ steps:
   - name: gcr.io/cloud-builders/git
     args: ['fetch', '--unshallow']
   - name: gcr.io/flutter-dev-230821/firebase-ghcli
-    # Set up, build, then deploy site to production
+    # Build the site, then deploy it to production.
     entrypoint: '/bin/bash'
     args:
       - '-c'
       - |-
         set -e
 
-        npm install
-        npm run build-site-for-production
+        dart pub get
+        dart run dash_site build --release
 
         firebase deploy --project=flutter-docs-prod --only=hosting
 options:

cloud_build/deploy.yaml

@@ -7,8 +7,8 @@ steps:
       - |-
         set -e
 
-        npm install
-        npm run build-site-for-staging
+        dart pub get
+        dart run dash_site build
 
         cloud_build/scripts/stage_site_and_comment_on_github.sh
     secretEnv: ['GH_PAT_TOKEN']