☂️ Migrate to 11ty #5177

parlough · 2023-09-18T15:10:35Z

An alternative to #4163 with a much lower up-front cost that still brings many of the benefits, greatly simplifying the site architecture and making it easier to add new features.

Details to be filled out...

These settings aren't used for anything anymore, so they can safely be removed. Contributes to #5177

- Moves `_tutorials` to `tutorials` for automatic rendering without collection - Removes now unused tutorials collection config - Moves all images used by tutorials to `/assets` Contributes to #5177

These settings aren't used for anything anymore, so they can safely be removed. Contributes to dart-lang#5177

- Moves `_tutorials` to `tutorials` for automatic rendering without collection - Removes now unused tutorials collection config - Moves all images used by tutorials to `/assets` Contributes to dart-lang#5177

Moves all docs under `/_guides` to `/guides` then removes now unnecessary collection setup. Contributes to #5177

Contributes to #5177 and #3846

- Moves `_tutorials` to `tutorials` for automatic rendering without collection - Removes now unused tutorials collection config - Moves all images used by tutorials to `/assets` Contributes to dart-lang#5177

Moves all docs under `/_guides` to `/guides` then removes now unnecessary collection setup. Contributes to dart-lang#5177

Contributes to dart-lang#5177 and dart-lang#3846

…lang#5202) We don't use indented code blocks on the site. Switching to fenced code blocks in this article does a few things: - Standardizes the snippets with the rest of the site - Allows us to specify `dart` as the language being highlighted, enabling syntax highlighting - Contributes to dart-lang#5177 which only supports fenced code blocks by default

This makes this relative include usage consistent with all other usages which use private files represented by beginning with a `_`. Contributes to dart-lang#5177 as some SSG don't use the existence of front matter to determine if something should be rendered or not.

This plugin's functionality is no longer used on the site. Removing it slightly reduces build times and reduces maintenance requirements for the site. Contributes to dart-lang#5177

The usage of these includes on dart.dev and docs.flutter.dev have diverged and will continue to. This PR copies the used ones to the local includes folder. This will allow easier atomic modifications of the files. We can eventually move them back to site-shared if/when their behavior stabilizes and is sufficient for both sites. Should slightly reduce build time as well. Contributes to dart-lang#5177 by allowing for changes which only one site will support temporarily.

It's good for each page to have a description, for discoverability (and SEO) reasons. Also for our own reference purposes. This change does the following: - Adds a check that each page has a description - Adds missing description - Cleans up or fixes some other descriptions Contributes to dart-lang#5177

This simplifies our site setup, as we work towards `/assets` being the standard location for all asset like files. Contributes to dart-lang#5193 Contributes to dart-lang#4473 by allowing any related image optimization to be consolidated to one location. Contributes to dart-lang#5177 by making asset pass-through easier to setup.

…5191) This simplifies our site setup, as we work towards `/assets` being the standard location for all asset like files. Contributes to dart-lang#5193 Contributes to dart-lang#4473 by allowing any related image optimization to be consolidated to one location. Contributes to dart-lang#5177 by making asset pass-through easier to setup.

This simplifies our site setup, as we work towards `/assets` being the standard location for all asset like files. Contributes to dart-lang#5177 by making asset pass-through easier to setup.

This simplifies our site setup, as we work towards `/assets` being the standard location for all asset like files. Contributes to dart-lang#5193 Contributes to dart-lang#4473 by allowing any related image optimization to be consolidated to one location. Contributes to dart-lang#5177 by making asset pass-through easier to setup.

The [articles index](https://dart.dev/articles) is a remnant of the past when some docs and some blog posts were published as articles on the site. It no longer serves a purpose as it's not in the sidenav and only links to one article. This PR removes the page and redirects it the Medium blog. The remaining articles under `/articles` will be slowly removed or moved elsewhere when they are updated. Contributes to dart-lang#5177

Some versions of liquid are more strict and require the existence to be verified first. Contributes to dart-lang#5177

Contributes to dart-lang#3846 and dart-lang#5177

…art-lang#5209) This makes css changes so the colored `.good` and `.bad` backgrounds apply successfully to the Effective Dart code blocks. Since all code blocks using highlighting (`[! !]`) are already code excerpts, highlighting continues to work. Contributes to dart-lang#3846 and dart-lang#5177

…ang#5205) All pages within `/_articles` are generated, so this PR converts it to be setup just like all the other content directories. As this removes our last collection, also uses a simpler (and faster) sitemap that just showcases all pages. Contributes to dart-lang#5177

- Prevents the 404 page being included on the generated page - Prevents non-HTML files (like CSS) being included - Stops looping through `site.documents` since we don't use it (therefore it's empty) Contributes to dart-lang#5177 which won't support `site.documents` anyway

We haven't used these includes in a long time. Removing them makes maintenance of the site easier. Contributes to dart-lang#5177 since we won't have to migrate these.

