diff --git a/images/validate-ai-gh-action.png b/images/validate-ai-gh-action.png new file mode 100644 index 00000000..59567767 Binary files /dev/null and b/images/validate-ai-gh-action.png differ diff --git a/images/validation-report-gh-action.png b/images/validation-report-gh-action.png new file mode 100644 index 00000000..ab4491b3 Binary files /dev/null and b/images/validation-report-gh-action.png differ diff --git a/maps/dita-articles.ditamap b/maps/dita-articles.ditamap index f8521d4c..648bc80d 100644 --- a/maps/dita-articles.ditamap +++ b/maps/dita-articles.ditamap @@ -43,6 +43,7 @@ + - + Building and Publishing Using a Script Radu Coravu diff --git a/topics/building_validating_and_publishing_using_github_actions.dita b/topics/building_validating_and_publishing_using_github_actions.dita new file mode 100644 index 00000000..d5dfadb9 --- /dev/null +++ b/topics/building_validating_and_publishing_using_github_actions.dita @@ -0,0 +1,96 @@ + + + + Building Validating And Publishing Using GitHub Actions + + Radu Coravu + + + + + +

If you have a GitHub hosted DITA XML project (either on a private or public repository) + you can define GitHub actions to validate and publish your DITA XML project.

+

As an example the Oxygen XML Blog contains GitHub actions to validate and publish a DITA + XML project:

    +
  • Validate the entire DITA project using the Oxygen Validate and Check for + Completeness command line script:
      +
    • Define in the GitHub project's Settings->Secrets and + variables->Actions category a variable named + SCRIPTING_LICENSE_KEY which has as value the Oxygen + scripting license key.
      • +
    • Set up a Gradle build file which + downloads an Oxygen all platforms kit, licenses it and runs it over the + DITA Map. The build file also applies an XSLT stylesheet over the XML + report to produce a Markdown report.
      • +
    • Create a GitHub action which is + triggered by pull requests or modifications done to pull requests, sets + up Java, calls the Gradle build file and then if there are errors + outputs the report in Markdown format using the + $GITHUB_STEP_SUMMARY variable. The report of + running such a GitHub action looks like this: + +
      • +
    • +
    +
  • Validate only the changed topics in a pull request using OpenAI and a + custom prompt to check for example for grammar problems:
      +
    • Define in the GitHub project's Settings->Secrets and + variables->Actions category a variable named + AI_LICENSE_KEY which has as value the OpenAI + key.
      • +
    • Create a custom Gradle build file which + finds all changed topics in the pull request and then uses the API key + to send the content to OpenAI asking for a report of changes in + Markdown format.
      • +
    • Create a custom GitHub action which + saves the list of changed files as an environmental variable and passes + this information to the build file, afterwards displaying the report + using the $GITHUB_STEP_SUMMARY variable. The report of + running such a GitHub action looks like this: + +
      • +
    • +
  • Publish the Oxygen XML Blog DITA XML project to Netlify using a + GitHub action:
      +
    • Create an account on Netlify and create a site for the account. + Create an authentication token to be + able to access Netlify from a command line and deploy to the site from a + remote location. In the Netlify UI obtain the ID of your site.
      • +
    • Define in the GitHub project's Settings->Secrets and + variables->Actions category two variables to keep the Netlify + authentication token and the side ID values. Create a secret also for + the Oxygen Publishing Engine license key.
      • +
    • Create a custom Gradle build file which + downloads the Oxygen Publishing Engine, licenses it, produces the + output and stores it in a specific folder.
      • +
    • Create a custom GitHub action which runs the + build file and then uses a plugin to upload the entire folder to the + Netlify web site. The end result looks like this: .
      • +
    • +

+ +