Metadata and tagging

Metadata is data about your page. Metadata include the a title, description, solution, product, feature, audience, document type, role, and more. Experience League (ExL) uses metadata to improve search engine optimization (SEO) on Google, and for content filtering and quality initiatives on Experience League.

This article describes metadata basics, how to add metadata to articles, the TOC (guide level), and at the repo-level.

This page also provides a complete reference list of all values used on Experience League, with definitions and examples.

IMPORTANT

Important requirements and best practices exist for metadata. Before adding metadata values in Markdown, review the basics in the next section so that you can avoid mistakes or validation errors.

What you should know about metadata

Metadata can be complicated, so here are the most important points to remember:

Important point Why it’s important
What values do I add first? Best practice is to first add title and description (which cannot be blank or null).

Then, depending on what you’re creating (video, article, or course), you might add feature, feature-set, role, level, topic, and so on. (See the tag reference section for a complete listing).

If you aren’t sure what to add next, get some advice. You might need to create values. Reach out to ExL support for guidance (Bob, Alva, or Blake).
Title and description must be uniquely written for SEO Title and description are different from an article’s first heading (# H1 page name) and first paragraph. They serve different purposes and have specific editorial guidelines.

Example title: How to create a segment

Example description: Learn how to create a segment in Analysis Workspace. Build segments from scratch or add an existing one.
For title, do not add the pipe and product name In Google results, the pipe and product name (Analytics, Target, etc.) are added automatically. Do not add these to your title metadata.
Which values are required for validation? Although title, description, and type must be present on an article, validation fails only if:
  • description is missing or null
  • Tag values (like type) are blank or don’t match their yaml values
In other words, description is the only value you must manually add to avoid validation failure.

Certain metadata that might otherwise cause validation failure have fall-back defaults. For example, if title is missing, the heading 1 (# Heading) value is used. If type is missing, Documentation becomes the default value.

See Add metadata in Markdown to learn which values you should add to articles, TOCs, and the repo metadata files.
Use tags to enable search filtering and content optimization Tags include cloud, feature, industries, interests, label, level, product, role, solution, topic, type, and version. (Not all are currently in use.) They must adhere to specific syntax requirements in their yaml files.

See Tagging requirements to learn more.

(To change or create tags, you must create them by filing a Jira ticket (UGP JIRA task, and select Content Tagging as the Component)).
Article values overwrite (supersede) values in the TOC or repo You add metadata at the top of the page and in three file types:
  • Article (page-level) (.md)
  • TOC (guide-level) (TOC.md)
  • Repo level (metadata.md)
The hierarchy is as follows:
  • Article values supersede TOC.md and metadata.md values
  • TOC.md values supersede repo values in the metadata.md file
In other words, the article values overwrite any values up the chain.
exl-id is automatically added and must be unique When creating a new page, do not use the exl-id metadata from an existing page that you plan to keep. This value must be unique on every page (and is automatically assigned).

Add metadata in Markdown

Add metadata at the top of each page. Order is not critical, but the best practice is to place title and description first, as shown in the following example:

metadata overview

The following sections describe which values belong in respective file types.

Article metadata

For typical articles (and video tutorials), add the following important metadata:

Other metadata sometimes used in articles:

NOTE

Validation does not fail if feature, role, level, or topic are missing. For example, level is primarily used only in video tutorials, so level can be left out of product documentation articles.
However, validation fails if the value is blank or if a value does not match its yaml syntax values.

Do not use empty placeholder tags like feature with no value.

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

TOC metadata (guide-level)

Metadata in the TOC.md file governs all the articles in a table of contents (unless over-written by article-level values).

Open the TOC.md and add the following metadata:

Other values you might use:

  • role - for example, you might add role: Developer to apply to all articles in the guide. If you want to override that value at the article level, you could add role: Admin, Developer to an article.

Repo metadata (metadata.md)

Although not required for validation, these metadata values belong in the metadata.md file:

  • git-repo - the repo URL
  • solution - the application name
  • type - the guide type (Documentation, Tutorial)
  • cloud - the cloud name
  • index - excludes the page from external search

Examples of typical repo-level metadata:

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

Be careful when applying the same metadata fields in both the metadata.md file and TOC.md file. 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.

Said differently, do not add the same metadata fields at lower levels unless you want to override the higher value.

Metadata and tag reference

The following is an alphabetical list of metadata tags with examples, requirements, status (current or planned use), and so on.

(If you’re new to metadata, you might want to stop and get familiar with the basics.)

Where used: TOC

A short title for the guide name (not an article name) that is used in the breadcrumb. Do not use in individual articles.

Example: breadcrumb-title: Components Guide

cloud

Where used: Repo

For ExL search and filtering APIs. Cloud values must be title case and use spaces, where applicable. You can add multiple values by using comma separators.

Example: cloud: Document Cloud, Document Cloud

Requirements: Case sensitive and match values in cloud yaml

Log a UGP JIRA ticket with component Content Tagging if you want to add cloud values.

description

Where used: article

Used by search engines and recommendations. Displays under the title metadata on a search engine results page. Validation fails if description does not exist (cannot be null).

Example: Learn about configuring segmentation in Analytics. Discover ways to focus on subsets of your data.

Requirements: Required for validation. Max 160 characters. See description for guidance.

exl-id

Where used: article - an automatic, numeric ID that associates a source markdown file with a URL.

The exl-id metadata is a read-only, system-generated string added automatically to all articles.

exl-id allows us to track a published article’s source file based on a permanent ID instead of a URL that might change. These IDs are especially important at this time for tutorial content in -learn repos to prevent course tracking from breaking when a URL changes after moving a file in a course repo. In the future, we hope to use exl-id values for auto-redirects.

What to do with the exl-id when copying or moving files:

When a new article is created, the system assigns an exl-id to the article and tracks it. If a writer accidentally deletes the exl-id, the system adds it back. Sometimes a writer wants to copy a file, and sometimes a writer wants to move a file. The system doesn’t know the writer’s intent.

  • If you want to copy a file, delete the exl-id in the new file. If you forget to do that, a duplicate ID error occurs during validation. If you get this error, delete the exl-id in the copied file.
  • If you want to move the article to a different repo, remove the exl-id from the old file and add it to the copied file in the new location. Then delete the original file (and add a redirect).

If you leave the exl-id in both files, the system honors the most recently pushed exl-id and does its best to preserve the exl-id, but when the same exl-id is added to two files, problems occur. The fix is to keep the exl-id in the correct file (depending on whether a file is being moved or copied) and delete the exl-id in the other file.

feature

Where used: article

For ExL search, filtering APIs, and recommendations (the More help on this feature heading and bullet list added automatically at the bottom of a page).

Example: feature: Content Fragment, Processing Rules

Requirements: Match feature values within the feature-set section of the feature yaml. 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. 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.

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

feature-set

Where used: article

For validation of the feature tag. Sometimes, different products can use different terms (such as Reports and Reporting), so we need to validate feature values from a specific section.

Example: feature-set: Experience Manager, Experience Manager Assets

Requirements: Match values in the feature yaml. You can include multiple feature-set values.

git-repo

Where used: repo

The git-repo URL lets customers 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

Requirements: If the git-repo metadata is not added, the feedback icons are not displayed in the right nav.

hide

Where used: article

Using ‘y’ or ‘yes’ excludes the pages from both external and internal search and the recommendations catalog. (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.

Example: hide: yes

Default is no.

See Hiding files for more information.

hidefromtoc

Where used: article

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.

Example: hidefromtoc: yes

See Hiding files for more information.

index

Where used: article

Using n or no excludes the page from external search (if available) and from the sitemap. This value is important for pages like Contact us, soft-launches, deprecated articles, or later articles in a tutorial series.

To exclude pages from both external and internal searches, use hide.

Example: index: y

Default is no.

industries

Not currently in use.

interests

Not currently in use.

internal

Where used: article

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.

Example: internal: yes

keywords

Not used and not recommended. Google ignores them, and might even penalize pages with “stuffed keywords.” Coveo (internal search) also ignores keywords.

label

Not currently in use.

landing-page-description

Where used: article

Optional. Used as description text on Experience League landing pages in articles if the description is too long.

Example: landing-page-description: Learn how to implement tagging services for Experience Platform.

IMPORTANT

Use SEO guidance for landing-page-descriptions. Doing so improves search traffic to Experience League.

Requirements: We recommend you limit the landing-page-description value to one sentence with no more than 20 words so that the description uses three or fewer lines on landing pages. If landing-page-description does not exist, the description value is used.

level

Where used: article

Under development.

To be used for ExL search and filtering APIs. Primarily used for learning courses.

Example: level: Experienced

Where used: article

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

level metadata

Requirements: Use only a defined enum value. These values are case-sensitive - level values start with a capital letter. See the level yaml for allowed valid ENUM values.

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

mini-toc-levels

Where used: article

This metadata determines the number of heading levels that appear in the mini-TOC in the right navigation. This metadata is usually added to the metadata.md or TOC.md file, but it’s sometimes added to individual articles.

Where used: Repo or TOC

Example: mini-toc-levels: 2

Default is 2. Valid values include 1-6.

product

Where used: article

Used by Experience League for site analytics. (This tag is not used for search filtering. Instead, use the solution metadata for this purpose.)

Example: product: target

Requirements: See the product yaml for valid ENUM values.

You can only use one product tag. Multiple tags are not allowed.

product metadata

Example of analytics enabled by this tag:

omega

recommendations

Where used: article

Used to prevent content recommendations from displaying on the page OR to exclude the page from the recommendations catalog (so it won’t be recommended).

Example: recommendations: noDisplay, noCatalog

Requirements:

  • noDisplay will prevent recommendations from displaying on the page (can be overridden with display)
  • noCatalog will exclude the page from the catalog (can be overridden with catalog)

More examples:

On a multi-page tutorial you might want to set recommendations: noDisplay, noCatalog in the TOC so that users aren’t distracted while going through the tutorial and so pages in the middle of the tutorial aren’t recommended. However, to drive traffic to the first page of the tutorial, you could override the metadata on the first page with recommendations: noDisplay, catalog.

role

Where used: article

Used for EXL search and filtering APIs and recommendations. Primarily used for learning courses. Use only a defined enum value.

Example: role: Leader

Requirements: See the role yaml for valid ENUM values.If role metadata 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.

solution

Where used: article

Used for ExL search filtering and recommendations. This tag differs from product, which is for site analytics. Note: solution and product tags are used for separate purposes, and each requires different ENUM values in their yaml files. (solution is for search filtering and product for ExL site analytics.)

Example: solution: Campaign, Campaign v8

Requirements: Must match value in solution yaml values. Multiple values allowed. Case sensitive. Fails validation when blank or incorrect values are used.

More examples:

Single solution

  • solution: Customer Journey Analytics

Sub-solutions (AEM and Campaign only)

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

Multiple solutions

  • solution: Target, Analytics, Audience Manager

solution metadata

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 v7).

Examples:

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

Adding or changing solution values

If you need a new solution value, log a JIRA issue (UGP project assigned to Bob).

If you need to replace a solution value that appears in the EXL UI, make sure that you give us at least two weeks advance notice, if possible. Log a JIRA issue (UGP project assigned to Bob). Include the deprecated value and the new value.

topic

Where used: article

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

Example: topic: Integrations

Requirements: 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. File a UGP JIRA ticket with Content Tagging component to add values.

title

Where used: article

Title is for internet SEO, particularly for Google. A pipe with the product name is appended automatically.

Requirements: Required in articles. 60 characters. Sentence case. The H1 is used when this value is not present. Title differs from the page’s heading and should be written with search results in mind.

See Title and description for SEO for important authoring guidelines.

Example: How to create calculated metrics

type

Where used: article

Allows customers to filter by guide type and also used by recommendations.

Example: type: Tutorial

Requirements: One value only. Must match values in the type yaml. If type metadata is not specified, the value defaults to type: Documentation

type metadata

version

Example: version: 6.4

Where used: article

This is now a search filter for AEM and Campaign. Must match values in the version yaml. If a version value is specified, the accompanying solution value must also be specified. For example, you cannot use version: 6.4 if Experience Manager is not also specified as one of the solution values.

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. |

user-guide-description

Where used: TOC

When Experience League landing pages are generated, the user-guide-description text is pulled from the TOC.md file and displayed as the guide’s description.

When user-guide-description is missing, the description on the ExL landing is blank.

Example: user-guide-description: Learn how to administer users and products for Identity Services.

Requirements: 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.

(Note that articles use landing-page-descrpition for ExL landing pages.)

user-guide-title

Where used: TOC

In limbo. Displays on ExL landings as the guide’s title.

Example: user-guide-title: Identity Services Admin Guide

Requirements: We recommend that the user-guide-title use the same text as the page title (such as # Identity Services Admin Guide {#admin}).

Technical Marketing metadata

The following metadata are specific to the Technical Marketing team.

Metadata Requirements About Capitalization
doc-type Optional Used by Technical Marketing team for analytics and recommendations. (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, and so on. 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 and recommendations.
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. Sentence 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.

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.

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.

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