Move, rename, and reorganize content

What happens when you rename a folder or file in Git? What happens when you shuffle around content in the TOC? Which changes affect page URLs? What’s the best way to avoid broken links to files and images?

There are two things you need to consider when moving, renaming, or deleting content in Git or the TOC.md file:

Key concepts

Let’s go over how URLs are generated so that you know which changes can cause the need for redirects.

Understand how URLs are generated

You should understand which changes in Git will affect URLs.

URLs are determined by the Git repo name, the Markdown filename, and the properties in the TOC.md file.

If you rename either a Markdown file or the repository name, you’ll affect the URL.

Changes to directory names in Git will not affect URLs. (They can affect links, but that’s a different matter.)

Check for broken links broken-links

When you rename a folder or rename, delete, or move a file, you’ll want to do a global search and replace in all files.

Rename a folder: Use the Replace in Files feature in Visual Studio Code to make changes like this:

Adding the trailing / helps make sure that you locate the directory name in a link and not a Markdown file.

Renaming, deleting, or moving files: To check for links, do a global search and replace to make changes like this:

In this example, I renamed the workflow folder to workflow-magic in Git. Here’s how I avoided broken links.

In this example, I renamed examples.md as user-guides.md. Here’s how I avoided broken links.

Add redirects redirects

If the file has been pushed live to experienceleague.adobe.com (and possibly linked to or bookmarked), account for redirects. If you move an entire guide or section, use a wildcard redirect. For individual articles, edit the redirects.csv file in your repo.

See Redirects.

Move, rename, and delete files and folders in Git

This section covers the consequences of renaming and removing files and folders in Git. Let’s start with the easy ones first.

Rename a folder in Git

If you rename a folder in Git, you just need to avoid broken links. URLs are not affected. See Checking for broken links.

Move a Markdown file in Git

Before you move a Markdown file to a different folder in Git, keep in mind that it usually isn’t necessary. The TOC.md file controls the user guide structure, not the Git location.

If you decide you want to move a Markdown file to a different folder in Git, you don’t have to worry about redirects. You just need to avoid the following link problems:

If you move a Markdown file in Git, account for these linking issues.

Delete or rename a Markdown file

When you delete a Markdown file, you need to account for broken links and redirects.

Rename the repo

If you need to rename a repo with live content, contact the SSE team. There’s a checklist of tasks to go through.

Restructure the TOC

Learn which changes in the TOC require redirects.

Rename the link text in the TOC

Renaming the link text in the TOC has no effect on links or redirects. It only affects what appears in the left rail of the user guide.

Rename the section IDs in the TOC

Don’t do this unless you really need to. If you think you need to rename a section ID, think again. If you really need to do it, add redirects for all the articles in that section.

Move links from one section of the TOC to another.

Moving articles in the TOC to a different section of the TOC will cause URLs to change.