docs: init docs site

.oxfmtignore

@@ -0,0 +1,2 @@
+# Docus MDC content - formatter breaks component syntax
+docs/content/**/*.md

docs/.gitignore

@@ -0,0 +1,5 @@
+node_modules
+.nuxt
+.output
+.data
+dist

docs/app/app.config.ts

@@ -0,0 +1,14 @@
+export default defineAppConfig({
+  docus: {
+    name: 'npmx.dev',
+    description: 'A fast, modern browser for the npm registry',
+    url: 'https://docs.npmx.dev',
+    socials: {
+      github: 'npmx-dev/npmx.dev',
+      x: '@npmx_dev',
+    },
+  },
+  llms: {
+    domain: 'https://docs.npmx.dev',
+  },
+})

docs/content/1.getting-started/.navigation.yml

@@ -0,0 +1,2 @@
+title: Getting Started
+icon: i-lucide-rocket

docs/content/1.getting-started/1.introduction.md

@@ -0,0 +1,33 @@
+---
+title: Introduction
+description: Learn what npmx.dev is and why you should use it
+navigation:
+  icon: i-lucide-house
+---
+
+npmx.dev provides a better way to browse the npm registry.
+
+## What is npmx.dev?
+
+npmx.dev is a fast, modern browser for the npm registry. It doesn't aim to replace [npmjs.com](https://www.npmjs.com/), but provides a better UI and developer experience for browsing packages, viewing documentation, and exploring code.
+
+## What you can do
+
+- **Search packages** - Quick package search with instant results and infinite scroll
+- **Browse source code** - View package source code with syntax highlighting
+- **Check security** - See vulnerability warnings and provenance indicators
+- **Use familiar URLs** - Replace npmjs.com with npmx.dev in any URL
+
+## When to use npmx.dev
+
+Use npmx.dev when you want to:
+
+- Quickly find and evaluate npm packages
+- Browse package source code without downloading
+- Check package security and provenance
+- View package metadata in a clean, dark-mode interface
+- Navigate with keyboard shortcuts
+
+::note
+This documentation includes AI integration with MCP server (`/mcp`) and automatic `llms.txt` generation.
+::

docs/content/1.getting-started/2.quick-start.md

