docs: update wording on misc. pages

johannschopplich · johannschopplich · commit 6038c97c2bd6 · 2025-10-18T08:21:52.000+02:00
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
@@ -86,8 +86,8 @@ function nav(): DefaultTheme.NavItem[] {
         {
           text: 'Placeholders',
           items: [
-            { text: 'BlurHash', link: '/placeholders/blurhash' },
-            { text: 'ThumbHash', link: '/placeholders/thumbhash' },
+            { text: 'Overview', link: '/placeholders/' },
+            { text: 'Hash-Based', link: '/placeholders/hash-based' },
           ],
         },
       ],
@@ -119,8 +119,8 @@ function nav(): DefaultTheme.NavItem[] {
         {
           text: 'Advanced',
           items: [
-            { text: 'Build Flags', link: '/advanced/build-flags' },
             { text: 'Aspect Ratio', link: '/advanced/aspect-ratio' },
+            { text: 'Build Flags', link: '/advanced/build-flags' },
           ],
         },
       ],
@@ -181,8 +181,8 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] {
     {
       text: 'Placeholders',
       items: [
-        { text: 'BlurHash', link: '/placeholders/blurhash' },
-        { text: 'ThumbHash', link: '/placeholders/thumbhash' },
+        { text: 'Overview', link: '/placeholders/' },
+        { text: 'Hash-Based', link: '/placeholders/hash-based' },
       ],
     },
     {
@@ -199,8 +199,8 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] {
     {
       text: 'Advanced',
       items: [
-        { text: 'Build Flags', link: '/advanced/build-flags' },
         { text: 'Aspect Ratio', link: '/advanced/aspect-ratio' },
+        { text: 'Build Flags', link: '/advanced/build-flags' },
       ],
     },
     { text: 'Playground', link: 'https://github.com/johannschopplich/unlazy/tree/main/packages/nuxt/playground' },
diff --git a/docs/advanced/build-flags.md b/docs/advanced/build-flags.md
@@ -26,7 +26,7 @@ export default defineConfig({
 
 ## Disable Hash Decoding <Badge type="info" text="^0.10.0" />
 
-unlazy includes [BlurHash](/placeholders/blurhash) and [ThumbHash](/placeholders/thumbhash) decoding algorithms (from `fast-blurhash` and `thumbhash` packages). If your project doesn't use hash-based placeholders, you can exclude these dependencies entirely:
+unlazy includes [BlurHash](/placeholders/hash-based#blurhash) and [ThumbHash](/placeholders/hash-based#thumbhash) decoding algorithms (from `fast-blurhash` and `thumbhash` packages). If your project doesn't use hash-based placeholders, you can exclude these dependencies entirely:
 
 - `__UNLAZY_HASH_DECODING__`: Set to `false` to tree-shake hash decoding code. Default is `true`.
 
@@ -41,12 +41,12 @@ This flag only affects the main entry point. If you directly import `unlazy/blur
 
 ## Disable Client Logging <Badge type="info" text="^0.10.2" />
 
-unlazy will help you locate missing `data-src` or `data-srcset` attributes in your project by logging a warning in the browser console. An example warning message looks like this:
+unlazy helps you locate missing `data-src` or `data-srcset` attributes by logging warnings in the browser console. An example warning message looks like this:
 
 ```
 [unlazy] Missing `data-src` or `data-srcset` attribute: <img>
 ```
 
-If you want to disable these warnings, you can use the following build flag:
+To disable these warnings, use the following build flag:
 
-- `__UNLAZY_LOGGING__`: This flag is set to `true` by default.
+- `__UNLAZY_LOGGING__`: Set to `false` to disable warnings. Default is `true`.
diff --git a/docs/advanced/index.md b/docs/advanced/index.md
@@ -1,6 +1,10 @@
 # Advanced Usage
 
-This is a collection of recipes for common use cases, since unlazy is a flexible library that can be used in many ways. If you have a use case that is not covered here, please [open an issue](https://github.com/johannschopplich/unlazy/issues).
+This section covers advanced configuration options and optimization techniques for unlazy. These topics help you fine-tune performance and behavior for production applications.
 
-- [Aspect Ratio for Blurry Placeholders](/advanced/aspect-ratio)
-- [Build Flags to Tree-Shake Unused Code](/advanced/build-flags)
+## Topics
+
+- **[Aspect Ratio](/advanced/aspect-ratio)** – Prevent CLS with aspect ratio settings for blurry placeholders
+- **[Build Flags](/advanced/build-flags)** – Tree-shake unused features to reduce bundle size
+
+If you have a use case not covered here, please [open an issue](https://github.com/johannschopplich/unlazy/issues).
diff --git a/docs/api/index.md b/docs/api/index.md
@@ -1,17 +1,10 @@
 # Overview
 
-unlazy provides a number of methods to help you with lazy loading images. The following methods are available:
+unlazy provides a number of methods to help you with lazy loading images:
 
 - [`lazyLoad`](/api/lazy-load) – Lazy load images with automatic placeholder generation
 - [`autoSizes`](/api/auto-sizes) – Automatically calculate the `sizes` attribute
 - [`loadImage`](/api/load-image) – Manually load an image before it enters the viewport
 - [`createPlaceholderFromHash`](/api/create-placeholder-from-hash) – Generate PNG data URI from BlurHash or ThumbHash
-
-## Server-Side Rendering
-
-unlazy supports server-side rendering for BlurHash and ThumbHash strings. This means that you can generate the placeholder images for the `src` attribute during SSR and avoid the [Cumulative Layout Shift](https://web.dev/cls/) (CLS) caused by the images loading after the page has been rendered.
-
-Both the `unlazy/blurhash` and `unlazy/thumbhash` exports provide a `createPngDataUri` function that can be used to generate a PNG data URI for a BlurHash or ThumbHash string, respectively. This function can be used to generate the `src` attribute for the `<img>` element.
-
-- [`createPngDataUri`](/api/blurhash-create-png-data-uri) – Generate a PNG data URI for a BlurHash string
-- [`createPngDataUri`](/api/thumbhash-create-png-data-uri) – Generate a PNG data URI for a ThumbHash string
+- BlurHash [`createPngDataUri`](/api/blurhash-create-png-data-uri) – Generate PNG data URI for SSR
+- ThumbHash [`createPngDataUri`](/api/thumbhash-create-png-data-uri) – Generate PNG data URI for SSR
diff --git a/docs/api/lazy-load.md b/docs/api/lazy-load.md
@@ -9,7 +9,7 @@ The `lazyLoad` function takes a CSS selector, a DOM element, a list of DOM eleme
    - The `data-src` attribute will be converted to `src`.
 2. Processes all images with a `loading="lazy"` attribute.
    - Calculates the image's `sizes` attribute if `data-sizes="auto"` is set.
-   - Generates a blurry placeholder from a [BlurHash](/placeholders/blurhash) or [ThumbHash](/placeholders/thumbhash) string if applicable.
+   - Generates a blurry placeholder from a [hash-based placeholder](/placeholders/hash-based) (BlurHash or ThumbHash) string if applicable.
 3. If the image has a blurry placeholder and is already in the viewport or the visitor is a crawler, it immediately loads the full-quality image.
 4. If the image is not yet in the viewport, an event listener is added to load the full-quality image when it enters the viewport.
 
diff --git a/docs/guide/index.md b/docs/guide/index.md
@@ -30,6 +30,4 @@ unlazy ensures that search engines can index the full-quality images by detectin
 
 Head over to the [installation guide](/guide/installation) to learn how to install unlazy in your project. After that, you can check out the [usage guide](/guide/usage) and may take a look at the [API reference](/api/).
 
-If your project is using [BlurHash](https://blurha.sh), you can check out the [BlurHash guide](/placeholders/blurhash) to learn how to use it with unlazy.
-
-The shiny new [ThumbHash](https://github.com/evanw/thumbhash) by Evan Wallace is also supported. You can check out the [ThumbHash guide](/placeholders/thumbhash) to learn how to use it with unlazy.
+If you want to use hash-based placeholders like [BlurHash](https://blurha.sh) or [ThumbHash](https://github.com/evanw/thumbhash), check out the [hash-based placeholders guide](/placeholders/hash-based).
diff --git a/docs/guide/installation.md b/docs/guide/installation.md
@@ -31,20 +31,16 @@ For more use cases, head over to the [Usage](/guide/usage) guide.
 
 ## Without a Build Step
 
-unlazy can be used without a build step. Useful for prototyping or when you do not want to add a build step to your project. Simply load it from a CDN:
+unlazy can be used without a build step from a CDN. Useful for prototyping or projects without bundlers.
 
-- Global build: <CdnLink name="unlazy.iife.js" />
-  - Exposes `UnLazy` global property, supports auto initializing
-- ESM build: <CdnLink name="unlazy.js" />
-  - Must be used with `<script type="module">`
+**Available Builds:**
+- **Standard Global**: <CdnLink name="unlazy.iife.js" /> - Exposes `UnLazy` global, supports auto-initialization
+- **Standard ESM**: <CdnLink name="unlazy.js" /> - Requires `<script type="module">`
+- **With Hashing Global**: <CdnLink name="unlazy.with-hashing.iife.js" /> - Includes BlurHash/ThumbHash decoders
+- **With Hashing ESM**: <CdnLink name="unlazy.with-hashing.js" /> - ESM with hash decoding
 
 ::: info
-To keep the bundle size small, the standard global build excludes BlurHash and ThumbHash decoding algorithms. Use the `with-hashing` variant if you need client-side hash decoding:
-
-- Global build with hashing: <CdnLink name="unlazy.with-hashing.iife.js" />
-- ESM build with hashing: <CdnLink name="unlazy.with-hashing.js" />
-
-If you decode hashes on the server (e.g., during SSR), use the standard bundle instead.
+Use standard builds if you decode hashes on the server (SSR). Use `with-hashing` builds only if you need client-side hash decoding.
 :::
 
 ### Auto-Initialization
@@ -59,12 +55,12 @@ When using the global build, you can use the `init` attribute to automatically i
 - The `init` attribute tells the library to automatically initialize and watch all elements that have a `loading="lazy"` attribute.
 
 ::: info
-The short CDN URLs are meant for prototyping. For production usage, use a fully resolved CDN URL to avoid resolving and redirect cost:
+The short CDN URLs are meant for prototyping. For production usage, use a fully resolved CDN URL to avoid resolving and redirect costs, for example: `https://unpkg.com/unlazy@1.0.0/dist/unlazy.iife.js`.
 :::
 
 ### Manual Initialization
 
-If you do not want the auto-initialize the library, remove the `init` attribute and move the scripts to end of the `<body>` tag:
+If you do not want to auto-initialize the library, remove the `init` attribute and move the scripts to end of the `<body>` tag:
 
 ```html
 <script src="https://unpkg.com/unlazy"></script>
@@ -74,7 +70,7 @@ If you do not want the auto-initialize the library, remove the `init` attribute
 ```
 
 ::: info
-The short CDN URLs are meant for prototyping. For production usage, use a fully resolved CDN URL to avoid resolving and redirect cost:
+The short CDN URLs are meant for prototyping. For production usage, use a fully resolved CDN URL to avoid resolving and redirect costs, for example: `https://unpkg.com/unlazy@1.0.0/dist/unlazy.iife.js`.
 :::
 
 ## Example
diff --git a/docs/guide/seo-considerations.md b/docs/guide/seo-considerations.md
@@ -1,10 +1,10 @@
 # SEO Considerations
 
-When implementing lazy loading with blurry placeholders, it is important to consider the impact it may have on SEO. Search engine bots and crawlers are responsible for indexing and ranking your website's content, and they might not always behave like human visitors when browsing the site. unlazy ensures that your website's images are indexed correctly and that their quality is not negatively affected by the use of blurry placeholders.
+When implementing lazy loading with blurry placeholders, consider the SEO impact. Search engine bots and crawlers may not behave like human visitors. unlazy ensures images are indexed correctly without compromising quality due to blurry placeholders.
 
 ## Detects Bots and Crawlers
 
-unlazy includes an exported function called `isCrawler` that detects if the visitor is a bot or a crawler. This ensures that the full-quality image is loaded and indexed by search engines.
+unlazy includes an exported `isCrawler` function that detects bots and crawlers, ensuring full-quality images are loaded and indexed by search engines.
 
 The detection mechanism works by:
 
@@ -16,6 +16,6 @@ The library trusts that bots and crawlers can evaluate the `srcset` attribute an
 
 ## Use `src`, `data-srcset` and `sizes`, or `data-src` Attributes
 
-When using blurry placeholders, it is important to set the `src` attribute with the blurry placeholder image and use the `data-srcset` (or `data-src`) attribute for the high-quality image. This ensures that the initial rendering of the page will display the blurry placeholders, while the full-quality images will be loaded later as they enter the viewport.
+Set the `src` attribute with the blurry placeholder and use `data-srcset` (or `data-src`) for the high-quality image. This displays placeholders during initial render while loading full-quality images as they enter the viewport.
 
-Additionally, using the `sizes` attribute (or [`data-sizes="auto"`](/guide/usage#auto-calculation-of-the-sizes-attribute) for automatic calculation) helps provide the search engine with information about the intended display size of the image. This enables search engines to select the most appropriate image source from the `srcset` attribute when indexing your website's content.
+Use the `sizes` attribute (or [`data-sizes="auto"`](/guide/usage#auto-calculation-of-the-sizes-attribute) for automatic calculation) to provide search engines with the intended display size. This enables search engines to select the appropriate image source from the `srcset` attribute when indexing.
diff --git a/docs/guide/usage.md b/docs/guide/usage.md
@@ -2,9 +2,9 @@
 
 1. Add the `loading="lazy"` attribute to a `<img>` element that you want to lazily load. You can also use the `<picture>` element to lazily load images in different formats.
 
-2. Use the `data-src` or `data-srcset` attribute to specify the high-quality image. These data attributes prevent browsers from loading images before they enter the viewport and are swapped to standard attributes by unlazy when loading occurs.
+2. Use `data-src` or `data-srcset` attributes to specify the high-quality image. These prevent browsers from loading images before they enter the viewport and are swapped to standard attributes when loading occurs.
 
-3. If you have a pre-generated blurry placeholder image, use the `src` attribute to specify it. Otherwise, you can use a [BlurHash](/placeholders/blurhash) or [ThumbHash](/placeholders/thumbhash) to generate a placeholder image on the fly.
+3. Set the `src` attribute with a pre-generated blurry placeholder, or use [hash-based placeholders](/placeholders/hash-based) (BlurHash or ThumbHash) to generate placeholders on the fly.
 
 ::: code-group
   ```html [Image tag]
@@ -51,7 +51,7 @@ const cleanup = lazyLoad()
 // Useful when unmounting components or removing images dynamically
 ```
 
-The `lazyLoad` function returns a cleanup function that removes all event listeners and ResizeObservers. Call this function when unmounting components or when images are no longer needed to prevent memory leaks.
+The `lazyLoad` function returns a cleanup function that removes event listeners and ResizeObservers. Call this when unmounting components or removing images to prevent memory leaks.
 
 ## Auto Calculation of the `sizes` Attribute
 
@@ -68,9 +68,9 @@ The automatic sizes calculation uses the display width of the image.
 >
 ```
 
-When calling [`lazyLoad`](/api/lazy-load), the library will automatically calculate the `sizes` attribute for all images with `data-sizes="auto"`.
+When calling [`lazyLoad`](/api/lazy-load), the library automatically calculates the `sizes` attribute for all images with `data-sizes="auto"`.
 
-Alternatively, you can use the [`autoSizes`](/api/auto-sizes) function to calculate the `sizes` attribute for all images with `data-sizes="auto"`, without lazy loading the images.
+Alternatively, use the [`autoSizes`](/api/auto-sizes) function to calculate the `sizes` attribute without lazy loading.
 
 To do so, import the [`autoSizes`](/api/auto-sizes) function from the library and call it:
 
@@ -113,5 +113,5 @@ loadImage(coolImage)
 ```
 
 ::: tip
-Keep in mind that manually loading images might negatively affect the perceived performance, as it will force the full-quality image to load immediately, even if it is not visible on the viewport.
+Manually loading images may negatively affect perceived performance by forcing immediate load, even when not visible in the viewport.
 :::
diff --git a/docs/integrations/index.md b/docs/integrations/index.md
@@ -2,9 +2,9 @@
 
 unlazy supports lazy loading images in your framework of choice. Each package provides a `UnLazyImage` component as a drop-in replacement for the native `<img>` element.
 
-## Generic How-To
+## Creating Custom Integrations
 
-To create a component for the framework of your choice, keep the following in mind:
+To create a component for your framework, keep the following in mind:
 
 1. The component should wrap a native `<img>` element with the `loading="lazy"` attribute set.
 2. The component should support at least a `src` or `srcset` attribute.
@@ -60,7 +60,7 @@ The following integrations are available as of now:
 ### Meta-Frameworks
 
 ::: tip
-These include SSR-decoding of [BlurHash](/placeholders/blurhash) and [ThumbHash](/placeholders/thumbhash) strings.
+These include SSR-decoding of [hash-based placeholders](/placeholders/hash-based) (BlurHash and ThumbHash).
 :::
 
 - [Nuxt](/integrations/nuxt)
diff --git a/docs/integrations/nuxt.md b/docs/integrations/nuxt.md
@@ -1,8 +1,6 @@
 # `@unlazy/nuxt`
 
-unlazy is not only framework-agnostic, but also provides a Nuxt module that you can use in your Nuxt application.
-
-The auto-imported `UnLazyImage` component is a drop-in replacement for the native `<img>` element and `<picture>` element respectively if you provide the `sources` prop.
+The Nuxt module provides an auto-imported `UnLazyImage` component as a drop-in replacement for native `<img>` and `<picture>` elements (when using the `sources` prop).
 
 ## Installation
 
@@ -50,7 +48,7 @@ export default defineNuxtConfig({
 ```
 
 ::: warning
-Disabling server-side rendering of the blurry placeholder image will result in a flash of the original image on the initial page load and kinda defeats the purpose of the SSR abilities from Nuxt.
+Disabling server-side rendering of the blurry placeholder image will result in a flash of the original image on the initial page load and largely defeats the purpose of the SSR abilities from Nuxt.
 :::
 
 ## `UnLazyImage` Component
diff --git a/docs/integrations/react.md b/docs/integrations/react.md
@@ -1,6 +1,6 @@
 # `@unlazy/react`
 
-unlazy is not only framework-agnostic, but also provides a React component that you can use in your React application.
+The React integration provides an `UnLazyImage` component for your React 19+ application.
 
 ## Installation
 
diff --git a/docs/integrations/solid.md b/docs/integrations/solid.md
@@ -1,6 +1,6 @@
 # `@unlazy/solid`
 
-unlazy is not only framework-agnostic, but also provides a Solid component that you can use in your Solid application.
+The Solid integration provides an `UnLazyImage` component for your Solid 1.9+ application.
 
 ## Installation
 
diff --git a/docs/integrations/svelte.md b/docs/integrations/svelte.md
@@ -1,10 +1,6 @@
 # `@unlazy/svelte`
 
-unlazy is not only framework-agnostic, but also provides a Svelte component that you can use in your Svelte application.
-
-::: info
-The component is written for Svelte 5 and above using runes.
-:::
+The Svelte integration provides an `UnLazyImage` component for Svelte 5+ applications using runes.
 
 ## Installation
 
diff --git a/docs/integrations/vue.md b/docs/integrations/vue.md
@@ -1,6 +1,6 @@
 # `@unlazy/vue`
 
-unlazy is not only framework-agnostic, but also provides a Vue component that you can use in your Vue application.
+The Vue integration provides an `UnLazyImage` component for your Vue 3 application.
 
 ## Installation
 
@@ -38,7 +38,7 @@ import { UnLazyImage } from '@unlazy/vue/components'
 
 ### Global Registration
 
-If you prefer to make the `LazyImage` component globally available, you can register it in your `main.ts` file across your entire Vue application:
+If you prefer to make the `UnLazyImage` component globally available, you can register it in your `main.ts` file across your entire Vue application:
 
 ```ts
 // src/main.ts
diff --git a/docs/placeholders/blurhash.md b/docs/placeholders/blurhash.md
diff --git a/docs/placeholders/hash-based.md b/docs/placeholders/hash-based.md
diff --git a/docs/placeholders/index.md b/docs/placeholders/index.md
diff --git a/docs/placeholders/thumbhash.md b/docs/placeholders/thumbhash.md
