A custom 404 page

SeriesPart of How this blog was built — documenting every decision that shaped this site.

A 404 page is easy to forget. You build the real pages, you wire up the routes, and the 404 sits at the bottom of the list — “I’ll do that later.” Later arrives when someone pastes a broken link, follows a dead URL from an old tweet, or misremembers your slug. What they see in that moment is not nothing: it is a page, it represents your site, and it should look like it belongs there.

In Astro, building one is trivial. The interesting part is the design.

Custom 404 page wireframe showing a hero panel with the outlined 404 number and ghost offset next to the Nothing here heading and two buttons, and a card grid below linking to guides and core pages

Click the expand icon to view it fullscreen.

How Astro handles 404s

Create a file at src/pages/404.astro and Astro will render it as /404.html in the static build output. Netlify serves that file automatically for any path that doesn’t match a real route. No configuration required — it works out of the box.

The page has access to everything a normal page does: layouts, components, styles, the full design system.

Skipping the standard layout

The first decision was whether to use the PageHero component that every other page uses. It gives you a kicker, a title, a subtitle, breadcrumbs, and optional cover image — which is fine for real content, but overkill for an error page. A 404 doesn’t need breadcrumbs. It doesn’t need a cover image. It needs to tell the user what happened and give them somewhere to go.

Dropping PageHero frees up the layout, but “somewhere to go” turned out to be more than one link. Rather than a single centred block, the page ended up as two sections: a hero panel that states the problem, and a grid of cards underneath that gives the visitor several concrete next steps.

The hero panel

The hero is a self-contained page-panel with a two-column grid on tablet and up: the outlined number on the left, the eyebrow, heading, copy, and buttons on the right. Below that breakpoint it stacks into a single column.

1
.not-found__panel {
2
  display: grid;
3
  gap: 1.5rem;
4
  align-items: center;
5
  background:
6
    radial-gradient(
7
      circle at top right,
8
      color-mix(in srgb, var(--accent-secondary) 14%, transparent) 0%,
9
      transparent 34%
10
    ),
11
    linear-gradient(
12
      150deg,
13
      color-mix(in srgb, var(--accent-primary) 4%, var(--surface-elevated)) 0%,
14
      var(--surface-elevated) 62%
15
    ),
16
    var(--surface-elevated);
17

18
  @media (min-width: 768px) {
19
    grid-template-columns: minmax(9rem, 0.6fr) minmax(0, 1.4fr);
20
    gap: 2rem;
21
  }
22
}

The gradients are subtle: a hint of the pink accent bleeding in from the left, a hint of the secondary green in the top-right corner, layered over the same --surface-elevated token every other panel on the site uses, so the page still looks like it belongs here rather than a one-off design experiment.

The number

The visual anchor is the “404” itself. The approach here is outlined text: transparent fill, a pink stroke, with a faint offset copy behind it to create a ghost effect.

1
.not-found__number {
2
  font-family: "Barlow Condensed", sans-serif;
3
  font-size: clamp(6rem, 18vw, 12rem);
4
  font-weight: 900;
5
  line-height: 0.9;
6
  letter-spacing: -0.03em;
7
  color: transparent;
8
  -webkit-text-stroke: 2px var(--accent-primary);
9
  position: relative;
10

11
  &::after {
12
    content: "404";
13
    position: absolute;
14
    inset: 0;
15
    color: rgba(var(--accent-primary-rgb), 0.07);
16
    -webkit-text-stroke: 0;
17
    transform: translate(6px, 6px);
18
    z-index: -1;
19
  }
20
}

-webkit-text-stroke has broad browser support and the effect is subtle enough that it degrades gracefully if it didn’t. The ::after pseudo-element repeats the text, shifts it six pixels, and uses a very low-opacity solid fill — it looks like a shadow but reads as intentional.

clamp(6rem, 18vw, 12rem) handles the responsive sizing without a media query: small on mobile, fluid in the middle, capped once the panel’s own column width takes over on wider screens.

The copy and the primary actions

Inside the right-hand column, there’s a small eyebrow above the heading, a two-line explanation, and two calls to action styled with the site’s existing Bulma button classes rather than anything bespoke:

