Metadata

The GitHub authoring and SCCM publishing platform supports a wide variety of metadata parameters. A complete list, sample usage, and more information is tabulated in the following sections.

Metadata Overview

Writers specify metadata in three locations:

  • At the beginning of each article/MD file.
  • At the beginning of the TOC.md file in the user guide directory. This metadata is added to all articles in the guide, unless overwritten.
  • (Optional) In the metadata.md file at the repo level. This metadata is added to all articles in the repo, unless overwritten.

Metadata hierarchy

The repo-level metadata (metadata.md) can be overwritten by user-guide-level metadata (TOC.md), which can be overwritten by article-level metadata. For example, you might specify a solution value (such as solution: Analytics) in the metadata.md file, 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 will take place.

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

Metadata purposes

Some metadata, such as product, solution, and type, requires specific enumerated values to function consistently and properly. For example, solution and type are used for search filtering, while product and sub-product are used for Omega Analytics metrics. Metadata can also be used in the future for filtering content based on role, feature, or difficulty level. Use appropriate metadata values to ensure consistency and accuracy.

Any metadata you specify is passed through to the HTML page.

Contact the SSE team if you need to add ENUM values to existing metadata or if you need to use custom metadata.

Metadata in use

When you create a new article, the following two metadata items are required. Title and description metadata are what Google and other search engines use to display content on the search engine results page (SERP):

  • title
  • description

Example:

---
title: How to Use decryptPassword in Adobe Analytics
description: Decrypt a password stored in an external account with the decryptPassword function. Learn how to call in JSSP or SOAP call implementations with Adobe API.
---

Continue reading for important guidelines on title and description.

title

This metadata is required for articles. Title is primarily used by Google for what it displays on the search results page. It’s also used in search results, the breadcrumb, and browser tabs.

