diff --git a/docs/app.config.ts b/docs/app.config.ts
index f4d1fec0..7beffb75 100644
--- a/docs/app.config.ts
+++ b/docs/app.config.ts
@@ -1,6 +1,19 @@
export default defineAppConfig({
- ui: {
- primary: 'green',
- gray: 'slate',
+ seo: {
+ title: 'Nuxt Color Mode',
+ description: 'Dark and light mode with auto detection made easy with Nuxt',
+ ogImage: '/social-card.jpg',
+ },
+ socials: {
+ github: 'nuxt-modules/color-mode',
+ x: 'https://x.com/nuxt_js',
+ },
+ github: {
+ url: 'https://github.com/nuxt-modules/color-mode',
+ branch: 'main',
+ rootDir: 'docs/content',
+ },
+ toc: {
+ title: 'On this page',
},
})
diff --git a/docs/app/components/AppHeaderLogo.vue b/docs/app/components/AppHeaderLogo.vue
new file mode 100644
index 00000000..1d4e52d6
--- /dev/null
+++ b/docs/app/components/AppHeaderLogo.vue
@@ -0,0 +1,24 @@
+
+
+
diff --git a/docs/app/components/CopyCodeInput.vue b/docs/app/components/CopyCodeInput.vue
new file mode 100644
index 00000000..bd1c3c97
--- /dev/null
+++ b/docs/app/components/CopyCodeInput.vue
@@ -0,0 +1,48 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/content/1.getting-started/1.index.md b/docs/content/1.getting-started/1.index.md
new file mode 100644
index 00000000..186c17cd
--- /dev/null
+++ b/docs/content/1.getting-started/1.index.md
@@ -0,0 +1,20 @@
+---
+title: Introduction
+description: Dark and light mode with auto detection made easy with Nuxt 🌗
+---
+
+# Nuxt Color Mode
+
+Dark and light mode with auto detection made easy with Nuxt 🌗
+
+## Features
+
+- Add `.${color}-mode` class to `` for easy CSS theming
+- Force a page to a specific color mode (perfect for incremental development)
+- Works with client-side and universal rendering
+- Works out of the box with [@nuxtjs/tailwindcss](https://github.com/nuxt-modules/tailwindcss)
+- Auto detect system [color-mode](https://drafts.csswg.org/mediaqueries-5/#descdef-media-prefers-color-mode)
+
+## Live Demo
+
+Check out the [online demo](https://color-mode.nuxt.dev/) and [source code](https://github.com/nuxt-modules/color-mode/tree/main/playground).
diff --git a/docs/content/1.getting-started/2.installation.md b/docs/content/1.getting-started/2.installation.md
new file mode 100644
index 00000000..160591e4
--- /dev/null
+++ b/docs/content/1.getting-started/2.installation.md
@@ -0,0 +1,30 @@
+---
+title: Installation
+description: Learn how to install and configure Nuxt Color Mode
+---
+
+# Installation
+
+::callout
+The current version of `@nuxtjs/color-mode` is compatible with [Nuxt 3+](https://nuxt.com). If you're looking for the previous version of this module, check out [v2.color-mode.nuxtjs.org](https://v2.color-mode.nuxtjs.org/).
+::
+
+## Setup
+
+Add `@nuxtjs/color-mode` dependency to your project:
+
+```bash
+npx nuxt module add color-mode
+```
+
+Then, add `@nuxtjs/color-mode` to the `modules` section of your `nuxt.config.ts`:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+ modules: [
+ '@nuxtjs/color-mode'
+ ]
+})
+```
+
+You are ready to start theming your CSS with `.dark-mode` and `.light-mode` classes ✨
diff --git a/docs/content/2.usage/1.basic.md b/docs/content/2.usage/1.basic.md
new file mode 100644
index 00000000..07c7103b
--- /dev/null
+++ b/docs/content/2.usage/1.basic.md
@@ -0,0 +1,50 @@
+---
+title: Basic Usage
+description: Learn how to use the color mode composable
+---
+
+# Usage
+
+You can access the color mode helper by either calling `useColorMode()` or accessing `$colorMode` directly in your template. This helper has the following properties:
+
+- `preference`: Actual color-mode selected (can be `'system'`), update it to change the user preferred color mode
+- `value`: Useful to know what color mode has been detected when `$colorMode === 'system'`, you should not update it
+- `unknown`: Useful to know if during SSR or Generate, we need to render a placeholder
+- `forced`: Useful to know if the current color mode is forced by the current page (useful to hide the color picker)
+
+## Example
+
+```html [pages/index.vue]
+
+
+
Color mode: {{ $colorMode.value }}
+
+
+
+
+
+
+
+```
diff --git a/docs/content/2.usage/2.force-mode.md b/docs/content/2.usage/2.force-mode.md
new file mode 100644
index 00000000..e063f36a
--- /dev/null
+++ b/docs/content/2.usage/2.force-mode.md
@@ -0,0 +1,26 @@
+---
+title: Force Color Mode
+description: Learn how to force a specific color mode on a page
+---
+
+# Force a Color Mode
+
+You can force the color mode at the page level by setting the `colorMode` property using `definePageMeta`:
+
+```html [pages/light.vue]
+
+
This page is forced with light mode
+
+
+
+```
+
+This feature is perfect for implementing dark mode to a website incrementally by setting the not-ready pages to `colorMode: 'light'`.
+
+::callout
+We recommend to hide or disable the color mode picker on the page since it won't be able to change the current page color mode, using `$colorMode.forced` value.
+::
diff --git a/docs/content/2.usage/3.configuration.md b/docs/content/2.usage/3.configuration.md
new file mode 100644
index 00000000..6f4bd4f0
--- /dev/null
+++ b/docs/content/2.usage/3.configuration.md
@@ -0,0 +1,62 @@
+---
+title: Configuration
+description: Configure the Color Mode module
+---
+
+# Configuration
+
+You can configure the module by providing the `colorMode` property in your `nuxt.config.ts`. Here are the default options:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+ modules: ['@nuxtjs/color-mode'],
+ colorMode: {
+ preference: 'system', // default value of $colorMode.preference
+ fallback: 'light', // fallback value if not system preference found
+ hid: 'nuxt-color-mode-script',
+ globalName: '__NUXT_COLOR_MODE__',
+ componentName: 'ColorScheme',
+ classPrefix: '',
+ classSuffix: '',
+ storage: 'localStorage', // or 'sessionStorage' or 'cookie'
+ storageKey: 'nuxt-color-mode'
+ }
+})
+```
+
+## Options
+
+### `preference`
+
+- Type: `string`
+- Default: `'system'`
+
+Default color mode preference. `'system'` is a special value that will automatically detect the color mode based on the system preferences.
+
+### `fallback`
+
+- Type: `string`
+- Default: `'light'`
+
+Fallback color mode value if no system preference is detected.
+
+### `dataValue`
+
+- Type: `string`
+- Default: `undefined`
+
+Optional dataset attribute to add to ``. For example, if you set `dataValue: 'theme'`, it will set `data-theme="dark"` on ``. This is useful when using libraries like daisyUI.
+
+### `storage`
+
+- Type: `'localStorage' | 'sessionStorage' | 'cookie'`
+- Default: `'localStorage'`
+
+Storage type to persist the color mode preference.
+
+### `storageKey`
+
+- Type: `string`
+- Default: `'nuxt-color-mode'`
+
+Storage key name.
diff --git a/docs/content/3.advanced/1.caveats.md b/docs/content/3.advanced/1.caveats.md
new file mode 100644
index 00000000..9790ad3b
--- /dev/null
+++ b/docs/content/3.advanced/1.caveats.md
@@ -0,0 +1,25 @@
+---
+title: Caveats
+description: Important considerations when using Color Mode
+---
+
+# Caveats
+
+When `$colorMode.preference` is set to `'system'`, using `$colorMode` in your Vue template will lead to a flash. This is due to the fact that we cannot know the user preferences when pre-rendering the page since they are detected on client-side.
+
+## Avoiding the Flash
+
+To avoid the flash, you have to guard any rendering path which depends on `$colorMode` with `$colorMode.unknown` to render a placeholder or use the `` component.
+
+### Example
+
+```vue
+
+
+ Color mode: {{ $colorMode.preference }}
+
+ ({{ $colorMode.value }} mode detected)
+
+
+
+```
diff --git a/docs/content/3.advanced/2.migration.md b/docs/content/3.advanced/2.migration.md
new file mode 100644
index 00000000..f7a3a14b
--- /dev/null
+++ b/docs/content/3.advanced/2.migration.md
@@ -0,0 +1,60 @@
+---
+title: Migrating to v3
+description: Guide for migrating from v2 to v3
+---
+
+# Migrating to v3
+
+v3 of `@nuxtjs/color-mode` requires either Nuxt Bridge or Nuxt 3. If you are using Nuxt 2 without Bridge, you should continue to use v2.
+
+## Main Changes
+
+### 1. Page Meta Configuration
+
+The main change between Nuxt 2 → Nuxt 3 is that you will define your color mode at the page level with `definePageMeta`:
+
+```diff
+
+
This page is forced with light mode
+
+
+-
+```
+
+::callout{type="warning"}
+If you are using Nuxt Bridge, you should not use `definePageMeta` but instead continue using the component option `colorMode`.
+::
+
+### 2. Composable API
+
+The `$colorMode` helper remains the same, but there is also a new composable (`useColorMode`) which is the recommended way of accessing color mode information.
+
+```vue
+
+```
+
+### 3. Type Imports
+
+If you were directly importing color mode configuration types, note that this has been renamed to `ModuleOptions`.
+
+```ts
+// Before
+import type { ColorModeConfig } from '@nuxtjs/color-mode'
+
+// After
+import type { ModuleOptions } from '@nuxtjs/color-mode'
+```
diff --git a/docs/content/4.contributing.md b/docs/content/4.contributing.md
new file mode 100644
index 00000000..74a403ff
--- /dev/null
+++ b/docs/content/4.contributing.md
@@ -0,0 +1,52 @@
+---
+title: Contributing
+description: Learn how to contribute to Nuxt Color Mode
+---
+
+# Contributing
+
+Contributions are welcome! Here's how you can help improve Nuxt Color Mode.
+
+## Development Setup
+
+1. Clone the repository:
+
+```bash
+git clone https://github.com/nuxt-modules/color-mode.git
+cd color-mode
+```
+
+2. Install dependencies:
+
+```bash
+pnpm install
+```
+
+3. Start the development server:
+
+```bash
+pnpm dev
+```
+
+This will start the playground at `http://localhost:3000`.
+
+## Project Structure
+
+- `src/` - Module source code
+- `playground/` - Test playground for development
+- `docs/` - Documentation website
+- `test/` - Test suite
+
+## Pull Requests
+
+1. Fork the repository
+2. Create a new branch for your feature or bugfix
+3. Make your changes
+4. Add tests if applicable
+5. Run the test suite: `pnpm test`
+6. Commit your changes following [Conventional Commits](https://www.conventionalcommits.org/)
+7. Submit a pull request
+
+## Issues
+
+Found a bug or have a feature request? Please open an issue on [GitHub](https://github.com/nuxt-modules/color-mode/issues).
diff --git a/docs/content/index.md b/docs/content/index.md
index f07d7bf5..2d8a2ce5 100644
--- a/docs/content/index.md
+++ b/docs/content/index.md
@@ -1,205 +1,136 @@
---
title: Nuxt Color Mode
-description: Dark and Light mode with auto detection made easy with Nuxt 🌗
+description: Dark and light mode with auto detection made easy with Nuxt 🌗
+navigation: false
+seo:
+ title: Nuxt Color Mode
+ description: Dark and light mode with auto detection made easy with Nuxt 🌗
+ ogImage: https://color-mode.nuxtjs.org/social-card.jpg
---
-## Features
-
-- Nuxt 3 and Nuxt Bridge support
-- Add `.${color}-mode` class to `` for easy CSS theming
-- Force a page to a specific color mode (perfect for incremental development)
-- Works with client-side and universal rendering
-- Works out of the box with [@nuxtjs/tailwindcss](https://github.com/nuxt-modules/tailwindcss)
-- Auto detect system [color-mode](https://drafts.csswg.org/mediaqueries-5/#descdef-media-prefers-color-mode)
-- Supports IE9+ 👴
-
-## Live demo
+::u-page-hero
+---
+orientation: horizontal
+---
-[{.border-b .border-r}](https://color-mode.nuxt.dev/)
+#title
+Dark and light mode with [auto detection]{.text-primary}
-Checkout the [online demo](https://color-mode.nuxt.dev/) and [source code](https://github.com/nuxt-modules/color-mode/tree/main/playground).
+#description
+Plug-and-play color mode module for Nuxt with auto detection made easy. Add `.dark-mode` and `.light-mode` classes to your CSS for easy theming.
-## Setup
+#links
+ :::u-button
+ ---
+ icon: i-ph-rocket-launch-duotone
+ size: xl
+ to: /getting-started
+ ---
+ Get started
+ :::
-::callout
-The current version of `@nuxtjs/color-mode` is compatible with [Nuxt 3+](https://nuxt.com). :br If you're looking for the previous version of this module, check out [v2.color-mode.nuxtjs.org](https://v2.color-mode.nuxtjs.org/), or [read more about the differences](#migrating-to-v3).
+ :::copy-code-input{source="npx nuxt module add color-mode"}
+ :::
::
-Add `@nuxtjs/color-mode` dependency to your project:
-
-```bash
-npx nuxt module add color-mode
-```
-
-Then, add `@nuxtjs/color-mode` to the `modules` section of your `nuxt.config.ts`
-
-```ts [nuxt.config.ts]
-export default defineNuxtConfig({
- modules: [
- '@nuxtjs/color-mode'
- ]
-})
-```
-
-You are ready to start theming your CSS with `.dark-mode` and `.light-mode` classes ✨
-
-## Usage
-
-You can access the color mode helper by either calling `useColorMode()` or accessing `$colorMode` directly in your template. This helper has the following properties:
-
-- `preference`: Actual color-mode selected (can be `'system'`), update it to change the user preferred color mode
-- `value`: Useful to know what color mode has been detected when `$colorMode === 'system'`, you should not update it
-- `unknown`: Useful to know if during SSR or Generate, we need to render a placeholder
-- `forced`: Useful to know if the current color mode is forced by the current page (useful to hide the color picker)
-
-```html [pages/index.vue]
-
-
-
Color mode: {{ $colorMode.value }}
-
-
-
-
-
-
-
-```
-
-## Force a color mode
-
-You can force the color mode at the page level (only parent) by setting the `colorMode` property:
-
-```html [pages/light.vue]
-
-
This page is forced with light mode
-
-
-
-```
-
-This feature is perfect for implementing dark mode to a website incrementally by setting the not-ready pages to `colorMode: 'light'`.
-
-::callout
-We recommend to hide or disable the color mode picker on the page since it won't be able to change the current page color mode, using `$colorMode.forced` value.
+::u-page-section
+#title
+Get the most of your app with :br [powerful features]{.text-primary}
+
+#features
+ :::u-page-card
+ ---
+ icon: i-ph-moon-duotone
+ to: /usage/basic
+ ---
+ #title
+ Auto Detection
+
+ #description
+ Automatically detects the user's system color mode preference and applies it to your app.
+ :::
+
+ :::u-page-card
+ ---
+ icon: i-ph-palette-duotone
+ to: /usage/basic
+ ---
+ #title
+ Easy CSS Theming
+
+ #description
+ Add `.dark-mode` and `.light-mode` classes to your CSS for effortless theming.
+ :::
+
+ :::u-page-card
+ ---
+ icon: i-ph-lock-duotone
+ to: /usage/force-mode
+ ---
+ #title
+ Force Mode Per Page
+
+ #description
+ Lock specific pages to a color mode, perfect for incremental dark mode implementation.
+ :::
+
+ :::u-page-card
+ ---
+ icon: i-ph-gear-duotone
+ to: /usage/configuration
+ ---
+ #title
+ Highly Configurable
+
+ #description
+ Customize storage, fallbacks, class names, and more to fit your needs.
+ :::
+
+ :::u-page-card
+ ---
+ icon: i-ph-brackets-angle-duotone
+ to: /usage/basic
+ ---
+ #title
+ SSR Ready
+
+ #description
+ Works seamlessly with both client-side and server-side rendering.
+ :::
+
+ :::u-page-card
+ ---
+ icon: i-ph-puzzle-piece-duotone
+ to: /getting-started/installation
+ ---
+ #title
+ Framework Support
+
+ #description
+ Works out of the box with Tailwind CSS and other popular CSS frameworks.
+ :::
::
-## Configuration
-
-You can configure the module by providing the `colorMode` property in your `nuxt.config.js`; here are the default options:
-
-```js{}[nuxt.config.js]
-import { defineNuxtConfig } from 'nuxt'
-
-export default defineNuxtConfig({
- modules: ['@nuxtjs/color-mode'],
- colorMode: {
- preference: 'system', // default value of $colorMode.preference
- fallback: 'light', // fallback value if not system preference found
- hid: 'nuxt-color-mode-script',
- globalName: '__NUXT_COLOR_MODE__',
- componentName: 'ColorScheme',
- classPrefix: '',
- classSuffix: '',
- storage: 'localStorage', // or 'sessionStorage' or 'cookie'
- storageKey: 'nuxt-color-mode'
- }
-})
-```
-
-Notes:
-- `'system'` is a special value; it will automatically detect the color mode based on the system preferences (see [prefers-color-mode spec](https://drafts.csswg.org/mediaqueries-5/#descdef-media-prefers-color-mode)). The value injected will be either `'light'` or `'dark'`. If `no-preference` is detected or the browser does not handle color-mode, it will set the `fallback` value.
-- Optional `dataValue` lets you add dataset to the `html`, for example if you currently have `class="dark"` on `html`, `dataValue: 'theme'` will also set `data-theme="dark"` on `html`. This is useful when using library like daisyUI that uses `data-theme="light"` on `html` to apply theme.
-
-## Caveats
-
-When `$colorMode.preference` is set to `'system'`, using `$colorMode` in your Vue template will lead to a flash. This is due to the fact that we cannot know the user preferences when pre-rendering the page since they are detected on client-side.
-
-To avoid the flash, you have to guard any rendering path which depends on `$colorMode` with `$colorMode.unknown` to render a placeholder or use our `` component.
-
-**Example:**
-
-```vue
-
-
- Color mode: {{ $colorMode.preference }}
- ({{ $colorMode.value }} mode detected)
-
-
-```
-
-Props:
-- `placeholder`: `String`
-- `tag`: `String`, default: `'span'`
-
-Slots:
-- `placeholder`: used to render as placeholder, similar to the `placeholder` prop
-
-## Migrating to v3
-
-v3 of `@nuxtjs/color-mode` requires either Nuxt Bridge or Nuxt 3. (If you are using Nuxt 2 without Bridge, you should continue to use v2.)
-
-1. The main change between Nuxt 2 -> Nuxt 3 is that you will define your color mode at the page level with `definePageMeta`:
-
-```diff
-
-
This page is forced with light mode
-
-
--
-```
-
-⚠️ If you are using Nuxt Bridge, you should not use `definePageMeta` but instead continue using the component option `colorMode`.
-
-2. The `$colorMode` helper remains the same, but there is also a new composable (`useColorMode`) which is the recommended way of accessing color mode information.
-
-3. If you were directly importing color mode configuration types, note that this has been renamed to `ModuleOptions`.
-
-## Contributing
-
-1. Clone this repository
-2. Install dependencies using `pnpm install`
-3. Start development server using `pnpm dev`
+::u-page-section
+---
+align: center
+---
-## License
+#title
+Trusted by thousands of developers
+
+#description
+Nuxt Color Mode is used by companies and developers worldwide to provide seamless dark mode experiences.
+
+#links
+ :::u-button
+ ---
+ icon: i-ph-rocket-launch-duotone
+ size: xl
+ to: /getting-started
+ ---
+ Get started
+ :::
+::
-[MIT License](https://github.com/nuxt-modules/color-mode/blob/main/LICENSE)
diff --git a/docs/nuxt.config.ts b/docs/nuxt.config.ts
index 9606f045..603d4176 100644
--- a/docs/nuxt.config.ts
+++ b/docs/nuxt.config.ts
@@ -1,8 +1,13 @@
// https://nuxt.com/docs/api/configuration/nuxt-config
export default defineNuxtConfig({
- extends: '@nuxt/ui-pro',
- modules: ['@nuxt/ui', '@nuxt/content', '@nuxtjs/plausible'],
+ extends: ['docus'],
+ modules: ['@nuxtjs/plausible'],
devtools: { enabled: true },
+ site: {
+ name: 'Nuxt Color Mode',
+ },
compatibilityDate: '2024-09-13',
- uiPro: { license: 'oss' },
+ llms: {
+ domain: 'https://color-mode.nuxtjs.org',
+ },
})
diff --git a/docs/package.json b/docs/package.json
index 4fbc4be0..277d3bfb 100644
--- a/docs/package.json
+++ b/docs/package.json
@@ -9,16 +9,13 @@
"preview": "nuxt preview",
"postinstall": "nuxt prepare"
},
- "devDependencies": {
- "@nuxt/devtools": "latest",
- "@nuxt/ui": "^2.18.7",
- "@nuxtjs/plausible": "^1.0.3",
- "nuxt": "^4.2.1"
- },
"dependencies": {
- "@iconify-json/ph": "^1.2.1",
- "@nuxt/content": "^2.13.4",
- "@nuxt/image": "^1.8.1",
- "@nuxt/ui-pro": "^1.4.4"
+ "@iconify-json/ph": "^1.2.2",
+ "@nuxtjs/mdc": "^0.18.2",
+ "@nuxtjs/plausible": "^2.0.1",
+ "better-sqlite3": "^12.4.1",
+ "docus": "^5.2.1",
+ "nuxt": "^4.2.1",
+ "unist-util-visit": "^5.0.0"
}
}
diff --git a/docs/pages/index.vue b/docs/pages/index.vue
deleted file mode 100644
index c1c0c90d..00000000
--- a/docs/pages/index.vue
+++ /dev/null
@@ -1,131 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-