Initial commit

2025-11-29 18:03:12 +08:00
commit bc9ae138e4
28 changed files with 7069 additions and 0 deletions
--- a/skills/pandoc/SKILL.md
+++ b/skills/pandoc/SKILL.md
@@ -0,0 +1,398 @@
+---
+name: pandoc
+description: Automatically assist with Pandoc document conversions when user mentions converting markdown to PDF/DOCX/HTML or other formats. Validate YAML frontmatter, check dependencies (bibliography, images), and provide format-specific conversion guidance. Use when user asks about citations, academic papers, presentations, or document generation from markdown.
+allowed-tools: Bash, Read, Write
+---
+
+# Pandoc Document Conversion
+
+## Overview
+
+Provide expert assistance for converting markdown documents to PDF, DOCX, HTML, and presentations using Pandoc. Handle YAML frontmatter validation, bibliography setup, template generation, and format-specific conversion guidance.
+
+## When to Use This Skill
+
+Automatically invoke this skill when the user:
+- Mentions "convert to PDF", "generate PDF", "export to Word/DOCX"
+- Asks about "pandoc", "markdown to PDF", "document conversion"
+- Shows markdown with YAML frontmatter
+- Asks about citations, bibliographies, academic papers
+- Requests help with presentations (Beamer, reveal.js)
+- Mentions LaTeX, XeLaTeX, or PDF engines
+- Has errors converting documents
+
+**Do not use** for:
+- Simple markdown rendering/preview
+- Other converters (not Pandoc)
+- Markdown syntax questions (unless conversion-related)
+
+## Plugin Resources
+
+### Scripts
+- `scripts/validate.py` - Python validation script for YAML frontmatter and dependencies
+
+### Templates (in assets/templates/)
+- `academic-paper.yaml` - Academic paper with citations
+- `thesis-report.yaml` - Thesis/report with custom title page
+- `presentation-beamer.yaml` - LaTeX Beamer slides
+- `presentation-revealjs.yaml` - reveal.js web slides
+- `article-simple.yaml` - Simple article format
+- `defaults-pdf.yaml` - Reusable PDF defaults file
+- `references.bib` - BibTeX bibliography template
+- `Makefile` - Project automation template
+
+### Citation Styles (in assets/csl/)
+- `harvard.csl` - Harvard Cite Them Right style
+- `apa.csl` - APA 7th edition style
+- `ieee.csl` - IEEE style
+
+Users can copy these to their project without downloading separately.
+
+### References
+- `references/conversion_guide.md` - Format-specific instructions
+- `references/yaml_reference.md` - Complete YAML variables
+- `references/templates_guide.md` - Template usage guide
+- `references/troubleshooting.md` - Common errors and solutions
+
+## Core Workflows
+
+### 1. Validate Document
+
+**User asks:** "Check if my document is ready to convert"
+
+**Workflow using tools directly:**
+
+```bash
+# Path to validation script
+PLUGIN_DIR="~/.claude/marketplaces/cadrianmae-claude-marketplace/plugins/pandoc"
+VALIDATE_SCRIPT="$PLUGIN_DIR/skills/pandoc/scripts/validate.py"
+
+# Run validation
+python3 "$VALIDATE_SCRIPT" document.md
+```
+
+**Suggest to user:** "You can also validate with: `/pandoc:validate document.md`"
+
+### 2. Create from Template
+
+**User asks:** "Help me create an academic paper"
+
+**Workflow using tools directly:**
+
+```bash
+# Path to templates
+PLUGIN_DIR="~/.claude/marketplaces/cadrianmae-claude-marketplace/plugins/pandoc"
+TEMPLATE="$PLUGIN_DIR/skills/pandoc/assets/templates/academic-paper.yaml"
+
+# Copy template to user's file
+cp "$TEMPLATE" paper.md
+
+# Show what to edit
+echo "Created paper.md from template"
+echo ""
+echo "Edit the following fields:"
+echo "  - title: Your paper title"
+echo "  - author: Your name"
+echo "  - bibliography: Path to your .bib file"
+```
+
+**Suggest to user:** "Or use the template command: `/pandoc:template academic-paper paper.md`"
+
+### 3. Convert Document
+
+**User asks:** "Convert this to PDF"
+
+**Workflow using tools directly:**
+
+```bash
+# Validate first
+PLUGIN_DIR="~/.claude/marketplaces/cadrianmae-claude-marketplace/plugins/pandoc"
+python3 "$PLUGIN_DIR/skills/pandoc/scripts/validate.py" document.md
+
+if [[ $? -eq 0 ]]; then
+    # Check for bibliography
+    if grep -q "^bibliography:" document.md; then
+        CITEPROC="--citeproc"
+        echo "Bibliography detected - enabling citations"
+    fi
+
+    # Convert with smart defaults
+    pandoc document.md -o document.pdf \
+        --pdf-engine=pdflatex \
+        --number-sections \
+        $CITEPROC
+
+    if [[ $? -eq 0 ]]; then
+        echo "✅ Conversion successful: document.pdf"
+    else
+        echo "❌ Conversion failed - check errors above"
+    fi
+else
+    echo "❌ Validation failed - fix errors before converting"
+fi
+```
+
+**Suggest to user:** "Or use the convert command with smart defaults: `/pandoc:convert document.md document.pdf`"
+
+### 4. Add Frontmatter to Existing File
+
+**User asks:** "This markdown file needs frontmatter"
+
+**Workflow using tools directly:**
+
+```bash
+FILE="document.md"
+PLUGIN_DIR="~/.claude/marketplaces/cadrianmae-claude-marketplace/plugins/pandoc"
+TEMPLATE="$PLUGIN_DIR/skills/pandoc/assets/templates/academic-paper.yaml"
+
+# Check if already has frontmatter
+if head -n 1 "$FILE" | grep -q "^---$"; then
+    echo "File already has frontmatter"
+    echo "Use Read tool to view and Edit tool to modify"
+else
+    # Read existing content
+    CONTENT=$(cat "$FILE")
+
+    # Create temp file with template + content
+    {
+        cat "$TEMPLATE"
+        echo ""
+        echo "$CONTENT"
+    } > "${FILE}.tmp"
+
+    # Replace original
+    mv "${FILE}.tmp" "$FILE"
+
+    echo "✅ Added frontmatter to $FILE"
+    echo "Edit the YAML fields at the top of the file"
+fi
+```
+
+**Suggest to user:** "Or use: `/pandoc:frontmatter document.md`"
+
+### 5. Setup Bibliography
+
+**User asks:** "How do I add citations?"
+
+**Workflow:**
+
+1. **Create bibliography file:**
+   ```bash
+   PLUGIN_DIR="~/.claude/marketplaces/cadrianmae-claude-marketplace/plugins/pandoc"
+   BIB_TEMPLATE="$PLUGIN_DIR/skills/pandoc/assets/templates/references.bib"
+
+   cp "$BIB_TEMPLATE" references.bib
+   echo "Created references.bib - edit to add your sources"
+   ```
+
+2. **Copy CSL file (bundled with plugin):**
+   ```bash
+   PLUGIN_DIR="~/.claude/marketplaces/cadrianmae-claude-marketplace/plugins/pandoc"
+
+   # Choose one:
+   cp "$PLUGIN_DIR/skills/pandoc/assets/csl/harvard.csl" .
+   cp "$PLUGIN_DIR/skills/pandoc/assets/csl/apa.csl" .
+   cp "$PLUGIN_DIR/skills/pandoc/assets/csl/ieee.csl" .
+   ```
+
+3. **Update frontmatter:**
+   Use Edit tool to add to document:
+   ```yaml
+   bibliography: references.bib
+   csl: harvard.csl
+   link-citations: true
+   ```
+
+4. **Explain citation syntax:**
+   ```markdown
+   Use [@citekey] for citations
+   Use @citekey for in-text citations
+   ```
+
+**Note:** Plugin includes Harvard, APA, and IEEE styles. For other styles, download from https://github.com/citation-style-language/styles
+
+### 6. Restyle Document to Match Template
+
+**User asks:** "Transform this document to match academic paper format"
+
+**Workflow using tools directly:**
+
+```bash
+PLUGIN_DIR="~/.claude/marketplaces/cadrianmae-claude-marketplace/plugins/pandoc"
+INPUT_FILE="document.md"
+TARGET_STYLE="academic-paper"  # or thesis, article, etc.
+
+# 1. Backup original
+cp "$INPUT_FILE" "${INPUT_FILE}.bak"
+echo "Backed up to ${INPUT_FILE}.bak"
+
+# 2. Read current frontmatter
+echo "Current frontmatter:"
+sed -n '/^---$/,/^---$/p' "$INPUT_FILE"
+
+# 3. Get target template
+TEMPLATE="$PLUGIN_DIR/skills/pandoc/assets/templates/${TARGET_STYLE}.yaml"
+
+if [[ -f "$TEMPLATE" ]]; then
+    # 4. Extract content (everything after second ---)
+    CONTENT=$(sed -n '/^---$/,/^---$/{/^---$/d;p};/^---$/,$p' "$INPUT_FILE" | tail -n +2)
+
+    # 5. Combine template frontmatter + content
+    {
+        cat "$TEMPLATE"
+        echo ""
+        echo "$CONTENT"
+    } > "${INPUT_FILE}.tmp"
+
+    # 6. Replace original
+    mv "${INPUT_FILE}.tmp" "$INPUT_FILE"
+
+    echo "✅ Restyled to $TARGET_STYLE format"
+    echo ""
+    echo "Next steps:"
+    echo "  1. Edit frontmatter fields (author, title, etc.)"
+    echo "  2. Validate: Check document is ready"
+    echo "  3. Convert: Generate output"
+else
+    echo "❌ Template not found: $TARGET_STYLE"
+    echo "Available: academic-paper, thesis, article, presentation-beamer, presentation-reveal"
+fi
+```
+
+**Common use cases:**
+
+1. **OCR/PDF → Academic:**
+   - Remove: `processed_date`, `ocr_model`, `source_type`
+   - Add: `author`, `bibliography`, `documentclass`
+
+2. **Draft → Thesis:**
+   - Add: `supervisor`, `institution`, `department`
+   - Add: `toc`, `lof`, `lot`
+
+3. **Blog → Paper:**
+   - Add: `bibliography`, `csl`, `numbersections`
+   - Update: `documentclass` to `report`
+
+**Suggest to user:** "Or use: `/pandoc:restyle document.md academic-paper`"
+
+## Error Diagnosis
+
+### Common Errors and Fixes
+
+**Missing bibliography file:**
+```bash
+# Check if file exists
+if [[ ! -f references.bib ]]; then
+    echo "Bibliography file not found"
+    echo "Create it with: /pandoc:template bibtex references.bib"
+fi
+```
+
+**YAML syntax errors:**
+```bash
+# Run validation to see exact error
+python3 "$PLUGIN_DIR/skills/pandoc/scripts/validate.py" document.md
+# Explains: tabs vs spaces, missing quotes, etc.
+```
+
+**Missing LaTeX packages (for PDF):**
+```bash
+echo "Install LaTeX packages:"
+echo "  sudo dnf install texlive-scheme-medium"
+echo "  # or"
+echo "  sudo apt-get install texlive-latex-base texlive-latex-extra"
+```
+
+**Unicode errors in PDF:**
+```bash
+echo "Use XeLaTeX instead of pdflatex:"
+pandoc document.md -o document.pdf --pdf-engine=xelatex
+```
+
+## Format-Specific Guidance
+
+### PDF Conversion
+- **Default:** pdflatex (included in validation/conversion workflow)
+- **Unicode:** Use `--pdf-engine=xelatex`
+- **Custom margins:** Add to frontmatter: `geometry: margin=1.5in`
+
+### HTML Conversion
+```bash
+pandoc document.md -o document.html \
+    --standalone \
+    --self-contained \
+    --toc
+```
+
+### DOCX Conversion
+```bash
+pandoc document.md -o document.docx --standalone
+```
+
+### Presentations
+```bash
+# Beamer (PDF slides)
+pandoc slides.md -o slides.pdf --to beamer
+
+# reveal.js (web slides)
+pandoc slides.md -o slides.html --to revealjs --standalone
+```
+
+## Best Practices
+
+1. **Always validate before converting** - Use validation script directly
+2. **Use templates** - Copy from `assets/templates/` directory
+3. **Check files early** - Verify `.bib`, `.csl`, images exist
+4. **Use relative paths** - Makes documents portable
+5. **Explain steps clearly** - Show what tools you're using
+6. **Suggest user commands** - Mention slash commands as convenient alternatives
+7. **Handle errors gracefully** - Run validation, explain fixes
+
+## Available User Commands
+
+The plugin provides these slash commands for users:
+
+- `/pandoc:template <type> [file]` - Generate document templates
+- `/pandoc:validate <file>` - Validate frontmatter and dependencies
+- `/pandoc:convert <input> <output> [options]` - Convert with smart defaults
+- `/pandoc:frontmatter <file> [type]` - Add/update frontmatter
+- `/pandoc:restyle <input> <target-style>` - Transform document to match template style
+- `/pandoc:defaults <format> [file]` - Generate defaults file
+
+**As the skill:** Use the underlying tools (scripts, pandoc CLI) directly via Bash. Mention these commands as suggestions for the user.
+
+## Reference Documentation
+
+Load these when needed for detailed information:
+
+- **`references/conversion_guide.md`** - Format-specific conversion details
+- **`references/yaml_reference.md`** - All YAML variables explained
+- **`references/templates_guide.md`** - Template customization guide
+- **`references/troubleshooting.md`** - Comprehensive error solutions
+
+## Quick Reference
+
+**Plugin directory:**
+```bash
+PLUGIN_DIR="~/.claude/marketplaces/cadrianmae-claude-marketplace/plugins/pandoc"
+```
+
+**Validation:**
+```bash
+python3 "$PLUGIN_DIR/skills/pandoc/scripts/validate.py" file.md
+```
+
+**Templates:**
+```bash
+cp "$PLUGIN_DIR/skills/pandoc/assets/templates/academic-paper.yaml" output.md
+```
+
+**Conversion (basic):**
+```bash
+pandoc input.md -o output.pdf --pdf-engine=pdflatex --number-sections
+```
+
+**Conversion (with citations):**
+```bash
+pandoc input.md -o output.pdf --pdf-engine=pdflatex --citeproc --number-sections
+```