Generate site with Dart based tooling #4163
Assignees
Labels
e4-months
Can complete in >= 1 month of normal, not dedicated, work
infra.structure
Relates to the tools that create dart.dev
p3-low
Valid but not urgent concern. Resolve when possible. Encourage upvote to surface.
st.triage.ltw
Indicates Lead Tech Writer has triaged
Comments
parlough
added
infra.structure
Closed
parlough
added a commit
that referenced
this issue
Jan 18, 2024
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 #4163 and #5177
atsansone
pushed a commit
to atsansone/site-www
that referenced
this issue
Jan 26, 2024
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
parlough
added a commit
that referenced
this issue
Feb 7, 2024
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 going to close this as solved for now. We've migrated to 11ty and a lot of the site tooling has been switched to a consolidated I expect more and more can be converted to Dart over time 🥳 |
atsansone
pushed a commit
to atsansone/site-www
that referenced
this issue
Feb 9, 2024
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
atsansone
pushed a commit
to atsansone/site-www
that referenced
this issue
Feb 12, 2024
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
atsansone
pushed a commit
to atsansone/site-www
that referenced
this issue
Feb 20, 2024
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Describe the problem
Currently, dart.dev and docs.flutter.dev both use a complex setup using Jekyll with Ruby plugins, some custom built Dart tools, as well as some JavaScript scripts for various functionality. It got so complex we migrated to using a Docker based build so users wouldn't have to deal with setting it all up.
This makes contributions and updates harder as our community is mostly familiar with Dart. If the website was made with Dart, it would make contributions and updates much easier, and also serve as a good example of Dart's capabilities as a command-line or developer tooling language.
Expected fix
Investigate current Dart static site generators (https://github.com/simolus3/built_site), either use them, or build a new one with needed capabilities.
Additional context
Some potentially related issues to keep in mind:
The text was updated successfully, but these errors were encountered: