OOTB Documentation for AEM Components | AEM 6.5 | AEMaaCs

As we work on different modules and components in AEM project we end up creating the Component Documentation and hosting it on client’s Confluence or other Documentation tools. Those documents contains technical details like how to configure the module to show certain functionality so that it is easy for new developers to understand the use case of the component.

Usually, we see the help (?) icon on the component dialog which redirects to the help path of respective  Adobe’s AEM Documentation . Let’s see how we can provide the documentation for our custom component or existing OOTB extended components.

You can find the list of components at:

1. Go to AEM Start Menu > Tools > General > Select Component Option. (http://localhost:4502/libs/wcm/core/content/sites/components.html)
2. Click on any of the components. which will show the component information on with following tabs.

• Properties — Title, Group, Description, Resource Type, etc.
• Policies — Show the mapping of component policies based on templates.
• Live Usage — It shows the page path where a component has been configured.
• Documentation – We will use the OOTB Documentation feature to add this Tab.

I am going to use the Accordion Component to record the Documentation.

AEM Component Details
Page

We can enable the Documentation Tab by using below configurations:

1. Open the CRXDE console http://localhost:4502/crx/de/index.jsp
2. Go to the component path. example – /apps/<project-name>/components/content
3. Now create a new file inside the component with the name README.md.
4. Now add the following sample markdown text into README.md file.

# AEM Component Documentation Sample
Lorem Ipsum..

***

## Accordion Component

Accordion component description here.

### Features


It's Features..

### Dialog Properties
  
Dialog Properties descriptions..

### Additional Authoring Documentation
There are no additional authoring document available for this component

5. Go to http://localhost:4502/libs/wcm/core/content/sites/components.html and select Accordion Component from the list with a valid component group. And observe the Documentation Tab with the content recorded.

6. Copy the URL from the address bar. In my case, URL will be /mnt/overlay/wcm/core/content/sites/components/details.html/apps/my-project/components/accordion.

7. Go to the component path in CRXDE > cq:dialog and set the helpPath property and set the value as /mnt/overlay/wcm/core/content/sites/components/details.html/apps/my-project/components/accordion.

8. Now open the component and click on the Help icon to open the Documentation.

How to make Documentations Tab as Default Tab ?

To show up documentation as the default active tab when the author clicks on the Help (?) icon, We will overlay the AEM’s certain functionality.

1. Go to CRXDE Lite Console http://localhost:4502/crx/de/index.jsp
2. Go to /libs/wcm/core/content/sites/components/details/jcr:content/content/single/content/items/content/items/tabs/items/documentation
3. Overalay th documentation node using 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. 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, Set following property on documentation node.
sling:orderBefore (String) : fixedColumnContainer

5. Now reopen the component dialog. Click on the help (?) icon and this will open the following window.

Now we can see Documentation as a default active tab when anyone clicks on the help (?) icon.

Thanks for reading my article.
Happy Coding!!