Redirect a moved page with a hash file

What you'll see

A page is moved, renamed or merged into another page – a service page moves into a new topic folder, two competing pages are consolidated, or a document is replaced by a hub. The old URL is linked from other sites, bookmarked and indexed by search engines, so it must keep working and pass its ranking on to the new address.

Docly has no redirect table in the site configuration, so the redirect has to live at the old path itself.

What's actually happening

docly.redirect(url) ends the request with HTTP 301 Moved Permanently and an absolute Location header (a relative target such as /portaler is expanded to https://your-domain/portaler). A 301 is what search engines expect for a permanent move: they transfer the old URL's signals to the target and replace it in the index.

Unlike ordinary hash output, the redirect is not frozen by the hash cache (see Hash files are cached). Verified on a live site: the file answered 301 on every request, and after changing the target in the file the next request – with no cache-busting query string – already went to the new target.

The function takes one argument. Verified: #docly.redirect("/portaler", 301)# returns 200 with an empty body and no Location header – the visitor gets a blank page and search engines see a live, empty page. There is no way to choose 302; the redirect is always permanent.

What to do

Do – one line, one argument, at the old path:

#docly.redirect("/portaler/salgsportal")#

Save it with the same name as the old page so the URL matches – for /tjenester/Salgsportaler that is tjenester/Salgsportaler.hash.

Don't – a second argument:

#docly.redirect("/portaler/salgsportal", 301)#   <!-- 200, blank page, no redirect -->

Checklist when moving a page:

• If the old URL was served by a document (Salgsportaler.docly), take a copy with docly get --raw and delete it before creating the .hash – a document and a hash file with the same name compete for the URL.
• Folder listings built with docly.getFiles() now also return the redirect file. Filter on fileschema (see getFiles returns every file in the folder), or the redirect shows up as an empty card or menu item.
• Remove the old URL from the sitemap and add the new one. A sitemap must not list URLs that redirect.
• Update internal links to point straight at the new URL. The redirect is for the outside world; internal links through a 301 cost an extra round trip.
• Verify with curl -I https://your-domain/old-url: expect 301 and the right Location.

To move a page into a folder of the same name (a file kunstig-intelligens.hash becoming the folder kunstig-intelligens/), no redirect file is needed – see A folder takes precedence over a file with the same name.