docs: assets (pubic and processed)

Resolves #210

Note: #209 should be merged first.

README.md

@@ -72,6 +72,7 @@ All documentation is located in [`docs/`](docs/):
 
 - [Getting Started](docs/getting-started.md)
 - [Accessibility (a11y)](docs/accessibility.md)
+- [Assets](docs/assets.md)
 - [Blocks and Components](docs/blocks-and-components.md)
 - [CMS Content Modelling](docs/cms-content-modelling.md)
 - [CMS Data Loading](docs/cms-data-loading.md)

docs/assets.md

@@ -0,0 +1,42 @@
+# Assets
+
+**Head Start provides a pre-configured setup for common assets like fonts and icons.**
+
+## `src/assets/` vs `public/` assets
+
+[Astro copies all assets in `public/` to the web root](https://docs.astro.build/en/basics/project-structure/#public) (`dist/`). Using [the `public/` directory](../public/) is suitable for static assets that don't require a build step and should be available as is. For example a some `.wellknown` file.
+
+Head Start uses [the `src/assets/` directory](../src/assets/) to organise raw assets that do require a build step. You are responsible for the processing and importing of these assets. Head Start provides a pre-configured setup for [fonts](#fonts) and [icons](#icons). These assets are eventually compiled to `dist/_astro/` and are configured to be served with immutable cache headers for performance.
+
+
+## Fonts
+
+Head Start provides a setup for custom fonts to improve their loading performance. An example font (Archivo) is pre-configured in [`src/assets/fonts.ts`](../src/assets/fonts.ts). To add your own custom fonts:
+
+1. Install the custom font. If it's an open source font, the easiest way is to [install your custom font using Fontsource](https://fontsource.org/docs/getting-started/install). Otherwise copy your custom font files (`woff2`) to `src/assets/fonts/` manually.
+2. Replace the example font imports in [`src/assets/fonts.ts`](../src/assets/fonts.ts) with those of your custom fonts.
+3. Replace the `const fonts` and `const fontsFamily...` values to match the name and variations of your custom fonts.
+
+That's it. Head Start will now automatically preload the font files and include critical CSS for your custom fonts.
+
+
+## Icons
+
+Head Start combines icons in a sprite and makes them available through the `<Icon>` component. To use an icon:
+
+1. Add an SVG icon to [`src/assets/icons/`](../src/assets/icons/). For example a `share.svg` icon.
+2. Use the `Icon` component with `name="share"` (SVG file basename):
+
+```astro
+---
+import Icon from '@components/Icon/';
+---
+<Icon name="share">
+
+<style>
+  /* optional: style on data attribute, or add a class */
+  [data-icon="share"] {
+    color: red;
+  }
+</style>
+```

package.json

@@ -36,7 +36,8 @@
     "pretest": "npm run prep",
     "test": "run-s test:*",
     "test:unit": "vitest run",
-    "post": "echo 'add post:x scripts and change this like to \"run-s post:* --print-label\"'",
+    "post": "run-s post:* --print-label",
+    "post:remove-public-dir-readme": "rm dist/README.md",
     "postinstall": "npx husky install"
   },
   "dependencies": {
@@ -96,4 +97,4 @@
   "nano-staged": {
     "*.{astro,js,ts}": "npm run lint:eslint -- --fix --max-warnings 0"
   }
-}
+}

public/README.md

@@ -0,0 +1,5 @@
+# Public
+
+**This directory contains static assets that don't require a build step and will be available as is.**
+
+See [documentation on Assets](../docs/assets.md).

src/assets/README.md

@@ -0,0 +1,5 @@
+# Assets
+
+**This directory contains raw assets that require a build step.**
+
+See [documentation on Assets](../../docs/assets.md).

src/components/Icon/README.md

@@ -1,22 +1,3 @@
 # Icon
 
-**Component to render an SVG icon from `src/icons/`.**
-
-## How to use?
-
-1. Add an SVG icon to `src/icons/`. For example a `share.svg` icon.
-2. Use the `Icon` component with `name="share"` (SVG file basename):
-
-```astro
----
-import Icon from 'path/to/components/Icon/';
----
-<Icon name="share">
-
-<style>
-  /* style on data attribute, or add a class */
-  [data-icon="share"] {
-    color: red;
-  }
-</style>
-```
+For usage see [documentation on Assets > Icons](../../../docs/assets.md#icons).