discussion-to-markdown

Current Status: v1.1.0-beta — Production hardening (Milestone 2) in progress

A GitHub Action to sync GitHub Discussions to Markdown files with GitOps-driven state management. Ideal for creating RAG (Retrieval-Augmented Generation) knowledge bases or publishing discussions as documentation.

Features (v1.1.0-beta)

• Sync Discussions: Fetches Discussions via GraphQL API.
• RAG-Ready Markdown: structured output with YAML frontmatter.
• Q&A Support: Automatically appends "✅ Solution" for resolved discussions.
• Idempotency: Only updates files if content has changed (checks updated_at).
• Secure: Validates token permissions and redacts secrets in logs.

🔴 Live Demo & Proof of Concept

This repository practices Dogfooding. The demo/ directory contains live markdown files generated by this Action from the repository's own discussions.

• Source: Repository Discussions
• Output: Sync Result (Markdown)
• Status: The "Dogfooding Test" workflow runs on every push to verify the sync process.

Note on Data: The discussions in this repository are seeded with realistic demo content to test various edge cases (images, code blocks, Q&A). They are labeled with demo.

Usage

Basic Workflow

Create a workflow file .github/workflows/sync-discussions.yml:

name: Sync Discussions to Markdown

on:
  schedule:
    - cron: '0 0 * * *' # Run daily
  workflow_dispatch:

permissions:
  contents: write
  discussions: read

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

      - name: Sync Discussions
        uses: ElmentorProgram/discussion-to-markdown@v1.1.0-beta
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          output_dir: docs/discussions
          sync_mode: q_and_a
          
      - name: Commit Changes
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add docs/discussions
          git commit -m "docs: sync discussions" || echo "No changes to commit"
          git push

Inputs

Input	Description	Required	Default
token	GitHub token (discussions:read scope required)	✅ Yes
output_dir	Directory to write synced markdown files	❌ No	docs/discussions
sync_mode	Sync mode: 'document' or 'q_and_a'	❌ No	document
category_filter	Comma-separated category names to sync	❌ No
organize_by_category	Organize files into subdirectories by category	❌ No	false
generate_index	Generate an index (README.md) in output_dir	❌ No	true
prune_missing	Delete local files if missing from API	❌ No	false

Output Format

Files are named {number}-{slug}.md.

---
id: 123
number: 123
title: "How to install?"
category: "Q&A"
author: "octocat"
created_at: "2024-01-01T00:00:00Z"
updated_at: "2024-01-02T00:00:00Z"
url: "https://github.com/.../123"
managed_by: "discussion-to-markdown"
resolved: true
---

# How to install?

I cannot find the install button...

## ✅ Solution

You just need to click...

Contributing

Prerequisites

• Node.js 20+
• .env file with GITHUB_TOKEN

Development Workflow

1. Install dependencies: npm install
2. Run tests: npm test
3. Verify locally: npm run verify:local (This runs the action logic against your real repo using the token in .env)
4. Build: npm run package

License

This project is licensed under the MIT License - see the LICENSE file for details.