Metadata and tagging

ExL publishing supports a wide variety of metadata parameters. This page provides a complete list, sample usage, and more about metadata and tags.

Which metadata values are required?

Required

The following values are system-required and must be in place (added to metadata.md, TOC.md, or article; or system-generated) for validation to succeed:

  • title (the # title heading is used if title metadata is missing; see Title and description for SEO for guidance)
  • description (validation fails if missing, blank, or null value)
  • solution (validation fails if missing, blank, or null value; dependent on yaml)
  • type (validation fails if blank or null value; defaults to type: Documentation if missing; dependent on yaml)

Recommended and validated against if used

The following metadata is highly recommended and required for ExL to enable or enhance SEO and ExL UI such as search filtering:

  • feature (dependent on yaml)
  • feature-set (dependent on yaml)
  • role (dependent on yaml)
  • level (dependent on yaml)
  • topic (dependent on yaml)
IMPORTANT

Validation will not fail if feature, role, level, or topic is missing. For example, level is primarily used in video tutorials, not documentation, so level can be missing. However, validation will fail if the value is blank or if the value does not match up with an approved yaml value.

If you add this metadata to content, make sure that the value you use matches an approved value. Do not use empty placeholder values, such as feature: , without a value.

Analytics tracking

The following metadata values is currently used by ExL for Analytics tracking, but will likely be replaced in the near future with solution:

  • product (dependent on yaml)
NOTE

See Tags used in ExL for explanations of each metadata value.

Requesting new metadata values

If you need changes or additions to the yaml lists, create a UGP JIRA task, and select Content Tagging as the Component.

How metadata is used in ExL publishing

Metadata and tagging enables ExL to optimize content for presentation, search optimization, analytics reporting, personalizing, and filtering. Some metadata, such as product, solution, and type require specific enumerated values to function consistently and properly.

For example, solution and type are used for search filtering, while product is used exclusively for Omega Analytics metrics. Here are examples showing where metadata values are used in output:

metadata overview

Use appropriate metadata values to ensure consistency and accuracy. Any metadata you specify is passed through to the HTML page, which you can see when you view the page source.

If you want to add new values to existing metadata or if you want to use custom metadata, contact Alva or Bob, or log a UGP Jira ticket (with Content Tagging as the Component).

Where to add required metadata

This section describes how to begin adding metadata and content tags, and which tags are required.

In new articles

For a new article, you must add title and description to the top of your page. For example:

---
title: How do I use segments to compare site sections?
description: How to use segmentation in Adobe Analytics. Learn how to compare news site visitors to other site section visitors.
---

That metadata gives your article an SEO title and description for Google searches. For content optimization, add add tags for feature , role , level, and so on (described below).

The following example shows a wide range of metadata, placed at the top of a typical tutorial article.

metadata example

In the table of Contents

Open the TOC.md and add a metadata that applies to the whole guide.

  • For example, you might add role: Developer to apply to all articles in the guide. If you want to override that value in an article, you could add role: Admin, Developer to the article, as described later.

In the metadata file

Open the metadata.md file and add, for example:

---
cloud: Experience Cloud
solution: Experience Manager, Experience Manager Assets
product: adobe experience manager
role: Business User, Admin, Developer
user-guide-title: Experience Manager 6.5 Assets Guide
---

Important tagging and metadata and guidelines are described below.

Metadata placement and hierarchy

Metadata is applied in three locations (or hierarchy levels). The repository-level metadata (metadata.md) can be overwritten by user-guide-level metadata (TOC.md), which can be overwritten by article-level metadata.

metadata trickle down

  • Repo level: (Optional, highest) At the top of the metadata.md file. This metadata governs all articles in the repo, unless superseded by the TOC or article metadata.
  • TOC level: At the top of the TOC.md file in the user guide directory. TOC metadata governs all articles in a guide, unless superseded by metadata at the article level.
  • Article level: At the top of each article (Markdown) file. Article metadata supersedes metadata at higher levels (TOC and Repo).

If duplicate values exist, the system uses the metadata that lives closest to the content to which the values apply, usually the article. For example, you can specify a solution value (such as solution: Analytics) in the metadata.md file (repo level), and then specify a different solution value for a user guide or article, such as solution: Analytics, Target.

IMPORTANT

Be careful when applying the same metadata fields in both the metadata.md file and TOC.md file, because values in TOC.md overwrite values in metadata.md. For example, if you set index: no in both places and then change it to index: yes in the metadata.md file, no change occurs.

In other words, don’t add the same metadata fields at lower levels unless you want to override the higher value.

Tagging requirements

Metadata tags are required to surface content to customers. Without tags, we cannot make content available to users if they want to filter by, for example, role.

Validation does not fail if tags don’t exist. However, validation fails if the value of these tags does not match the master GitHub yaml lists. If you need to add new values to the yaml lists, log an Experience League UGP JIRA task, using Content Tagging as the component.

Tags used in ExL

Here’s a round-up of ExL tags and how to use them.

Tag Requirement(s) About Capitalization
cloud Used by ExL (not yet enabled) For ExL search and filtering APIs
Example: cloud: Document Cloud.
Cloud values must be title case and use spaces, where applicable, for example, Experience Cloud, Document Cloud. You can add multiple values by using comma separators.
* Log a UGP JIRA ticket with component Content Tagging if you want to add cloud values.
Case sensitive. Match values in cloud yaml
product Used by ExL (See below for more.) Used in ExL analytics. Case sensitive. Match values in product yaml values.
solution Required for validation (See below for more.) Tag for ExL search filtering. Example: solution: Experience Platform, Data Collection
This tag differs from product, described below.
Case sensitive. Match value in solution yaml values.
feature Used by ExL For ExL search and filtering APIs.
Example: feature: Processing Rules.
Feature values must be title case and use spaces, where applicable, for example, User and Groups.
You can add multiple feature values by using comma separators such as feature: Content Fragment, Processing Rules.
* Log a UGP JIRA ticket with component Content Tagging if you need to add feature values.
Case sensitive. Match values in feature yaml
feature-set (See below for more.) To be used for validation of feature. Sometimes, different products can use different terms (such as “Reports” and “Reporting”), so we need to validate feature values from a specific section.
You can include multiple feature-set values such as feature-set: Experience Manager, Experience Manager Assets.
Match values in the feature yaml
role Used by ExL (See below for more.) Example: role: Administrator
To be used for EXL search and filtering APIs. Use only a defined enum value. These values are case-sensitive - role values are title case.
You can add multiple role values by using comma separators, such as role: Leader, Architect.
Although you can tag for Data Engineer and Data Architect, currently these tags are surfaced in the UI as Data Architect and Engineer until there is enough content to make that separation meaningful to customers.
Case sensitive. Match values in role yaml
level Used by ExL (tutorials and courses) (See below for more.) For EXL search and filtering APIs. Case sensitive. Match values in level yaml
type Required for validation (See below for more.) For EXL search and filtering APIs. Lets customers filter by guide type. Case sensitive. Match values in type yaml.
topic Used by ExL (See below for more.) Example: topic: Integration
In progress to be used for EXL search and filtering APIs. The topic tag is used for cross-product topics such as Integrations and Administration. Use only a defined enum value.
Topic values must be title case and use spaces, where applicable.
You can add multiple topic values by using comma separators.
Do not edit this page to add values; instead, file a UGP JIRA ticket with Content Tagging component.
Case sensitive. Match values in topic yaml
version Under consideration (See below for more.) Example: version: 6.5
Possible use for EXL search and filtering APIs. Currently, multiple solution values are used for subordination.
Case sensitive. Match values in version yaml.
title Required in articles. 60 characters. Used in search results. The title displays in Google, and a pipe with the product name is appended automatically. See Title and description for SEO for authoring guidelines. Title case
user-guide-title Example: user-guide-title: Identity Services Admin Guide
Use only in the TOC.md file (do not use in article pages).
We recommend that the user-guide-title use the same text as the page title (such # Identity Services Admin Guide {#admin}).
Match guide title.
breadcrumb-title breadcrumb-title: Components Guide
Displays a shorter title for the guide name (not an article name) in the breadcrumb. This text is used in the guide breadcrumb that appears at the top of the page. Specify the breadcrumb-title in the TOC.md file for a user guide;o not use in individual articles.
Based on guide name
description Required for validation.
Max 160 characters.

Description is used by search engines and displays under the title metadata on a search engine results page. Validation fails if description does not exist (cannot be null).
See description in the authoring guide for guidance.
Sentence style
landing-page-description Example: landing-page-description: Learn how to implement tagging services for Experience Platform.
When Experience League landing pages are generated, the landing-page-description value is pulled from the article file. If landing-page-description does not exist, the description value is used.
We recommend you limit the user-guide-description value to one sentence with no more than 20 words so that the description uses 3 or fewer lines on landing pages.
Same as guide title.
user-guide-description Example: user-guide-description: Learn how to administer users and products for Identity Services.
Use only in the TOC.md file (do not use in article pages). When Experience League landing pages are generated, the user-guide-description value is pulled from the TOC.md file.
We recommend you limit the user-guide-description value to one sentence with no more than 20 words so that the description uses 3 or fewer lines on landing pages.
Same as guide title.
exl-id Automatic The exl-id metadata is a read-only, system-generated string added automatically to all articles. This exl-id allows us to track articles based on a permanent ID instead of a URL that might change. These IDs are especially important for tutorial content in -learn repos to prevent course tracking from breaking when a URL changes. While we recommend that you not edit, delete, or copy the exl-id value, the system should replace the metadata value properly in such cases. numeric
git-repo The git-repo URL allows users to click Edit this page icon (log issue image) or Log an issue icon (log issue image) to open the page in GitHub.
Example: git-repo: https://github.com/AdobeDocs/analytics.en
URL
hide See Hiding files Example: hide: yes
Default is no. Using ‘y’ or ‘yes’ excludes the pages from both external and internal search. (When hide = yes, index is set to no automatically in the output file.) The article appears in the TOC unless you set hidefromtoc to yes.
If you add hide: yes to the TOC.md file, the entire guide is excluded from external and internal search and available only through a URL.
See Hiding files.
N/A
hidefromtoc See Hiding files Example: hidefromtoc: yes
If you set hidefromtoc to yes, the article does not appear in the TOC and is available only through direct links or URLs.
If all articles in a TOC section are hidden from the TOC, the section is hidden in the left nav.
See Hiding files.
N/A
index Default is no. Example: index: y
Using ‘n’ or ‘no’ excludes the page from external search (if available) and sitemap. Important for pages such as “Contact us,” soft-launches, deprecated articles, or later articles in a tutorial series.
To exclude pages from both external and internal searches, use hide.
N/A
landing-page-description Overrides description.
20-word guideline. Used as the guide description on the ExL landing pages displaying a link to the article.
Sentence style (matches article name) See Authoring landing pages for guidance.
mini-toc-levels Currently disabled Example: mini-toc-levels: 2
Default is 2. Valid values include 1-6.
This metadata determines the number of heading levels that appear in the mini-TOC in the right nav. This metadata is usually added to the metadata.md or TOC.md file, but it’s sometimes added to individual articles.
N/A
internal Available Example: internal: yes
Used for internal documentation for Adobe eyes only. If internal is set to yes, content is not flagged for using internal links such as git.corp.adobe.com.
N/A

feature

For ExL search and filtering APIs.

Example: feature: Processing Rules

Feature values must be title case and use spaces, where applicable, for example, User and Groups.
You can add multiple feature values by using comma separators such as feature: Content Fragment, Processing Rules.

Log a UGP JIRA ticket with component Content Tagging if you need to add feature values. Case sensitive.

When you tag your articles with appropriate feature tags, it is also necessary to specify a valid feature-set tag. The feature-set metadata is usually the same as the solution value.

Match feature values within the feature-set section of the feature yaml.

solution

Use solution metadata to Experience League search filtering. The solution and product tags are used for different purposes that require different ENUM values—one for search filtering and one for Omega analytics. See the product section next.

Examples:

  • solution: Customer Journey Analytics
  • solution: Experience Platform, Data Collection
  • solution: Campaign, Campaign Standard

solution metadata

You must use one (or more) of the solution tags listed in the solution yaml.

If you specify a value that’s not in the yaml, validation will fail.

NOTE

For solutions that include multiple versions, such as Experience Manager and Campaign, specify multiple values. Start with the more general term (such as Campaign), and then add more specific versions (such as Campaign Standard).

Examples:

  • solution: Campaign, Campaign Standard
  • solution: Experience Manager, Experience Manager Sites, Experience Manager 6.5

product

Example: product: target

In use. The product item requires a defined enum value so that it can be used in Adobe Analytics.

  • These product tags MUST correspond with the Omega product names.
  • You can only use one product tag; that is, multiple tags are not allowed.

product metadata

For search filtering, use the solution metadata described previously.

omega

Use the appropriate product metadata for Omega data collection.

See the product yaml for valid ENUM values.

type

Example: type: Tutorial

In use for EXL search and filtering APIs. Use only a defined enum value.

If type metdata is not specified, the value defaults to type: Documentation

type metadata

See the type yaml for valid ENUM values.

level

Example: level: Experienced

If level metdata is not specified, the value defaults to level: Beginner

In progress to be used for EXL search and filtering APIs. Primarily used for learning courses. Use only a defined enum value.

These values are case sensitive - level values start with a capital letter.

You can add multiple level values by using comma separators such as level: Beginner, Intermediate.

level metadata

See the level yaml for valid ENUM values.

role

Example: role: Leader

In progress to be used for EXL search and filtering APIs. Primarily used for learning courses. Use only a defined enum value.

If role metdata is not specified, the value defaults to role: User

You can add multiple role values by using comma separators such as role: Developer, Data Architect.

See the role yaml for valid ENUM values.

topic

Example: topic: Integrations

In progress to be used for EXL search and filtering APIs. The topic tag is used for cross-product topics such as Integrations and Administration. Use only a defined enum value.

Topic values must be title case and use spaces, where applicable.

You can add multiple topic values by using comma separators.

See the topic yaml for valid values. Do not edit this page to add values; instead, file a UGP JIRA ticket with Content Tagging component.

Technical Marketing metadata

Click the linked names for additional information about technical requirements and authoring guidelines.

Metadata Requirement(s) About Capitalization
doc-type Optional Used by Technical Marketing team for analytics. (Video, article, tutorial, and so on. lowercase
activity Tech Marketing Used by Technical Marketing team for analytics. Helps define the use of the page (understand, implement, troubleshoot, setup, develop, etc. lowercase
sub-product Optional Example: sub-product: search
You can use sub-product for Adobe Analytics (Omega) data, among other applications. The sub-product values are less restrictive than product values. Work with solution teams to determine enum values for sub-products in your solution.
Example: livefyre could include library, search, instagram-search, apps, media-wall, carousel. Experience Manager could include assets, sites, community and so on.
Case sensitive.
kt Tech Marketing Used by Technical Marketing team.
Example: kt: <jira-number>
Last Updated Optional Used by Technical Marketing team for analytics.
team Tech Marketing (Optional) Example: team: TM
thumbnail Optional Used by Technical Marketing team for analytics.
title Required in articles. 60 characters. Used in search results. The title displays in Google, and a pipe with the product name is appended automatically. See Title and description for SEO for authoring guidelines. Title case

Landing Page Metadata (EXL)

Landing Page Metadata is EXL only. We use metadata in landing pages to define the breadcrumb experience.

Breadcrumb format:

Home > [Solution] > [Guide Name] > [article-name].html

Home jumps to the main AdobeDocs landing page. Likely https://experienceleague.adobe.com/docs/home.html

Solution jumps to the solution landing page, such as Analytics or Experience Platform.

Guide Name jumps to the home page of the user guide.

The article name is not a link.

breadcrumb-name

breadcrumb-name: Analytics

Required. The breadcrumb name should be the solution landing page name, such as Analytics or Experience Platform. This name appears in the breadcrumb for any content assigned to that landing page as a child repo.

child-repos

child-repos: id-service, core-services, core-services-learn, device-coop

Required. Add the repo names (no language suffix) to the child-repos metadata on the landing page. Any content within a child repo uses the breadcrumb information from the landing page in which the child-repo is specified. For example, if “id-service” is added as a child repo to Core Services, any ID Service article has this breadcrumb:

Home > Core Services > ID Service User Guide > article name

A repo can be added as a child repo to only one landing page (although the repo can be linked to from multiple repos).

parent-landing-page:

parent-landing-page: experience-manager-landing.md

This is used for special tutorials landing pages (or possibly sub-landing pages) to make sure that the appropriate landing page appears in the breadcrumb.

Uploading metadata from a CSV file (Admin)

Uploading metadata from a CSV file can be a great time saver. It’s especially useful for updating title and description metadata and for assigning feature metadata to articles.

Contact Bob if you want to run this workflow either on your own or with help.

  1. (Writers) develop a list of values for the metadata yaml files (feature, solution, role, and so on).

    To add values to any yaml file, create a UGP JIRA task, and select Content Tagging as the Component.

  2. (Writers) Make sure that your repo is up to date. Remove any previous __metadata_updates branch and guide-metadata.csv file or files.

  3. (Bob) Run the batch job or the individual generateMetaCsvFiles Jenkins job.

    Specify the metadata to be included. Default: title, description, feature, topic, role, level.

    This job creates a branch called __metadata_updates and uploads a separate guide-metadata.csv file in the same directory as its corresponding TOC.md file.

  4. (Writer) Switch to the __metadata_updates branch and edit the guide-metadata.csv files. When you’re done, tell Bob that you’re ready to upload.

    alt text

  5. (Bob) Add feature-set value to metadata.md or individual TOC.md files.

  6. (Bob) Run the updateMetaFromCsvFiles Jenkins job to upload the metadata from the CSV to the individual files.

  7. (Bob) Remove the CSV files from the branch and submit a PR.

  8. (Bob) Let writer know when complete.

Metadata Not in Use

uuid

Some files include uuid values from migration. If your content has already been migrated and redirects from the preview authoring system are in place, you can delete these uuid values.

audience

Example: audience: administrator

Not in use. Instead, use role (see above).

difficulty

Not in use. Instead, use level (see above).

badge

Example: badge: premium

We used this term during migration for Target to flag premium content so we could add a “Premium” badge image to the title. This metadata is used only for reference currently.

If you want a badge for your solution, contact the SSE team.

author

Example: author: John Doe

Not yet used.

last-updated

Example: last-updated: n

Default is yes. If you change the metadata to “last-updated: n”—-such as for minor changes—-the “Last updated” date in the right rail will not be updated. Not yet implemented.

private-beta

Example: private-beta: y

Not yet in use. Default is no.

private-feature-pack

Example: private-feature-pack: y

Not yet in use. For AEM, we might use Private Feature Pack and Admitted Domains from helpx. Default is no. If you select this option, admitted-domains is also required. We should verify admitted-domains is specified if private is enabled. Don’t allow publish if not specified.

admitted-domains

Example: admitted-domains: <string>

Not yet in use. Required for AEM private feature packs.

legacypath For AEM

internal

Example: internal: y

For KB docs. Default is no. Way to publish content for Adobe tech support operators only. Not yet in use.

previous

Example: previous: <URL>

Not yet in use. Show previous article in tutorial thread. Proposed for tutorials.

next

Example: next: <URL>

Not yet in use. Show next article in tutorial thread. Proposed for tutorials.

original-author

last-author

original-publish

Deprecated Metadata

seo-title

No longer used. The title metadata is used for SEO. The H1 (#) title is used for page display.

seo-description

No longer used. The description metadata is used for SEO. For any page display of description, use different supported metadata such as landing-page-description or user-guide-description.

solution-title

Example: solution-title: Learn & Support

Required for AEM. Not used for EXL. This item is the link text for the first of three links in the header. For standard help guides, use “Learn & Support” unless you need to create a link to different content.

solution-hub-url

Example: solution-hub-url: https://helpx.adobe.com/support/analytics.html

Required for AEM. Not used for EXL. The hub URL determines the link destination when users click the Product name in the user guide header.

solution-icon

Example: solution-icon: assets/logo-24.png

Never used. Intended to be used for solution icon in the header.

getting-started-title

Example: getting-started-title: Getting Started

Required for AEM. Not used for EXL. This item is the link text for the second of three links in the header. Use “Getting Started” unless you need to create a link to different content.

getting-started-url

Example: getting-started-url: https://landing.adobe.com/experience-league/

Required for AEM. Not used for EXL. The getting started URL determines the link destination when users click the middle link in the header.

tutorials-title

Example: tutorials-title: Tutorials

Required for AEM. Not used for EXL. This item is the link text for the third of three links in the header. Use “Tutorials” unless you need to create a link to different content.

tutorials-url

tutorials-url: https://helpx.adobe.com/experience-cloud/tutorials.html

Required for AEM. Not used for EXL. The tutorials URL determines the link destination when users click the third link in the header.

user-guide-url

Example: user-guide-url: /content/help/en/audience-manager/user-guide/aam-home.html

Never used. Ignore or delete.

Metadata log files for reference

Open any CSV file in a spreadsheet to see all the metadata in each file in the repo.

On this page