Integration Guide

Publish markdown from GitHub Actions

Push to your repo and your markdown goes live. No manual steps, no copy-pasting into a CMS. Just git push and done.

Why publish markdown from CI?

Your docs live in your repo. Your changelog is a markdown file. Your README is already written. The only missing piece is getting those files onto a URL that anyone can open in a browser.

• ✓ Auto-publish docs on merge. Every time you merge to main, your latest documentation goes live at a stable URL.
• ✓ Ship changelogs with releases. Tag a release and your CHANGELOG.md becomes a shareable page automatically.
• ✓ Keep READMEs in sync. Your project README updates whenever you push changes. No drift between repo and published version.
• ✓ Share internal docs externally. Publish internal markdown files to a URL you can send to clients or stakeholders who don't have repo access.

Setup in 3 steps

Complete workflow example

This workflow installs MDtoLink, authenticates with your API key, and publishes every markdown file in the docs/ directory on every push to main.

name: Publish Docs with MDtoLink

on:
  push:
    branches: [main]
    paths:
      - "docs/**/*.md"
      - "README.md"
      - "CHANGELOG.md"

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install MDtoLink
        run: npm install -g mdtolink

      - name: Publish markdown files
        env:
          MDTOLINK_API_KEY: ${{ secrets.MDTOLINK_API_KEY }}
        run: |
          mdtolink publish docs/*.md
          mdtolink publish README.md
          mdtolink publish CHANGELOG.md

The paths filter ensures the workflow only runs when markdown files actually change. No wasted CI minutes.

Publish on release (alternative)

If you only want to publish when you tag a release, swap the trigger:

name: Publish on Release

on:
  release:
    types: [published]

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

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: npm install -g mdtolink

      - name: Publish changelog
        env:
          MDTOLINK_API_KEY: ${{ secrets.MDTOLINK_API_KEY }}
        run: mdtolink publish CHANGELOG.md

This pairs well with tools like changesets or semantic-release. Your changelog gets a public URL the moment you ship a new version.

Tips

• Use path filters. Only trigger the workflow when markdown files change. This keeps your CI fast and avoids unnecessary API calls.
• Pin the MDtoLink version. Use npm install -g mdtolink@latest or pin to a specific version for reproducible builds.
• Publish selectively. You don't have to publish everything. List specific files or use glob patterns to target only what you need.
• Check the output. MDtoLink prints the published URL for each file. You can capture it in subsequent steps to post in Slack, update a PR comment, or write it to a file.

Frequently asked questions

How do I store my MDtoLink API key in GitHub Actions?

Go to your GitHub repo settings, then Secrets and variables > Actions. Click 'New repository secret' and add your key as MDTOLINK_API_KEY. The workflow references it with ${{ secrets.MDTOLINK_API_KEY }}.

Can I publish multiple markdown files in one workflow run?

Yes. You can pass multiple file paths to the publish command, or use a glob pattern like 'mdtolink publish docs/*.md' to publish all markdown files in a directory.

Will re-publishing the same file create a new URL?

No. MDtoLink detects the file and updates the existing document in place. The URL stays the same, so any shared links keep working.

Do I need a paid plan to use MDtoLink in CI/CD?

The free plan works in CI/CD, but published links expire after 7 days. For permanent links and higher document limits, upgrade to Pro ($6/mo) or Publisher ($18/mo). See the pricing page for details.