Initial migration of site to 11ty (#5483)

I'm sorry that this ended up as such a large pull request, but that's
mostly because it essentially touched every file with a small set of
changes. See the different sections below for considerations for review
or future reference. Please note that we'd like this to land despite it
not being perfect, as then pain points can be identified and improved.
Then I can also follow up with proper documentation as the
implementation and syntax is stabilized. I'll be staying on top of any
reported issue. If anything goes majorly wrong, we can always revert the
change as well. Thanks for your time 💙

Resolves #5177
Resolves #3846
Resolves #5323
Fixes #4297
Fixes #4919
Closes #4631
Contributes to #4163

**Changes potentially worth reviewing from a technical perspective
are:**

- Implemented 11ty in `eleventy.config.js` with customizations in
`/src/_11ty`.
- `eleventy.config.js` configures the site build, enables used plugins,
and connects the custom logic added in `/src/_11ty`. This will be
greatly simplified and better documented in follow-up work.
- Replaced prettify, rouge, and custom code excerpter logic with custom
markdown plugin.
- You can find this at `/src/_11ty/plugins/highlight.js` _(super messy
for now)_.
  - New custom theme is at `/src/_11ty/syntax/dash-light.js`.
- The implementation of this needs a lot of cleanup and will be
simplified greatly in follow-up work to rely on recent improvements in
underlying highlighting package.
- Added a `build` and `serve` command to `dart run dart_site` (found in
`/tool/dart_site/lib`).
- The deploy configs in `/cloud_build` have been migrated from using
Docker to use Node to build the site. I reused the Docker image we built
for firebase_tools, as that already has Node. Let me know if I shouldn't
though :)
- Removed remnants of previous infra (Jekyll files, gem files, docker
files, makefile, etc).
- All written docs and assets have been moved into `/content` to enable
a separation from site tooling and configuration.

**Changes potentially worth reviewing or knowing about from a
writer/contributor perspective:**

- **Major:** All doc content has been moved into `/content`. This allows
site implementation to be separate from content, potentially enabling
easier downstream localization as well.
- The pre-existing global variables are now defined in
`/src/_data/site.yml`.
- Alerts/asides use a new syntax and have a design closer to other doc
sites, search for `:::` for examples.
- Prettify doesn't exist anymore. Always use Markdown code blocks. They
now always support highlighting with `[! !]`.
- Terminal code blocks now use `console` instead of `terminal`. Just
textual ones use `plaintext` instead of `nocode`.
- Markdown code blocks now support specifying a title/filename with
syntax like `title="main.dart"`. Various code blocks have been updated
to use it instead of one-off solutions.
- Code blocks have a new design, with slightly bigger text, new colors,
reduced padding, a more defined border, and a tag with the code block's
language.
- The README is updated with the core setup requirements. Note that more
comprehensive docs will come.
- To change the anchor of a header, a slightly modified `{:#new-id}`
syntax is now used.
- The include syntax is slightly different, put quotes around the
include filename and define arguments with colons: `{% include
'linter-rule-mention.md', rule:'unnecessary_getters_setters' %}`.

**Current issues:**

The following are some issues or regressions that I plan to accept in
the short term to get this landed.

- Terminal/console code blocks do not have their formatted black
background yet. They appear as normal code blocks.
- Incremental rebuild is slower than it should be due to a new bug in
11ty.

**Follow-up work:**

The following are some remaining tasks and improvements that I'd like to
complete in follow-up so this can land and stretch its feet. These
improvements can then be reviewed in isolation and incorporate what I've
learned from deploying.

