Getting Started - Developer Tutorial
This tutorial will get you up-and-running with a new Adobe Experience Manager (AEM) project. In ten to twenty minutes, you will have created your own site and be able to create, preview, and publish your own content, styling, and add new blocks.
- You have a GitHub account, and understand Git basics.
- You have a Google account.
- You have Node/
npminstalled for local development.
This tutorial uses macOS, Chrome, and Visual Studio Code as the development environment and the screenshots and instructions reflect that setup. You can use a different operating system, browser, and code editor, but the UI you see and steps you must take may vary accordingly.
Get started with the boilerplate repository template
The fastest and easiest way to get started following AEM best practices is to create your repository using the Boilerplate GitHub repository as a template.
Just click the
Use this template button and select
Create a new repository, and select where you want to create this repository.
We recommend that the repository is set to
The only remaining step in GitHub is to install the AEM Code Sync GitHub App on your repository by visiting this link: https://github.com/apps/aem-code-sync/installations/new
Repository access settings of the AEM Code Sync App, make sure you select
Only select Repositories (not
All Repositories). Then select your newly created repository, and click
Note: If you are using Github Enterprise with IP filtering, you can add the following IP to the allow list:
Congratulations! You have a new website running on
https://<branch>--<repo>--<owner>.hlx.page/ In the example above that’s
Link your own content source using Google Drive
In your fork of the Boilerplate GitHub repository, the site points to an existing content source in Google Drive. See this folder for some example content.
This content is read-only, but it can be copied into your Google Drive folder to serve as a starting point.
To author your own content, create a folder in your own Google Drive and share the folder with the Adobe Experience Manager user (
A good way to start authoring your own content is to copy
footer from the sample content and familiarize yourself with the content structure.
footer are not changed frequently in a project and have a special structure. Most of the files in a project look more similar to
Open the files and copy/paste the entire content into corresponding files in your own Google Drive. You can also download the files via
Download All or download individual files. However, remember to convert the downloaded
.docx files back into native Google Docs, when you upload them to your folder in your Google Drive.
Now that you have your content, you need to connect that content to your GitHub repo. You do this by changing the reference in
fstab.yaml in your GitHub repo to the folder you just shared.
Copy/paste the folder URL from your Google Drive to
Be aware that after you make that change, you will see
404 not found errors as your content has not been previewed yet. Please refer to the next section to see how to start authoring and previewing your content. If you copied over
footer all three of those are separate documents with their own preview and publish cycles, so make sure you preview (and publish) all of them if needed.
Commit your changes and you have hooked up your own content source to your website.
Preview and publish your content
After completing the last step, your new content source is not empty, but no content has been promoted to the
live stages, which means your website serves 404s.
To preview content, an author has to install the Sidekick Chrome extension. Find the Chrome extension here.
After adding the extension to Chrome, don’t forget to pin it, this will make it easier to find it.
To setup the Chrome extension, go to your previously shared Google Drive folder and click the extension icon in the browser toolbar and select
Add this project.
As soon as the extension is installed and your project is added, you are ready to preview and publish your content from your Google Drive.
Select all three docs and activate the AEM Sidekick by clicking on your pinned extension. A new toolbar will appear. Clicking the
publish buttons will trigger the corresponding operation.
index doc and make some changes. Activate the Sidekick by clicking on your pinned extension and then click the
Preview button which will trigger the preview operation and open a new tab with the preview rendition of the content.
Start developing styling and functionality
To get started with development, it is easiest to install the AEM Command Line Interface (CLI) and clone your repo locally through using the following.
npm install -g @adobe/aem-cli git clone https://github.com/<owner>/<repo>
From there change into your project folder and start your local dev environment using the following.
cd <repo> aem up
http://localhost:3000/ and you are ready to make changes.
A good place to start is in the
blocks folder which is where most of the styling and code lives for a project. Simply make a change in a
.js and you should see the changes in your browser immediately.
Once you are are ready to push your changes, simply use Git to add, commit, and push and your code to your preview (
https://<branch>--<repo>--<owner>.hlx.page/) and production (
That’s it, you made it! Congrats, your first site is up and running. If you need help in the tutorial, please join our Discord channel.