diff --git a/docs/docs/components/_category_.json b/docs/docs/components/_category_.json
deleted file mode 100644
index 57bbce61..00000000
--- a/docs/docs/components/_category_.json
+++ /dev/null
@@ -1,4 +0,0 @@
-{
- "label": "Components",
- "position": 2
-}
diff --git a/docs/docs/components/_category_.yml b/docs/docs/components/_category_.yml
new file mode 100644
index 00000000..f3bb17cf
--- /dev/null
+++ b/docs/docs/components/_category_.yml
@@ -0,0 +1,4 @@
+label: Components
+position: 1
+collapsed: true
+collapsible: true
diff --git a/docs/docs/extend.mdx b/docs/docs/extend/extend.mdx
similarity index 80%
rename from docs/docs/extend.mdx
rename to docs/docs/extend/extend.mdx
index 7d4c6812..2d6494c7 100644
--- a/docs/docs/extend.mdx
+++ b/docs/docs/extend/extend.mdx
@@ -1,5 +1,7 @@
---
-sidebar_position: 4
+sidebar_position: 3
+title: Extend
+description: Learn how to extend @pixi/react with custom PixiJS components and use the extend API to keep your bundle size small.
---
One of the most important concepts to understand with v8 is `extend`. Normally `@pixi/react` would have to import all of Pixi.js to be able to provide the full library as JSX components. Instead, we use an internal catalogue of components populated by the `extend` API. This allows you to define exactly which parts of Pixi.js you want to import, keeping your bundle sizes small.
diff --git a/docs/docs/getting-started/_category_.yml b/docs/docs/getting-started/_category_.yml
new file mode 100644
index 00000000..325fb57b
--- /dev/null
+++ b/docs/docs/getting-started/_category_.yml
@@ -0,0 +1,4 @@
+label: Getting Started
+position: 0
+collapsed: false
+collapsible: true
diff --git a/docs/docs/getting-started/ecosystem.mdx b/docs/docs/getting-started/ecosystem.mdx
new file mode 100644
index 00000000..fe1722f2
--- /dev/null
+++ b/docs/docs/getting-started/ecosystem.mdx
@@ -0,0 +1,266 @@
+---
+sidebar_position: 2
+title: Ecosystem
+description: Explore the @pixi/react ecosystem, including React-specific tools, PixiJS integration, and community resources.
+---
+
+`@pixi/react` is designed to work seamlessly with both the React and PixiJS ecosystems. This integration allows you to leverage the best tools and libraries from both worlds to create powerful, interactive applications.
+
+## React Integration
+
+### React DevTools
+
+Since `@pixi/react` components are real React components, you can use [React DevTools](https://react.dev/learn/react-developer-tools) to inspect component hierarchies, props, and state just like any other React application.
+
+### State Management
+
+Use any React state management solution with `@pixi/react`:
+
+#### Redux Toolkit
+
+```jsx
+import { useSelector, useDispatch } from 'react-redux'
+import { Application, extend } from '@pixi/react'
+import { Sprite } from 'pixi.js'
+
+extend({ Sprite })
+
+function GameSprite() {
+ const player = useSelector(state => state.player)
+ const dispatch = useDispatch()
+
+ return (
+
+ dispatch(movePlayer())}
+ />
+
+ )
+}
+```
+
+#### Zustand
+
+```jsx
+import { usePlayerStore } from './store'
+
+function PlayerSprite() {
+ const { x, y, texture, move } = usePlayerStore()
+
+ return (
+
+ )
+}
+```
+
+### Custom Hooks
+
+Create reusable game logic with React hooks:
+
+```jsx
+import { useTick } from '@pixi/react'
+import { useCallback, useMemo } from 'react'
+
+function useGameLoop(callback, enabled = true) {
+ const memoizedCallback = useCallback(callback, [callback])
+
+ useTick(memoizedCallback, { isEnabled: enabled })
+}
+
+function useCollision(sprite1, sprite2) {
+ return useMemo(() => {
+ // collision detection logic
+ return checkCollision(sprite1, sprite2)
+ }, [sprite1, sprite2])
+}
+```
+
+### Context Providers
+
+Share game state across components:
+
+```jsx
+import { createContext, useState } from 'react'
+import { Application } from '@pixi/react'
+
+const GameContext = createContext()
+
+function GameProvider({ children }) {
+ const [gameState, setGameState] = useState(initialState)
+
+ return (
+
+
+ {children}
+
+
+ )
+}
+```
+
+---
+
+## PixiJS Integration
+
+Since `@pixi/react` is a thin wrapper around PixiJS, you can use any PixiJS features directly:
+
+### Filters
+
+Apply visual effects using PixiJS filters:
+
+```jsx
+import { BlurFilter } from 'pixi.js'
+import { useMemo } from 'react'
+
+function FilteredSprite() {
+ const filters = useMemo(() => [
+ new BlurFilter(4)
+ ], [])
+
+ return (
+
+ )
+}
+```
+
+### Custom Components with Third-Party Libraries
+
+Use the `extend` API to integrate third-party PixiJS libraries:
+
+#### [pixi-viewport](https://github.com/davidfig/pixi-viewport)
+
+Create interactive, zoomable viewports:
+
+```jsx
+import { extend } from '@pixi/react'
+import { Viewport } from 'pixi-viewport'
+
+extend({ Viewport })
+
+function GameViewport() {
+ return (
+
+
+ {/* Your game objects */}
+
+
+ )
+}
+```
+
+> **Note**: Third-party libraries compatibility may vary. Always test thoroughly and check library documentation for PixiJS v8 compatibility.
+
+---
+
+## Development Tools
+
+### TypeScript Support
+
+`@pixi/react` provides full TypeScript support. For custom components, extend the type definitions:
+
+```typescript
+// global.d.ts
+import { PixiReactElementProps } from '@pixi/react'
+import { Viewport } from 'pixi-viewport'
+
+declare module '@pixi/react' {
+ interface PixiElements {
+ viewport: PixiReactElementProps
+ }
+}
+```
+
+### Testing
+
+Test your `@pixi/react` components with [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/):
+
+```jsx
+import { render } from '@testing-library/react'
+import { Application } from '@pixi/react'
+import MyGameComponent from './MyGameComponent'
+
+test('renders game component', () => {
+ render(
+
+
+
+ )
+ // Test your component logic
+})
+```
+
+### Storybook
+
+Document your graphics components with [Storybook](https://storybook.js.org/):
+
+```jsx
+export default {
+ title: 'Game/PlayerSprite',
+ component: PlayerSprite,
+}
+
+export const Default = () => (
+
+
+
+)
+```
+
+---
+
+## React Framework Integration
+
+### Next.js
+
+`@pixi/react` works seamlessly with Next.js. For server-side rendering, make sure to import PixiJS components dynamically:
+
+```jsx
+import dynamic from 'next/dynamic'
+
+const GameComponent = dynamic(
+ () => import('../components/GameComponent'),
+ { ssr: false }
+)
+
+export default function GamePage() {
+ return
+}
+```
+
+### Vite
+
+Perfect compatibility with Vite's fast development experience:
+
+```bash
+npm create vite@latest my-pixi-app -- --template react
+npm install pixi.js@^8.2.6 @pixi/react
+```
+
+---
+
+## Community Resources
+
+- **[GitHub Repository](https://github.com/pixijs/pixi-react)** - Source code, issues, and discussions
+- **[GitHub Discussions](https://github.com/pixijs/pixi-react/discussions)** - Ask questions and share ideas
+- **[PixiJS Discord](https://discord.gg/zqbXQAADuM)** - Get help from the community
+- **[Examples](https://github.com/pixijs/pixi-react/tree/main/docs/src/examples)** - Browse code examples
+
+The combination of React's declarative component model with PixiJS's high-performance rendering provides everything you need to build incredible interactive experiences.
diff --git a/docs/docs/getting-started/intro.mdx b/docs/docs/getting-started/intro.mdx
new file mode 100644
index 00000000..aac06362
--- /dev/null
+++ b/docs/docs/getting-started/intro.mdx
@@ -0,0 +1,97 @@
+---
+title: Introduction
+sidebar_position: 0
+hide_title: true
+description: Overview of @pixi/react, its features, and what makes it the best way to write PixiJS applications in React.
+---
+
+
+
+
+
+
+
+
Simply the best way to write PixiJS applications in React
+
+
+ Write PixiJS applications using React declarative style 👌
+
+
+ 
+ 
+ 
+ 
+