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 basically three 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 ghosting or 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. And let’s go over ghosting, which is a made-up term.
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 commit content to the master branch, the Markdown files go through the pipeline into AEM. When you make certain changes such as renaming a file or moving an article to a different section in the TOC, the system leaves the article active on
docs.adobe.com, but there is no longer a source file associated with that published article. We call this ghosting (or orphaning).
If you have ghosted files in your repo, contact the SSE team. We have a fix to remove the ghosts. Run the removeGhosts job in Jenkins, as described later. It removes all ghosted files and gives a list of fixes that you can use for submitting redirects.
Example 1: When you rename a file
Suppose I renamed a file from
reference/user-guides.md. When I look at my structure in AEM author, I would see
user-guides but not
However, if the old
examples article was activated, that URL will remain active. There are now two files on docs.adobe.com with the same content, but only one file in AEM.
There is no longer an
examples.html page in AEM to edit or deactivate. The
examples source file is ghosted in AEM. It will show up in search results.
Example 2: When you rename a TOC ID
Let’s suppose you rename a user guide ID or parent section ID in the TOC.md file. For example, you might change
When you do this, you’ll end up with two different sections in your AEM structure.
In this case, the articles in the old
workflow folder are still active on docs.adobe.com but ghosted in AEM. The new
workflow-tips folder is the new source of truth.
To see how to avoid or clean up ghosting, see Working with ghosted files.
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
reference/user-guides.md. Here’s how I avoided broken links.
Whenever you make a change that results in a URL change, such as renaming a file or making certain changes in the TOC, the previous article location is ghosted, as described earlier on this page. If ghosting occurs, follow these instructions to do clean-up.
Go to Jenkins and sign in using your LDAP account.
Search for the removeGhosts job and run it.
Click the Build with Parameters option.
Specify the details of your repo.
If you want see a list of ghosted files without removing them, select the REPORT_ONLY option.
Run the removeGhosts job.
When the job is complete, open the job and click Console Output to view the list of ghosted files.
If necessary, submit a redirect request.
If you experience problems with ghosted files, contact the SSE team or post to the sccm-assistance channel in Slack.
If the file has been pushed live to docs.adobe.com (and possibly linked to or bookmarked), account for redirects.
This section covers the consequences of renaming and removing files and folders in Git. Let’s start with the easy ones first.
If you rename a folder in Git, you don’t have to worry about redirects or ghosting. You just need to avoid broken links. 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 or ghosting. 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 ghosting or redirect issues.
If you need to rename a repo, contact the SSE team.
Learn which changes in the TOC require redirects and ghosting.
Renaming the link text in the TOC has no effect on links, redirects, or ghosting. 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 and ghosting to occur.