Experience League Authoring Guide
This content is intended only for Adobe employees. If you are not an Adobe employee, see the Adobe Contributor Guide.
Searchable list of articles
TIP
Use shortcut keys (
cmd + f or ctrl + f) to search for topics and their links.Article
Description and Keywords
Editorial guidance and style
Find editorial guidance. Contact Blake Frei with questions.
Guidance and best practices for writing headings for concepts, tasks, and page titles
How to write titles and descriptions to optimize search.
Learn how to improve your content’s SEO with both basic and advanced strategies including tools. Use AI to create prompts for title and description metadata and general authoring.
Learn how to improve search results both internally and externally (that is, Google) in Adobe documentation.
Learn about guidance for alt-text in Experience League publishing.
Learn about gender and inclusive terminology for Experience League publishing.
Learn how to create an effective FAQ article.
Learn about cross-referencing additional or related information.
Learn about guide definitions and content types in technical writing.
Learn editorial guidance on steps and sub-steps technical writing.
Editorial rules for punctuation and structure in bulleted lists.
Editorial rules for writing numbered, step-by-step procedures.
Guidance on UI vocabulary and verbs for describing interface actions.
Formatting lists and steps so AI tools can parse and surface them.
Guidance and best practices for creating a TOC
How to write landing page descriptions.
Learn best practices and consequences of moving and renaming files and folders in Git, and of restructuring content in the TOC.
Learn how to use AI to generate a summary from a PDF.
Reference table of Adobe CX Enterprise product names and approved secondary mentions.
Apply DNL and UICONTROL to interface strings.
Learn how to author a page in Experience league, add metadata, headings, paragraphs, and more.
See a sample article for authoring and publishing to Experience League.
Markdown syntax reference
A basic introduction to Markdown styling. Page elements: Block quotes, Escape characters, Code Blocks, Code Blocks with line numbering, Definition Lists, Download Files, Headings, Images, icons and inline images, special characters, Links and Cross-References, Metadata, Image Links, Numbered Lists, Bullet Lists, Comments, Tables, Notes, Tips, Important, Video and video transcripts, More Like This/Related articles, CONTEXTUALHELP, Tabs, Shade Boxes
Quick overview of supported Markdown syntax for Adobe documentation.
Find syntax guidance. Contact Bob Bringhurst with questions.
Editorial rules for using badges in Markdown.
Syntax for inline code blocks in Markdown.
Markdown syntax for headings (H1-H6).
Syntax for authoring processing rules content.
When and how to use raw HTML in Markdown, including HTML tables.
Syntax for images, resizing, aligning, click-to-zoom, and icons.
Markdown link syntax, cross-references, and related-article links.
Markdown syntax for numbered and bulleted lists.
Which special characters need to be escaped in Markdown and how.
Working with markdown tables and HTML tables.
How to control auto or fixed table rendering in Experience League.
Linking tips
You can create a collapsible section (sometimes called an accordion) that is hidden by default. The user can click the title to expand or collapse the section.
Markdown syntax that is under consideration, but not yet supported.
Metadata and tagging
How to use metadata and tags for AdobeDocs. Information about where to add metadata and metadata hierarchy. Common tags: solution, product, role, level, feature, feature-set, topic, title, description, exl-id, git-repo, mini-toc-levels, hide, hidefromtoc, index, recommendations (“More help on this feature”), internal.
Metadata tag linking a page to its parent landing page.
How to request a new metadata value be added to the approved list.
Adding feature, role, and level metadata tags for the new EXL UI.
Learn how to use the Review Tags tool to scan a repo, review and suggest auto tags after migration, and merge the branch.
Validation and publishing
How to resolve validation errors, including validation summaries in pull requests and Slack. Validation errors include Git conflicts, illegal characters, BOM characters, package and structure, link check.
Types of Markdown validation errors and how they’re reported.
How broken absolute link checking works and how to fix flagged links.
Technical details of how the validation pipeline checks Markdown.
How to resolve Git merge conflicts flagged during validation.
How to publish content. How to preview content using
hide: true.How to create a review branch for previewing content and staging a review
Learn to manage public github.com pull requests (PRs) and logged issues. Information about public github.com mirrors and user feedback.
Hide files, sections, or entire guides from search engines or in the TOC or both.
Demo pages illustrating the
hide: true metadata field: Hidden article 1, Hidden article 2, Hidden article 3.Adding redirects for previous domains or for different locations within experienceleague.adobe.com
Clean-up tasks for writers to perform
Tools: VS Code and RedPen
Overview of the AdobeDocs Chrome extension, Adobe Markdown Authoring, and Adobe ExL Authors extensions—what each one does and how to install it.
Guidance and best practices for writing in Visual Studio Code.
- Prevent common errors
- Visual Studio Code tips
- Creating keyboard shortcuts
- Global Find/Replace and wildcard expression searches
- Visual Studio Code add-ons
Common Markdown and metadata mistakes and how to avoid them.
General VS Code tips for Experience League authoring.
Installing and using the Adobe Markdown Authoring VS Code extension.
Recommended VS Code add-ons for writers.
How to do a global find/replace across a repo in VS Code.
How to use wildcard expressions in VS Code find/replace.
Recommended and custom keyboard shortcuts for VS Code authoring.
How to use RedPen Scoring to check spelling, usage, and terminology.
Repo and guide setup
What Adobe lead writers should know about user guide setup in Git.
- Adobe Docs repo structure
- Required repo files
- User guide files (TOC.md file) and home page
- Naming files and folders
- How URLs are generated
- Landing pages and breadcrumbs
Required files in an Adobe Docs repo, such as metadata.md and TOC.md.
How to set up more than one user guide in a single repo.
What the repo-level metadata.md file controls.
What the TOC.md file controls and how it’s structured.
How Experience League generates article URLs from file paths.
How to work with Table of Contents files to determine what appears in left nav of user guide.
Best practices for designing the home page of the user guide. Use a template for the home page.
Create a repository, add required files, and configure settings for pushing content live
Guidance and best practices for creating a new repo in AdobeDocs
How to remove repositories
How Adobe contributors should set up Git, GitHub Desktop, and other tools
This article explains an overview of Git, GitHub repository, how content is organized, and naming conventions used for Adobe documentation.
How Adobe lead writers should work in GitHub and Visual Studio Code.
Learn different methods for logging issues and editing content.
Content types and features
A quick reference for creating and uploading video tutorials to Experience League. AdobeTV and MPC.
Learn how to set up your desktop and quickly record a video for Experience League.
Learn how to edit a video using Adobe Premiere Rush.
Learn how to convert text to audio using AI (Voxify) for videos and slides.
How to add a video to Experience League in the least amount of steps.
How to update a video already on Experience League.
How to add a video to Experience League manually, in the least amount of steps.
How to add an event recording to Experience League.
How to manually add an event recording to Experience League.
How to advertise an event recording on Experience League.
How to identify content in the Knowledge Transfer Jira project.
How to request content to be produced for Experience League.
Quick start guides and videos for recording, editing, and uploading videos.
Learn about creating and editing course files, metadata for courses, thumbnails, and other course requirements.
Creating and editing playlists using VSC extension.
Creating and editing slides using VSC extension.
A microsite is an HTML website that is uploaded to Experience League directly instead of through the standard authoring pipeline. Microsites are useful for displaying HTML sample files or providing tools or services not available through markdown authoring.
Understand how landing pages are generated. Understand the different syntax and validation rules.
Localization Overview
Use snippets or includes to share text among articles in a repo.
Learn how to set up content for contextual help popovers that can appear in the Experience Cloud product UI.
Reference and resources
List of new articles and significant changes.
GHEC migration information. How to sign in to GHEC, new features, new validation, ongoing issues.
Release notes for updates to the SCCM publishing pipeline.
Learn how to find site Experience League analytics usage data in Adobe Analytics.
Learn how to add metadata to ensure optimal Analytics data. Get tips for viewing reports.
Learning resources for Git and GitHub, GoURLs or go urls, upload videos to AdobeTV/MPC, Slack channels, list of writers, design resources, use Spectrum icons, logging jira tickets.
Design resources for writers, including Spectrum icons.
list of repos and writers and teams
Learn about the Knowledge Transfer process.
Example of an article that stays visible in the TOC despite living in a hidden-articles section.
Featured Articles
More Resources
recommendation-more-help
authoring-guide-help-main-guide