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:

# 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:

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:

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:

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:

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:

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

This will not work:

import confetti from "canvas-confetti"

Local Imports

You can import local files from your homepage entry file.

Example:

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.