Automating Your Technical Blog with GitHub Actions

Modern documentation workflows demand automation. Manually converting documents and publishing them is error-prone and time-consuming. In this guide, we'll set up a GitHub Actions pipeline that automatically converts uploaded documents to Markdown using the mdstill API.

Overview

The workflow is straightforward:

1. A contributor uploads a document (PDF, DOCX, etc.) to a specific directory in the repo
2. A GitHub Action triggers on push
3. The action calls the mdstill API to convert the document
4. The resulting Markdown is committed back to the repo
5. A static site generator rebuilds the documentation site

Setup

First, you'll need an mdstill API key. Store it as a GitHub secret named MDSTILL_API_KEY.

Then, create the directory structure:

docs/
  uploads/     # Drop source documents here
  converted/   # Markdown output goes here

Workflow File

Create .github/workflows/convert-docs.yml:

name: Convert Documents
on:
  push:
    paths:
      - 'docs/uploads/**'

jobs:
  convert:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Convert new documents
        run: |
          for file in docs/uploads/*; do
            curl -X POST https://mdstill.com/api/convert \
              -F "file=@$file" \
              -o "docs/converted/$(basename $file .pdf).md"
          done

      - name: Commit converted files
        run: |
          git config user.name "mdstill-bot"
          git add docs/converted/
          git commit -m "Auto-convert documents" || true
          git push

Deployment

Once the Markdown files are committed, your existing static site generator (Hugo, Astro, Next.js, etc.) can pick them up during the next build. The entire pipeline runs in under 30 seconds for typical document sizes.

This approach ensures your documentation is always up-to-date and consistently formatted, without any manual intervention.