# github-pages-homepage-required

> Fix GitHub Pages homepage 404 by creating docs/index.md

- Author: Andrew Holder
- Repository: drewswiredin/vincent-chappie
- Version: 20260209202943
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-10
- Source: https://github.com/drewswiredin/vincent-chappie
- Web: https://mule.run/skillshub/@@drewswiredin/vincent-chappie~github-pages-homepage-required:20260209202943

---

---
name: github-pages-homepage-required
description: Fix GitHub Pages homepage 404 by creating docs/index.md
domain: GitHub
user-invocable: false
allowed-tools: Read, Write
---

# GitHub Pages Homepage Required

GitHub Pages shows MkDocs 404 on root URL if `docs/index.md` is missing.

## The Problem

- Site URL loads but shows "404 - Not found"
- Subpages work fine (e.g., /work/, /environment/)
- Navigation references `index.md` but file doesn't exist

## Root Cause

MkDocs requires `docs/index.md` for the homepage. Navigation can reference it, but the actual file must exist in the docs directory.

## Solution

Create `docs/index.md` with homepage content:

```markdown
# Site Title

Welcome to the site...

## Quick Links
- [Link 1](path/to/page.md)
- [Link 2](path/to/other.md)
```

## Verification

```bash
# Check if homepage exists
test -f docs/index.md || echo "Missing homepage!"

# After deploy
curl -I https://username.github.io/repo-name/
# Should return 200, not 404
```

## Gotcha

Even if mkdocs.yml navigation has this entry:
```yaml
nav:
  - Home: index.md
```

The file must still physically exist at `docs/index.md`. Navigation alone is not sufficient.