For a team or org

You describe your AEM estate once, host that description somewhere your team’s browsers can reach, and send two links. Nobody else opens a YAML file, and when your environments change you edit the hosted files once.

1. Get it right for yourself first

   Do the individual setup before you package anything. The configuration you are about to hand out is the one you have already proved on your own machine.

2. Write the configuration

   Four files drive everything, and you can see and edit all of them under Configuration in the extension settings.

   File	What it controls	Do you change it?
   environment-config.yaml	Which hosts are AEM authors, which are public sites, and how URLs map between them	Yes. This is the job
   link-matrix.yaml	Which quick links appear on each screen	Optional
   message-matrix.yaml	Contextual warnings and tips	Optional
   region-map.yaml	How the toolbar tells one AEM screen from another	Only for a heavily customised author UI

   A realistic environment-config.yaml for two sites across three environments:

   authors:
     prod:  [author.acme.com]
     stage: [author-stage.acme.com]
     local: [http://localhost:4502]
   
   sites:
     acme:
       stripPath: /en
       public:
         prod:  [www.acme.com]
         stage: [stage.acme.com]
         local: [http://localhost:3000]
   
     acme-blog:
       public:
         prod:  [blog.acme.com]
   
   environments:
     prod:
       color: "#D32F2F"
     stage:
       color: "#FF8F00"
     local:
       color: "#1976D2"

   The easiest way to author this is to build it through the extension UI first, then copy the YAML out of the editors under Configuration. Configuration is the reference for every option, and worked examples show four estates end to end.

3. Put it in a package

   A package is a folder holding those four files plus a manifest whose filename ends in .aem-toolbar.json. That suffix is what makes the extension offer to import it.

   aem-toolbar-config/
     acme.aem-toolbar.json
     environment-config.yaml
     link-matrix.yaml
     message-matrix.yaml
     region-map.yaml

   acme.aem-toolbar.json

   {
     "name": "Acme AEM Toolbar Config",
     "version": "1.0.0",
     "description": "Toolbar configuration for Acme's AEM environments",
     "author": "Acme Web Team",
     "configs": {
       "environmentConfig": "./environment-config.yaml",
       "linkMatrix": "./link-matrix.yaml",
       "messageMatrix": "./message-matrix.yaml",
       "regionMap": "./region-map.yaml"
     }
   }

   name, version and configs are required and the rest is display only. Config paths can be relative to the manifest or absolute URLs. Every file is fetched and validated before anything is stored, so a package can never be half imported: one bad file rejects the whole thing and nothing changes.

   Download the sample package to start from a folder that already works, or test yours before hosting it by saving the folder locally and opening the manifest in Chrome over a file:/// URL.

4. Host it

   Four requirements, and the third is the one that catches people out.

   • HTTPS. The extension refuses packages served over plain HTTP, because the package decides which sites the toolbar activates on. Localhost is the exception.
   • Reachable from your team’s browsers. That is all. An intranet-only or VPN-only server is fine, because every fetch happens from each user’s own machine rather than from any server of ours. Worked example 4 spells out why.
   • No interactive login in front of the files. The first import happens while the user is looking at the page, but the scheduled refresh is a plain fetch with no login flow. A package behind an SSO redirect imports once and then silently stops updating. Test the URL in an incognito window: if you get a login screen, so does the refresh.
   • A stable URL. It is baked into everyone’s settings, so pick one you will not need to move.

   An internal static server, a cloud bucket with static hosting, GitHub Pages if the hostnames in your config are not sensitive, or your AEM publish instance itself all work.

5. Send two links

   Each person installs the extension, clicks your package URL, and presses import in the dialog that appears in the page. That is the whole setup for everyone who is not you.

   We have set up a browser extension that adds shortcuts to AEM: jump between the editor and the live page, see which environment you are in, and get a warning before the common mistakes.

   1. Install it: https://chromewebstore.google.com/detail/aem-editorial-toolbar/dadkbhhjkoakmjjgbmfccbadkdcjciie
   2. Then open this link and press Import: https://intranet.acme.com/aem-toolbar/acme.aem-toolbar.json

   That is it. It updates itself when we change the configuration.

   If click-to-import does not suit your environment, the manual equivalent is Full Extension Settings, then Configuration, then Connection: paste the manifest URL, set a refresh interval, and press Fetch Package & Apply All Now.

Changing it later

Edit the hosted YAML, bump version in the manifest, and stop. Every installation re-fetches on its own schedule, four hours by default, and anyone in a hurry can force it from Connection.

How personal settings and your package fit together

Each of the four files resolves in the same order: a user’s own override first, then your hosted package, then the defaults the extension ships with.

So a person can add their own links and messages on top of your configuration without breaking it. When your package changes a file somebody has overridden personally, they get a notice with a diff and choose which version to keep. Worth telling the team about: the Links & Messages tab builds custom links and warnings with no YAML, and every one of them has a Share button that copies it as JSON for a colleague to import. The same tab has Generate with AI, which writes out a prompt describing the rule format for you to paste into whichever AI assistant you already use, and you import the JSON it hands back. It only writes the prompt: the extension makes no AI request of its own.

For your IT reviewer

• Why access to all websites? AEM runs on customer-chosen domains, so the extension cannot declare them ahead of time. It reads the page URL to decide whether the current host is one the user configured. On any other host it does nothing beyond that check. The one other thing that loads anywhere is the package importer, on any URL containing .aem-toolbar.json: that is how a configuration package is imported, and all it does is read the page’s own text and offer an import dialog that has to be accepted before anything is stored.
• No data collection. The extension makes no request to its author or to any third party, and there is no analytics or telemetry of any kind.
• Outbound requests are user-configured only. The package URL if one is set, and requests to the user’s own AEM instances: the logged-in check, the DAM lookup, the content fragments an author page uses, and the page’s own properties when a rule needs them. Those carry the editor’s existing AEM session and go nowhere else.
• One page path is remembered locally. So the options page can offer a property picker, the content path of the last author page opened is kept in the user’s own browser profile and overwritten each time. It is one page, not a history, and there is a button to forget it.
• No remote code. The package is YAML and JSON data, and nothing downloaded is ever executed: the extension uses no eval() and no remote script execution. A few of its own screens, such as the import prompt and the asset hover overlay, are built as HTML strings, and every value read out of a package is HTML-escaped before it reaches the page.

The privacy policy is the full statement, and the FAQ answers the rest.