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 basically three things you need to consider when moving, renaming, or deleting content in Git or the file.

  • Links to or from the affected article
  • Redirects – for changes that affect URLs
  • Ghosting – the previous file or folder remains in AEM

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.

Key concepts

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.

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

Understanding “ghosting” in AEM

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, 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 to reference/ When I look at my structure in AEM author, I would see user-guides but not examples.

ghosting example image

However, if the old examples article was activated, that URL will remain active. There are now two files on with the same content, but only one file in AEM.

ghosting url image

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 file. For example, you might change {#workflow} to {#workflow-tips}.

ghosting toc image

When you do this, you’ll end up with two different sections in your AEM structure.

ghosting toc result

In this case, the articles in the old workflow folder are still active on 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:

  • 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:
  • Replace with:

global replace

In this example, I renamed as reference/ Here’s how I avoided broken links.

Working with ghosted files

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.

  1. Go to Jenkins and sign in using your LDAP account.

  2. Search for the removeGhosts job and run it.

    remove ghosts search

  3. Click the Build with Parameters option.

  4. Specify the details of your repo.

    remove ghosts settings

    If you want see a list of ghosted files without removing them, select the REPORT_ONLY option.

  5. Run the removeGhosts job.

  6. When the job is complete, open the job and click Console Output to view the list of ghosted files.

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

Adding redirects

If the file has been pushed live to (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.

Renaming a folder in Git

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.

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

  • 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, redirects, and ghosting.


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.

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

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 and ghosting to occur.

On this page