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:
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.
Let’s go over how URLs are generated so that you know which changes can cause the need for redirects.
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.)
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:
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
user-guides.md. Here’s how I avoided broken links.
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.
This section covers the consequences of renaming and removing files and folders in Git. Let’s start with the easy ones first.
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.
If you rename a folder in Git, you just need to avoid broken links. URLs are not affected. See Checking for broken links.
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:
../) that jump from the moved file to other files
If you move a Markdown file in Git, account for these linking issues.
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.
If you need to rename a repo with live content, contact the SSE team. There’s a checklist of tasks to go through.
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.
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.