Adding Documentation for AEM Components

4 min readAug 31, 2021

Documentation is one of the important key processes when it comes to delivering any kind of software functionality. Meanwhile, It is a technical write-up that is helpful from a developer’s perspective. It contains technical details like how to configure the module to show certain functionality otherwise it is difficult for the new developers to understand the whole process. Explaining the whole functionality is a time-consuming procedure instead one can share a technical document that covers actual functionality.

Most of the time, We provide technical documentation to AEM Content Authors when it comes to authoring the component. It is helpful for AEM authors to understand & authoring the functionality of components. Ordinarily, we see the help (?) icon on the component dialog which contains the help path of respective component documentation. On click, it redirects to Adobe’s AEM Documentation URL. But, what if we want to provide the documentation for our custom component? Most of us are not aware of how to achieve this functionality in AEM. But yes, We do have such AEM OOTB functionality for providing component documentation.

You can see the list of all components available in AEM here.

Go to AEM Start Menu > Tools > General > Select Component Option.
Direct URL:http://localhost:4502/libs/wcm/core/content/sites/components.html
Click on any of the components. This will open a new window box that will show the component-related information on the following tabs.

Properties — Title, icon, Group, Description, Resource Type, etc.
Policies — This will show the list of component policies based on templates.
Live Usage — This will show the actual page path where a component has been configured.
Documentation -?

We can enable the documentation tab by following some simple steps.

Adding Component Documentation

First of all, Open the CRXDE console http://localhost:4502/crx/de/index.jsp
Go to the component path. example - /apps/<project-name>/components/general
Now create a new markdown file inside the component with the name README.md.
Now add the following sample markdown text into README.md file.

5. Now, go to http://localhost:4502/libs/wcm/core/content/sites/components.html and select Title Component from the list with a valid component group.
You will notice the following output.

6. Now copy the URL from the address bar. In my case, URL will be /mnt/overlay/wcm/core/content/sites/components/details.html/apps/Suraj/title

7. Go to the component inside CRXDE Lite > cq:dialog and set the helpPath property and set the value from the above-copied path.
The code should look as follow.

Sample XML Code:

8. Now allow & add the component to the page, Open the Dialog and Click on the Help (?) icon.

You will see the following component details window

Steps to set Documentation as Default Active Tab

In order to show up documentation as the default active tab when the author clicks on the Help (?) icon, We need to overlay the AEM’s certain functionality. Just follow certain steps.

Go to CRXDE Lite Console http://localhost:4502/crx/de/index.jsp
Go to /libs/wcm/core/content/sites/components/details/jcr:content/content/single/content/items/content/items/tabs/items/documentation
Right-Click on the documentation node & Select the Overlay Node option.
Set the following properties on the Overlay Node dialog and Click on OK.
Path: /libs/wcm/core/content/sites/components/details/jcr:content/content/single/content/items/content/items/tabs/items/documentation
Overlay Location: /apps/
Match Node Types: Checked

4. Now go to overlayed path inside /apps folder
/apps/wcm/core/content/sites/components/details/jcr:content/content/single/content/items/content/items/tabs/items/documentation Click on documentation Node and set following property
sling:orderBefore (String) : fixedColumnContainer