Install and Set Up the Sage Tutorial Authoring Extension

The Sage extension is distributed as a platform-specific .vsix file. There are separate builds for macOS and Windows.

1. Navigate to the Sage Tutorial Extension releases page.

2. The latest release is always listed at the top of the page.

3. Scroll past the change log to the bottom of the release entry, where you will find two .vsix files — one for Mac and one for Windows. Click the file for your platform to download it.

1. Open Visual Studio Code.

2. Open the Command Palette: select View > Command Palette… (or press Ctrl+Shift+P / Cmd+Shift+P).

3. In the Command Palette, type VSIX and select Extensions: Install from VSIX….

4. In the file dialog, navigate to your Downloads folder, select the Sage .vsix file you downloaded, and click Install.

5. After installation completes, you will see the Sage owl icon appear in the VS Code Activity Bar on the left side of the window. Click it to open the Sage sidebar.

When you first open the Sage sidebar after installation, you will see a Setup Workspace button. Click it to launch the setup wizard.

Note: Wait for VS Code to finish initializing extensions (indicated by the spinning circular arrow in the status bar) before clicking Setup Workspace.

The first step in the wizard asks you to choose a local directory where Sage will clone your tutorial repositories and store its data.

1. Click Browse to open a file selection dialog.

2. Navigate to the location where you want to store your tutorial repositories — typically your Documents folder.

   If you prefer to keep GitHub repositories out of OneDrive (which syncs automatically on SAP machines), choose a directory outside your Documents folder.

3. Create a new folder (for example, sap-tutorials) and select it.

4. Click Select to confirm. The wizard will display the selected path and enable the Next button.

Each tutorial team uses a pair of GitHub repositories: a QA/Contribution repository (with a -Contribution suffix) and a Production repository. Sage refers to each such pair as a repository group.

1. The wizard displays a list of all available repository groups.

2. Select the repository group (or groups) that you work with. For most authors, this will be a single group. If you are unsure which group to select, check with your team lead.

3. Click Next to proceed.

1. Click the Sign in to GitHub button.

2. VS Code will open a browser window asking for permission to authenticate. Click Allow (or Yes) in each prompt.

3. Once authenticated, the wizard displays your GitHub username and enables the next step.

   Multiple GitHub accounts: If you use GitHub Copilot for Business within VS Code, you may have multiple GitHub accounts active. Sage automatically filters out the Copilot/GitHub for Business account and selects your personal tutorial-authoring GitHub ID. If the wrong account is selected, contact Riley Rainey.

1. Click the Sign in to IMS button.

2. VS Code will open a browser window to the IMS OAuth authentication page. SAP Single Sign-On will automatically detect your SAP credentials and log you in.

3. After signing in, your browser will display a dialog asking permission to open a link in VS Code. Click Allow.

4. Return to VS Code and accept any remaining permission dialogs. The wizard will display your IMS username and enable the Next button.

   Each dialog may include a “Don’t ask again” or “Always allow” option. Selecting it streamlines future sign-ins so you do not need to confirm each step every time.

1. Review the summary of your selections, then click Complete Setup.

2. Sage will now:

   • Fork the Production repository for each selected group (if not already forked in your GitHub account)
   • Clone the QA (Contribution) repository for each selected group
   • Clone the Production fork for each selected group

   The Tutorials-Contribution repository is very large. Cloning it may take several minutes. Sage displays progress for each repository as it works.

3. When all repositories have been cloned, completely close VS Code and reopen it to complete initialization.

After reopening VS Code and clicking the Sage icon in the Activity Bar:

1. Wait for the spinning circular arrow in the status bar to disappear, indicating that extensions have finished loading.

2. If you see a Setup Workspace button, the setup wizard did not complete successfully — return to the previous steps.

3. If you see an Initialize your Sage session button, click it. Sage will re-authenticate with GitHub and IMS and then retrieve your assigned tutorials, issues, and pull requests. This takes approximately 60–90 seconds.

4. Once initialization is complete, you will see three panels in the Sage sidebar:

   • My Tutorials — tutorials assigned to you in IMS, plus unpublished tutorials found in your cloned repositories
   • My GitHub Issues — GitHub issues assigned to or mentioning you
   • My Pull Requests — active pull requests in your repositories

The My Tutorials panel shows a distilled view of the content you work on, combining data from IMS and your cloned repositories.

1. Each entry shows the tutorial’s slug (URL name). Click the ABC toggle button in the panel header to switch between slug view and title view.

2. Each entry also shows a status label (for example, In Production, Needs Review, New - Unpublished).

3. Click any tutorial entry to open its Markdown file in the editor.

4. Right-click a tutorial entry to access the context menu, which includes:

   • QA Preview — opens the tutorial in the QA Tutorial Navigator in your browser
   • Preview — opens a live preview panel directly inside VS Code
   • Edit Validation Rules — opens or creates the rules.vr file
   • Reveal in Explorer — switches to the Explorer view and highlights the tutorial folder
   • Commit to QA — stages and commits your changes to the QA repository
   • Promote QA to Production — automates the full publish-to-production workflow
   • Edit Front Matter — opens the front matter editor UI
   • Mark as Reviewed — marks the tutorial as reviewed in IMS

Sage provides a high-fidelity in-editor preview of your tutorial that renders approximately 95% of the production output, including interactive validation questions.

1. With a tutorial’s Markdown file open, right-click the tutorial in the My Tutorials panel and select Preview, or use the Command Palette and run Sage: Preview Current File.

2. The preview panel opens alongside your editor. Scroll through it to review formatting, images, and step structure.

3. To test a validation question, click answers in the preview just as a reader would. To reset the question state, click the Reset Preview button at the top of the preview panel.

Sage validates your tutorial file every time you save it and displays results in VS Code’s Problems panel.

1. Save your Markdown file (Ctrl+S / Cmd+S).

2. Open the Problems panel (View > Problems) to see any errors or warnings, such as:

   • Missing required front matter fields
   • Tags that do not exist in IMS
   • Image filename case mismatches (which cause images to disappear in production)
   • Code blocks with blank lines adjacent to fence markers (which break the copy button)

3. Click any problem entry to jump directly to the relevant line in your editor.

The front matter editor provides a form-based UI for editing the YAML header of your tutorial without editing raw text.

1. Right-click the tutorial in My Tutorials and select Edit Front Matter.

2. The editor panel opens and displays your current tags, primary tag, author information, estimated time, and other fields.

3. To search for and add a tag, type in the tag search box — Sage queries its local cache of IMS tags for fast results.

4. To change the primary tag, click any existing tag in the primary tag section.

5. Click Save when you are done. Sage updates the front matter in the Markdown file automatically.

1. After making and saving your changes, right-click the tutorial in My Tutorials and select Commit to QA.

2. A dialog lists all changed files for this tutorial. Select the files you want to include in the commit (for example, the Markdown file and any new images).

3. Check Automatically sync to also push the commit to the remote repository.

4. Click Commit Changes. Sage stages, commits, and optionally pushes your changes in a single operation.

When your tutorial is ready for production, Sage automates the entire publish workflow — normally a multi-step manual process.

1. Right-click the tutorial in My Tutorials and select Promote QA to Production.

2. Sage will:

   • Sync your fork of the Production repository with the upstream
   • Copy the tutorial files from the QA repository to your Production fork
   • Commit the changes
   • Open a pull request against the main Production repository

3. Review the pull request details and click Create to submit.

4. Curators will review and merge your pull request to publish the tutorial to production.