DocumentationExperience League Authoring Guide

Slides in markdown

Last update: Fri Sep 12 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

You can create slides to replace or supplement videos for tutorial, using Voxify technology for text-to-speech. Slides are authored in a central repo. If you have any access issues, reach out in the Exl-slides Slack channel.

Clone the Slides repo

Clone the Slides repo.

The slides.en repo is on the new GitHub Enterprise Cloud environment. If you have an issue with your sign-in, see GitHub setup - Signing in to GitHub Enterprise Cloud.

Install the VSCode plug-in for slides

Download and install the VS Code Plug-in from this .vsix file on the releases wiki

  1. In VSC, open Extensions.

  2. Install the file from VSIX:

    Click Views and More Actions (the ellipses), then click Install from VSIX…

Organize folders

In the repo, use recognizable folder names with a product or feature to avoid naming collisions. Avoid generic names like get started.

Create a Markdown file

Each slide set is a standalone Markdown file with required front matter (including publish flag, title, description).

Metadata and headings

Use the standard editorial guidelines for these elements on a slides page:

  • Title meta: Use title case and follow standard character limitations. Learn more
  • Description meta: Use the standard guidance for description metadata. Learn more
  • Headings: Sentence case for headings.

Add images

Insert screen captures relevant to each step. Use the Visual Studio Code Explorer to ensure images are within the project and tracked by Git.

Use the VSC plugin for slides:

  1. Click the slides button in the activity bar.
  2. Click New Slides and provide a file name.
  3. Add images via Explorer or file browser.

Annotate images with callouts

  • Draw rectangle or circle callouts on images to highlight UI elements.
  • Multiple callouts per image are supported.
  • Callout positions use percentage-based offsets for scalability.

Add titles and descriptions

Enter a unique title and description for each slide step; these are used for metadata and accessibility (alt tags).

Save and review

Save the Markdown file; the plugin generates the correct template and structure.
Review and edit as needed in either the plugin or directly in Markdown.

Publish and build

  • Set the publish flag to true when ready for production.
  • Commit and push changes to Git; only changed content is built, enabling fast iteration.

Preview on stage

Slides are built and available for preview on the staging environment almost immediately after pushing.

Follow authoring guidelines

Adhere to naming conventions and metadata standards to support future discoverability and reuse.

(Optional) Use advanced features

  • Duplicate slides for repeated UI steps.
  • Use keyboard shortcuts for callout management.
  • Toggle publish flag and edit alt tags as needed.

Including the slide in a markdown article (in-progress)

This feature is not yet available in production, but we’re including the syntax here for testing purposes.

  1. In a markdown file, add >[!SLIDE](<id>) on a blank line where you want the slide content to appear.

    The <id> is the name of the slide markdown file, such as analyze-project for analyze-project.md.

  2. Update the file. (Again, this currently works only on dev.)

Syntax:

>[!SLIDE](analyze-project)
https://experienceleague-stage.adobe.com/en/slides/analyze-project

Rendered (not yet available):

>[!SLIDE](analyze-project)
recommendation-more-help
92f1a422-8a81-400b-85d3-388f0c36dfda