Why are Bookmarks a deprecated feature?

I don’t understand why bookmarks are deprecated as they are the only way apart from a document id to retrieve a universally unique document. UIDs are great, but they are only unique to a specific type/language.

If you have a project where nearly everything is a “page” type (Because slices have your back for content). How do you route to a specific document at a permanent url? Your home page is a prime example of this - it’s just a page like everything else, but how do you compute which one the home page is without having bookmarks as a mechanism to identify it?

Will the bookmark feature be removed in future releases of the writing room?

Hey George,

Welcome to the community!

This sounds like something that could be solved with the link resolver. I have a project that follows a similar structure, for which I create the link resolver based off of the uid and tags:

export default function (doc) {
  if (doc.isBroken) {
    return '/not-found'
  if (doc.uid === 'home') {
    return '/'
  if (doc.uid === 'documentation') {
    return `/${doc.uid}`
  if (
  ) {
    return `/documentation/${doc.uid}`
  if (
  ) {
    return `/blog/${doc.uid}`
  return '/not-found'

You can see the full list of fields available in the link resolver here:

Hopefully this will help.

Otherwise in regards to whether bookmarks will be remove or if they are safe to use? I don’t know, I’ll need some help from the @features-team for that one. We’ll update you here once we have more info.


Hello @Phil. Thank you for your answer.

I don’t really have a problem that needs solving and I’m comfortable writing and consuming a link resolver.

To me, bookmarks are not just about routing, they are about having a stable and unique string you can use to get specific documents that you care about.

Uids can be changed by the user whereas id’s can not and bookmarks are effectively a much easier way of pointing to a single unique document.

I’m aware the you can retrieve documents by old uid’s if they change, but this is an undocumented feature (AFAIK). Also, retrieving documents by uid means you must also know in advance the type and the language of the document.

Perhaps a good example is a content managed 404. Without a bookmark to point at a single doc, I would have to hard-code the type, language and uid of the 404 page in order to query the api for the correct result. With a bookmark, it’s just one string that tells me which document to retrieve.

My opinion is that it would be remiss to remove the feature as it has valid use-cases.



Hey @gsteel,

Thanks for the feedback. We pushed a while ago the singleton custom type and figured out that this feature was a better answer than the bookmark feature for use cases like Homepage, navigation, 404, etc.

Maybe we missed something, could you give us a better view on why / how singleton types are not the right solution in your opinion?

Thanks a lot

Hi @renaud,
IMO, the type here is an ‘error-page’ - I might have an error page for 404, 403, 500 etc. Rather than making a single type for each flavour of error, I’d want to use the same type with different content. I might also have versions of 404s for different contexts or languages and the bookmarked one is how you’d find the translations. If I use a single for each error, when my document structure changes, I’d have to update all of those types. I don’t dispute the usefulness of single types but they don’t provide the ability to zero in on one document amongst many of the same type.

There’s a few ways I can imagine that you could replicate bookmarks using a custom single and linking documents, but that’s project specific. Having bookmarks supported by the api means fewer requests and greater reliability.

Just for my understanding, if we improve this process of updating different custom types, will using singleton still be an issue?

It’s difficult for me to say. Using many different types just feels wrong to me. (Though a write api for custom types would be awesome :tada:)

Typically, I will map a document-type to a specific template, or route, or a type in my own domain. This tends to be a 1-to-1 mapping. It wouldn’t be the end of the world to have to repeat this mapping, or change the way things work so that many types render to the same template, or map to the same object type.

Bookmarks are very convenient to me. Is the feature holding you back from implementing other things?

Also, with bookmarks you can have multiple versions of a document for the same purpose and choose when to change where a bookmark points as the developer as opposed to the writer - this might be a moot point, but as a contrived example, maybe you have a document for user configuration and using a release and a single type is not convenient for some reason.

This is being tracked as an open feature request. Though we are moving in a different direction that bookmarks, we'll have updates on what this means soon. :slight_smile:

If you have another use-case for this feature, you can 'Flag' this topic to reopen. Please use the :heart: button to show your support for the feature and check out our Feature Request Guidelines.