Slugs: Best practices

Introduction

A slug is a unique, static address for documents on the SignalWire docs site. Slugs are used to build each page's URL.

Never change slugs!

Caution

Slugs should be changed as little as possible to avoid broken links and disrupted SEO.

Pages on the docs site are be indexed by search engines based on their unique slug. It might also have been posted on forums and on social media, or have been referenced in our blogs and other articles inside the documentation.

When you change a slug, all of those links become useless, including all the helpful forum posts. New Google searches will lead to the "content not found" page. In addition to looking unprofessional, search engines deprioritize websites that lead frequently to 404s.

So if you are creating new content, take great care when picking a slug. It will be the unique and permanent address for your article.

Create a slug

All docs have a direct URL address. For example: https://developer.signalwire.com/sdks/reference/swml/introduction

This URL is automatically generated based on the path of the doc - in other words, where you have placed your Markdown file in the directory structure.

This automatic behavior can be overridden with the slug property in the front-matter. For example, if you wanted the SWML introduction page to exist rather at https://developer.signalwire.com/swml/intro, you could edit the front-matter of the introduction file:

---
title: Introduction to SWML
slug: /swml/intro
---

# Introduction to SWML

SignalWire Markup Language (SWML) lets you write Relay applications using simple statements in a YAML or a JSON document.

...

In general slugs should be indicative of the hierarchy of your article, its type, and its general description.

---

If you must change slugs:

In rare occasions when you must change a slug, the following checklist makes sure there aren't any loose ends:

1. Add nginx redirects to the provisioning/nginx/redirects.map file

Our docs use the nginx map directive to redirect old slug to the new slug. This makes sure that people with the old link will still get redirected to the new page. This also ensures that search engines understand that the URL has permanently changed, and update their database.

2. Validate your redirects

Since the redirects.map file is a part of the nginx server configuration, any bugs or typos in that file will cause it to fail build and deploy.

❌ Redirects won't work when locally developing with npm run start

❌ Redirects won't work on the Netlify deploy previews

✅ Redirects will work when locally running the docker container

✅ Redirects will work once merged to main

Which means that any bugs that might be present in the redirects.map file won't be noticed during development.

To ensure your redirects are working, build and run the docker container each time you change the redirects.map file. Automatic checks will automatically flag dead links during the docker build stage.

But running it on your browser and manually testing the links each time is still extremely important. Several subtle bugs won't be caught by the automated checks. Nginx configuration is powerful and flexible, which makes it very easy to cause unintended effects.

docker build -t swdocs .
docker run -d -p 80:80 --name swdocs_run swdocs
open http://localhost # for mac

Or run as a single command like so:

docker build -t swdocs . && docker run -d -p 80:80 --name swdocs_run swdocs && open http://localhost

Rebuild the docker image each time you change the redirects.map file.