# Links, slugs, and redirects

Every article on your docs site lives at a flat URL:

```text
https://yourproject.clayo.site/articles/your-slug
```

The same path works wherever your docs are served, including a [custom domain](/articles/custom-domain) or a [subpath like yoursite.com/docs](/articles/subpath-hosting). This article covers how slugs are chosen, what happens when they change, and how to link within your docs.

## Where slugs come from

By default, the slug is derived from the article title at first publish: "Invite your team" becomes `invite-your-team`. If you want a specific slug, say so:

```
Create a "Frequently asked questions" article with the slug "faq".
```

Slugs are lowercase, hyphen-separated, and unique within your project.

## Changing a slug is safe

When a published article's slug changes, the old URL is not abandoned. Clayo issues a permanent redirect (HTTP 308) from every previous slug to the current one, forever. Bookmarks, shared links, and search engine results all keep working, and search engines transfer the page's ranking to the new URL.

Retired slugs stay reserved: a slug that once pointed to one article can never be claimed by a different article, so old links can never silently start pointing somewhere wrong.

```
Rename "Getting started with the API" to "API quickstart" and update the slug to match.
```

## Internal links

Link between your own articles with root-relative paths:

```text
See [Invite your team](/articles/invite-your-team) for roles.
```

Root-relative links adapt to wherever the site is served. If your docs later move to `yoursite.com/docs`, the same markdown resolves correctly with no rewriting.

Moving an article to a different collection never changes its URL, so reorganizing your sidebar breaks nothing.

## Heading anchors

Every level 2 through level 4 heading has a stable anchor. Readers get a copy-link button on hover; you can deep-link to a specific answer:

```text
/articles/custom-domain#add-the-dns-records
```

Your agent knows every heading anchor in your project and can cross-link precisely, so requests like "link to the DNS section of the custom domain article" resolve to the right anchor without guesswork.

## Section URLs

Sections have URLs too: `/sections/guides` redirects to the first article in that section. This makes section links safe to share in onboarding emails or app navigation, since they always land on real content. Section slugs stay stable when a section is renamed; see [Organize with sections and collections](/articles/sections-and-collections).