Publishing oXygen XML project to GitHub Pages

Prerequisites

Before starting, make sure you have the following:

Prepare Your DITA Project

  1. Open your DITA project in oXygen XML Editor.
  2. Create a .ditamap file for your project if it doesn’t exist yet.
  3. Make sure all output files are saved within the /docs subfolder your local GitHub repository folder.

Note:
Don’t save your output files directly in the main repository folder!

Create a Transformation Scenario

  1. In the Transformation Scenarios right bottom panel, click the plus (+) button.
  2. Select DITA-OT Transformation from the dropdown. Selecting DITA-OT Transformation
  3. In the dialogue that appears, choose WebHelp Responsive.
  4. Name your scenario and select a template under the Templates tab.
  5. Under the Output tab:
    • Choose an output directory within your local GitHub repository (e.g., yourrepositoryname/docs) to ensure compatibility with GitHub Pages.
    • Ensure the Temporary files directory is different from the Output directory. Transformation Scenario Settings
  6. Click OK to save your scenario.

Generating the WebHelp Output

  1. Select the transformation scenario you have just created in the Transformation Scenarios panel.
  2. Click the Apply Transformation Scenario button (red triangle icon). Applying Transformation Scenario

oXygen XML will generate a WebHelp Responsive website in the specified output folder.

Reviewing and Preparing Your Project for Publishing

  1. Open the output folder and confirm that all files were generated successfully.
  2. Launch GitHub Desktop.
  3. In the Changes tab, review the file modifications.
  4. Enter a commit summary (e.g., “Add WebHelp output for publishing”).
  5. Click Commit to main (or your current working branch).
  6. Click Push origin to upload the changes to your GitHub repository.

Enabling GitHub Pages

  1. Open your repository on Github.com.
  2. Navigate to the Settings tab.
  3. In the left sidebar, select Pages.
  4. Under Source, configure the following settings:
    • Branch: main (or your current working branch),
    • Folder: /docs.
  5. Click Save.

GitHub will build and publish your documentation automatically. Once the publication process is completed, a link to your live GitHub Pages site will appear on the same page.

  1. Visit the link to your GitHub Pages site to view your published oXygen XML content.