Sitemap (theoretical definition)

If your website is composed of pages, a sitemap is a structure in which those pages are arranged. It defines which page is a root, or 'a homepage'. A sitemap also defines parent-children relationships - if you have a blog then "blog listing page" is a parent of all the "blog posts". It's probably not surprising or novel knowledge for you but at least now we're on the same page (pun intended).

Is sitemap just sitemap.xml?

No. Sitemap.xml is a way to tell (mostly) Google which pages exist on your page so that it can efficiently scan and index your website without a need to crawl it to discover all the links.

So what is a sitemap (practical definition)?

In this post, "a sitemap" is rather a model that holds the structure of the website. In technical terms - taking Object-Oriented approach - it might be an object of a class:

class Sitemap {
    // some way to store all the pages here.
    // Maybe a map???
    private pages: Map<FullPagePath, Page> = new Map()

    // ---
    // And some methods to retrieve all the information

    // Maybe??
    getHomepage(): Page

    // Probably more methods here???
}

Do you need a sitemap at all?

The other (important) question is if you need a sitemap. Or rather, if you need a flexible, dynamic sitemap model because every website has a sitemap - it may be small, hardcoded, and implicit but it's there.

If you create a simple personal website or portfolio site with a handful of pages, you're probably better off with hard-coding the sitemap in code. To make things nicer, you can have a central place where a sitemap is defined, like so:

const sitemap = {
    homepage: "/",
    blogRoot: "/blog",
    contact: "/contact",
    privacyPolicy: "/privacy-policy"
}

and use it in your code to generate links (React-example):

<a href={sitemap.contact}>Contact me</a>

This way, the odds of making a typo in a link are close to zero (especially if you use TypeScript) and you can easily change all the links in one central place (DRY, they call it).

In this case, you (probably) don't need an explicit sitemap.

When do you need a sitemap?

Things get much more complex if we need more features. These might include a need support:

• multi-language (English, German, Spanish) or even multi-locale (English-UK, English-US, German-Germany, German-Austria) website,
• integration with an external content source (CMS, and not local filesystem),
• dynamic sitemap structure (generated every time something changes in external system),
• instant update and preview capabilities (without rebuilding a whole website from scratch),
• integration with other platforms (like eCommerce products, store locators, etc.),
• deeply nested site hierarchies (like /en/products/product-category/subcategory/product/product-variant) with localized URLs/slugs,
• HTTP redirects and aliases,
• horizontal scaling capabilities (infrastructure).

Now, the problem is much more complicated. A simple const sitemap = ... won't do the trick.

Sitemap in Contentful

Contentful focuses on enabling businesses to tailor content models to their exact needs. It provides a convenient UI to create custom content elements and extend them with new fields without any of the developer's help. On top of that, it comes with a powerful App Framework and APIs developers can use to create bespoke solutions using a universal platform of Contentful - managed, run, maintained, and extended as SaaS.

One of Contentful's defining features is having references between content entries as a first-class citizen. Contentful tracks all the connections between content entries and makes it easy to view existing relationships, either in UI or programmatically. That's really great.

On the other hand, there's no default sitemap solution in Contentful. Every business using Contentful needs to develop its own sitemap model. But how hard can it be?

Creating your own sitemap in Contentful

Possibility to create your own content types, reference-tracking support, and custom UI built with App Framework? And don't forget you have REST API, GraphQL API, and SDKs to use. It shouldn't be any hard to create your own sitemap, right?

It's actually not very hard... until you try.

Problems with creating your own Contentful sitemap

It doesn't sound that complex at first but the number of challenges starts to emerge if you actually make your attempt. Questions might include:

• How to model content?
• How to efficiently use APIs without hitting complexity limits?
• How to provide the best TTFB (time-to-first-byte) without (over-)caching?
• How to instantly update the current state based on changes in Contentful?
• Preview and published modes support

aaaand many more (ping me if you're interested).

Wrap up

In this post, we covered what a sitemap is, when you might need one, and what are the challenges for implementing your own sitemap for Contentful. In the next post on this topic, we'll cover how it can be solved. Stay tuned!