docs: Rewrite and restructure the documentation website

docs/.vitepress/config.ts

@@ -8,6 +8,8 @@ import {
   prepareTypedocSidebar,
 } from './utils/menus';
 import { meta, script } from './utils/head';
+import { version as wxtVersion } from '../../packages/wxt/package.json';
+import { version as i18nVersion } from '../../packages/i18n/package.json';
 
 const title = 'Next-gen Web Extension Framework';
 const titleSuffix = ' – WXT';
@@ -64,92 +66,78 @@ export default defineConfig({
     ],
 
     nav: [
-      navItem('Get Started', '/get-started/introduction'),
-      navItem('Guide', '/guide/key-concepts/manifest'),
-      navItem('API', '/api/reference/wxt'),
+      navItem('Guide', '/guide/get-started/installation'),
       navItem('Examples', '/examples'),
+      navItem('API', '/api/reference/wxt'),
+      navItem('---', [
+        navItem('wxt', [
+          navItem(`v${wxtVersion}`, '/'),
+          navItem(
+            `Changelog`,
+            'https://github.com/wxt-dev/wxt/blob/main/packages/wxt/CHANGELOG.md',
+          ),
+        ]),
+        navItem('@wxt-dev/i18n', [
+          navItem(`v${i18nVersion}`, '/i18n'),
+          navItem(
+            `Changelog`,
+            'https://github.com/wxt-dev/wxt/blob/main/packages/i18n/CHANGELOG.md',
+          ),
+        ]),
+      ]),
     ],
 
     sidebar: {
-      '/get-started/': menuRoot([
-        menuGroup('Get Started', '/get-started/', [
-          menuItem('Introduction', 'introduction'),
-          menuItem('Installation', 'installation'),
-          menuItem('Configuration', 'configuration'),
-          menuItem('Entrypoints', 'entrypoints'),
-          menuItem('Assets', 'assets'),
-          menuItem('Publishing', 'publishing'),
-          menuItem('Migrate to WXT', 'migrate-to-wxt'),
-          menuItem('Compare', 'compare'),
-        ]),
-      ]),
       '/guide/': menuRoot([
-        menuGroup('Key Concepts', '/guide/key-concepts/', [
-          menuItem('Manifest', 'manifest'),
-          menuItem('Auto-imports', 'auto-imports'),
-          menuItem('Web Extension Polyfill', 'web-extension-polyfill'),
-          menuItem('Frontend Frameworks', 'frontend-frameworks'),
-          menuItem('Content Script UI', 'content-script-ui'),
+        menuGroup('Get Started', '/guide/get-started/', [
+          menuItem('Introduction', 'introduction.md'),
+          menuItem('Installation', 'installation.md'),
+          menuItem('Migrate to WXT', 'migrate.md'),
         ]),
-        menuGroup('Directory Structure', '/guide/directory-structure/', [
-          // Folders
-          menuItem('.output/', 'output'),
-          menuItem('.wxt/', 'wxt'),
-          menuItem('assets/', 'assets'),
-          menuItem('components/', 'components'),
-          menuItem('composables/', 'composables'),
-          menuGroup('entrypoints/', '/guide/directory-structure/entrypoints/', [
-            menuItem('background', 'background.md'),
-            menuItem('bookmarks', 'bookmarks.md'),
-            menuItem('*.content.ts', 'content-scripts.md'),
-            menuItem('*.css', 'css.md'),
-            menuItem('devtools', 'devtools.md'),
-            menuItem('history', 'history.md'),
-            menuItem('newtab', 'newtab.md'),
-            menuItem('options', 'options.md'),
-            menuItem('popup', 'popup.md'),
-            menuItem('sandbox', 'sandbox.md'),
-            menuItem('sidepanel', 'sidepanel.md'),
-            menuItem('*.html', 'unlisted-pages.md'),
-            menuItem('*.ts', 'unlisted-scripts.md'),
-          ]),
-          menuItem('hooks/', 'hooks'),
-          menuItem('public/', 'public/', [
-            menuItem('_locales/', 'public/locales'),
-          ]),
-          menuItem('utils/', 'utils'),
-
-          // Files
-          menuItem('.env', 'env'),
-          menuItem('app.config.ts', 'app-config'),
-          menuItem('package.json', 'package'),
-          menuItem('tsconfig.json', 'tsconfig'),
-          menuItem('web-ext.config.ts', 'web-ext-config'),
-          menuItem('wxt.config.ts', 'wxt-config'),
+        menuGroup('Using WXT', '/guide/building/', [
+          menuItem('Project Structure', 'project-structure.md'),
+          menuItem('Entrypoints', 'entrypoints.md'),
+          menuItem('Extension APIs', 'extension-apis.md'),
+          menuItem('Assets', 'assets.md'),
+          menuItem('Target Different Browsers', 'target-different-browsers.md'),
+          menuItem('Content Scripts', 'content-scripts.md'),
+          menuItem('Storage', 'storage.md'),
+          menuItem('Messaging', 'messaging.md'),
+          menuItem('I18n', 'i18n.md'),
+          menuItem('Scripting', 'scripting.md'),
+        ]),
+        menuGroup('Configuration', '/guide/config/', [
+          menuItem('wxt.config.ts', 'wxt.md'),
+          menuItem('Manifest', 'manifest.md'),
+          menuItem('Frontend Frameworks', 'frontend-frameworks.md'),
+          menuItem('Browser Startup', 'browser-startup.md'),
+          menuItem('Runtime Config', 'runtime.md'),
+          menuItem('TypeScript', 'typescript.md'),
+          menuItem('Vite', 'vite.md'),
         ]),
-        menuGroup('Extension APIs', '/guide/extension-apis/', [
-          menuItem('Storage', 'storage'),
-          menuItem('Messaging', 'messaging'),
-          menuItem('I18n', 'i18n'),
-          menuItem('Scripting', 'scripting'),
-          menuItem('Others', 'others'),
+        menuGroup('WXT Modules', '/guide/wxt-modules/', [
+          menuItem('Using Modules', 'using-modules.md'),
+          menuItem('Writing Modules', 'writing-modules.md'),
+          menuItem('Recipes', 'recipes.md'),
         ]),
-        menuGroup('Go Further', '/guide/go-further/', [
-          menuItem('Testing', 'testing'),
-          menuItem('ES Modules', 'es-modules'),
-          menuItem('Debugging', 'debugging'),
-          menuItem('Handling Updates', 'handling-updates'),
-          menuItem('Vite', 'vite'),
-          menuItem('Custom Events', 'custom-events'),
-          menuItem('Reusable Modules', 'reusable-modules'),
-          menuItem('Remote Code', 'remote-code'),
-          menuItem('Entrypoint Loaders', 'entrypoint-loaders'),
-          menuItem('How WXT Works', 'how-wxt-works'),
+        menuGroup('Maintain Your Project', '/guide/maintainence/', [
+          menuItem('Upgrading WXT', 'upgrading.md'),
+          menuItem('Unit Testing', 'unit-testing.md'),
+          menuItem('E2E Testing', 'e2e-testing.md'),
+          menuItem('Debugging', 'debugging.md'),
         ]),
-        menuGroup('Upgrade Guide', '/guide/upgrade-guide/', [
-          menuItem('wxt', 'wxt'),
+        menuGroup('Going to Production', '/guide/production/', [
+          menuItem('Publishing', 'publishing.md'),
+          menuItem('Bundle Remote Code', 'remote-code.md'),
+          menuItem('Testing Updates', 'testing-updates.md'),
         ]),
-        menuGroup('@wxt-dev/i18n', '/guide/i18n/', [
+        menuGroup('Resources', '/guide/resources/', [
+          menuItem('Compare', 'compare.md'),
+          menuItem('How WXT Works', 'how-wxt-works.md'),
+        ]),
+      ]),
+      '/i18n/': menuRoot([
+        menuGroup('@wxt-dev/i18n', '/i18n/', [
           menuItem('Introduction', 'introduction.md'),
           menuItem('Installation', 'installation.md'),
           menuItem('Messages File Format', 'messages-file-format.md'),
@@ -158,7 +146,22 @@ export default defineConfig({
         ]),
       ]),
       '/api/': menuRoot([
-        menuGroup('CLI', '/api/cli/', [
+        menuGroup('Entrypoints Reference', '/api/entrypoints/', [
+          menuItem('Background', 'background.md'),
+          menuItem('Bookmarks', 'bookmarks.md'),
+          menuItem('Content Script', 'content-scripts.md'),
+          menuItem('Devtools', 'devtools.md'),
+          menuItem('History', 'history.md'),
+          menuItem('Newtab', 'newtab.md'),
+          menuItem('Options', 'options.md'),
+          menuItem('Popup', 'popup.md'),
+          menuItem('Sandbox', 'sandbox.md'),
+          menuItem('Sidepanel', 'sidepanel.md'),
+          menuItem('Unlisted CSS', 'unlisted-css.md'),
+          menuItem('Unlisted HTML', 'unlisted-pages.md'),
+          menuItem('Unlisted Script', 'unlisted-scripts.md'),
+        ]),
+        menuGroup('CLI Reference', '/api/cli/', [
           menuItem('wxt', 'wxt.md'),
           menuItem('wxt build', 'wxt-build.md'),
           menuItem('wxt zip', 'wxt-zip.md'),

docs/.vitepress/utils/menus.ts

@@ -2,9 +2,20 @@ import { DefaultTheme } from 'vitepress';
 
 type SidebarItem = DefaultTheme.SidebarItem;
 type NavItem = DefaultTheme.NavItem;
+type NavItemWithLink = DefaultTheme.NavItemWithLink;
+type NavItemWithChildren = DefaultTheme.NavItemWithChildren;
+type NavItemChildren = DefaultTheme.NavItemChildren;
 
-export function navItem(text: string, link: string): NavItem {
-  return { text, link };
+export function navItem(text: string): NavItemChildren;
+export function navItem(text: string, link: string): NavItemChildren;
+export function navItem(text: string, items: any[]): NavItemWithChildren;
+export function navItem(text: string, arg2?: unknown): any {
+  if (typeof arg2 === 'string') {
+    return { text, link: arg2 };
+  } else if (Array.isArray(arg2)) {
+    return { text, items: arg2 };
+  }
+  return { text };
 }
 
 export function menuRoot(items: SidebarItem[]) {

docs/guide/directory-structure/entrypoints/content-scripts.md → docs/api/entrypoints/content-scripts.md

@@ -104,4 +104,4 @@ export default defineContentScript({
 });
 ```
 
-See [Content Script UI](/guide/key-concepts/content-script-ui) for more info on creating UIs and including CSS in content scripts.
+See [Content Script UI](/guide/content-scripts/ui) for more info on creating UIs and including CSS in content scripts.

docs/guide/directory-structure/entrypoints/css.md → docs/api/entrypoints/unlisted-css.md

@@ -1,11 +1,11 @@
-# CSS
+# Unlisted CSS
 
 WXT can build CSS entrypoints individually. CSS entrypoints are always unlisted.
 
-See [Content Script CSS](/guide/directory-structure/entrypoints/content-scripts#css) documentation for the recommended approach to include CSS with a content script.
+See [Content Script CSS](/guide/content-scripts/css) documentation for the recommended approach to include CSS with a content script.
 
 :::info
-If the recommended approach doesn't work for your use case, you can use any of the filename patterns below to build the styles separate from the JS and use the [`transformManifest` hook](/api/reference/wxt/interfaces/InlineConfig#transformmanifest) to manually add your CSS file to the manifest.
+If the recommended approach doesn't work for your use case, you can use any of the filename patterns below to build the styles separate from the JS and use the [`build:manifestGenerated` hook](/api/reference/wxt/interfaces/WxtHooks#build-manifestgenerated) to manually add your CSS file to the manifest.
 :::
 
 ## Filenames

docs/auto-icons.md

@@ -0,0 +1 @@
+<!--@include: ../packages/auto-icons/README.md-->

docs/guide/building/assets.md

@@ -0,0 +1,80 @@
+# Assets
+
+## `/assets` Directory
+
+Any assets imported or referenced inside the `<srcDir>/assets/` directory will be processed by WXT's bundler.
+
+Here's how you access them:
+
+:::code-group
+
+```ts [JS]
+import imageUrl from '~/assets/image.png';
+
+const img = document.createElement('img');
+img.src = imageUrl;
+```
+
+```html [HTML]
+<img src="~/assets/image.png" />
+```
+
+```css [CSS]
+.bg-image {
+  background-image: url(~/assets/image.png);
+}
+```
+
+:::
+
+## `/public` Directory
+
+Files inside `<srcDir>/public/` are copied into the output folder as-is, without being processed by WXT's bundler.
+
+Here's how you access them:
+
+:::code-group
+
+```ts [JS]
+import imageUrl from '/image.png';
+
+const img = document.createElement('img');
+img.src = imageUrl;
+```
+
+```html [HTML]
+<img src="/image.png" />
+```
+
+```css [CSS]
+.bg-image {
+  background-image: url(/image.png);
+}
+```
+
+:::
+
+## Inside Content Scripts
+
+Assets inside content scripts are a little different. By default, when you import an asset, it returns just the path to the asset. This is because WXT assumes you're loading assets from the same hostname.
+
+But, inside content scripts, the hostname is whatever the tab is set to. So if you try to fetch the asset, manually or as an `<img>`'s `src`, it will be loaded from the tab's website, not your extension.
+
+To fix this, you need to convert the image to a full URL using `browser.runtime.getURL`:
+
+```ts
+// entrypoints/content.ts
+import iconUrl from '/icon/128.png';
+
+export default defineContentScript({
+  matches: ['*://*.google.com/*'],
+  main() {
+    console.log(iconUrl); // "/icon/128.png"
+    console.log(browser.runtime.getURL(iconUrl)); // "chrome-extension://<id>/icon/128.png"
+  },
+});
+```
+
+## WASM
+
+TODO