In each article, you specify the title in both metadata (title:) and as a heading (# <Head1>). The title metadata is used for search results, the breadcrumb, and browser tabs. The title heading is used for page display.

Title metadata

Examples of how you might use a title and description metadata, along with an article title:

---
title: What is Cohort Analysis and How Does it Work?
description: Dig deeper into the data around your audience and break into related groups with Cohort Analysis in Adobe Analytics.
---

# Overview of Cohort Analysis in Adobe Analytics

Important editorial guidelines for title metadata

  • Capitalization: Use title case for title, and sentence case for article (page) title.
  • 60 characters is the maximum length for title (English). 120 characters maximum for localization, including spaces and the pipe/product name (see the important note above). A useful tool for counting characters is the Google SERP snippet optimization tool.
  • The title metadata will rarely match the article title heading (# Title) word-for-word. Meaning, optimize the meta title for SEO. Optimize the article title for reading when in the context of the help guide. For example:

    • Metadata title: What Is a Fallout Report?
    • Article title: Overview of Fallout reports in Workspace
  • Overview, by itself, isn’t useful as a metadata or article title…

  • Use keywords. Your most important keywords should be closer to the beginning of the title (for both the meta title and article title). The primary keywords are the feature name or article’s subject, and words people type when searching. For example:

    • How to, as in How to Upload a PDF
    • Learn How to, as in Learn How to Use Adobe Target
    • Get Started with, as in Get Started with Activities in Target
    • Feature explained, as in Page Views Metrics Explained
    • Action feature, as in Download Data with CSV
    • Guide to, as in Guide to Statistical Anomaly

description

Required for articles. Description is used by search engines and displays under the title metadata on a search engine results page.

Maximum length is 160 characters. Ideally, the size is around 150-160 characters, but anything over 60 is acceptable. The goal is to use as much as the description as possible to target keywords for Google to rank the page higher.

If you need to shorten or otherwise edit the description of an article that’s linked to on a landing page, use landing-page-description. Otherwise, the description value is used in landing page links to articles.

Editorial guidelines for description metadata

  • Think of your description as describing the intent of the article.
  • Make sure the description reads naturally; do not cram random keywords in the description - Google will flag this and could demote content.
  • Write your description in two parts: First, summarize the content of the article, then add a call to action and the intent of the article. Examples:
    • description: Sign in to Adobe Analytics to start configuring and accessing reports, add users and more. Follow these steps for a successful Adobe Analytics sign-in.
    • description: Decrypt a password stored in an external account with the decryptPassword function. Learn how to call in JSSP or SOAP call implementations with Adobe Analytics.
  • Think of what users search for; for example, Learn how to use Adobe xx might be something users type rather than simply Overview of Adobe xx.

Some examples of effective descriptions:

  • Action feature with call to action: description: Dig deeper into the data around your audience and break into related groups with Cohort Analysis. Learn about Cohort Analysis with Adobe Analytics.
  • Learn how to, Get started with and Discover are all great ways to add calls to action or describe intent, as in description: Learn how to use Data Warehouse in Analytics to get custom reports. Transform raw data into insights that reveal patterns. Get started with Adobe Analytics.

landing-page-description

This is used when an article is linked to from a landing page. If you want the description that appears on landing pages to be shorter than the SEO description, add landing-page-description metadata in the targeted article. Otherwise, the article description value will be used on the landing pages.

keywords

Example: keywords: experience, visual experience composer, enhanced experience composer

Keywords are copied during the migration for reference. Keywords are optional. They are indexed for use in internal search. External search engines such as Google have deprecated keywords.

solution

Use solution metadata to Experience League search filtering. Note that solution and product 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 following enumerated values for solution:

  • Acrobat DC
  • Admin
  • Adobe Sign
  • Advertising Cloud
  • Analytics
  • Audience Manager
  • Campaign
  • Campaign Classic
  • Campaign Standard
  • Connect
  • Core Services
  • Creative Cloud
  • Customer Journey Analytics
  • Data Collection
  • Document Cloud
  • Dynamic Media Classic
  • Experience Cloud
  • Experience Cloud Services
  • Experience Manager
  • Experience Manager Forms
  • Experience Manager Screens
  • Experience Manager Sites
  • Experience Manager Assets
  • Experience Platform
  • Experience Platform Launch
  • Intelligent Services
  • Journey Orchestration
  • Magento
  • Marketo
  • Offer Decisioning
  • Primetime
  • Real-time Customer Data Platform
  • Social
  • Target

If you specify a value that’s not on this list, validation will fail.

If you need a solution to be added to this list, please log an Experience League UGP JIRA task, or contact the SSE team.

API call that displays solution values

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 names MUST correspond with the Omega product names. You can only use one product tag; that is, multiple tags are not allowed.

For search filtering, use the solution metadata described previously.

omega

Use the appropriate product metadata for Omega data collection.

Valid ENUM values:

  • adobe analytics or analytics or aa
  • adobe audience manager or audience manager
  • adobe campaign or campaign or ac
  • adobe experience manager or experience-manager or aem
  • adobe experience manager cloud manager or experience manager cloud manager or cm
  • adobe livefyre or livefyre or alf
  • adobe marketing cloud or marketing cloud or experience-cloud or experience cloud or amc
  • adobe media optimizer or media optimizer or or amo
  • adobe target or target or at
  • adobe dynamic tag management or dynamic tag management or dtm
  • adobe experience platform or experience platform
  • adobe launch or launch
  • adobe primetime or primetime
  • adobe social or social
  • auditor
  • adobe core services or core services

sub-product

Example: sub-product: search

You can use this for Adobe Analytics (Omega) data, among other applications. 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. AEM could include assets, sites, community and so on.

type

Example: type: Tutorial

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

type metadata

The default value is Documentation.

Valid ENUM values:

  • Documentation (default)
  • Tutorial
  • Course
  • Event

role

Example: role: Admin

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

Valid ENUM values:

  • Coming soon…

level

Example: level: Advanced

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

Valid ENUM values:

  • Coming soon…

version

Example: version: 6.5

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

Valid ENUM values:

  • Coming soon…

feature

Example: feature: Processing Rules

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

Feature values must be title case and use spaces, where applicable, for example, User and Groups.

Valid ENUM values:

index

Example: index: y

Default is no. 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. You can also use hide.

hide

hide: yes

Default is no. Using ‘y’ or ‘yes’ excludes the page from both external and internal search. (When hide = yes,index is set to no automatically in the output file.) The article will appear in the TOC unless you set hidefromtoc to yes.

If you add hide: yes to the TOC.md file, the entire guide will be excluded from external and internal search and available only through a URL.

See Hiding files.

hidefromtoc

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.

snippet

Example: snippet: n

Opt out of Google feature snippets. Default is yes.

mini-toc-levels

Example: mini-toc-levels: 2

This metadata is currently disabled in EXL. We’re currently investigating this issue.

Default is 2. Valid values include 1, 2, and 3.

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

git-repo

git-repo: https://github.com/AdobeDocs/analytics.en

Required. The git-repo URL allows users to click Edit this page or Log an issue to open the page in GitHub.

This metadata should be added to either the metadata.md or TOC.md file.

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

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.

breadcrumb-title: Components Guide

Optional to display a shorter title for the guide 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. Do not use in individual articles.

seo-title / seo-description

Currently, when you specify seo-title, the value is output in the HTML file as <title> and used in browser tabs and search snippets. But I believe we’re going to deprecate these metadata items and use only title and description metadata for SEO.

Metadata Not Yet in Use

audience/role

Example: audience: administrator

Currently not in use, but will likely be used in the future with specific ENUM values such as all, administrator, analyst, marketer, implementer, developer, architect, author.

difficulty

Example: difficulty: 3

ENUM values 1, 2, 3, 4, 5. 1=beginning, 3=intermediate, 5=advance. To be used primarily for videos and tutorials, not help articles.

doc-type

Example: doc-type: troubleshooting

Default is reference. Currently not in use, but might be used in the future with specific ENUM values such as developer, troubleshooting, tutorial, reference, video, white-paper, release-notes. See also type above.

(Note: Tech marketing = understand, use, setup, implement, troubleshoot, develop)

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 at this time.

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

version

Example: version: 6.4

Primarily for AEM and Campaign. Not yet used. When in use, likely ENUM values are 6.5, 6.4, 6.3 and 6.2 for AEM and v6 and v7 for Campaign Classic.

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

Default is no. Not yet in use.

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.

feature

Example: feature: Content Insights

Primary DX feature name. Each solution team has a list of features; these are currently being defined by teams. Please note that features are written as they appear - Title case, no hyphen between values.

topic

Example: topic: Implementation

Cross feature use cases and capabilities/themes for DX products. Set values across all products. This is an optional value that solution teams can decide to use for cross-functional capabilities. Currently not surfaced in the user interface.

activity

Example: activity: asset-insights

Understand the intended use of the page. Set values for each solution? understand, use, setup, implement, troubleshooting, developer. Proposed by tech marketing. similar to doc-type and audience

previous

Example: previous: <URL>

Show previous article in tutorial thread. Proposed for tutorials.

next

Example: next: <URL>

Show next article in tutorial thread. Proposed for tutorials.

original-author

last-author

team

original-publish

kt (Example: kt: <jira-number>)

cloud

Example: cloud: experience-cloud

Not yet in use. When used, proposed ENUM values include experience-cloud, marketing-cloud, analytics-cloud, advertising-cloud.

Deprecated (or soon-to-be deprecated) Metadata

uuid

Unique page ID used for post-migration redirects. Do not copy to another file.

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.

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 will appear 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 will have 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 the appropriate landing page appears in the breadcrumb.

On this page