@@ -0,0 +1,48 @@
+---
+title: Quick Start
+description: Start using npmx.dev in seconds
+navigation:
+  icon: i-lucide-zap
+---
+
+npmx.dev works in your browser with no installation required.
+
+## Open npmx.dev
+
+Visit [npmx.dev](https://npmx.dev) to start browsing packages.
+
+## Search for a package
+
+1. Press `/` to focus the search bar (or click it)
+2. Type a package name
+3. Use arrow keys to navigate results
+4. Press `Enter` to view the package
+
+## View package details
+
+Each package page shows:
+
+- **README** - Package documentation
+- **Versions** - All published versions with release dates
+- **Dependencies** - Required packages with version ranges
+- **Metadata** - License, repository, maintainers, and more
+
+## Browse source code
+
+1. Click the **Code** tab or press `.`
+2. Navigate the file tree
+3. Click any file to view its contents with syntax highlighting
+
+## Use npm URLs
+
+Replace `npmjs.com` with `npmx.dev` in any npm URL:
+
+| npm URL                       | npmx.dev equivalent          |
+| ----------------------------- | ---------------------------- |
+| `npmjs.com/package/nuxt`      | `npmx.dev/package/nuxt`      |
+| `npmjs.com/package/@nuxt/kit` | `npmx.dev/package/@nuxt/kit` |
+| `npmjs.com/~sindresorhus`     | `npmx.dev/~sindresorhus`     |
+
+::tip
+Install the [npmx-replace browser extension](https://github.com/tylersayshi/npmx-replace-extension) for automatic redirects from npmjs.com.
+::

docs/content/2.guide/.navigation.yml

@@ -0,0 +1,2 @@
+title: Guide
+icon: i-lucide-book-open

docs/content/2.guide/1.features.md

@@ -0,0 +1,60 @@
+---
+title: Features
+description: Explore all the features npmx.dev offers
+navigation:
+  icon: i-lucide-sparkles
+---
+
+npmx.dev provides a comprehensive set of features for browsing npm packages.
+
+## Browse packages
+
+### View package details
+
+Each package page displays:
+
+- **README** - Rendered markdown documentation
+- **Versions** - Complete version history with release dates
+- **Dependencies** - Required packages with version ranges that resolve to actual versions
+- **Dependents** - Packages that depend on this one (coming soon)
+
+### Check package badges
+
+Packages display helpful badges:
+
+| Badge            | Meaning                                                     |
+| ---------------- | ----------------------------------------------------------- |
+| ESM / CJS / Dual | Module format support                                       |
+| TypeScript       | Includes type definitions (links to `@types/*` if separate) |
+| Provenance       | Verified build from a known source                          |
+
+### View security information
+
+- **Vulnerability warnings** - Security advisories from the OSV database
+- **Deprecation notices** - Clear warnings for deprecated packages and versions
+- **Provenance indicators** - Verified build badges for packages with npm provenance
+
+## Browse source code
+
+Press `.` or click the **Code** tab to open the code viewer:
+
+- **File tree** - Navigate the package structure
+- **Syntax highlighting** - Language-aware code display
+- **Permalinks** - Link to specific lines in files
+
+## View statistics
+
+- **Download counts** - Weekly downloads with sparkline charts
+- **Install size** - Total size including transitive dependencies
+- **Repository stats** - Stars and forks from GitHub, GitLab, Bitbucket, Codeberg, Gitee, and Sourcehut
+
+## Explore users and organizations
+
+- **User profiles** - View any npm user's public packages at `/~username`
+- **Organization pages** - Browse org packages at `/@orgname`
+- **Search and filter** - Find packages within user/org lists
+
+## Access related resources
+
+- **JSR availability** - See if scoped packages are also available on JSR
+- **Playground links** - Quick access to StackBlitz, CodeSandbox, and other demo environments from READMEs

docs/content/2.guide/2.keyboard-shortcuts.md

@@ -0,0 +1,36 @@
+---
+title: Keyboard Shortcuts
+description: Navigate npmx.dev efficiently with keyboard shortcuts
+navigation:
+  icon: i-lucide-keyboard
+---
+
+npmx.dev supports keyboard navigation for faster browsing.
+
+## Use global shortcuts
+
+| Key | Action           |
+| --- | ---------------- |
+| `/` | Focus search bar |
+| `.` | Open code viewer |
+
+## Navigate search results
+
+| Key                       | Action                |
+| ------------------------- | --------------------- |
+| `Arrow Up` / `Arrow Down` | Move through results  |
+| `Enter`                   | Open selected package |
+
+## Browse code
+
+When in the code viewer:
+
+| Key                       | Action             |
+| ------------------------- | ------------------ |
+| `Arrow Up` / `Arrow Down` | Navigate file tree |
+| `Enter`                   | Open selected file |
+| `Escape`                  | Close code viewer  |
+
+::tip
+These shortcuts work anywhere on the site. Press `/` from any page to quickly search for a package.
+::

docs/content/2.guide/3.url-structure.md

@@ -0,0 +1,47 @@
+---
+title: URL Structure
+description: Understand how URLs work in npmx.dev
+navigation:
+  icon: i-lucide-link
+---
+
+npmx.dev supports npm-compatible URLs and simpler alternatives.
+
+## Use npm-compatible URLs
+
+Replace `npmjs.com` with `npmx.dev` (or `xnpmjs.com`) in any npm URL:
+
+| npm URL                         | npmx.dev equivalent                                                    |
+| ------------------------------- | ---------------------------------------------------------------------- |
+| `npmjs.com/package/nuxt`        | [`npmx.dev/package/nuxt`](https://npmx.dev/package/nuxt)               |
+| `npmjs.com/package/@nuxt/kit`   | [`npmx.dev/package/@nuxt/kit`](https://npmx.dev/package/@nuxt/kit)     |
+| `npmjs.com/package/vue/v/3.4.0` | [`npmx.dev/package/vue/v/3.4.0`](https://npmx.dev/package/vue/v/3.4.0) |
+| `npmjs.com/search?q=vue`        | [`npmx.dev/search?q=vue`](https://npmx.dev/search?q=vue)               |
+| `npmjs.com/~sindresorhus`       | [`npmx.dev/~sindresorhus`](https://npmx.dev/~sindresorhus)             |
+| `npmjs.com/org/nuxt`            | [`npmx.dev/org/nuxt`](https://npmx.dev/org/nuxt)                       |
+
+::tip
+Install the [npmx-replace browser extension](https://github.com/tylersayshi/npmx-replace-extension) for automatic redirects.
+::
+
+## Use simpler URLs
+
+npmx.dev also supports shorter, cleaner URLs:
+
+| Pattern                | Example                                            |
+| ---------------------- | -------------------------------------------------- |
+| `/<package>`           | [`/nuxt`](https://npmx.dev/nuxt)                   |
+| `/<package>@<version>` | [`/vue@3.4.0`](https://npmx.dev/vue@3.4.0)         |
+| `/@scope/name`         | [`/@nuxt/kit`](https://npmx.dev/@nuxt/kit)         |
+| `/@org`                | [`/@nuxt`](https://npmx.dev/@nuxt)                 |
+| `/~username`           | [`/~sindresorhus`](https://npmx.dev/~sindresorhus) |
+
+## Understand URL limitations
+
+Some npm URLs are not yet supported:
+
+| URL Pattern                  | Status                           |
+| ---------------------------- | -------------------------------- |
+| `/package/<name>/access`     | Not yet supported                |
+| `/package/<name>/dependents` | Coming soon                      |
+| `/settings/*`                | Not supported (account settings) |

docs/content/3.faq/.navigation.yml

@@ -0,0 +1,2 @@
+title: FAQ
+icon: i-lucide-circle-help

docs/content/3.faq/1.troubleshooting.md

@@ -0,0 +1,43 @@
+---
+title: Troubleshooting
+description: Common issues and how to resolve them
+navigation:
+  icon: i-lucide-wrench
+---
+
+Solutions to common issues when using npmx.dev.
+
+## Package not found
+
+If a package doesn't appear in search results or shows a 404 error:
+
+1. **Check the package name** - Ensure the name is spelled correctly
+2. **Verify it exists on npm** - Check [npmjs.com](https://www.npmjs.com/) directly
+3. **Wait for sync** - Newly published packages may take a few minutes to appear
+
+## Code viewer not loading
+
+If the code viewer shows an error or doesn't load:
+
+1. **Check package size** - Very large packages may take longer to load
+2. **Try a specific version** - Use a versioned URL like `/package-name@1.0.0`
+3. **Refresh the page** - Clear cache and reload
+
+## Missing features compared to npmjs.com
+
+Some features are not yet available:
+
+| Feature                       | Status      |
+| ----------------------------- | ----------- |
+| Dependents list               | Coming soon |
+| Package admin (access/owners) | Coming soon |
+| Org/team management           | Coming soon |
+| 2FA/account settings          | Not planned |
+
+## Report an issue
+
+If you encounter a bug or have a feature request:
+
+1. Check [existing issues](https://github.com/npmx-dev/npmx.dev/issues)
+2. [Open a new issue](https://issues.npmx.dev) with details
+3. Join the [Discord community](https://chat.npmx.dev) for discussion

docs/content/3.faq/2.comparison.md

@@ -0,0 +1,48 @@
+---
+title: Comparison
+description: How npmx.dev compares to npmjs.com
+navigation:
+  icon: i-lucide-git-compare
+---
+
+A feature comparison between npmx.dev and npmjs.com.
+
+## Feature comparison
+
+| Feature                        | npmjs.com |  npmx.dev   |
+| ------------------------------ | :-------: | :---------: |
+| Package search                 |    Yes    |     Yes     |
+| Package details & README       |    Yes    |     Yes     |
+| Version history                |    Yes    |     Yes     |
+| Dependencies list              |    Yes    |     Yes     |
+| User profiles                  |    Yes    |     Yes     |
+| Organization pages             |    Yes    |     Yes     |
+| Provenance indicators          |    Yes    |     Yes     |
+| Code browser                   |    Yes    |     Yes     |
+| Dark mode                      |    No     |     Yes     |
+| Outdated dependency warnings   |    No     |     Yes     |
+| Module format badges (ESM/CJS) |    No     |     Yes     |
+| TypeScript types indicator     |    Yes    |     Yes     |
+| Install size calculation       |    No     |     Yes     |
+| JSR cross-reference            |    No     |     Yes     |
+| Vulnerability warnings         |    Yes    |     Yes     |
+| Deprecation notices            |    Yes    |     Yes     |
+| Download charts                |    Yes    |     Yes     |
+| Playground links               |    No     |     Yes     |
+| Keyboard navigation            |    No     |     Yes     |
+| Multi-provider repo support    |    No     |     Yes     |
+| Version range resolution       |    No     |     Yes     |
+| Dependents list                |    Yes    | Coming soon |
+| Package admin (access/owners)  |    Yes    | Coming soon |
+| Org/team management            |    Yes    | Coming soon |
+| 2FA/account settings           |    Yes    |     No      |
+| Claim new package names        |    Yes    |     Yes     |
+
+## Why use npmx.dev?
+
+npmx.dev focuses on:
+
+- **Speed** - Fast page loads with no layout shift
+- **Developer experience** - Dark mode, keyboard navigation, cleaner UI
+- **Insights** - Module format badges, install size, outdated dependencies
+- **Compatibility** - Works with existing npm URLs

docs/content/index.md

@@ -0,0 +1,37 @@
+---
+seo:
+  title: npmx.dev Documentation
+  description: A fast, modern browser for the npm registry
+---
+
+::u-page-hero{title="npmx.dev" description="A fast, modern browser for the npm registry. Speed first, URL compatible, and simple."}
+#links
+:::u-button{color="neutral" size="xl" to="/getting-started/introduction" trailing-icon="i-lucide-arrow-right"}
+Get Started
+:::
+
+:::u-button{color="neutral" icon="i-simple-icons-github" size="xl" to="https://github.com/npmx-dev/npmx.dev" target="\_blank" variant="outline"}
+View on GitHub
+:::
+::
+
+::u-page-section{title="What you can do"}
+#features
+:::u-page-feature{icon="i-lucide-search" to="/guide/features" title="Search packages" description="Fast package search with instant results, infinite scroll, and keyboard navigation."}
+:::
+
+:::u-page-feature{icon="i-lucide-code" to="/guide/features" title="Browse source code" description="View package source code with syntax highlighting and permalink to specific lines."}
+:::
+
+:::u-page-feature{icon="i-lucide-link" to="/guide/url-structure" title="Use familiar URLs" description="Replace npmjs.com with npmx.dev in any URL and it just works."}
+:::
+
+:::u-page-feature{icon="i-lucide-keyboard" to="/guide/keyboard-shortcuts" title="Navigate with keyboard" description="Press / to search, . for code viewer, arrow keys to navigate results."}
+:::
+
+:::u-page-feature{icon="i-lucide-shield-check" to="/guide/features" title="Check security" description="Vulnerability warnings from OSV database and provenance indicators for verified builds."}
+:::
+
+:::u-page-feature{icon="i-lucide-moon" to="/guide/features" title="Enjoy dark mode" description="Dark mode by default for a better viewing experience."}
+:::
+::