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 in an article.
  • (Optional) In the metadata.md file at the repo level. This metadata is added to all articles in the repo, unless overwritten in the TOC or article.

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

metadata trickle down

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 is used exclusively for Omega Analytics metrics. 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 need to add ENUM values to existing metadata or if you need to use custom metadata, contact Alva or Bob, or log a UGP Jira ticket.

Metadata in use

When you create a new article, the following two metadata items are required:

  • title
  • description

Title and description metadata are what Google and other search engines use to display content on the search engine results page (SERP).

Examples:

---
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. In each article, specify a title in both metadata (title:) and as a heading (# <Head1>), or page title. The title metadata is used for search results, the breadcrumb, and browser tabs. The page title heading is used for page display. These titles should correspond to one another (when not identical) because readers can see the breadcrumb and the page title at the same time.

Title metadata

IMPORTANT

Regarding the pipe (|) and Adobe + product name: The system automatically appends this to the title metadata when generating HTML output, so do not add it manually. For example, the metadata title Create an Activity displays as Create an Activity | Adobe Target in Google. Given that the maximum length is 60 characters (English), make sure that you consider the pipe and product name when determining your title name length in this field.

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 system appends | Adobe nameofproduct when creating title metadata for output. (See the important note above). Because of this, do not include the product name in your meta title unless it’s necessary to understand the meaning of the title.

  • 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 can 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 description, add landing-page-description metadata in the targeted article. Otherwise, the article description value will be used on the landing pages.

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

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 core services or amc
  • adobe advertising cloud or advertising cloud or adc
  • adobe media optimizer or media optimizer or amo
  • adobe target or target or at
  • adobe dynamic tag management or dynamic tag management or dtm
  • adobe experience platform or experience platform or platform
  • adobe customer journey analytics or customer journey analytics or cja
  • adobe intelligent services or intelligent services or is
  • adobe real time customer data platform or real time cdp or rtcdp
  • adobe marketo or marketo or amk
  • adobe bizible or bizible or biz
  • adobe magento or magento or mag
  • adobe acrobat or acrobat or acr
  • adobe sign or sign or asi
  • adobe document cloud or document cloud or dcl
  • adobe search and promote or search and promote or asp
  • adobe dynamic media classic or dynamic media classic or dmc
  • adobe launch or launch
  • adobe primetime or primetime
  • adobe social or social
  • auditor
  • adobe journey orchestration or journey orchestration or jo
  • adobe device co-op or device co-op or dcp
  • adobe debugger or debugger or dbg
  • adobe web sdk or web sdk or sdk
  • adobe places service or places service or aps
  • adobe id service or id service or ids

sub-product

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

Valid ENUM values:

  • Leader
  • Architect
  • Developer
  • Data Architect
  • Data Engineer
  • Administrator
  • Business Practitioner

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

See the Tagging wiki for more details.

NOTE

Although you can tag for Data Engineer and Data Architect, currently these tags will be surfaced in the UI as Data Architect and Engineer until there is enough content to make that separation meaningful to customers.

level

Example: level: Advanced

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

Valid ENUM values:

  • Beginner
  • Intermediate
  • Experienced

See the Tagging wiki for more details.

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.

Alva is working with team members to define a set of valid feature values for each solution. Log a UGP JIRA ticket with component Content Tagging if you need to add feature values.

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.

For a list of valid values, locate the appropriate link for your solution on the Tagging wiki. We plan to host these values in a different location soon.

topic

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 Integration and Implementation. Use only a defined enum value. Alva is defining a set of valid topic values. Log a UGP JIRA ticket with component Content Tagging if you need to add topic values.

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

You can add multiple topic values by using comma separators.

For a list of valid values, see the Tagging wiki.

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(s) 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 (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. Do not use in individual articles.

seo-title / seo-description

The seo-title and seo-description metadata tags are deprecated. Don’t use. Use title and description for SEO.

Metadata Not Yet in Use

uuid

Unique page ID used for tracking a file for redirects and course flow. Do not edit or copy the uuid to another file.

If you accidentally remove the page ID (such as by deleting and re-creating a file), please use Git history to copy the previous ID into the new page. Contact the SSE team if you have questions.

audience

Example: audience: administrator

Currently not in use. However, role is in use (see above).

difficulty

Currently not in use. However, level is in use (see above).

doc-type

Example: doc-type: troubleshooting

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.

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.

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

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