1
<p class="not-found__eyebrow">Page not found</p>
2
<h1 class="not-found__heading">Nothing here.</h1>
3
<p class="not-found__sub">
4
  That URL may have moved, been deleted, or never existed. Start
5
  from the homepage, jump into the latest writing, or pick the guide
6
  that matches where you are now.
7
</p>
8
<div class="not-found__actions">
9
  <a href="/" class="button is-primary is-medium">Home</a>
10
  <a href="/blog" class="button is-light is-medium">Browse the blog</a>
11
</div>

“Nothing here.” is short deliberately. “Page not found” is accurate but passive, so it moved to a small uppercase eyebrow instead, and the <h1> gets to be the blunt version. The is-primary button (solid pink) covers the obvious escape route; is-light gives a lower-commitment second option for someone who just wants to keep reading.

Try these instead: guides and core pages

Two buttons cover the obvious cases, but a 404 is also a reasonable place to hand someone a menu. Below the hero panel sits a second section, labelled “Try these instead”, with a card grid mixing two sources:

The site’s audienceGuides data — the same array that powers the guide landing pages — mapped straight into cards.
A short, hard-coded list of core pages: Blog, About, Contact.

1
{audienceGuides.map((guide) => (
2
  <article class="not-found-card not-found-card--guide">
3
    <p class="not-found-card__eyebrow">Guide</p>
4
    <h3 class="not-found-card__title">{guide.title}</h3>
5
    <p class="not-found-card__body">{guide.summary}</p>
6
    <a href={guide.href} class="not-found-card__cta">Open the guide</a>
7
  </article>
8
))}
9
{corePages.map((page) => (
10
  <article class="not-found-card">
11
    <p class="not-found-card__eyebrow">Page</p>
12
    <h3 class="not-found-card__title">{page.label}</h3>
13
    <p class="not-found-card__body">{page.description}</p>
14
    <a href={page.href} class="not-found-card__cta">Open {page.label}</a>
15
  </article>
16
))}

Reusing audienceGuides instead of duplicating the guide titles and blurbs means the 404 page can’t drift out of sync with the guides landing page: if a guide is renamed or its summary is rewritten, this grid picks it up automatically. The two card types are visually distinguished by a thin top border: guide cards use --accent-secondary, core page cards use --accent-primary.

Accessibility notes

The number carries aria-hidden="true", since it’s decoration and the <h1> already says what happened, so a screen reader doesn’t need to announce “404” on top of “Nothing here.” Both sections use aria-labelledby pointing at their own heading id (not-found-heading, not-found-paths-heading) rather than a generic aria-label, so the accessibility tree gets the same heading text a sighted reader sees, instead of a second, possibly diverging, piece of copy to maintain.

Full code listing

1
---
2
import BaseLayout from "../layouts/BaseLayout.astro";
3
import { audienceGuides } from "../data/audienceGuides";
4

5
const corePages = [
6
  {
7
    href: "/blog",
8
    label: "Blog",
9
    description: "Start with the latest writing and browse by topic.",
10
  },
11
  {
12
    href: "/about",
13
    label: "About",
14
    description: "Find out who I help and the kind of work I do.",
15
  },
16
  {
17
    href: "/contact",
18
    label: "Contact",
19
    description: "Get in touch about mentoring, consulting, or a question.",
20
  },
21
];
22
---
23

24
<BaseLayout
25
  pageTitle="Page not found — Sourcier"
26
  description="The page you're looking for doesn't exist."
27
>
28
  <div class="not-found flow-section flow-section--loose">
29
    <div class="container is-max-desktop">
30
      <section class="not-found__hero" aria-labelledby="not-found-heading">
31
        <div class="page-panel not-found__panel">
32
          <div class="not-found__number" aria-hidden="true">404</div>
33
          <div class="not-found__copy">
34
            <p class="not-found__eyebrow">Page not found</p>
35
            <h1 class="not-found__heading" id="not-found-heading">
36
              Nothing here.
37
            </h1>
38
            <p class="not-found__sub">
