Setting up Content Managed 404 Pages

Fully content managed 404's for your copy writers and site editors

Illustration of a young lady sitting on top of the numbers 404

Custom 404 pages are an opportunity to reorient lost visitors and do more marketing stuff. With WordPress for example, you'd need to edit a theme file by hand to make changes to the content (by default). Primo makes editing the content of your 404 exactly the same experience as changing any other page on your site.

However, to take advantage of custom 404's, you need to provide some configuration so that a single document can be identified in your content repository.

First Step: Create Your Document

The first thing you'll need to do is create and publish your initial 404 page in Prismic.

I like to use a specific document type for all error types (that’s how this repository is setup). I will normally assign an HTTP error code to these documents too so it's easy to find them in code.

Once you've created your custom document type and got the document published, flush the cache manually if the cache-busting web hook is not yet activated.

Explain how to find your 404 page

Next, you need to tell the NotFoundDocumentLocator where to find your 404 document.

There are lots of ways to configure how to find each document, below is an example of finding the first document that matches the type "error" and the uid "my-document-uid".

<?php
// Some config file… perhaps `config/autoload/static-documents.global.php`
return [
    'primo' => [
        'documents' => [
            'my.404' => [
                'type' => 'error',
                'uid'  => 'my-document-uid',
            ],
        ],
    ],
];

You then need to make sure that the unique name is returned as a single document locator from the container. There's a static factory shipped with the skeleton that wraps a finder function so that the document can be fetched lazily only when required. You configure it like this.

<?php
use App\Content\Container\SingleDocumentLocatorStaticFactory;

return [
    'dependencies' => [
        // ... Other dependency config
        'factories' => [
            'my.404' => [SingleDocumentLocatorStaticFactory::class, 'my.404'],
        ],
    ],
];

Finally, configure the NotFoundDocumentLocator so that it knows which document to get.

<?php
return [
    'primo' => [
        'notFound' => [
            'finder' => 'my.404',
        ],
        // … Other config relevant to 'primo' section…
    ],
];