Change Site Root

The AEM Boilerplate project assumes that the document root is situated at the project's root. However, if your project begins on a subpage of another site, it is necessary to adjust the site root to align with the path.

Modifying the site root involves relocating various files and folders in both the document storage and code repository, along with making code updates where paths are referenced. The new folder should have identical names in both the document storage and GitHub and it should also correspond to the name in the path where the site will be located.

That means if the site location will be at https://yourdomain.com/topics then the recommended folder name would be topics.

Note: If you plan to move multiple sections of the site over at different times, then follow the “Code Changes” section but move it to a unique folder name (that does not clash with any existing paths you may already have) like aemedge so that it is not tied to just one section of the site content.

Content Changes

To update your document storage, follow these steps:

• Create the new root folder in document storage
• Move all items into the new folder, excluding the following:
  • .helix folder
  • redirects(.xslx)
  • block-library folder (if it exists)
• Publish the relocated files in their new location

IMPORTANT: In case any files in the previous location have been previewed or published, it is advisable to first delete the published content. These outdated files can be seen as duplicate content, will probably not get updates from authors and confuse visitors who stumble upon them.

Code Changes

To update your project code, follow these steps:

• Create the new root folder in your code, using the identical folder name used in document storage
• Move the following folders into the new folder:
  • blocks
  • fonts
  • icons
  • scripts
  • styles
• Update the paths to styles and scripts in the following files:
  • head.html
  • 404.html
• In font.css, update the paths to your font files in the src properties of @font-face definitions
  • Since the fonts folder was moved, these paths may need to be updated
• In package.json, update the lint:css path for both blocks and styles

Note: window.hlx.codeBasePath is set automatically by the AEM Boilerplate code, so you do not need to explicitly define it in your scripts.js.

Other things to look for

Depending on your stage of development, you might have to identify additional instances where paths are referenced.

• Look for fetchPlaceholders() calls. Pass your folder name as an argument
  • e.g. fetchPlaceholders('/your-folder-name')
• Look for loadCSS() or loadBlock() calls
  • In some cases the window.hlx.codeBasePath may not have been used
• Look for HTML snippets that are included in blocks
  • You can incorporate HTML snippets into your custom code. If the snippet contains relative paths, it may be necessary to update them
• Look for any custom Git workflows
  • In a workflow, file relocations may occur, necessitating the correction of paths as needed