docs! (#67)

docs/astro.config.mjs

@@ -51,6 +51,7 @@ export default defineConfig({
           label: 'Getting started',
           items: [
             { label: 'Quick start', link: '/user/quick-start/' },
+            { label: 'Rules', link: '/user/rules/' },
             { label: 'Improve performance', link: '/user/performance/' },
             { label: 'Interpret results', link: '/user/actionability/' },
             { label: 'Static vs dynamic assessment', link: '/user/assessment-mode/' },

docs/src/components/CapoOptions.astro

@@ -0,0 +1,10 @@
+---
+import { Image } from 'astro:assets';
+import CrxOptionsLight from '../assets/crx-options-light.png';
+import CrxOptionsDark from '../assets/crx-options-dark.png';
+---
+
+<picture>
+  <source srcset={CrxOptionsLight.src} media="(prefers-color-scheme: dark)"/>
+  <Image src={CrxOptionsDark} alt="Screenshot of the options page of the Capo extension" />
+</picture>

docs/src/components/CapoPalette.astro

@@ -20,15 +20,7 @@ const bgcolors = JSON.parse(colors).map(color => {
 </style>
 
 <div>
-  <span class="capo-color" style={bgcolors[0]}></span>
-  <span class="capo-color" style={bgcolors[1]}></span>
-  <span class="capo-color" style={bgcolors[2]}></span>
-  <span class="capo-color" style={bgcolors[3]}></span>
-  <span class="capo-color" style={bgcolors[4]}></span>
-  <span class="capo-color" style={bgcolors[5]}></span>
-  <span class="capo-color" style={bgcolors[6]}></span>
-  <span class="capo-color" style={bgcolors[7]}></span>
-  <span class="capo-color" style={bgcolors[8]}></span>
-  <span class="capo-color" style={bgcolors[9]}></span>
-  <span class="capo-color" style={bgcolors[10]}></span>
+  {bgcolors.map(style => (
+    <span style={style}></span>
+  ))}
 </div>

docs/src/components/InlineCapoIcon.astro

@@ -0,0 +1,15 @@
+---
+import Capo256 from '../assets/capo256.png';
+
+const { width=20 } = Astro.props;
+---
+
+<style>
+  img {
+    display: inline !important;
+    margin: 0;
+    vertical-align: text-bottom;
+  }
+</style>
+
+<img src={Capo256.src} width={width}/>

docs/src/components/InlineCapoWeightBars.astro

@@ -0,0 +1,36 @@
+---
+const DEFAULT_PALETTE = [
+  "#9e0142",
+  "#d53e4f",
+  "#f46d43",
+  "#fdae61",
+  "#fee08b",
+  "#e6f598",
+  "#abdda4",
+  "#66c2a5",
+  "#3288bd",
+  "#5e4fa2",
+  "#cccccc"
+];
+
+
+let { weight="1", color } = Astro.props;
+
+weight = Number(weight);
+
+if (!color) {
+  color = DEFAULT_PALETTE[11 - weight];
+}
+
+const style = `color: ${color};`;
+const bars = new Array(weight).fill('█').join('');
+---
+
+<style>
+  span {
+    display: inline !important;
+    white-space: nowrap;
+  }
+</style>
+
+<span style={style}>{bars}</span>

docs/src/content/docs/index.mdx

@@ -1,9 +1,9 @@
 ---
-title: Get your ﹤𝚑𝚎𝚊𝚍﹥ in order
+title: "capo.js: get your ﹤𝚑𝚎𝚊𝚍﹥ in order"
 description: Getting starting with capo.js
 hero:
-  title: Get your <code>&lt;head></code> in order
-  tagline: Getting started with capo.js
+  title: capo.js
+  tagline: Get your <code>&lt;head></code> in order
   image:
     file: ../../assets/capo256.png
   actions:

docs/src/content/docs/user/config.mdx

@@ -3,12 +3,10 @@ title: Configuring capo.js
 description: Learn how to use config options to customize the capo.js behavior
 ---
 
-import { Image } from 'astro:assets';
 import { Tabs, TabItem } from '@astrojs/starlight/components';
+import CapoOptions from '../../../components/CapoOptions.astro';
 import CapoPalette from '../../../components/CapoPalette.astro';
-import Capo256 from '../../../assets/capo256.png';
-import CrxOptionsLight from '../../../assets/crx-options-light.png';
-import CrxOptionsDark from '../../../assets/crx-options-dark.png';
+import InlineCapoIcon from '../../../components/InlineCapoIcon.astro';
 
 You can configure how capo.js behaves in a couple of different ways depending on which tool you're using.
 
@@ -50,11 +48,15 @@ To disable validation, set the `validation` parameter to `false`.
 
 ### Built-in color palettes
 
-capo.js supports three built-in color palettes: default, pink, and blue.
+capo.js supports three built-in color palettes:
 
-#### Default
+- `"DEFAULT"` (rainbow)
+- `"PINK"`
+- `"BLUE"`
+
+The snippet supports [custom color palettes](#custom-color-palette).
 
-The default color palette is a rainbow:
+#### Default
 
 <CapoPalette colors='[
   "#9e0142",
@@ -70,12 +72,8 @@ The default color palette is a rainbow:
   "#cccccc"
 ]' />
 
-Omit the `palette` parameter to use the default palette, or explicitly specify it using the `"DEFAULT"` value.
-
 #### Pink
 
-Another buit-in palette is the pink theme:
-
 <CapoPalette colors='[
   "oklch(5% .1 320)",
   "oklch(13% .2 320)",
@@ -90,12 +88,8 @@ Another buit-in palette is the pink theme:
   "#ccc"
 ]' />
 
-Enable the pink theme by setting the `palette` parameter to `"PINK"`.
-
 #### Blue
 
-capo.js also supports the built-in blue theme:
-
 <CapoPalette colors='[
   "oklch(5% .1 200)",
   "oklch(13% .2 200)",
@@ -110,31 +104,26 @@ capo.js also supports the built-in blue theme:
   "#ccc"
 ]' />
 
-Enable the blue theme by setting the `palette` parameter to `"BLUE"`.
-
 ## Configuring the extension
 
-:::note
-The extension doesn't support custom logging prefixes. Also, only [built-in color palettes](#built-in-color-palettes) are available.
-:::
-
 Open the **Options** page to configure the [extension](/capo.js/user/extension/):
 
-1. Right click on the extension icon <img src={Capo256.src} style="display: inline; width: 20px; vertical-align: text-bottom; margin: 0;"/>
+1. Right click on the extension icon <InlineCapoIcon />
 
     ![The context menu shown after right clicking the extension icon](../../../assets/crx-menu.png)
 
 2. Select **Options**
 
 Select or deselect the options you want to enable or disable.
 
-<picture>
-    <source srcset={CrxOptionsLight.src} media="(prefers-color-scheme: dark)"/>
-    <Image src={CrxOptionsDark} alt="Screenshot of the options page of the Capo extension" />
-</picture>
+<CapoOptions/>
 
 Options are saved automatically after each change.
 
+:::note
+The extension doesn't support custom logging prefixes. Also, only [built-in color palettes](#built-in-color-palettes) are available.
+:::
+
 ## Configuring the snippet
 
 The [snippet](/capo.js/user/snippet/) can be customized by setting your preferences in a global configuration object, `__CAPO__`.
@@ -205,3 +194,5 @@ window.__CAPO__ = {
 ![The custom color palette in use](../../../assets/custom-palette.png)
 
 You can provide colors in any format supported by Chrome, for example: hex, rgb, hsl, oklch, named colors, etc. Formats can also be mixed and matched within the same config.
+
+The array must contain exactly 11 colors.

docs/src/content/docs/user/extension.mdx

@@ -0,0 +1,44 @@
+---
+title: Using the Capo extension
+description: Learn about the Capo extension for Chrome and how to use it with capo.js
+hero:
+  actions:
+    - text: Install the extension
+      link: https://chrome.google.com/webstore/detail/capo-get-your-%EF%B9%A4%F0%9D%9A%91%F0%9D%9A%8E%F0%9D%9A%8A%F0%9D%9A%8D%EF%B9%A5/ohabpnaccigjhkkebjofhpmebofgpbeb
+      icon: rocket
+      variant: primary
+---
+
+import CapoOptions from '../../../components/CapoOptions.astro';
+import InlineCapoIcon from '../../../components/InlineCapoIcon.astro';
+
+
+![Capo extension](../../../assets/capo-chrome.png)
+
+Capo is a Chrome extension that gives you one-click access to the capo.js script. Clicking the extension icon ( <InlineCapoIcon/> ) will open a color bar visualizing the `<head>` ordering, and log messages to the console, including validation warnings and detailed element info.
+
+## Installation
+
+To install the Capo extension:
+
+1. Navigate to the [Capo extension](https://chrome.google.com/webstore/detail/capo-get-your-%3Chead%3E-in-o/ohabpnaccigjhkkebjofhpmebofgpbeb) in the Chrome Web Store
+
+    ![The Capo extension in the Chrome Web Store](../../../assets/crx-store.png)
+
+2. Click the **Add to Chrome** button
+3. On any page, click the Capo icon ( <InlineCapoIcon/> ) in the browser toolbar
+    - Open the DevTools Console to see additional logs
+
+    ![Capo extension](../../../assets/capo-extension.png)
+
+:::tip
+The extension will auto-update whenever new versions are released.
+:::
+
+## Configuration
+
+<CapoOptions/>
+
+The extension comes with a few default options for static evaluation, validation, and the color palette.
+
+See the [Configuration](/capo.js/user/config/#configuring-the-extension) guide for more info on accessing the options page and what each option does.

docs/src/content/docs/user/quick-start.md → docs/src/content/docs/user/quick-start.mdx

@@ -3,6 +3,9 @@ title: Quick start guide to capo.js
 description: What's Capo, how do you use it, and why should you care?
 ---
 
+import InlineCapoIcon from '../../../components/InlineCapoIcon.astro';
+
+
 `capo.js` is a tool for assessing the quality of the document `<head>`. You can run it in your browser as a Chrome extension or DevTools snippet, in a testing environment like WebPageTest, or an analytical datastore like BigQuery.
 
 An unoptimized `<head>` can lead to poor performance and a poor user experience. `capo.js` can help you identify and fix these issues.
@@ -17,7 +20,7 @@ The best way to start using `capo.js` is to install the [Capo extension for Chro
 
 1. Navigate to the [Capo extension](https://chrome.google.com/webstore/detail/capo-get-your-%3Chead%3E-in-o/ohabpnaccigjhkkebjofhpmebofgpbeb) in the Chrome Web Store
 2. Click the **Add to Chrome** button
-3. On any page, click the Capo icon (&lt;👤>) in the browser toolbar
+3. On any page, click the Capo icon <InlineCapoIcon /> in the browser toolbar
     - Open the DevTools Console to see additional logs
 
 Learn more about [using the extension](/capo.js/user/extension/) and interpreting the results.