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
NOTE

If you are moving or deleting files as part of the migration clean-up before you push content live, you don’t need to address redirect issues. Just focus on avoiding broken links until your content becomes active and public.

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.

generated urls image

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

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.

rename folder image

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

global replace

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.

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.

IMPORTANT

If you work on the same repo with multiple writers, make sure that you let other writers know about your plans to move, rename, or delete files.

If other writers edit files that you rename, for example, git conflicts will result.

Renaming a folder in Git

If you rename a folder in Git, you just need to avoid broken links. 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.

NOTE

Again, if you are deleting files as part of the migration clean-up before you push content live, you don’t need to address redirect issues.

Renaming the repo

If you need to rename a repo, contact the SSE team.

Restructuring the TOC

Learn which changes in the TOC require redirects.

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 articles in the TOC to a different section of the TOC will cause URLs to change.

On this page