Helps us verify the code snippets stay up to date. Also switches from prettify to fenced code blocks where possible. Contributes to dart-lang#3846 and dart-lang#5177

Contributes to dart-lang#3846 and dart-lang#5177

Continuing the goal of reducing site maintenance costs, removes the unmaintained popover support and updates the one remaining use to no longer be reliant on it. This will also slightly reduce site loading time with less JS and CSS downloaded on every page :) We can revisit popover support in code snippets in the future if desired. Browsers are currently implementing [standardized popovers](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) that are more accessible and easier to implement. They have shipped in WebKit and Chromium based browsers and are set to be enabled in Firefox soon. Closes dart-lang#2316 Fixes dart-lang#4987 Contributes to dart-lang#5177 **Staged:** https://dart-dev--pr5271-feature-remove-popup-farcxcqp.web.app/tutorials/server/cmdline

This tooling is accessible from the root directory of the repository by calling `dart run dart_site <command> <args>`. It replaces our various scripts and will be the home of future staging and deploy commands after the migration to 11ty. To learn more about the commands available, run `dart run dart_site --help`. You can add a shortcut for `dart run dart_site` if you'd like, or I'll likely come up with a standard shortcut we can use as part of followup. I'll improve the formatting of the output and add a proper guide after the 11ty migration lands, as I expect to change some in that process. Contributes to dart-lang#4163 and dart-lang#5177

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

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 dart-lang#5177 Resolves dart-lang#3846 Resolves dart-lang#5323 Fixes dart-lang#4297 Fixes dart-lang#4919 Closes dart-lang#4631 Contributes to dart-lang#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

parlough self-assigned this Sep 18, 2023

This was referenced Sep 18, 2023

Redirect away from unused articles index page #5180

Merged

Remove unused settings in Jekyll config #5181

Merged

Simplify and cleanup setup of /tutorials #5182

Merged

parlough added a commit that referenced this issue Sep 18, 2023

Remove unused settings in Jekyll config (#5181)

7652dd6

These settings aren't used for anything anymore, so they can safely be removed. Contributes to #5177

atsansone pushed a commit to atsansone/site-www that referenced this issue Sep 18, 2023

Remove unused settings in Jekyll config (dart-lang#5181)

a72714f

These settings aren't used for anything anymore, so they can safely be removed. Contributes to dart-lang#5177

This was referenced Sep 18, 2023

Require each page to have a description #5184

Merged

Simplify setup of /guides docs #5186

Merged

parlough added a commit that referenced this issue Sep 18, 2023

Simplify setup of /guides docs (#5186)

4e5cf1e

Moves all docs under `/_guides` to `/guides` then removes now unnecessary collection setup. Contributes to #5177

atsansone pushed a commit that referenced this issue Sep 19, 2023

Use fenced code blocks for yaml where possible (#5188)

0464540

Contributes to #5177 and #3846

atsansone pushed a commit that referenced this issue Sep 19, 2023

Mark a few gitignore code blocks more specifically (#5187)

9a5c80e

Contributes to #5177 and #3846

parlough mentioned this issue Sep 19, 2023

Use fenced code blocks in outdated numeric computation article #5202

Merged

atsansone pushed a commit to atsansone/site-www that referenced this issue Jan 26, 2024

Simplify setup of /guides docs (dart-lang#5186)

89ced21

Moves all docs under `/_guides` to `/guides` then removes now unnecessary collection setup. Contributes to dart-lang#5177

atsansone pushed a commit to atsansone/site-www that referenced this issue Jan 26, 2024

Use fenced code blocks for yaml where possible (dart-lang#5188)

b9df2ff

Contributes to dart-lang#5177 and dart-lang#3846

atsansone pushed a commit to atsansone/site-www that referenced this issue Jan 26, 2024

Mark a few gitignore code blocks more specifically (dart-lang#5187)

a82380e

Contributes to dart-lang#5177 and dart-lang#3846

atsansone pushed a commit to atsansone/site-www that referenced this issue Jan 26, 2024

Explicitly only run css and js loops if specified (dart-lang#5211)

cd9b76a

Some versions of liquid are more strict and require the existence to be verified first. Contributes to dart-lang#5177

atsansone pushed a commit to atsansone/site-www that referenced this issue Jan 26, 2024

Switch to fenced code blocks in codecs articles (dart-lang#5208)

75e56b0

Contributes to dart-lang#3846 and dart-lang#5177

atsansone pushed a commit to atsansone/site-www that referenced this issue Jan 26, 2024

Misc migrations away from prettify (dart-lang#5218)

7c95be0

Contributes to dart-lang#3846 and dart-lang#5177

parlough closed this as completed in #5483 Feb 7, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

☂️ Migrate to 11ty #5177

☂️ Migrate to 11ty #5177

parlough commented Sep 18, 2023

☂️ Migrate to 11ty #5177

☂️ Migrate to 11ty #5177

Comments

parlough commented Sep 18, 2023