- Incorporate fix for 11ty's current incremental rebuild issue.
- Add back external link icons where it makes sense during static build.
- Reintroduce terminal code block's having a custom style.
- Standardize old and new liquid functions and filters to modern 11ty
suggestions for consistent experience.
- Document the 11ty, liquid, and custom features we use that are
relevant to site writers and contributors.
- Speed up sidenav and TOC generation. Potentially reduce needed
dependencies while doing so.
- Clean up implementation of custom 11ty and Markdown plugins. Rely on
new features in underlying syntax highlighting plugin rather than
implementing our own form.
- Automate image optimization in production builds.
- Use TypeScript for custom 11ty functionality to avoid painfully adding
JSDocs everywhere.
- Add back a devcontainer setup for users who want to a functioning
workflow in the browser.
- Add skippable setup checks to `dart_site` tool
- Move the Cloud Build commands to `dart_site` tool

Author: parlough

.devcontainer/devcontainer.json

@@ -3,14 +3,6 @@
 
 version: 2
 updates:
-  - package-ecosystem: "bundler"
-    directory: "/"
-    schedule:
-      interval: "daily"
-    labels:
-      - "auto.dependencies"
-      - "auto.bundler"
-      - "lang.ruby"
   - package-ecosystem: "docker"
     directory: "/"
     schedule:

.dockerignore

@@ -23,7 +23,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        language: [ 'javascript', 'ruby' ]
+        language: [ 'javascript' ]
         # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python', 'ruby' ]
         # Learn more about CodeQL language support at https://git.io/codeql-language-support
 

.github/dependabot.yml

@@ -43,7 +43,7 @@ jobs:
       - uses: dart-lang/setup-dart@fedb1266e91cf51be2fdb382869461a434b920a3
         with:
           sdk: ${{ matrix.sdk }}
-      - name: Fetch packages
+      - name: Fetch Dart packages
         run: dart pub get
       - name: Check Dart code formatting
         run: dart run dart_site format-dart --check
@@ -57,25 +57,42 @@ jobs:
   linkcheck:
     name: Build site and check links
     runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
     steps:
       - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
         with:
           submodules: recursive
-      - run: make build
       - uses: dart-lang/setup-dart@fedb1266e91cf51be2fdb382869461a434b920a3
         with:
           sdk: stable
-      - name: Fetch packages
+      - name: Fetch Dart packages
         run: dart pub get
-      - name: Check for broken Markdown links
-        run: dart run dart_site check-link-references
-      - name: Validate the firebase.json file
-        run: dart run dart_site verify-firebase-json
-      - uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8
+      - uses: pnpm/action-setup@ebcfd6995dade4b0104ac774445cef8b3b4635b0
+        with:
+          version: 8
+      - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8
         with:
           node-version: ${{ env.NODE_VERSION }}
-      - run: npm install -g firebase-tools@13.0.2
+          cache: 'pnpm'
+      - name: Install node dependencies
+        run: pnpm install
+      - name: Build site
+        run: dart run dart_site build
+      - name: Check for broken Markdown links
+        run: dart run dart_site check-link-references
       - name: Check internal site links are functional
         run: dart run dart_site check-links
+
+  firebase-validate:
+    name: Validate Firebase configuration
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
+        with:
+          submodules: recursive
+      - uses: dart-lang/setup-dart@ca7e6fee45ffbd82b555a7ebfc236d2c86439f5b
+        with:
+          sdk: stable
+      - name: Fetch Dart packages
+        run: dart pub get
+      - name: Validate the firebase.json file
+        run: dart run dart_site verify-firebase-json

.github/workflows/codeql-analysis.yml

@@ -1,5 +1,3 @@
-_asset_bundler_cache
-_bookhtml
 _cache/
 _site/
 .*-cache
@@ -10,8 +8,6 @@ _site/
 .env*
 .firebase
 .idea
-.packages
-.pub
 .spelling
 .vscode
 *.cache
@@ -25,6 +21,7 @@ build
 firebase-debug.log
 node_modules
 pubspec.lock
+package-lock.json
 tmp
 
 # Misc

.github/workflows/test.yml