39
              That URL may have moved, been deleted, or never existed. Start
40
              from the homepage, jump into the latest writing, or pick the guide
41
              that matches where you are now.
42
            </p>
43
            <div class="not-found__actions">
44
              <a href="/" class="button is-primary is-medium">Home</a>
45
              <a href="/blog" class="button is-light is-medium">
46
                Browse the blog
47
              </a>
48
            </div>
49
          </div>
50
        </div>
51
      </section>
52

53
      <section
54
        class="not-found__paths"
55
        aria-labelledby="not-found-paths-heading"
56
      >
57
        <p class="section-label">Try these instead</p>
58
        <h2 class="not-found__paths-heading" id="not-found-paths-heading">
59
          Start from a guide or a core page
60
        </h2>
61
        <div class="not-found__grid">
62
          {
63
            audienceGuides.map((guide) => (
64
              <article class="not-found-card not-found-card--guide">
65
                <p class="not-found-card__eyebrow">Guide</p>
66
                <h3 class="not-found-card__title">{guide.title}</h3>
67
                <p class="not-found-card__body">{guide.summary}</p>
68
                <a href={guide.href} class="not-found-card__cta">
69
                  Open the guide
70
                </a>
71
              </article>
72
            ))
73
          }
74
          {
75
            corePages.map((page) => (
76
              <article class="not-found-card">
77
                <p class="not-found-card__eyebrow">Page</p>
78
                <h3 class="not-found-card__title">{page.label}</h3>
79
                <p class="not-found-card__body">{page.description}</p>
80
                <a href={page.href} class="not-found-card__cta">
81
                  Open {page.label}
82
                </a>
83
              </article>
84
            ))
85
          }
86
        </div>
87
      </section>
88
    </div>
89
  </div>
90
</BaseLayout>
91

92
<style lang="scss">
93
  .not-found {
94
    padding: 0 1.5rem;
95
  }
96

97
  .not-found__panel {
98
    display: grid;
99
    gap: 1.5rem;
100
    align-items: center;
101
    margin-bottom: 3rem;
102
    background:
103
      radial-gradient(
104
        circle at top right,
105
        color-mix(in srgb, var(--accent-secondary) 14%, transparent) 0%,
106
        transparent 34%
107
      ),
108
      linear-gradient(
109
        150deg,
110
        color-mix(in srgb, var(--accent-primary) 4%, var(--surface-elevated)) 0%,
111
        var(--surface-elevated) 62%
112
      ),
113
      var(--surface-elevated);
114

115
    @media (min-width: 768px) {
116
      grid-template-columns: minmax(9rem, 0.6fr) minmax(0, 1.4fr);
117
      gap: 2rem;
118
    }
119
  }
120

121
  .not-found__number {
122
    font-family: "Barlow Condensed", sans-serif;
123
    font-size: clamp(6rem, 18vw, 12rem);
124
    font-weight: 900;
125
    line-height: 0.9;
126
    letter-spacing: -0.03em;
127
    color: transparent;
128
    -webkit-text-stroke: 2px var(--accent-primary);
129
    user-select: none;
130
    position: relative;
131

132
    &::after {
133
      content: "404";
134
      position: absolute;
135
      inset: 0;
136
      color: rgba(var(--accent-primary-rgb), 0.07);
137
      -webkit-text-stroke: 0;
138
      transform: translate(6px, 6px);
139
      z-index: -1;
140
    }
141
  }
142

143
  .not-found__eyebrow {
144
    margin: 0 0 0.65rem;
145
    font-family: "Barlow Condensed", sans-serif;
146
    font-size: 0.8rem;
147
    font-weight: 700;
148
    text-transform: uppercase;
149
    letter-spacing: 0.1em;
150
    color: var(--accent-secondary);
151
  }
152

153
  .not-found__heading {
154
    margin: 0;
155
    font-family: "Barlow Condensed", sans-serif;
156
    font-size: clamp(2rem, 5vw, 3.5rem);
157
    line-height: 0.95;
158
    text-transform: uppercase;
159
    color: var(--text-primary);
160
  }
