DEV Community

loading...
Cover image for My GitHub Action for Markdown Pre-Processing

My GitHub Action for Markdown Pre-Processing

The Sharp Ninja
・2 min read

Over the years, I have come to appreciate the markedpp NPM package for it's ability to stitch together a single Markdown document from multiple files. Some of the projects I've used it on include:

  1. Body & Brain RPG - A table-top RPG that my son and I have worked on for years.
  2. Pattern-Lang - Specification website.
  3. GPS.Markedpp - VS Code Extension for combining and publishing markdown files in the above projects.

So fast-forward to this weekend and I started messing around with PlantUML and have started working on a Blazor-based UML tool called UML Mate. I'm designing the app with Markdown + PlantUML files and so would need to use VS Code to use my markedpp extension. But then it hit me, I can use a GitHub Action to execute markedpp, and I already have the code to do it! Enter gatewayprogrammingschool/action-markedpp, which you add as a secondary GitHub Action file as such:

# This is a basic workflow to help you get started with Actions

name: Markedpp

# Controls when the action will run. 
on:
  # Triggers the workflow on push or pull request events but only for the main branch
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  # This workflow contains a single job called "build"
  build:
    # The type of runner that the job will run on
    runs-on: ubuntu-latest

    # Steps represent a sequence of tasks that will be executed as part of the job
    steps:
      - uses: actions/checkout@v2
      - uses: gatewayprogrammingschool/action-markedpp@testing
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          manifest: ./.gps.markedpp
Enter fullscreen mode Exit fullscreen mode

Markedpp.yml - source

Now, whenever there is a checkin, the action will run and apply markedpp based on the manifest file:


{
  "rootSourceFiles": [
    "./README.md"
  ],
  "outputDirectory": "./docs",
  "options": {
    "gfm": true,
    "include": true,
    "toc": true,
    "numberedheadings": true,
    "ref": true,
    "breaks": true,
    "tags": true,
    "level": 3,
    "minlevel": 1,
    "autonumber": true,
    "autoid": true,
    "githubidv": false
  }
}
Enter fullscreen mode Exit fullscreen mode

.gps.markedpp - source

The options are straight from markedpp itself, the files listed in rootSourceFiles are each the root of a document chain and will be rendered to the outputDirectory. Choosing ./docs as your output directory allows you to easily assign GitHub Pages to process the output.

I'm not quit ready to publish the GH Action quite yet as I'm going to add PlantUML processing as well so that my documentation can be seamlessly created and published.

If you would like to test out the action, just add another action yaml file to your repository and add the .gps.markedpp setting s file to the root of your repository. You can point the output directory to ./docs and publish the results with GitHub pages.

Discussion (0)