Getting started with Helix - Developer Tutorial
This tutorial should have you up and running with your AEM Helix projects in 10 - 20 minutes to a place where you can create, preview and publish your own content and create your styling and add new blocks.
Pre-requisites:
- You have a github account, and understand git basics
- You have a google account
- You understand the basic HTML, CSS and JavaScript
- Have node/npm installed for local development
This tutorial assumes that you are using MacOS, Chrome and Visual Studio Code as part of your development environment.
Of course you can use a different operating system, browser and code editor, but you will see that screenshots and default instructions are most compatible with that setup.
Get started with the Helix Boilerplate Repository Template
The fastest and easiest way to get started with all the best practices in AEM Helix is to create your repo using the helix boilerplate github repo as a template:
https://github.com/adobe/helix-project-boilerplate
Just click the Use this Template button, and select where you want to create this repo.
We recommend that the repo stays public by default.
The only step that’s left to get you all setup in github is to install the Helix Bot on your repo, by visiting this link: https://github.com/apps/helix-bot/installations/new
Make sure you select Only select Repositories (NOT All Repositories).
Select your newly created repo, and hit save.
Congrats you are done, and have a new website running on https://<branch>--<repo>--<owner>.aem.page/ in the above example that’s https://main--my-website--davidnuescheler.aem.page/
Link your own content source (Google Drive)
In your fork the content points to an existing content source in gdrive, see this folder with some example content in it.
This content is read-only, but it can be copied into your google drive folder.
To get started creating your own content, create a folder in your gdrive and share the folder with the Helix Bot (helix@adobe.com).
A good way to get started is to copy index, nav and footer from the sample content to familiarize yourself with the content structure. nav and footer are not changed frequently in a project and have a special structure, most of the files in a helix project look more similar to index.
A good way to copy those files and to familiarize yourself with the structure is to open the files and copy/paste the entire content into your corresponding file. You can also download the files via “Download All” or downloads of individual files, but be mindful to convert the downloaded .docx files back into native google docs, if you upload them to your folder in your google drive.
To complete hooking up your content the only thing left is to tell Helix, where to get the content for the site by changing the reference in fstab.yaml in your github repo to the folder you just shared.
Just copy/paste the folder URL from your google drive to fstab.yaml.
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 preview your content. If you copied over index, nav and 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 completed the steps needed to hook up your own content source.
Preview and Publish your content
After completing your last step, your new content source is possibly not completely empty, but no content has been promoted to the preview or live stages, which means your website should serve blank 404s at this point.
To preview content any author has to install the helix chrome extension or bookmarklet. Find the chrome extension here.
After adding the extension to chrome, don’t forget to pin it.
To setup the chrome extension the easiest path is to go to your github repo, and click “Add Project”
As soon as the extension is installed you are now ready to preview and publish your content from your google drive. Open the index doc and activate the helix 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.
Once on the preview page, you can just press the Publish button which will trigger the publication of the content to the live environment and redirect you to the corresponding URL.
That’s it, you just published your first page with Helix.
Let’s make some changes and republish.
To complete the content of your site go through the same process with the nav and footer documents. After these steps you should have a fully functional website with a header and a footer, with all the content being completely controlled out of your own gdrive.
Start Developing Styling and Functionality
To get started with development, it is easiest to install the helix-cli and clone your repo locally through via…
npm install -g @adobe/helix-cli
git clone https://github.com/<owner>/<repo>
…from there change into your project folder via and start your local dev env via
cd <repo>
hlx up
which will open up http://localhost:3000/ and you are ready to make changes.
A good place to start is the blocks folder which is where most of the styling and code will live for you helix project. Simply make a change in a .css or .js and you should see the changes in your browser immediately.
Once you are are ready to push your changes, simply git add, commit and push and your code is on your preview (https://<branch>--<repo>--<owner>.aem.page/) and production (https://<branch>--<repo>--<owner>.hlx.live/) site.
That’s it, you made it! Congrats, your first Helix site is up and running.