Moving, Renaming, and Reorganizing 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:

• Links to or from the affected article.
• Redirects – for changes that affect experienceleague.adobe.com URLs

Key concepts

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

Understanding 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.)

Checking for 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.

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

• Search for: old-directory-name/
• Replace with: new-folder-name/

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.

• Search for: old-filename.md
• Replace with: new-filename.md

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

Adding 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.

Moving, renaming, and deleting 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.

Renaming 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.

Moving 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:

• Links that jump from other files to the moved file
• Relative links (links that start with ../) that jump from the moved file to other files
• Links to images and other files in the assets folder

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

Deleting or renaming a Markdown file

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

Renaming 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.

Restructuring the TOC

Learn which changes in the TOC require redirects.

Renaming 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.

Renaming 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.

Moving 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.