@@ -0,0 +1 @@
+lts/*

.gitignore

@@ -13,3 +13,4 @@ Chris Buckett <chrisbuckett@gmail.com>
 Michael Haubenwallner <michael.haubenwallner@gmail.com>
 Victor Berchet <victor.berchet@gmail.com>
 Pradumna Saraf <pradumnasaraf@gmail.com>
+Parker Lougheed <parlough@gmail.com>

.nvmrc

@@ -18,8 +18,7 @@ You can contribute in a few ways.
 
 * **[Report issues][].**
 
-* **Fix known issues** (especially ones with the label **[help wanted][]** or
-  **[beginner][]**). These issues may or may not be easy to fix. Sometimes
+* **Fix known issues.** These issues may or may not be easy to fix. Sometimes
   they're issues that we don't have the expertise to fix, and we'd love to
   work with a contributor who has the right skills.
 
@@ -37,11 +36,9 @@ More info:
 * For more ways to contribute to Dart, see the
   [dart-lang/sdk Contributing page][].
 
-[beginner]: https://github.com/dart-lang/site-www/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3A%22help%20wanted%22%20label%3Abeginner%20
 [dart-lang/sdk Contributing page]: https://github.com/dart-lang/sdk/blob/main/CONTRIBUTING.md
-[GitHub pull request]: https://docs.github.com/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests
+[GitHub pull request]: https://docs.github.com/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests
 [Google Developer Documentation Style Guide]: https://developers.google.com/style/
-[help wanted]: https://github.com/dart-lang/site-www/issues?utf8=%E2%9C%93&q=is%3Aopen%20is%3Aissue%20label%3A%22help%20wanted%22%20
 [in the site-shared repo]: https://github.com/dart-lang/site-shared/blob/main/doc
 [issue tracker]: https://github.com/dart-lang/site-www/issues
 [on Flutter's Discord server]: https://github.com/flutter/flutter/wiki/Chat
@@ -62,29 +59,35 @@ you'll probably need to change the code in two places:
 For example, say you want to change the following code in the
 [Variables documentation](https://dart.dev/language/variables):
 
-```
+````
 <?code-excerpt "misc/lib/language_tour/variables.dart (var-decl)"?>
-{% prettify dart tag=pre+code %}
+```dart
 var name = 'Bob';
-{% endprettify %}
 ```
+````
 
 Besides editing
-[/src/language/variables.md][]
+[`/src/language/variables.md`][]
 (which you can find by clicking the GitHub icon at the top right of the page),
 you'll also need to edit the `var-decl` region of
-[/examples/misc/lib/language_tour/variables.dart][].
+[`/examples/misc/lib/language_tour/variables.dart`][].
 
 If you create a PR but forget to edit the Dart file,
 or if your changes don't analyze/test cleanly,
 the [GitHub Actions][] CI build will fail.
 Just update the PR, and GitHub Actions will run again.
 
+If you followed the setup in the README,
+you can instead run `dart run dart_site refresh-excerpts`
+from the root directory of the repository to update the Markdown files.
+
 [GitHub Actions]: https://docs.github.com/actions/learn-github-actions/understanding-github-actions
-[/src/language/variables.md]: https://github.com/dart-lang/site-www/blob/main/src/language/variables.md
-[/examples/misc/lib/language_tour/variables.dart]: https://github.com/dart-lang/site-www/blob/main/examples/misc/lib/language_tour/variables.dart
+[`/src/language/variables.md`]: https://github.com/dart-lang/site-www/blob/main/src/language/variables.md
+[`/examples/misc/lib/language_tour/variables.dart`]: https://github.com/dart-lang/site-www/blob/main/examples/misc/lib/language_tour/variables.dart
 
 ## A word about conduct
 
 We pledge to maintain an open and welcoming environment.
-For details, see our [code of conduct](https://dart.dev/community/code-of-conduct).
+For details, see our [code of conduct][].
+
+[code of conduct]: https://dart.dev/community/code-of-conduct