How can I customize the 404 page?

[mickmcg]

I initially tried to do this in Netlify with a _redirects file to point to my 404.html for any URLs not found. With that method, you see the custom 404 page flash up for a split second before the standard Docusaurus page is shown instead with this text.

Page Not Found
We could not find what you were looking for.
Please contact the owner of the site that linked you to the original URL and let them know their link is broken.

Is there a proper Docusaurus way to have custom 404 pages?

[Josh-Cena]

Hi, you can swizzle the NotFound component. https://docusaurus.io/docs/using-themes#swizzling-theme-components

And ignore any warnings / cautions that might come up. This is a very safe component.

[Josh-Cena]

@B4nan It works for me locally. Did you restart your dev server?

[B4nan]

Ok my bad, the confusion coming from me changing the texts inside <Translate> tags, as that has no effect (which is quite weird to me, I would expect unmatched translation for the block instead, and seeing the text I wrote).

[B4nan]

btw the component is not listed at all when doing npm run swizzle -- --list (but when swizzling you dont get any warnings, just like with the ones considered stable)

[Josh-Cena]

Really? Shows for me:

[B4nan]

Ok, again my bad, I was trying to search just notfound and was in a case sensitive mode 🤦

Thanks for the prompt responses.

[mickmcg]

Hi Josh, thanks for the fast response. I can confirm this method works. 👍

npm run swizzle @docusaurus/theme-classic NotFound

Then edit src/theme/NotFound.js

[andrewm4894]

Just adding an example for any newbies like me who are a little unsure about all this (as i was).

I used this to eject and put in some code like this to fire a PostHog telemetry event each time a user hits the Not Found page.

[slorber]

I'd suggest to --wrap instead of --eject for this use-case: you'd have less duplicated code to maintain on your side

[andrewm4894]

cool - good to know - i'll give that a go.

[kazisean]

Hi Josh, thanks for the fast response. I can confirm this method works. +1

npm run swizzle @docusaurus/theme-classic NotFound

Then edit src/theme/NotFound.js

for any newbies like me, here is the default NotFound.js file (From andrewm4894)

import React, { useEffect } from 'react';
import Translate, {translate} from '@docusaurus/Translate';
import {PageMetadata} from '@docusaurus/theme-common';
import Layout from '@theme/Layout';
export default function NotFound() {

  return (
    <>
      <PageMetadata
        title={translate({
          id: 'theme.NotFound.title',
          message: 'Page Not Found',
        })}
      />
      <Layout>
        <main className="container margin-vert--xl">
          <div className="row">
            <div className="col col--6 col--offset-3">
              <h1 className="hero__title">
                <Translate
                  id="theme.NotFound.title"
                  description="The title of the 404 page">
                  Page Not Found
                </Translate>
              </h1>
              <p>
                <Translate
                  id="theme.NotFound.p1"
                  description="The first paragraph of the 404 page">
                  We could adadadnot find what you were looking for.
                </Translate>
              </p>
              <p>
                <Translate
                  id="theme.NotFound.p2"
                  description="The 2nd paragraph of the 404 page">
                  Please contact the owner of the site that linked you to the
                  original URL and let them know their link is broken.
                </Translate>
              </p>
            </div>
          </div>
        </main>
      </Layout>
    </>
  );
}

[tisonkun]

Is it possible to provide a JSON return conditionally instead of always a page?

[tisonkun]

Even I try to fake a /api/auth/me to return JSON content, I don't find a way to do so.

[slorber]

I still have no idea what you are trying to do sorry. Please start by explaining your goal instead of roadblocks.

Since the 404 page is returned with Docu, the status is 200 instead of 404 so I have to match the error content for specially handling.

It is the responsibility of your host to return the status code on the initial request. Only the initial request has a status code. If you "navigate" to an unexisting page (with a broken link for example), there's no status code involved.

Your host can definitively return a 404 status code. Most hosts would do that by default.

If you want /api/auth/me to return a JSON instead of a 404, again you can try adding an edge middleware for that 🤪 or probably just a regular node/serverless function too.

[tisonkun]

Thank you! This is not a roadblock to me anymore. I'm fine with all things provided now :)

[tisonkun]

@slorber For the status code part, here is a repo:

yarn start # with a docusaurus quickstart project

curl -i localhost:3000/api/auth/me # or any path not exist

You will get a 200 return:

curl -i localhost:3000/api/auth/me
HTTP/1.1 200 OK
X-Powered-By: Express
access-control-allow-origin: *
Content-Type: text/html; charset=utf-8
Accept-Ranges: bytes
Content-Length: 1285
ETag: W/"505-fYqcMyKlu4OHsJA9G4TaGdStWAg"
Vary: Accept-Encoding
Date: Wed, 28 Dec 2022 09:35:14 GMT
Connection: keep-alive
Keep-Alive: timeout=5

<!DOCTYPE html>
<html lang="en">
...

This is not an issue or something that asks for help. Just share a case. It doesn't require a feedback, also.

[slorber]

yarn start is a dev server, not a production host

You get a 404 on a production host (or you should configure it if you don't)

curl -i https://docusaurus.io/api/auth/me

[mickmcg]

I just realized we had lost our custom 404 page, possibly since upgrading to Docuraurus 3.x

I tried the same steps as previously npm run swizzle @docusaurus/theme-classic NotFound and saw 2 options JavaScipt/TypeScript so I said JavaScript and then 2 options after that for swizzle action Wrap/Eject and I tried both when I customise the resulting /src/theme/NotFound/Content/index.js file I don't see my changes picked up.

[mickmcg]

Please ignore my message above, it is working now. Don't know why it suddenly started working, maybe restarting the application although pretty sure I already did that more than once before posting so one of life's unexplained mysteries 😄

[slorber]

This is probably due to the fact that swizzle does not support hot reload properly (#10238)