From d45191b8629650da6a8c87ad1c3600e61eb2ab95 Mon Sep 17 00:00:00 2001 From: Princesseuh <3019731+Princesseuh@users.noreply.github.com> Date: Wed, 20 Mar 2024 15:21:49 +0100 Subject: [PATCH 1/5] feat: Add a high-level page about the dev toolbar --- src/content/docs/en/guides/dev-toolbar.mdx | 75 ++++++++++++++++++++++ src/i18n/en/nav.ts | 5 ++ 2 files changed, 80 insertions(+) create mode 100644 src/content/docs/en/guides/dev-toolbar.mdx diff --git a/src/content/docs/en/guides/dev-toolbar.mdx b/src/content/docs/en/guides/dev-toolbar.mdx new file mode 100644 index 0000000000000..407404db52c08 --- /dev/null +++ b/src/content/docs/en/guides/dev-toolbar.mdx @@ -0,0 +1,75 @@ +--- +title: Dev Toolbar +--- + +Astro includes a development toolbar at the bottom of every page. This toolbar includes a number of useful tools ("apps") for debugging and inspecting your site during development, and can be extended using [Astro integrations](/en/guides/integrations-guide/) with the [Dev Toolbar API](/en/reference/dev-toolbar-app-reference/). + +This toolbar is enabled by default and will only appear in development mode. It is not included in the final build of your site. + +## Built-in apps + +### Astro + +The Astro app provides easy access to different information about the current project and links about Astro. Notably, it provides a one-click access to the Astro documentation, GitHub repository, and Discord server. + +This app also include a "Copy debug info" button, which will copy the output of the [`astro info`](/en/reference/cli-reference/#astro-info) command to your clipboard. This can be useful when asking for help or reporting issues. + +### X-ray + +The X-ray app allows you to inspect the [Islands](/en/concepts/islands/) on the current page, showing you the properties that are being passed to each islands, and the client directive that is being used to render them. + +### Audits + +The Audits app runs a series of audits on the current page, checking for common performance and accessibility issues. When an issue is found, a red dot will appear in the toolbar, and the issue will be highlighted in the page once you click on the app. + +:::note +The performance and accessibility audits done by the dev toolbar are intentionally not as comprehensive as those provided by dedicated tools like [Pa11y](https://pa11y.org/) or [Lighthouse](https://developers.google.com/web/tools/lighthouse), or even better, humans. + +The dev toolbar aims to provide a quick and easy way to catch common issues during development, without needing to context-switch to a different tool. +::: + +### Settings + +The Settings app allows you to toggle different settings for the development toolbar, such as verbose logging, and the ability to disable notifications. + +## Extending the dev toolbar + +[Astro integrations](/en/guides/integrations-guide/) can add new apps to the dev toolbar, allowing you to extend it with custom tools that are specific to your project. To see a list of integrations that provide dev toolbar apps, see the "Dev Toolbar" section of the [integrations list](https://astro.build/integrations/?search=&categories%5B%5D=toolbar). + +```shell + +## Disabling the dev toolbar + +### Per-project + +To disable the dev toolbar for everyone working on a project, you can set `devToolbar: false` in your project's [config file](/en/reference/config-reference/). + +```js title="astro.config.mjs" +import { defineConfig } from "astro/config"; + +export default defineConfig({ + devToolbar: { + enabled: false + } +}) +``` + +### Per-user + +If you want to disable the dev toolbar for yourself on a specific project, you can do so using the `astro preferences` command. + +```shell +astro preferences disable devToolbar +``` + +To disable the devToolbar in all Astro projects on the current machine: + +```shell +astro preferences disable --global devToolbar +``` + +The devToolbar can later be enabled with: + +```shell +astro preferences enable devToolbar +``` diff --git a/src/i18n/en/nav.ts b/src/i18n/en/nav.ts index 4ebd07160a8ab..e5a8cd9f83702 100644 --- a/src/i18n/en/nav.ts +++ b/src/i18n/en/nav.ts @@ -80,6 +80,11 @@ export default [ slug: 'guides/prefetch', key: 'guides/prefetch', }, + { + text: 'Dev Toolbar', + slug: 'guides/dev-toolbar', + key: 'guides/dev-toolbar', + }, { text: 'Integrations', header: true, type: 'learn', key: 'addons' }, { text: 'Add integrations', slug: 'guides/integrations-guide', key: 'guides/integrations-guide' }, From 1663f5f178f75964d65266ff560b7b8c533c8678 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Thu, 21 Mar 2024 12:39:04 +0000 Subject: [PATCH 2/5] Talking and docing tiny edits --- src/content/docs/en/guides/dev-toolbar.mdx | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/src/content/docs/en/guides/dev-toolbar.mdx b/src/content/docs/en/guides/dev-toolbar.mdx index 407404db52c08..3c3afc9f9e22c 100644 --- a/src/content/docs/en/guides/dev-toolbar.mdx +++ b/src/content/docs/en/guides/dev-toolbar.mdx @@ -4,7 +4,7 @@ title: Dev Toolbar Astro includes a development toolbar at the bottom of every page. This toolbar includes a number of useful tools ("apps") for debugging and inspecting your site during development, and can be extended using [Astro integrations](/en/guides/integrations-guide/) with the [Dev Toolbar API](/en/reference/dev-toolbar-app-reference/). -This toolbar is enabled by default and will only appear in development mode. It is not included in the final build of your site. +This toolbar is enabled by default, appears when you hover over the bottom of the page, and will only appear in development mode. It is not included in the final build of your site. ## Built-in apps @@ -36,8 +36,6 @@ The Settings app allows you to toggle different settings for the development too [Astro integrations](/en/guides/integrations-guide/) can add new apps to the dev toolbar, allowing you to extend it with custom tools that are specific to your project. To see a list of integrations that provide dev toolbar apps, see the "Dev Toolbar" section of the [integrations list](https://astro.build/integrations/?search=&categories%5B%5D=toolbar). -```shell - ## Disabling the dev toolbar ### Per-project @@ -62,13 +60,13 @@ If you want to disable the dev toolbar for yourself on a specific project, you c astro preferences disable devToolbar ``` -To disable the devToolbar in all Astro projects on the current machine: +To disable the dev toolbar in all Astro projects for a user on the current machine: ```shell astro preferences disable --global devToolbar ``` -The devToolbar can later be enabled with: +The dev toolbar can later be enabled with: ```shell astro preferences enable devToolbar From 65f16e6b86b718de45b6b8211492a5174f95279a Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Fri, 22 Mar 2024 10:13:39 -0300 Subject: [PATCH 3/5] Apply Ming-jun Lu suggestions from code review Co-authored-by: Ming-jun Lu <40516784+mingjunlu@users.noreply.github.com> --- src/content/docs/en/guides/dev-toolbar.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/guides/dev-toolbar.mdx b/src/content/docs/en/guides/dev-toolbar.mdx index 3c3afc9f9e22c..d7125e40a97f4 100644 --- a/src/content/docs/en/guides/dev-toolbar.mdx +++ b/src/content/docs/en/guides/dev-toolbar.mdx @@ -16,7 +16,7 @@ This app also include a "Copy debug info" button, which will copy the output of ### X-ray -The X-ray app allows you to inspect the [Islands](/en/concepts/islands/) on the current page, showing you the properties that are being passed to each islands, and the client directive that is being used to render them. +The X-ray app allows you to inspect the [Islands](/en/concepts/islands/) on the current page, showing you the properties that are being passed to each island, and the client directive that is being used to render them. ### Audits @@ -40,7 +40,7 @@ The Settings app allows you to toggle different settings for the development too ### Per-project -To disable the dev toolbar for everyone working on a project, you can set `devToolbar: false` in your project's [config file](/en/reference/config-reference/). +To disable the dev toolbar for everyone working on a project, you can set `devToolbar: false` in your project's [config file](/en/reference/configuration-reference/). ```js title="astro.config.mjs" import { defineConfig } from "astro/config"; From d828f403d1368fc26c96fd2496ab25fa0d67b2a5 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Fri, 22 Mar 2024 14:20:44 +0000 Subject: [PATCH 4/5] sarah edits --- src/content/docs/en/guides/dev-toolbar.mdx | 42 +++++++++++++--------- 1 file changed, 26 insertions(+), 16 deletions(-) diff --git a/src/content/docs/en/guides/dev-toolbar.mdx b/src/content/docs/en/guides/dev-toolbar.mdx index d7125e40a97f4..a4755c24609a0 100644 --- a/src/content/docs/en/guides/dev-toolbar.mdx +++ b/src/content/docs/en/guides/dev-toolbar.mdx @@ -1,29 +1,33 @@ --- title: Dev Toolbar +description: A guide to using the developer toolbar in Astro +i18nReady: true --- -Astro includes a development toolbar at the bottom of every page. This toolbar includes a number of useful tools ("apps") for debugging and inspecting your site during development, and can be extended using [Astro integrations](/en/guides/integrations-guide/) with the [Dev Toolbar API](/en/reference/dev-toolbar-app-reference/). +While the dev server is running, Astro includes a development toolbar at the bottom of every page in your local browser preview. -This toolbar is enabled by default, appears when you hover over the bottom of the page, and will only appear in development mode. It is not included in the final build of your site. +This toolbar includes a number of useful tools for debugging and inspecting your site during development and can be [extended with more dev toolbar apps](#extending-the-dev-toolbar) found in the integrations directory. You can even build your own apps using the [Dev Toolbar API](/en/reference/dev-toolbar-app-reference/)! + +This toolbar is enabled by default and appears when you hover over the bottom of the page. It is a development tool only and will not appear on your published site. ## Built-in apps -### Astro +### Astro Menu -The Astro app provides easy access to different information about the current project and links about Astro. Notably, it provides a one-click access to the Astro documentation, GitHub repository, and Discord server. +The Astro Menu app provides easy access to various information about the current project and links to extra resources. Notably, it provides one-click access to the Astro documentation, GitHub repository, and Discord server. -This app also include a "Copy debug info" button, which will copy the output of the [`astro info`](/en/reference/cli-reference/#astro-info) command to your clipboard. This can be useful when asking for help or reporting issues. +This app also includes a "Copy debug info" button which will run the [`astro info`](/en/reference/cli-reference/#astro-info) command and copy the output to your clipboard. This can be useful when asking for help or reporting issues. -### X-ray +### Inspect -The X-ray app allows you to inspect the [Islands](/en/concepts/islands/) on the current page, showing you the properties that are being passed to each island, and the client directive that is being used to render them. +The Inspect app provides information about any [islands](/en/concepts/islands/) on the current page. This will show you the properties passed to each island, and the client directive that is being used to render them. -### Audits +### Audit -The Audits app runs a series of audits on the current page, checking for common performance and accessibility issues. When an issue is found, a red dot will appear in the toolbar, and the issue will be highlighted in the page once you click on the app. +The Audit app automatically runs a series of audits on the current page, checking for the most common performance and accessibility issues. When an issue is found, a red dot will appear in the toolbar. Clicking on the app will pop up a list of results from the audit and will highlight the related elements directly in the page. :::note -The performance and accessibility audits done by the dev toolbar are intentionally not as comprehensive as those provided by dedicated tools like [Pa11y](https://pa11y.org/) or [Lighthouse](https://developers.google.com/web/tools/lighthouse), or even better, humans. +The basic performance and accessibility audits performed by the dev toolbar are not a replacement for dedicated tools like [Pa11y](https://pa11y.org/) or [Lighthouse](https://developers.google.com/web/tools/lighthouse), or even better, humans! The dev toolbar aims to provide a quick and easy way to catch common issues during development, without needing to context-switch to a different tool. ::: @@ -34,15 +38,19 @@ The Settings app allows you to toggle different settings for the development too ## Extending the dev toolbar -[Astro integrations](/en/guides/integrations-guide/) can add new apps to the dev toolbar, allowing you to extend it with custom tools that are specific to your project. To see a list of integrations that provide dev toolbar apps, see the "Dev Toolbar" section of the [integrations list](https://astro.build/integrations/?search=&categories%5B%5D=toolbar). +Astro integrations can add new apps to the dev toolbar, allowing you to extend it with custom tools that are specific to your project. You can find [more dev tool apps to install in the integrations directory](https://astro.build/integrations/?search=&categories%5B%5D=toolbar) or using the [Astro Menu](#astro-menu). + +Install additional dev toobar app integrations in your project just like any other [Astro integration](/en/guides/integrations-guide/) according to its own installation instructions. ## Disabling the dev toolbar +The dev toolbar is enabled by default for every site. You can choose to disable it for individual projects and/or users as needed. + ### Per-project -To disable the dev toolbar for everyone working on a project, you can set `devToolbar: false` in your project's [config file](/en/reference/configuration-reference/). +To disable the dev toolbar for everyone working on a project, set `devToolbar: false` in the [Astro config file](/en/reference/configuration-reference/). -```js title="astro.config.mjs" +```js title="astro.config.mjs" ins={4-6} import { defineConfig } from "astro/config"; export default defineConfig({ @@ -52,15 +60,17 @@ export default defineConfig({ }) ``` +To enable the dev toolbar again, remove these lines from your configuration, or set `enabled:true`. + ### Per-user -If you want to disable the dev toolbar for yourself on a specific project, you can do so using the `astro preferences` command. +To disable the dev toolbar for yourself on a specific project, run the [`astro preferences`](/en/reference/cli-reference/#astro-preferences) command. ```shell astro preferences disable devToolbar ``` -To disable the dev toolbar in all Astro projects for a user on the current machine: +To disable the dev toolbar in all Astro projects for a user on the current machine, add the `--global` flag when running `astro-preferences`: ```shell astro preferences disable --global devToolbar @@ -70,4 +80,4 @@ The dev toolbar can later be enabled with: ```shell astro preferences enable devToolbar -``` +``` \ No newline at end of file From 3f664cee6820088175ba3d303acbe22311d49395 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Fri, 22 Mar 2024 14:28:56 +0000 Subject: [PATCH 5/5] update link on main installation page to point here instead of API page --- src/content/docs/en/install/auto.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/install/auto.mdx b/src/content/docs/en/install/auto.mdx index da79372259ee0..3ee352e86f4a0 100644 --- a/src/content/docs/en/install/auto.mdx +++ b/src/content/docs/en/install/auto.mdx @@ -85,7 +85,7 @@ If all goes well, Astro should now be serving your project on [http://localhost: Astro will listen for live file changes in your `src/` directory, so you will not need to restart the server as you make changes during development. -When viewing your site in the browser, you'll have access to the [Astro dev toolbar](/en/reference/configuration-reference/#dev-toolbar-options). As you build, it will help you inspect your [islands](/en/concepts/islands/), spot accessibility issues, and more. +When viewing your site in the browser, you'll have access to the [Astro dev toolbar](/en/guides/dev-toolbar/). As you build, it will help you inspect your [islands](/en/concepts/islands/), spot accessibility issues, and more. If you aren't able to open your project in the browser, go back to the terminal where you ran the `dev` command and look to see if an error occurred, or if your project is being served at a different URL than the one linked to above.