161

162
  .not-found__sub {
163
    margin: 0.95rem 0 0;
164
    max-width: 58ch;
165
    line-height: 1.75;
166
    color: var(--text-muted);
167
  }
168

169
  .not-found__actions {
170
    display: flex;
171
    flex-wrap: wrap;
172
    gap: 0.75rem;
173
    margin-top: 1.4rem;
174
  }
175

176
  .not-found__paths-heading {
177
    margin: 0 0 1.5rem;
178
    font-family: "Barlow Condensed", sans-serif;
179
    font-size: clamp(1.8rem, 4vw, 2.5rem);
180
    line-height: 1.02;
181
    text-transform: uppercase;
182
    color: var(--text-primary);
183
  }
184

185
  .not-found__grid {
186
    display: grid;
187
    gap: 1rem;
188

189
    @media (min-width: 768px) {
190
      grid-template-columns: repeat(3, minmax(0, 1fr));
191
    }
192
  }
193

194
  .not-found-card {
195
    display: flex;
196
    flex-direction: column;
197
    gap: 0.85rem;
198
    min-height: 100%;
199
    padding: 1.4rem;
200
    border: 1px solid var(--border-subtle);
201
    border-top: 3px solid var(--accent-primary);
202
    border-radius: var(--radius-panel);
203
    background:
204
      linear-gradient(
205
        160deg,
206
        color-mix(in srgb, var(--accent-primary) 4%, var(--surface-elevated)) 0%,
207
        var(--surface-elevated) 62%
208
      ),
209
      var(--surface-elevated);
210
    box-shadow: var(--shadow-panel);
211
    transition:
212
      transform 0.18s ease,
213
      box-shadow 0.18s ease,
214
      border-color 0.18s ease;
215

216
    &:hover {
217
      transform: translateY(-3px);
218
      box-shadow: var(--shadow-lift);
219
    }
220
  }
221

222
  .not-found-card--guide {
223
    border-top-color: var(--accent-secondary);
224
    background:
225
      radial-gradient(
226
        circle at top right,
227
        color-mix(in srgb, var(--accent-secondary) 12%, transparent) 0%,
228
        transparent 34%
229
      ),
230
      linear-gradient(
231
        160deg,
232
        color-mix(in srgb, var(--accent-primary) 3%, var(--surface-elevated)) 0%,
233
        var(--surface-elevated) 62%
234
      ),
235
      var(--surface-elevated);
236
  }
237

238
  .not-found-card__eyebrow {
239
    margin: 0;
240
    font-family: "Barlow Condensed", sans-serif;
241
    font-size: 0.78rem;
242
    font-weight: 700;
243
    letter-spacing: 0.1em;
244
    text-transform: uppercase;
245
    color: var(--text-muted);
246
  }
247

248
  .not-found-card--guide .not-found-card__eyebrow {
249
    color: var(--accent-secondary);
250
  }
251

252
  .not-found-card__title {
253
    margin: 0;
254
    font-family: "Barlow Condensed", sans-serif;
255
    font-size: 1.15rem;
256
    line-height: 1.05;
257
    text-transform: uppercase;
258
    color: var(--text-primary);
259
  }
260

261
  .not-found-card__body {
262
    margin: 0;
263
    line-height: 1.65;
264
    color: var(--text-muted);
265
  }
266

267
  .not-found-card__cta {
268
    margin-top: auto;
269
    display: inline-flex;
270
    align-items: center;
271
    padding-block: 0.75rem;
272
    font-family: "Barlow Condensed", sans-serif;
273
    font-size: 0.86rem;
274
    font-weight: 700;
275
    letter-spacing: 0.08em;
276
    text-transform: uppercase;
277
    color: var(--accent-primary);
278
    text-decoration: none;
279
  }
280

281
  .not-found-card--guide .not-found-card__cta {
282
    color: var(--accent-secondary);
283
  }
284
</style>

What Netlify does with it

Netlify serves 404.html for any unmatched route. No netlify.toml redirect rule needed, no custom headers — it just works. Deploy it and broken links get your page instead of the browser default.