# Homepage

The homepage is a special page in Doctopus.

It is always the page at `/`.

Doctopus looks for a file named `index` in the root of your docs directory.

Supported homepage files are:

- `docs/index.md`
- `docs/index.markdown`
- `docs/index.jsx`
- `docs/index.tsx`

## Index Page vs Regular Page

The index page is your homepage.

A regular page is any other Markdown file.

Examples:

- `docs/index.md` becomes `/`
- `docs/config.md` becomes `/config/`
- `docs/getting_started.md` becomes `/getting_started/`

The main differences are:

- the index page is the only page at `/`
- the index page can be Markdown or React
- regular pages are Markdown only

If you want a normal docs page, use Markdown.

If you want a custom landing page, use the special index page.

## Markdown Index

If you create `docs/index.md`, the homepage behaves like a normal Markdown page.

Example:

```md
# Welcome

This is my documentation site.

- Start here
- Read the guide
- Check the config
```

This is the simple option.

It is good for:

- a text-first homepage
- simple links and lists
- a homepage that matches the rest of the docs

## React Index

If you create `docs/index.jsx` or `docs/index.tsx`, the homepage is built from a React component.

Use a named export called `App`.

Example:

```tsx
export function App() {
  return (
    <section>
      <h1>Welcome</h1>
      <p>This homepage is written in React.</p>
    </section>
  )
}
```

`App` is mounted as the root component for the homepage.

## Markdown Index vs React Index

`index.md` or `index.markdown`:

- simple
- easy to write
- best for normal documentation content

`index.jsx` or `index.tsx`:

- more flexible
- best for high customization
- supports interactive UI

Use Markdown when you want a simple homepage.

Use React when you want a custom homepage with more control.

## What React Is Good For

The React homepage is useful when Markdown is not enough.

It is good for:

- hero sections
- custom layouts
- feature cards
- call-to-action sections
- interactive parts
- homepage designs that look more like a product landing page

Simple interactive example:

```tsx
import { useState } from "react"

export function App() {
  const [count, setCount] = useState(0)

  return (
    <section>
      <h1>Interactive homepage</h1>
      <p>You clicked {count} times.</p>
      <button onClick={() => setCount(count + 1)}>Click me</button>
    </section>
  )
}
```

## How The React Integration Works

Doctopus handles the React homepage for you.

At build time, Doctopus:

1. Renders your `App` component to HTML.
2. Builds a browser script for the homepage.
3. Hydrates the rendered HTML in the browser.

This means:

- the homepage already has HTML when the site is generated
- the browser script is added automatically
- interactive parts start working after hydration

You do not need to mount React yourself.

## What It Does Not Require

The React homepage does not need a normal React project setup.

You do not need:

- `package.json`
- `npm`
- `pnpm`
- `yarn`
- a separate React app
- your own bundler config
- your own hydration code

You only need `docs/index.jsx` or `docs/index.tsx`.

## React Version

Doctopus uses React `18.3.1`.

That version is pinned by Doctopus.

## What You Can Import

Imports from these React packages are handled by Doctopus:

- `react`
- `react-dom`
- `react-dom/client`
- `react-dom/server`

In most homepage files, you only need `react`.

Example:

```tsx
import { useState } from "react"

export function App() {
  const [open, setOpen] = useState(false)

  return (
    <section>
      <button onClick={() => setOpen(!open)}>Toggle</button>
      {open ? <p>Hello</p> : null}
    </section>
  )
}
```

## Using External Libraries

You can also use other libraries.

For external libraries, use a full ESM URL import.

Example:

```tsx
import confetti from "https://esm.sh/canvas-confetti@1.9.3"

export function App() {
  return <button onClick={() => confetti()}>Celebrate</button>
}
```

This works because Doctopus can fetch remote ESM modules while it builds the homepage.

Important:

- React imports are built in
- other bare imports are not resolved automatically
- for other libraries, use a full URL import

This is a good import:

```tsx
import confetti from "https://esm.sh/canvas-confetti@1.9.3"
```

This will not work:

```tsx
import confetti from "canvas-confetti"
```

## Local Imports

You can import local files from your homepage entry file.

Example:

```tsx
import { Hero } from "./hero"

export function App() {
  return <Hero />
}
```

This is useful if you want to split the homepage into small components.

## Summary

The index page is special because it is the homepage.

Use Markdown when you want a simple docs-style homepage.

Use React when you want high customization or interactivity.