commit bc9ae138e4727569946a25bc98b71064e6f1b104 Author: Zhongwei Li Date: Sat Nov 29 18:03:12 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..59c8bc1 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,15 @@ +{ + "name": "pandoc", + "description": "Document conversion toolkit for Pandoc with templates, validation, and format-specific helpers. Convert markdown to PDF, DOCX, HTML, and presentations with smart defaults and YAML frontmatter validation.", + "version": "1.0.0", + "author": { + "name": "Mae Capacite", + "email": "cadrianmae@users.noreply.github.com" + }, + "skills": [ + "./skills" + ], + "commands": [ + "./commands" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..fb86567 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# pandoc + +Document conversion toolkit for Pandoc with templates, validation, and format-specific helpers. Convert markdown to PDF, DOCX, HTML, and presentations with smart defaults and YAML frontmatter validation. diff --git a/commands/convert.md b/commands/convert.md new file mode 100644 index 0000000..31b5cad --- /dev/null +++ b/commands/convert.md @@ -0,0 +1,41 @@ +--- +description: Convert markdown to PDF/DOCX/HTML with validation +argument-hint: [options] +allowed-tools: Bash, Read +disable-model-invocation: true +--- + +# /pandoc:convert - Convert Document + +Ask Claude to validate and convert your markdown file. + +## Quick Reference + +**Basic conversions:** +```bash +pandoc document.md -o document.pdf +pandoc document.md -o document.html --standalone +pandoc document.md -o document.docx +``` + +**With citations:** +```bash +pandoc paper.md -o paper.pdf --citeproc --number-sections +``` + +**Custom options:** +```bash +pandoc doc.md -o doc.pdf --pdf-engine=xelatex -V geometry:margin=1.5in +``` + +## Common Issues + +- Missing LaTeX: `sudo dnf install texlive-scheme-medium` +- Unicode errors: Use `--pdf-engine=xelatex` +- Citations not showing: Add `--citeproc` flag + +## Ask Claude + +"Validate and convert paper.md to PDF with citations" +"Convert this document to HTML with table of contents" +"Help me convert to PDF - it's giving errors" diff --git a/commands/defaults.md b/commands/defaults.md new file mode 100644 index 0000000..6c6deb7 --- /dev/null +++ b/commands/defaults.md @@ -0,0 +1,49 @@ +--- +description: Generate defaults file for consistent conversions +argument-hint: [output-file] +allowed-tools: Bash, Write +disable-model-invocation: true +--- + +# /pandoc:defaults - Defaults File + +Ask Claude to create a defaults file for project-wide settings. + +## Quick Reference + +**PDF Defaults:** +```yaml +from: markdown +to: pdf +pdf-engine: pdflatex +citeproc: true +number-sections: true +metadata: + fontsize: 12pt + geometry: margin=1in +``` + +**Use defaults:** +```bash +pandoc doc.md --defaults=defaults.yaml -o output.pdf +``` + +**Makefile Integration:** +```makefile +%.pdf: %.md defaults.yaml + pandoc $< --defaults=defaults.yaml -o $@ +``` + +## Available Formats + +- `pdf` - PDF with pdflatex +- `html` - Standalone HTML +- `docx` - Word documents +- `beamer` - PDF presentations +- `revealjs` - Web presentations + +## Ask Claude + +"Create a PDF defaults file for my project" +"Set up defaults for consistent conversions" +"Generate defaults for HTML output" diff --git a/commands/frontmatter.md b/commands/frontmatter.md new file mode 100644 index 0000000..932328b --- /dev/null +++ b/commands/frontmatter.md @@ -0,0 +1,51 @@ +--- +description: Add/update YAML frontmatter in markdown +argument-hint: [template-type] +allowed-tools: Bash, Read, Write +disable-model-invocation: true +--- + +# /pandoc:frontmatter - Add Frontmatter + +Ask Claude to add or update YAML frontmatter in your markdown file. + +## Quick Reference + +**Minimal Frontmatter:** +```yaml +--- +title: "Document Title" +author: "Your Name" +date: "Date" +--- +``` + +**Academic Paper:** +```yaml +--- +title: "Research Paper" +author: "Student Name" +date: "November 2024" +bibliography: references.bib +csl: harvard.csl +documentclass: report +fontsize: 12pt +geometry: margin=1in +numbersections: true +toc: true +--- +``` + +**Common Fields:** +- `title` - Document title +- `author` - Author name(s) +- `date` - Publication date +- `bibliography` - Path to .bib file +- `csl` - Citation style file +- `lang` - Language (en-GB, en-US) + +## Ask Claude + +"Add frontmatter to this markdown file" +"Update my document with academic template frontmatter" +"This file needs proper YAML frontmatter" diff --git a/commands/help.md b/commands/help.md new file mode 100644 index 0000000..ec19969 --- /dev/null +++ b/commands/help.md @@ -0,0 +1,106 @@ +--- +description: "Get help with the Pandoc plugin - available commands and quick start guide" +disable-model-invocation: true +--- + +# Pandoc Plugin Help + +Quick reference for the Pandoc document conversion plugin. + +## Available Commands + +- `/pandoc:help` - This help message +- `/pandoc:template` - Generate document templates (academic, thesis, presentations) +- `/pandoc:validate` - Validate YAML frontmatter and dependencies +- `/pandoc:convert` - Convert documents with smart defaults +- `/pandoc:frontmatter` - Add or update document metadata +- `/pandoc:restyle` - Transform document to match different template styles +- `/pandoc:defaults` - Generate reusable defaults files + +## Quick Start + +### Ask Claude to help with: + +**Simple conversion:** +> "Convert this markdown file to PDF" + +**Academic papers:** +> "Format this as an academic paper with citations" + +**Presentations:** +> "Turn this into a presentation" + +**Document transformation:** +> "Restyle this document to match thesis format" + +**Validation:** +> "Check if my document is ready to convert" + +## Common Tasks + +### Convert to PDF +Just ask: "Convert document.md to PDF" + +### Add Bibliography +Just ask: "Add bibliography support to this document" + +### Fix Errors +Just ask: "This conversion failed, what's wrong?" + +### Apply Template +Just ask: "Format this as [academic paper / thesis / presentation]" + +## When Things Go Wrong + +Common issues and what to ask: + +**YAML errors:** +> "The YAML frontmatter has errors, can you fix it?" + +**Missing files:** +> "It says bibliography file is missing, help me set this up" + +**LaTeX errors:** +> "The PDF conversion failed with a LaTeX error" + +**Citation issues:** +> "Citations aren't showing up in the output" + +## Templates Available + +- **academic-paper** - Research papers with citations +- **thesis-report** - Thesis/dissertation with custom title page +- **article-simple** - Simple article format +- **presentation-beamer** - LaTeX Beamer slides +- **presentation-revealjs** - Web-based reveal.js slides + +## How It Works + +The plugin auto-activates when you ask about: +- Document conversion +- PDF generation +- Bibliography/citations +- Academic formatting +- Templates + +Just describe what you want to do - no need to know Pandoc syntax! + +## Examples + +> "I have a markdown file about my research, can you convert it to PDF?" + +> "This needs to be formatted as an academic paper with Harvard citations" + +> "Can you check if this document is ready to convert?" + +> "Transform this into thesis format with table of contents" + +## Need More Help? + +For detailed information, use specific commands: +- `/pandoc:template` - Template details +- `/pandoc:convert` - Conversion options +- `/pandoc:validate` - Validation guide +- `/pandoc:restyle` - Document transformation + +Or just ask Claude naturally about what you're trying to accomplish! diff --git a/commands/restyle.md b/commands/restyle.md new file mode 100644 index 0000000..a2f271a --- /dev/null +++ b/commands/restyle.md @@ -0,0 +1,108 @@ +--- +description: Transform document to match target template style +argument-hint: +allowed-tools: Bash, Read, Write +disable-model-invocation: true +--- + +# /pandoc:restyle - Restyle Document + +Ask Claude to transform a document's frontmatter and structure to match a target template style. + +## Available Styles + +- `academic-paper` - Academic paper with citations +- `thesis` - Thesis/report with title page +- `article` - Simple article +- `presentation-beamer` - PDF slides +- `presentation-reveal` - Web slides + +## What It Does + +1. Reads current document and analyzes frontmatter +2. Replaces frontmatter with target template style +3. Preserves all markdown content +4. Suggests structural improvements if needed + +## Quick Reference + +**OCR → Academic Paper:** +```yaml +# Before (OCR metadata) +--- +title: "Document Title" +processed_date: "2025-11-15" +ocr_model: "model-name" +--- + +# After (Academic) +--- +title: "Paper Title" +author: "Author Name" +date: "Month Year" +bibliography: references.bib +csl: harvard.csl +documentclass: report +fontsize: 12pt +geometry: margin=1in +numbersections: true +--- +``` + +**Simple → Thesis:** +```yaml +# Before +--- +title: "Document" +author: "Name" +--- + +# After +--- +title: "Thesis Title" +author: "Student Name" +supervisor: "Supervisor Name" +institution: "University Name" +department: "Department Name" +degree: "Degree Name" +bibliography: references.bib +csl: harvard.csl +documentclass: report +toc: true +lof: true +lot: true +--- +``` + +## Workflow + +1. Backup: `cp document.md document.md.bak` +2. Ask Claude to restyle to target template +3. Review frontmatter changes +4. Edit custom fields (author, title, etc.) +5. Validate: Check document is ready +6. Convert: Generate output + +## Ask Claude + +"Restyle this document to match the thesis template" +"Transform this OCR output to academic paper format" +"Convert this to presentation style" +"Reformat this with proper academic frontmatter" + +## Common Transformations + +**Template from PDF/OCR:** +- Remove: `source`, `processed_date`, `ocr_model`, `processor` +- Add: `author`, `date`, `documentclass`, `geometry` +- Update: `title` to actual document title + +**Blog/Draft → Academic:** +- Add: `bibliography`, `csl`, `documentclass` +- Add: `fontsize`, `geometry`, `numbersections` +- Structure: Academic section organization + +**Article → Thesis:** +- Add: `supervisor`, `institution`, `department`, `degree` +- Add: `toc`, `lof`, `lot` +- Add: Abstract, Declaration, Acknowledgements sections diff --git a/commands/template.md b/commands/template.md new file mode 100644 index 0000000..da13cca --- /dev/null +++ b/commands/template.md @@ -0,0 +1,58 @@ +--- +description: Generate document template with frontmatter +argument-hint: [output-file] +allowed-tools: Bash, Read +disable-model-invocation: true +--- + +# /pandoc:template - Document Templates + +Ask Claude to create a document from template. + +## Available Templates + +- `academic-paper` - Paper with citations +- `thesis` - Thesis/report with title page +- `presentation-beamer` - PDF slides +- `presentation-reveal` - Web slides +- `article` - Simple article +- `bibtex` - Bibliography examples + +## Quick Reference + +**YAML Frontmatter Example:** +```yaml +--- +title: "Paper Title" +author: "Your Name" +date: "November 2024" +bibliography: references.bib +csl: harvard.csl +documentclass: report +fontsize: 12pt +geometry: margin=1in +--- +``` + +**BibTeX Entry Example:** +```bibtex +@article{smith2024, + author = {Smith, John}, + title = {Paper Title}, + journal = {Journal Name}, + year = {2024}, + volume = {42}, + pages = {123--145} +} +``` + +**Citation Syntax:** +```markdown +[@smith2024] or @smith2024 found that... +``` + +## Ask Claude + +"Create an academic paper template" +"Show me the thesis template" +"Set up a new document with bibliography" diff --git a/commands/validate.md b/commands/validate.md new file mode 100644 index 0000000..06bc3e7 --- /dev/null +++ b/commands/validate.md @@ -0,0 +1,51 @@ +--- +description: Validate YAML frontmatter and dependencies +argument-hint: +allowed-tools: Bash +disable-model-invocation: true +--- + +# /pandoc:validate - Validate Document + +Ask Claude to check your document for errors before converting. + +## What It Checks + +- ✅ YAML syntax (spaces not tabs) +- ✅ Bibliography file exists +- ✅ CSL file exists +- ✅ Image files exist +- ✅ Required fields present + +## Quick Reference + +**Common YAML Errors:** +```yaml +# ❌ Wrong (tabs) +title:→"Paper" + +# ✅ Correct (spaces) +title: "Paper" + +# ❌ Wrong (missing quotes) +title: Paper: A Study + +# ✅ Correct +title: "Paper: A Study" +``` + +**Required Structure:** +```yaml +--- +title: "Title" +author: "Name" +--- + +# Content here +``` + +## Ask Claude + +"Validate my document before converting" +"Check if this is ready to convert to PDF" +"Why won't my document convert?" diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..e4816ae --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,141 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:cadrianmae/claude-marketplace:plugins/pandoc", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "7d9f22b915c0139a3f0ea169bb89ec464f59d744", + "treeHash": "7532ed136e404575db45b71058e13b64383d9651bcd15f3c1fcb5a4687a15691", + "generatedAt": "2025-11-28T10:14:28.551536Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "pandoc", + "description": "Document conversion toolkit for Pandoc with templates, validation, and format-specific helpers. Convert markdown to PDF, DOCX, HTML, and presentations with smart defaults and YAML frontmatter validation.", + "version": "1.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "479e51d4a199ecf22dc3fe00c45cfff19d4a6241ae2340170c22017843f5bccc" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "1739d2924f4010184554ad44cd9c7b7c7528608f36a312610f9de8f2d404632d" + }, + { + "path": "commands/defaults.md", + "sha256": "dfb19e89e9672a3df4cc35fd3059e848ffb05e3e24716a205b69cf8968453d16" + }, + { + "path": "commands/template.md", + "sha256": "32e75ac4b29013f5e411439518c031f87c5300e24f03a339a310936c0189d509" + }, + { + "path": "commands/validate.md", + "sha256": "e7d16eac6e8015966d73372f1e32a199c065f944a582e63c8e475f5ee7774765" + }, + { + "path": "commands/help.md", + "sha256": "be37ce5576c97b382369ad697d8b9f1f802e4552138fd1bd131cbed3386e6bdf" + }, + { + "path": "commands/restyle.md", + "sha256": "5c79f8f057f565a52426cdab61f4413381bc62c6b73d75b6e720858ed3cede82" + }, + { + "path": "commands/frontmatter.md", + "sha256": "bdb795fb76e1b18b6510c4f096346714eec2cb3631b5aecdc1ca01573b60ed77" + }, + { + "path": "commands/convert.md", + "sha256": "bc3da70b7f58f0c08d8cd72543cb8864eb6896ce81ca0de3037ceafa364799f5" + }, + { + "path": "skills/pandoc/SKILL.md", + "sha256": "e0dc01ace5bfe05973cd50006db6741be84edc0e35e35c556549324f31182c02" + }, + { + "path": "skills/pandoc/references/templates_guide.md", + "sha256": "c383272ff747cdbfb99adb3b99874670a144e4a7a0a52f6c85186e85f6de0b4e" + }, + { + "path": "skills/pandoc/references/snippets.md", + "sha256": "9e40627fd1e61322d0a7d58e2cdc66ae4d1ebe194e717265f7f9ea291d3480dc" + }, + { + "path": "skills/pandoc/references/troubleshooting.md", + "sha256": "4cf0c9900da9cbe5a9fce1e2a8757329e8ed4dc0caf76a67b4ee84ad13621cd2" + }, + { + "path": "skills/pandoc/references/conversion_guide.md", + "sha256": "a7838de116fd1d19cd5f767e68cbbbd6de5e99254b00507f157bfa7f24d680e8" + }, + { + "path": "skills/pandoc/references/yaml_reference.md", + "sha256": "17fd582282528103e603a6f4be0dc7ac1609b05299ec52389789709cb3cf12ae" + }, + { + "path": "skills/pandoc/scripts/validate.py", + "sha256": "8fcf25011591c9ad1f8c9b2649796425ee1c715e059e618f0da0d78a3a763223" + }, + { + "path": "skills/pandoc/assets/csl/ieee.csl", + "sha256": "aa16e45534a7ae59be10193a78bb11350d9fa2e6bd6c5fc3d182a903ae3ac2f9" + }, + { + "path": "skills/pandoc/assets/csl/apa.csl", + "sha256": "56b2dc053036b6103aaeaf3c772e023e4f3773dca53481d29450fb6131364ca3" + }, + { + "path": "skills/pandoc/assets/csl/harvard.csl", + "sha256": "88a9549c9ab09ccaaa383bfc45a5674aa55ec382b28addbea5660e97a004d324" + }, + { + "path": "skills/pandoc/assets/templates/presentation-revealjs.yaml", + "sha256": "af540b011dfefb0c1e1817f692dfdb03a5c08f8fd9997d5395827f711209dc73" + }, + { + "path": "skills/pandoc/assets/templates/references.bib", + "sha256": "a8a06e2eedf07dfb4de4edef8d1c9d7e108cb028da514578da61860352faa674" + }, + { + "path": "skills/pandoc/assets/templates/Makefile", + "sha256": "d64d42a5c266c99925d9949bc4f6e89725359ea0533bf7939ee396333824d4f2" + }, + { + "path": "skills/pandoc/assets/templates/presentation-beamer.yaml", + "sha256": "d2b6a1109e336bc4006812a3a629949b226455905abca0a6819bce9a18ebdba0" + }, + { + "path": "skills/pandoc/assets/templates/academic-paper.yaml", + "sha256": "22670fc3a7f93a4b8297637fb5e03e4a10f2abb1cdc436f050c75e9699f7b210" + }, + { + "path": "skills/pandoc/assets/templates/thesis-report.yaml", + "sha256": "d020ae3b41f6d211c6a7e0b56f7f2811bd8dcd751907762c91e8734a9590b1a1" + }, + { + "path": "skills/pandoc/assets/templates/article-simple.yaml", + "sha256": "43a5ce411a41ef3b6eb94f70d7dc75e2c7d0d42708aa743c81aa5626134c932d" + }, + { + "path": "skills/pandoc/assets/templates/defaults-pdf.yaml", + "sha256": "ad93bc0e279e59dde12a89098ee24d901c4e924221796f0ff129881d94922008" + } + ], + "dirSha256": "7532ed136e404575db45b71058e13b64383d9651bcd15f3c1fcb5a4687a15691" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/pandoc/SKILL.md b/skills/pandoc/SKILL.md new file mode 100644 index 0000000..8574667 --- /dev/null +++ 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 [file]` - Generate document templates +- `/pandoc:validate ` - Validate frontmatter and dependencies +- `/pandoc:convert [options]` - Convert with smart defaults +- `/pandoc:frontmatter [type]` - Add/update frontmatter +- `/pandoc:restyle ` - Transform document to match template style +- `/pandoc:defaults [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 +``` diff --git a/skills/pandoc/assets/csl/apa.csl b/skills/pandoc/assets/csl/apa.csl new file mode 100644 index 0000000..14a863c --- /dev/null +++ b/skills/pandoc/assets/csl/apa.csl @@ -0,0 +1,2133 @@ + + diff --git a/skills/pandoc/assets/csl/harvard.csl b/skills/pandoc/assets/csl/harvard.csl new file mode 100644 index 0000000..32cef16 --- /dev/null +++ b/skills/pandoc/assets/csl/harvard.csl @@ -0,0 +1,321 @@ + + diff --git a/skills/pandoc/assets/csl/ieee.csl b/skills/pandoc/assets/csl/ieee.csl new file mode 100644 index 0000000..bb58f0e --- /dev/null +++ b/skills/pandoc/assets/csl/ieee.csl @@ -0,0 +1,512 @@ + + diff --git a/skills/pandoc/assets/templates/Makefile b/skills/pandoc/assets/templates/Makefile new file mode 100644 index 0000000..669053a --- /dev/null +++ b/skills/pandoc/assets/templates/Makefile @@ -0,0 +1,99 @@ +# Pandoc Makefile Template +# Copy this to your project directory and customize + +# Configuration +PANDOC = pandoc +PYTHON = python3 +PLUGIN_DIR = ~/.claude/marketplaces/cadrianmae-claude-marketplace/plugins/pandoc +VALIDATE = $(PYTHON) $(PLUGIN_DIR)/skills/pandoc/scripts/validate.py + +# Project files +MAIN_DOC = document.md +OUTPUT_PDF = document.pdf +OUTPUT_HTML = document.html +OUTPUT_DOCX = document.docx + +# Pandoc options +PDF_ENGINE = pdflatex +PANDOC_OPTS = --number-sections +CITE_OPTS = --citeproc + +# Default target +all: pdf + +# PDF output +pdf: $(OUTPUT_PDF) + +$(OUTPUT_PDF): $(MAIN_DOC) + @echo "Validating $(MAIN_DOC)..." + @$(VALIDATE) $(MAIN_DOC) + @echo "Converting to PDF..." + $(PANDOC) $(MAIN_DOC) -o $(OUTPUT_PDF) \ + --pdf-engine=$(PDF_ENGINE) \ + $(PANDOC_OPTS) \ + $(CITE_OPTS) + @echo "✅ Created: $(OUTPUT_PDF)" + +# HTML output +html: $(OUTPUT_HTML) + +$(OUTPUT_HTML): $(MAIN_DOC) + @echo "Validating $(MAIN_DOC)..." + @$(VALIDATE) $(MAIN_DOC) + @echo "Converting to HTML..." + $(PANDOC) $(MAIN_DOC) -o $(OUTPUT_HTML) \ + --standalone \ + --self-contained \ + --toc + @echo "✅ Created: $(OUTPUT_HTML)" + +# DOCX output +docx: $(OUTPUT_DOCX) + +$(OUTPUT_DOCX): $(MAIN_DOC) + @echo "Validating $(MAIN_DOC)..." + @$(VALIDATE) $(MAIN_DOC) + @echo "Converting to DOCX..." + $(PANDOC) $(MAIN_DOC) -o $(OUTPUT_DOCX) \ + --standalone \ + $(CITE_OPTS) + @echo "✅ Created: $(OUTPUT_DOCX)" + +# Validation only +validate: + @$(VALIDATE) $(MAIN_DOC) + +# Watch for changes and rebuild +watch: + @echo "Watching $(MAIN_DOC) for changes..." + @while true; do \ + inotifywait -e modify $(MAIN_DOC) 2>/dev/null && make pdf; \ + done + +# Clean generated files +clean: + rm -f $(OUTPUT_PDF) $(OUTPUT_HTML) $(OUTPUT_DOCX) + rm -f *.aux *.log *.out *.toc + +# Install project scripts locally +setup: + @echo "Copying validation script to project..." + @mkdir -p ./scripts + @cp $(PLUGIN_DIR)/skills/pandoc/scripts/validate.py ./scripts/ + @chmod +x ./scripts/validate.py + @echo "✅ Setup complete - validation script available at ./scripts/validate.py" + +# Help +help: + @echo "Available targets:" + @echo " all (default) - Build PDF" + @echo " pdf - Build PDF document" + @echo " html - Build HTML document" + @echo " docx - Build DOCX document" + @echo " validate - Validate document only" + @echo " watch - Watch for changes and rebuild" + @echo " setup - Copy scripts to project directory" + @echo " clean - Remove generated files" + @echo " help - Show this help message" + +.PHONY: all pdf html docx validate watch clean setup help diff --git a/skills/pandoc/assets/templates/academic-paper.yaml b/skills/pandoc/assets/templates/academic-paper.yaml new file mode 100644 index 0000000..6cba7b0 --- /dev/null +++ b/skills/pandoc/assets/templates/academic-paper.yaml @@ -0,0 +1,52 @@ +--- +# Document Metadata +title: "Paper Title" +author: "Author Name" +date: "Date" +lang: en-GB # British English for citations + +# Bibliography Settings +bibliography: references.bib # Path to your BibTeX file +csl: harvard.csl # Citation style (Harvard, APA, etc.) +link-citations: true # Make citations clickable links + +# PDF Output Settings +documentclass: report # Document class (report, article, book) +fontsize: 12pt # Font size (10pt, 11pt, 12pt) +geometry: margin=1in # Page margins +linestretch: 1.5 # Line spacing (1.0, 1.5, 2.0) +numbersections: true # Number sections automatically +toc: true # Include table of contents +toc-depth: 3 # TOC depth (1-5) + +# LaTeX Packages (optional) +header-includes: | + \usepackage{graphicx} + \usepackage{float} + \usepackage{hyperref} +--- + +# Introduction + +Your content goes here. + +# Literature Review + +More content here. + +# Methodology + +... + +# Results + +... + +# Conclusion + +... + +# References + +::: {#refs} +::: diff --git a/skills/pandoc/assets/templates/article-simple.yaml b/skills/pandoc/assets/templates/article-simple.yaml new file mode 100644 index 0000000..a875536 --- /dev/null +++ b/skills/pandoc/assets/templates/article-simple.yaml @@ -0,0 +1,24 @@ +--- +# Document Metadata +title: "Article Title" +author: "Author Name" +date: "Date" +lang: en-GB + +# PDF Settings +documentclass: article +fontsize: 11pt +geometry: margin=1in +--- + +# Introduction + +Your content here. + +# Main Content + +More content. + +# Conclusion + +Final thoughts. diff --git a/skills/pandoc/assets/templates/defaults-pdf.yaml b/skills/pandoc/assets/templates/defaults-pdf.yaml new file mode 100644 index 0000000..3834635 --- /dev/null +++ b/skills/pandoc/assets/templates/defaults-pdf.yaml @@ -0,0 +1,41 @@ +# Pandoc Defaults File for PDF Output +# Usage: pandoc document.md --defaults=defaults-pdf.yaml + +# Input/Output +from: markdown +to: pdf + +# PDF Engine +pdf-engine: pdflatex # Options: pdflatex, xelatex, lualatex + +# Citation Processing +citeproc: true # Enable citation processing + +# Document Options +standalone: true # Create standalone document +number-sections: true # Number sections automatically + +# Metadata Defaults +metadata: + lang: en-GB + fontsize: 12pt + geometry: margin=1in + linestretch: 1.5 + documentclass: article + +# Table of Contents +table-of-contents: false +toc-depth: 3 + +# Variables +variables: + colorlinks: true + linkcolor: blue + urlcolor: blue + citecolor: blue + +# Include paths for images/assets +resource-path: + - . + - images + - assets diff --git a/skills/pandoc/assets/templates/presentation-beamer.yaml b/skills/pandoc/assets/templates/presentation-beamer.yaml new file mode 100644 index 0000000..6c60523 --- /dev/null +++ b/skills/pandoc/assets/templates/presentation-beamer.yaml @@ -0,0 +1,67 @@ +--- +# Presentation Metadata +title: "Presentation Title" +author: "Author Name" +date: "Date" +institute: "Institution Name" + +# Beamer Theme +theme: "Madrid" # Options: Madrid, Berlin, Copenhagen, Dresden +colortheme: "default" # Options: default, dolphin, beaver, crane +fonttheme: "default" # Options: default, serif, structurebold + +# PDF Settings +aspectratio: 169 # 16:9 aspect ratio (43 for 4:3) +lang: en-GB + +# Code Highlighting +highlight-style: tango # Options: tango, pygments, kate, monochrome + +# Beamer Options +navigation: horizontal # Horizontal navigation symbols +--- + +# Introduction + +## Slide Title + +- Point 1 +- Point 2 +- Point 3 + +## Another Slide + +Content here. + +# Main Section + +## Code Example + +```python +def hello_world(): + print("Hello, World!") +``` + +## Lists + +**Incremental reveal:** + +::: incremental + +- First item +- Second item +- Third item + +::: + +# Conclusion + +## Summary + +- Key point 1 +- Key point 2 +- Key point 3 + +## Thank You + +Questions? diff --git a/skills/pandoc/assets/templates/presentation-revealjs.yaml b/skills/pandoc/assets/templates/presentation-revealjs.yaml new file mode 100644 index 0000000..16dac84 --- /dev/null +++ b/skills/pandoc/assets/templates/presentation-revealjs.yaml @@ -0,0 +1,95 @@ +--- +# Presentation Metadata +title: "Presentation Title" +author: "Author Name" +date: "Date" + +# Reveal.js Theme +theme: black # Options: black, white, league, beige, sky, night, serif, simple, solarized +transition: slide # Options: none, fade, slide, convex, concave, zoom + +# Slide Settings +slideNumber: true # Show slide numbers +controls: true # Show navigation controls +progress: true # Show progress bar +history: true # Enable browser history + +# Code Highlighting +highlight-style: monokai # Options: monokai, zenburn, github, atom-one-dark + +# Background +background-color: "#1e1e1e" + +# Responsive Design +width: 1280 +height: 720 +margin: 0.1 +--- + +# Introduction {background-color="#2E3440"} + +## Slide Title + +- Point 1 +- Point 2 +- Point 3 + +## Another Slide {background-image="image.jpg"} + +Content with background image. + +# Main Section + +## Code Example + +```python +def fibonacci(n): + if n <= 1: + return n + return fibonacci(n-1) + fibonacci(n-2) +``` + +## Two Column Layout + +::::: {.columns} + +:::: {.column width="50%"} +**Left Column** + +- Item 1 +- Item 2 +:::: + +:::: {.column width="50%"} +**Right Column** + +- Item A +- Item B +:::: + +::::: + +## Fragment Animation + +::: {.fragment} +Fade in first +::: + +::: {.fragment .fade-up} +Fade up second +::: + +# Conclusion + +## Summary {background-color="#4C566A"} + +- Key point 1 +- Key point 2 +- Key point 3 + +## Thank You + +**Contact:** + +- Email: email@example.com +- Website: example.com diff --git a/skills/pandoc/assets/templates/references.bib b/skills/pandoc/assets/templates/references.bib new file mode 100644 index 0000000..67f6c30 --- /dev/null +++ b/skills/pandoc/assets/templates/references.bib @@ -0,0 +1,135 @@ +% BibTeX Bibliography Template +% Copy this file to your project and edit the entries + +% Article from a journal +@article{example-article, + author = {Smith, John and Doe, Jane}, + title = {A Comprehensive Study of Something Important}, + journal = {Journal of Important Studies}, + year = {2024}, + volume = {42}, + number = {3}, + pages = {123--145}, + doi = {10.1234/example.2024.001} +} + +% Book +@book{example-book, + author = {Johnson, Alice}, + title = {Introduction to Advanced Topics}, + publisher = {Academic Press}, + year = {2023}, + edition = {2nd}, + address = {New York}, + isbn = {978-0-12-345678-9} +} + +% Conference paper +@inproceedings{example-conference, + author = {Brown, Robert and Green, Emily}, + title = {Novel Approach to Problem Solving}, + booktitle = {Proceedings of the International Conference on Computing}, + year = {2024}, + pages = {45--52}, + publisher = {ACM}, + address = {San Francisco, CA}, + doi = {10.1145/example.2024} +} + +% PhD Thesis +@phdthesis{example-phd, + author = {Williams, Michael}, + title = {Advanced Research in Computer Science}, + school = {University Name}, + year = {2023}, + address = {City, Country}, + month = {June} +} + +% Master's Thesis +@mastersthesis{example-masters, + author = {Davis, Sarah}, + title = {Investigation of Novel Methods}, + school = {University Name}, + year = {2024}, + address = {City, Country} +} + +% Technical Report +@techreport{example-report, + author = {Miller, James}, + title = {Technical Analysis of System Performance}, + institution = {Research Institute}, + year = {2024}, + number = {TR-2024-01}, + address = {City, Country} +} + +% Website / Online Resource +@misc{example-website, + author = {Organization Name}, + title = {Important Online Resource}, + year = {2024}, + url = {https://example.com/resource}, + note = {Accessed: 2024-11-16} +} + +% Chapter in edited book +@incollection{example-chapter, + author = {Taylor, Lisa}, + title = {Specific Topic in Field}, + booktitle = {Comprehensive Handbook of Field}, + editor = {Anderson, Mark}, + publisher = {Academic Press}, + year = {2023}, + pages = {200--225}, + chapter = {10} +} + +% Unpublished work +@unpublished{example-unpublished, + author = {Wilson, David}, + title = {Work in Progress on Important Topic}, + note = {Manuscript in preparation}, + year = {2024} +} + +% =================================== +% Field Reference Guide +% =================================== +% +% REQUIRED vs OPTIONAL fields vary by entry type +% +% Common Fields: +% author = Author name(s) - use "and" to separate multiple authors +% title = Title of work +% year = Year of publication +% journal = Journal name (for @article) +% booktitle = Book/conference name (for @inproceedings, @incollection) +% publisher = Publisher name (for @book) +% school = University name (for @phdthesis, @mastersthesis) +% pages = Page range (123--145) +% volume = Volume number +% number = Issue number +% edition = Edition (2nd, 3rd, etc.) +% address = Location (city, country) +% doi = Digital Object Identifier +% url = Web address +% note = Additional information +% +% Author Name Formats: +% Single: {Lastname, Firstname} +% Multiple: {Lastname1, Firstname1 and Lastname2, Firstname2} +% Or: {Firstname Lastname} (automatically parsed) +% +% Page Ranges: +% Use double dash: 123--145 (not single dash 123-145) +% +% Special Characters: +% Protect capitalization: {DNA} or {IoT} to prevent lowercasing +% Accents: {\'e} for é, {\`e} for è, {\"o} for ö +% +% Citation Keys: +% Format: author-year or descriptive-keyword +% Examples: smith2024, johnson-ml-2023, example-article +% Must be unique in file diff --git a/skills/pandoc/assets/templates/thesis-report.yaml b/skills/pandoc/assets/templates/thesis-report.yaml new file mode 100644 index 0000000..2aa8d7f --- /dev/null +++ b/skills/pandoc/assets/templates/thesis-report.yaml @@ -0,0 +1,124 @@ +--- +# Document Metadata +title: "Thesis Title" +author: "Author Name" +date: "Month Year" +lang: en-GB + +# Academic Details +supervisor: "Supervisor Name" +institution: "Institution Name" +department: "Department Name" +degree: "Degree Name" + +# Bibliography Settings +bibliography: references.bib +csl: harvard.csl +link-citations: true + +# PDF Output Settings +documentclass: report +fontsize: 12pt +geometry: margin=1in +linestretch: 1.5 +numbersections: true +secnumdepth: 3 + +# Table of Contents +toc: true +toc-depth: 3 +lof: true # List of figures +lot: true # List of tables + +# LaTeX Packages +header-includes: | + \usepackage{graphicx} + \usepackage{float} + \usepackage{hyperref} + \usepackage{setspace} + \renewcommand{\maketitle}{ + \begin{titlepage} + \centering + \vspace*{2cm} + {\Huge\bfseries $title$\par} + \vspace{1.5cm} + {\Large $author$\par} + \vspace{1cm} + {\large A thesis submitted in partial fulfilment\par} + {\large of the requirements for the degree of\par} + \vspace{0.5cm} + {\large\itshape $degree$\par} + \vspace{1.5cm} + {\large $department$\par} + {\large $institution$\par} + \vspace{1cm} + {\large $date$\par} + \vspace{1cm} + {\large Supervisor: $supervisor$\par} + \end{titlepage} + } +--- + + +\begin{abstract} +Write your abstract here (200-300 words). +\end{abstract} + +\newpage + + +# Declaration + +I hereby declare that this thesis is entirely my own work and that it has not been submitted as an exercise for a degree at any other university. + +\vspace{1cm} + +Signed: \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ + +Date: \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ + +\newpage + + +# Acknowledgements + +I would like to thank... + +\newpage + +# Introduction + +Your content here. + +# Literature Review + +... + +# Methodology + +... + +# Implementation + +... + +# Results and Discussion + +... + +# Conclusion + +... + +# References + +::: {#refs} +::: + +\newpage + +# Appendices + +## Appendix A: Additional Material + +... diff --git a/skills/pandoc/references/conversion_guide.md b/skills/pandoc/references/conversion_guide.md new file mode 100644 index 0000000..5d43d90 --- /dev/null +++ b/skills/pandoc/references/conversion_guide.md @@ -0,0 +1,412 @@ +# Pandoc Conversion Guide + +Format-specific conversion instructions and best practices. + +## PDF Conversion + +### Basic PDF + +```bash +pandoc document.md -o document.pdf +``` + +### With Smart Defaults + +```bash +pandoc document.md -o document.pdf \ + --pdf-engine=pdflatex \ + --number-sections +``` + +### PDF Engines + +**pdflatex (default)** +- Fast, widely available +- ASCII-only (no Unicode support) +- Good for most documents +```bash +pandoc doc.md -o doc.pdf --pdf-engine=pdflatex +``` + +**XeLaTeX** +- Unicode support +- Custom fonts +- Slightly slower +```bash +pandoc doc.md -o doc.pdf --pdf-engine=xelatex +``` + +**LuaLaTeX** +- Modern, full Unicode +- Advanced typography +- Slowest option +```bash +pandoc doc.md -o doc.pdf --pdf-engine=lualatex +``` + +### With Citations + +```bash +pandoc paper.md -o paper.pdf \ + --pdf-engine=pdflatex \ + --citeproc \ + --number-sections +``` + +### Custom Margins + +```bash +pandoc doc.md -o doc.pdf \ + -V geometry:margin=1.5in +``` + +### Table of Contents + +```bash +pandoc doc.md -o doc.pdf \ + --toc \ + --toc-depth=3 +``` + +### Custom Template + +```bash +pandoc doc.md -o doc.pdf \ + --template=custom.tex +``` + +## HTML Conversion + +### Standalone HTML + +```bash +pandoc doc.md -o doc.html --standalone +``` + +### Self-Contained (Embed Resources) + +```bash +pandoc doc.md -o doc.html \ + --standalone \ + --self-contained +``` + +### With Table of Contents + +```bash +pandoc doc.md -o doc.html \ + --standalone \ + --toc \ + --toc-depth=3 +``` + +### Custom CSS + +```bash +pandoc doc.md -o doc.html \ + --standalone \ + --css=style.css +``` + +### Syntax Highlighting + +```bash +pandoc doc.md -o doc.html \ + --standalone \ + --highlight-style=tango +``` + +Available highlight styles: +- `tango` (default) +- `pygments` +- `kate` +- `monochrome` +- `espresso` +- `zenburn` +- `haddock` +- `breezedark` + +### Fragment (No HTML/Body Tags) + +```bash +pandoc doc.md -o fragment.html +# No --standalone flag +``` + +## DOCX Conversion + +### Basic DOCX + +```bash +pandoc doc.md -o doc.docx +``` + +### With Reference Template + +```bash +pandoc doc.md -o doc.docx \ + --reference-doc=template.docx +``` + +### With Citations + +```bash +pandoc paper.md -o paper.docx \ + --citeproc +``` + +### Preserve Formatting + +```bash +pandoc doc.md -o doc.docx \ + --standalone +``` + +## Presentation Conversion + +### Beamer (PDF Slides) + +**Basic:** +```bash +pandoc slides.md -o slides.pdf --to beamer +``` + +**With Theme:** +```yaml +--- +title: "Presentation" +author: "Name" +theme: Madrid +colortheme: default +--- +``` + +```bash +pandoc slides.md -o slides.pdf --to beamer +``` + +**Slide Breaks:** +```markdown +# Section Title + +## Slide 1 + +Content + +## Slide 2 + +More content +``` + +### reveal.js (Web Slides) + +**Basic:** +```bash +pandoc slides.md -o slides.html \ + --to revealjs \ + --standalone +``` + +**With Theme:** +```bash +pandoc slides.md -o slides.html \ + --to revealjs \ + --standalone \ + -V theme=black \ + -V transition=slide +``` + +**Available Themes:** +- black (default) +- white +- league +- beige +- sky +- night +- serif +- simple +- solarized + +**Custom Background:** +```markdown +## Slide Title {background-color="#2E3440"} + +Content +``` + +**Two Columns:** +```markdown +::::: {.columns} + +:::: {.column width="50%"} +Left content +:::: + +:::: {.column width="50%"} +Right content +:::: + +::::: +``` + +## Advanced Options + +### Metadata Override + +```bash +pandoc doc.md -o doc.pdf \ + -M title="New Title" \ + -M author="Author Name" +``` + +### Include Files + +```bash +pandoc doc.md -o doc.pdf \ + --include-before-body=header.tex \ + --include-after-body=footer.tex +``` + +### Filters + +```bash +pandoc doc.md -o doc.pdf \ + --filter pandoc-citeproc \ + --lua-filter=custom.lua +``` + +### Resource Path + +```bash +pandoc doc.md -o doc.pdf \ + --resource-path=.:images:assets +``` + +### Variables + +```bash +pandoc doc.md -o doc.pdf \ + -V documentclass=report \ + -V fontsize=12pt \ + -V geometry:margin=1in +``` + +## Defaults Files + +Instead of long command lines, use defaults files: + +**Create defaults file:** +```yaml +# defaults.yaml +from: markdown +to: pdf +pdf-engine: pdflatex +citeproc: true +number-sections: true +metadata: + fontsize: 12pt + geometry: margin=1in +``` + +**Use defaults:** +```bash +pandoc doc.md --defaults=defaults.yaml -o doc.pdf +``` + +## Batch Conversion + +### Convert All MD Files + +```bash +for file in *.md; do + pandoc "$file" -o "${file%.md}.pdf" --pdf-engine=pdflatex +done +``` + +### With Validation + +```bash +PLUGIN_DIR="~/.claude/marketplaces/cadrianmae-claude-marketplace/plugins/pandoc" + +for file in *.md; do + if python3 "$PLUGIN_DIR/skills/pandoc/scripts/validate.py" "$file"; then + pandoc "$file" -o "${file%.md}.pdf" + fi +done +``` + +## Format Detection + +Pandoc auto-detects formats from extensions: + +| Extension | Format | +|-----------|--------| +| `.md`, `.markdown` | Markdown | +| `.pdf` | PDF | +| `.html`, `.htm` | HTML | +| `.docx` | DOCX | +| `.tex` | LaTeX | +| `.epub` | EPUB | +| `.rst` | reStructuredText | +| `.org` | Org-mode | + +Override with `--from` and `--to`: +```bash +pandoc input.txt --from markdown --to html -o output.html +``` + +## Common Patterns + +### Academic Paper + +```bash +pandoc paper.md -o paper.pdf \ + --pdf-engine=pdflatex \ + --citeproc \ + --number-sections \ + --toc \ + --toc-depth=3 +``` + +### Web Article + +```bash +pandoc article.md -o article.html \ + --standalone \ + --self-contained \ + --toc \ + --css=style.css \ + --highlight-style=tango +``` + +### Presentation + +```bash +pandoc slides.md -o slides.html \ + --to revealjs \ + --standalone \ + -V theme=black \ + -V transition=slide +``` + +### Book/Thesis + +```bash +pandoc thesis.md -o thesis.pdf \ + --pdf-engine=xelatex \ + --citeproc \ + --number-sections \ + --toc \ + --toc-depth=4 \ + -V documentclass=book \ + -V fontsize=12pt \ + -V geometry:margin=1in +``` + +## Performance Tips + +1. **Use pdflatex for speed** - Switch to xelatex only if needed +2. **Cache intermediate files** - Use `--standalone` wisely +3. **Batch similar conversions** - Reuse pandoc process +4. **Optimize images** - Compress before embedding +5. **Use defaults files** - Faster than parsing long command lines diff --git a/skills/pandoc/references/snippets.md b/skills/pandoc/references/snippets.md new file mode 100644 index 0000000..f3a5581 --- /dev/null +++ b/skills/pandoc/references/snippets.md @@ -0,0 +1,298 @@ +# Pandoc Quick Reference Snippets + +Copy-paste ready commands for common Pandoc operations. + +## Validation + +```bash +# Validate document +PLUGIN_DIR="~/.claude/marketplaces/cadrianmae-claude-marketplace/plugins/pandoc" +python3 "$PLUGIN_DIR/skills/pandoc/scripts/validate.py" document.md +``` + +## Basic Conversions + +```bash +# Markdown to PDF +pandoc document.md -o document.pdf + +# Markdown to HTML +pandoc document.md -o document.html --standalone + +# Markdown to DOCX +pandoc document.md -o document.docx +``` + +## PDF with Options + +```bash +# Academic paper +pandoc paper.md -o paper.pdf \ + --pdf-engine=pdflatex \ + --citeproc \ + --number-sections \ + --toc + +# With XeLaTeX (Unicode support) +pandoc paper.md -o paper.pdf \ + --pdf-engine=xelatex \ + --citeproc \ + --number-sections + +# Custom margins +pandoc doc.md -o doc.pdf \ + -V geometry:margin=1.5in +``` + +## HTML with Options + +```bash +# Standalone HTML with TOC +pandoc doc.md -o doc.html \ + --standalone \ + --toc \ + --toc-depth=3 + +# Self-contained (embed resources) +pandoc doc.md -o doc.html \ + --standalone \ + --self-contained + +# With custom CSS +pandoc doc.md -o doc.html \ + --standalone \ + --css=style.css + +# With syntax highlighting +pandoc doc.md -o doc.html \ + --standalone \ + --highlight-style=tango +``` + +## 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 \ + -V theme=black + +# With custom theme +pandoc slides.md -o slides.pdf \ + --to beamer \ + -V theme=Madrid \ + -V colortheme=dolphin +``` + +## Using Templates + +```bash +# Copy template +PLUGIN_DIR="~/.claude/marketplaces/cadrianmae-claude-marketplace/plugins/pandoc" +cp "$PLUGIN_DIR/skills/pandoc/assets/templates/academic-paper.yaml" paper.md + +# Copy bibliography template +cp "$PLUGIN_DIR/skills/pandoc/assets/templates/references.bib" references.bib + +# Copy Makefile +cp "$PLUGIN_DIR/skills/pandoc/assets/templates/Makefile" Makefile +``` + +## Using Defaults Files + +```bash +# Create defaults file +PLUGIN_DIR="~/.claude/marketplaces/cadrianmae-claude-marketplace/plugins/pandoc" +cp "$PLUGIN_DIR/skills/pandoc/assets/templates/defaults-pdf.yaml" defaults.yaml + +# Use defaults +pandoc document.md --defaults=defaults.yaml -o output.pdf + +# Override output +pandoc document.md --defaults=defaults.yaml -o custom-name.pdf +``` + +## Project Setup + +```bash +# Create project structure +mkdir -p project/{images,.pandoc} +cd project + +# Copy templates +PLUGIN_DIR="~/.claude/marketplaces/cadrianmae-claude-marketplace/plugins/pandoc" +cp "$PLUGIN_DIR/skills/pandoc/assets/templates/academic-paper.yaml" paper.md +cp "$PLUGIN_DIR/skills/pandoc/assets/templates/references.bib" references.bib +cp "$PLUGIN_DIR/skills/pandoc/assets/templates/defaults-pdf.yaml" .pandoc/defaults.yaml +cp "$PLUGIN_DIR/skills/pandoc/assets/templates/Makefile" Makefile + +# Setup local scripts +make setup + +# Build +make +``` + +## Batch Conversion + +```bash +# Convert all MD files to PDF +for file in *.md; do + pandoc "$file" -o "${file%.md}.pdf" --pdf-engine=pdflatex +done + +# With validation +PLUGIN_DIR="~/.claude/marketplaces/cadrianmae-claude-marketplace/plugins/pandoc" +for file in *.md; do + if python3 "$PLUGIN_DIR/skills/pandoc/scripts/validate.py" "$file"; then + pandoc "$file" -o "${file%.md}.pdf" + fi +done +``` + +## Download Citation Styles + +```bash +# Harvard +curl -o harvard.csl https://raw.githubusercontent.com/citation-style-language/styles/master/harvard-cite-them-right.csl + +# APA +curl -o apa.csl https://raw.githubusercontent.com/citation-style-language/styles/master/apa.csl + +# IEEE +curl -o ieee.csl https://raw.githubusercontent.com/citation-style-language/styles/master/ieee.csl + +# Chicago +curl -o chicago.csl https://raw.githubusercontent.com/citation-style-language/styles/master/chicago-author-date.csl +``` + +## Debugging + +```bash +# Check Pandoc version +pandoc --version + +# Generate LaTeX to inspect +pandoc doc.md -o doc.tex +cat doc.tex + +# Minimal test +echo "# Test" > test.md +pandoc test.md -o test.pdf + +# Verbose output +pandoc doc.md -o doc.pdf --verbose +``` + +## Environment Variables + +```bash +# Set plugin directory +export PANDOC_PLUGIN_DIR="~/.claude/marketplaces/cadrianmae-claude-marketplace/plugins/pandoc" + +# Use in commands +python3 "$PANDOC_PLUGIN_DIR/skills/pandoc/scripts/validate.py" document.md +``` + +## Shell Functions + +```bash +# Add to ~/.bashrc or ~/.zshrc + +# Validate and convert +pandoc-convert() { + PLUGIN_DIR="~/.claude/marketplaces/cadrianmae-claude-marketplace/plugins/pandoc" + python3 "$PLUGIN_DIR/skills/pandoc/scripts/validate.py" "$1" && \ + pandoc "$1" -o "$2" --pdf-engine=pdflatex --citeproc --number-sections +} + +# Usage: pandoc-convert paper.md paper.pdf + +# Quick validate +pandoc-validate() { + PLUGIN_DIR="~/.claude/marketplaces/cadrianmae-claude-marketplace/plugins/pandoc" + python3 "$PLUGIN_DIR/skills/pandoc/scripts/validate.py" "$1" +} + +# Usage: pandoc-validate document.md +``` + +## Git Integration + +```bash +# .gitignore for Pandoc projects +cat > .gitignore << 'EOF' +# Generated files +*.pdf +*.html +*.docx +*.tex + +# LaTeX auxiliary files +*.aux +*.log +*.out +*.toc + +# Keep source files +!*.md +!*.bib +!*.csl +!*.yaml +EOF +``` + +## CI/CD (GitHub Actions) + +```yaml +# .github/workflows/build.yml +name: Build Document + +on: [push] + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + + - name: Install Pandoc + run: | + sudo apt-get update + sudo apt-get install -y pandoc texlive-latex-base + + - name: Build PDF + run: | + pandoc document.md -o document.pdf \ + --pdf-engine=pdflatex \ + --citeproc + + - name: Upload artifact + uses: actions/upload-artifact@v2 + with: + name: document + path: document.pdf +``` + +## Common Patterns + +```bash +# Academic paper workflow +PLUGIN_DIR="~/.claude/marketplaces/cadrianmae-claude-marketplace/plugins/pandoc" +cp "$PLUGIN_DIR/skills/pandoc/assets/templates/academic-paper.yaml" paper.md +# Edit paper.md +python3 "$PLUGIN_DIR/skills/pandoc/scripts/validate.py" paper.md +pandoc paper.md -o paper.pdf --pdf-engine=pdflatex --citeproc --number-sections + +# Web article workflow +pandoc article.md -o article.html --standalone --toc --css=style.css + +# Presentation workflow +cp "$PLUGIN_DIR/skills/pandoc/assets/templates/presentation-revealjs.yaml" slides.md +# Edit slides.md +pandoc slides.md -o slides.html --to revealjs --standalone +``` diff --git a/skills/pandoc/references/templates_guide.md b/skills/pandoc/references/templates_guide.md new file mode 100644 index 0000000..11acc06 --- /dev/null +++ b/skills/pandoc/references/templates_guide.md @@ -0,0 +1,462 @@ +# Pandoc Templates Guide + +How to use and customize Pandoc document templates. + +## Available Templates + +### 1. academic-paper.yaml +**Purpose:** Academic papers with citations +**Features:** +- Bibliography support +- Citation style (CSL) +- Standard academic formatting +- Table of contents + +**Best for:** Research papers, essays, academic assignments + +### 2. thesis-report.yaml +**Purpose:** Thesis and long-form reports +**Features:** +- Custom title page +- Supervisor/institution fields +- List of figures/tables +- Chapter-based structure +- Declaration section + +**Best for:** Final year projects, dissertations, technical reports + +### 3. presentation-beamer.yaml +**Purpose:** PDF presentations via LaTeX Beamer +**Features:** +- Slide themes +- Code highlighting +- Incremental reveals +- Speaker notes + +**Best for:** Academic presentations, lectures, conferences + +### 4. presentation-revealjs.yaml +**Purpose:** Web-based presentations +**Features:** +- Modern web slides +- Transitions and animations +- Two-column layouts +- Background images +- Fragment animations + +**Best for:** Web presentations, online seminars, interactive slides + +### 5. article-simple.yaml +**Purpose:** Quick, minimal documents +**Features:** +- Basic metadata only +- Fast compilation +- Minimal configuration + +**Best for:** Quick notes, simple documents, drafts + +### 6. defaults-pdf.yaml +**Purpose:** Reusable defaults file +**Features:** +- Consistent settings across documents +- Project-wide configuration +- Override-able options + +**Best for:** Multi-document projects, team collaboration + +### 7. references.bib +**Purpose:** BibTeX bibliography template +**Features:** +- Example entries for all common types +- Field reference guide +- Formatting instructions + +**Best for:** Citation management, bibliography creation + +## Using Templates + +### Method 1: Copy to New File + +```bash +PLUGIN_DIR="~/.claude/marketplaces/cadrianmae-claude-marketplace/plugins/pandoc" +cp "$PLUGIN_DIR/skills/pandoc/assets/templates/academic-paper.yaml" paper.md +``` + +### Method 2: User Command + +```bash +/pandoc:template academic-paper paper.md +``` + +### Method 3: View Then Create + +```bash +# View template first +/pandoc:template academic-paper + +# Then create when ready +/pandoc:template academic-paper paper.md +``` + +## Customizing Templates + +### 1. Edit Metadata Fields + +Replace placeholder values: +```yaml +title: "Your Paper Title" # Change this +author: "Your Name" # Change this +date: "November 2024" # Change this +``` + +### 2. Add Custom Fields + +```yaml +# Add to existing frontmatter +student-id: "C21348423" +module: "COMP4060" +supervisor: "Dr. Smith" +``` + +### 3. Modify Formatting + +```yaml +# Change document appearance +fontsize: 11pt # Was 12pt +geometry: margin=1.5in # Was 1in +linestretch: 2.0 # Was 1.5 (now double-spaced) +``` + +### 4. Bibliography Settings + +```yaml +# Change citation style +csl: apa.csl # Was harvard.csl + +# Add multiple bibliography files +bibliography: + - references.bib + - additional.bib +``` + +### 5. LaTeX Customization + +```yaml +header-includes: | + \usepackage{graphicx} + \usepackage{custom-package} + \newcommand{\mycommand}{text} +``` + +## Creating Custom Templates + +### Step 1: Start from Existing + +```bash +PLUGIN_DIR="~/.claude/marketplaces/cadrianmae-claude-marketplace/plugins/pandoc" + +# Copy closest match +cp "$PLUGIN_DIR/skills/pandoc/assets/templates/academic-paper.yaml" my-template.yaml +``` + +### Step 2: Customize Frontmatter + +Edit `my-template.yaml`: +```yaml +--- +# Your custom fields +title: "Template Title" +custom-field: "Custom Value" + +# Your formatting preferences +documentclass: report +fontsize: 12pt +geometry: "left=1.5in, right=1in" +linestretch: 1.5 + +# Your packages +header-includes: | + \usepackage{custom} +--- + +# Template Content + +Your template content here. +``` + +### Step 3: Save for Reuse + +```bash +# Save in project +mkdir -p .pandoc/templates/ +mv my-template.yaml .pandoc/templates/ + +# Use it +cp .pandoc/templates/my-template.yaml new-document.md +``` + +## Template Inheritance + +### Using Defaults Files + +Create base configuration: + +**.pandoc/base.yaml:** +```yaml +from: markdown +to: pdf +pdf-engine: pdflatex + +metadata: + lang: en-GB + fontsize: 12pt + geometry: margin=1in +``` + +**Use in document:** +```bash +pandoc document.md --defaults=.pandoc/base.yaml -o output.pdf +``` + +### Layered Defaults + +**Base settings:** +```yaml +# .pandoc/base.yaml +metadata: + fontsize: 12pt + lang: en-GB +``` + +**Citation settings:** +```yaml +# .pandoc/citations.yaml +citeproc: true +metadata: + link-citations: true +``` + +**Combine:** +```bash +pandoc doc.md \ + --defaults=.pandoc/base.yaml \ + --defaults=.pandoc/citations.yaml \ + -o output.pdf +``` + +## Project Templates + +### Academic Project Structure + +``` +project/ +├── .pandoc/ +│ ├── defaults.yaml # Project-wide settings +│ ├── templates/ +│ │ ├── chapter.yaml # Chapter template +│ │ └── appendix.yaml # Appendix template +│ └── filters/ +│ └── custom.lua # Custom filters +├── chapters/ +│ ├── chapter1.md +│ ├── chapter2.md +│ └── chapter3.md +├── references.bib +├── harvard.csl +└── Makefile +``` + +### Makefile for Project + +```makefile +# Variables +PANDOC = pandoc +DEFAULTS = .pandoc/defaults.yaml +CHAPTERS = chapters/*.md +OUTPUT = thesis.pdf + +# Main targets +all: $(OUTPUT) + +$(OUTPUT): $(CHAPTERS) references.bib + $(PANDOC) $(CHAPTERS) \ + --defaults=$(DEFAULTS) \ + -o $(OUTPUT) + +# Individual chapters +chapter%.pdf: chapters/chapter%.md + $(PANDOC) $< \ + --defaults=$(DEFAULTS) \ + -o $@ + +# Clean +clean: + rm -f *.pdf + +# Help +help: + @echo "Available targets:" + @echo " all - Build complete thesis" + @echo " chapter%.pdf - Build individual chapter" + @echo " clean - Remove generated PDFs" + +.PHONY: all clean help +``` + +**Usage:** +```bash +make # Build thesis +make chapter1.pdf # Build chapter 1 only +make clean # Remove PDFs +``` + +## Template Best Practices + +### 1. Use Placeholders + +```yaml +title: "Document Title" # Clear what to change +author: "Author Name" # Not "TODO" or "FILL IN" +date: "Date" # Simple placeholder +``` + +### 2. Include Comments + +```yaml +documentclass: report # Options: article, report, book +fontsize: 12pt # Options: 10pt, 11pt, 12pt +geometry: margin=1in # Or: margin=2cm, left=1.5in +``` + +### 3. Provide Examples + +```yaml +# Single author +author: "Author Name" + +# Multiple authors +# author: +# - "First Author" +# - "Second Author" +``` + +### 4. Set Sensible Defaults + +```yaml +lang: en-GB # British English +fontsize: 12pt # Standard academic +geometry: margin=1in # Standard margins +linestretch: 1.5 # Standard spacing +``` + +### 5. Document Requirements + +```yaml +# Required files for this template: +# - references.bib (bibliography) +# - harvard.csl (citation style) +# - logo.png (if using custom title page) +``` + +## Troubleshooting Templates + +### Template Won't Convert + +**Check:** +1. YAML syntax (spaces not tabs) +2. Required files exist +3. Field names spelled correctly +4. Values properly quoted + +**Validate:** +```bash +PLUGIN_DIR="~/.claude/marketplaces/cadrianmae-claude-marketplace/plugins/pandoc" +python3 "$PLUGIN_DIR/skills/pandoc/scripts/validate.py" template.md +``` + +### Custom Fields Not Working + +Some fields are LaTeX-specific: +```yaml +# Works in PDF +geometry: margin=1in + +# Doesn't work in HTML/DOCX +# Use CSS for HTML instead +``` + +### Bibliography Issues + +**Ensure:** +```yaml +bibliography: references.bib # File exists +csl: harvard.csl # File exists +``` + +**Then convert with:** +```bash +pandoc doc.md -o doc.pdf --citeproc +``` + +## Advanced Customization + +### Custom LaTeX Template + +**Create template.tex:** +```latex +\documentclass{$documentclass$} + +% Packages +$for(header-includes)$ +$header-includes$ +$endfor$ + +\title{$title$} +\author{$author$} +\date{$date$} + +\begin{document} +\maketitle + +$body$ + +\end{document} +``` + +**Use template:** +```bash +pandoc doc.md -o doc.pdf --template=template.tex +``` + +### Conditional Content + +```yaml +# In frontmatter +draft: true +``` + +```markdown + +$if(draft)$ +**DRAFT VERSION** +$endif$ +``` + +### Variables in Content + +**Frontmatter:** +```yaml +institution: "University Name" +``` + +**Content:** +```markdown +This research was conducted at $institution$. +``` + +## Resources + +- **Pandoc Templates:** https://pandoc.org/MANUAL.html#templates +- **Template Variables:** https://pandoc.org/MANUAL.html#variables +- **LaTeX Templates:** https://www.latextemplates.com/ +- **CSL Styles:** https://github.com/citation-style-language/styles diff --git a/skills/pandoc/references/troubleshooting.md b/skills/pandoc/references/troubleshooting.md new file mode 100644 index 0000000..ba9e413 --- /dev/null +++ b/skills/pandoc/references/troubleshooting.md @@ -0,0 +1,526 @@ +# Pandoc Troubleshooting Guide + +Common errors and solutions for Pandoc document conversion. + +## YAML Frontmatter Errors + +### Error: YAML syntax error + +**Problem:** Invalid YAML in frontmatter +``` +Error: YAML syntax error: mapping values are not allowed here +``` + +**Common Causes:** +1. **Tabs instead of spaces** + ```yaml + # ❌ Wrong (contains tabs) + title:→"My Paper" + + # ✅ Correct (spaces only) + title: "My Paper" + ``` + +2. **Missing quotes around special characters** + ```yaml + # ❌ Wrong + title: Paper: A Study + + # ✅ Correct + title: "Paper: A Study" + ``` + +3. **Incorrect indentation** + ```yaml + # ❌ Wrong + author: + - "Name" # Should be indented + + # ✅ Correct + author: + - "Name" + ``` + +**Fix:** Use validation to find exact error +```bash +PLUGIN_DIR="~/.claude/marketplaces/cadrianmae-claude-marketplace/plugins/pandoc" +python3 "$PLUGIN_DIR/skills/pandoc/scripts/validate.py" document.md +``` + +### Error: YAML not properly closed + +**Problem:** Missing second `---` marker +``` +Error: YAML frontmatter not properly closed (missing second '---') +``` + +**Fix:** +```yaml +--- +title: "Paper" +author: "Name" +--- # Must have this! + +# Content starts here +``` + +## Bibliography Errors + +### Error: Bibliography file not found + +**Problem:** `.bib` file doesn't exist or wrong path +``` +Error: Bibliography file not found: references.bib +``` + +**Solutions:** + +1. **Create bibliography file:** + ```bash + PLUGIN_DIR="~/.claude/marketplaces/cadrianmae-claude-marketplace/plugins/pandoc" + cp "$PLUGIN_DIR/skills/pandoc/assets/templates/references.bib" references.bib + ``` + +2. **Fix path in frontmatter:** + ```yaml + # ❌ Wrong (absolute path from another location) + bibliography: /old/location/refs.bib + + # ✅ Correct (relative path) + bibliography: references.bib + bibliography: ./refs/references.bib + ``` + +3. **Check file actually exists:** + ```bash + ls -la references.bib + ``` + +### Error: CSL file not found + +**Problem:** Citation style file missing +``` +Error: CSL file not found: harvard.csl +``` + +**Solutions:** + +1. **Download CSL file:** + ```bash + # Harvard style + curl -o harvard.csl https://raw.githubusercontent.com/citation-style-language/styles/master/harvard-cite-them-right.csl + + # APA style + curl -o apa.csl https://raw.githubusercontent.com/citation-style-language/styles/master/apa.csl + + # IEEE style + curl -o ieee.csl https://raw.githubusercontent.com/citation-style-language/styles/master/ieee.csl + ``` + +2. **Browse all styles:** + https://github.com/citation-style-language/styles + +3. **Remove CSL if using default:** + ```yaml + bibliography: references.bib + # csl: harvard.csl # Comment out to use default + ``` + +### Error: BibTeX parse error + +**Problem:** Invalid BibTeX syntax in `.bib` file + +**Common Issues:** + +1. **Missing commas:** + ```bibtex + # ❌ Wrong + @article{key, + author = "Name" + title = "Title" # Missing comma after author + } + + # ✅ Correct + @article{key, + author = "Name", # Comma added + title = "Title" + } + ``` + +2. **Unclosed braces:** + ```bibtex + # ❌ Wrong + @article{key, + title = {Unclosed brace + } + + # ✅ Correct + @article{key, + title = {Closed brace} + } + ``` + +3. **Invalid characters in cite key:** + ```bibtex + # ❌ Wrong + @article{smith&jones2024, + + # ✅ Correct + @article{smith-jones-2024, + ``` + +## PDF Generation Errors + +### Error: ! LaTeX Error: File not found + +**Problem:** Missing LaTeX packages + +**Solution:** +```bash +# Fedora/RHEL +sudo dnf install texlive-scheme-medium + +# Ubuntu/Debian +sudo apt-get install texlive-latex-base texlive-latex-extra texlive-fonts-recommended + +# macOS +brew install --cask mactex +``` + +### Error: Unicode characters not supported + +**Problem:** Using pdflatex with Unicode +``` +! Package inputenc Error: Unicode character ... not set up for use with LaTeX +``` + +**Solution:** Use XeLaTeX instead +```bash +pandoc document.md -o document.pdf --pdf-engine=xelatex +``` + +Or update frontmatter: +```yaml +# Add to defaults file +pdf-engine: xelatex +``` + +### Error: Missing fonts + +**Problem:** Custom font not found +``` +! Font ... not found +``` + +**Solutions:** + +1. **Use standard fonts:** + ```yaml + # Remove custom fonts + # mainfont: "Custom Font" + ``` + +2. **Install font:** + ```bash + # Copy font to system + sudo cp font.ttf /usr/share/fonts/ + sudo fc-cache -f -v + ``` + +3. **Use XeLaTeX with system fonts:** + ```yaml + mainfont: "Times New Roman" # Must use XeLaTeX + ``` + +### Error: ! Package geometry Error + +**Problem:** Invalid geometry specification +``` +! Package geometry Error: ... is too large +``` + +**Fix:** +```yaml +# ❌ Wrong +geometry: margin=5in # Too large for paper + +# ✅ Correct +geometry: margin=1in +geometry: "left=1.5in, right=1in, top=1in, bottom=1in" +``` + +## Image Errors + +### Error: Image file not found + +**Problem:** Image path incorrect or file missing + +**Solutions:** + +1. **Use relative paths:** + ```markdown + # ❌ Wrong (absolute path from different location) + ![](/ old/path/image.png) + + # ✅ Correct + ![](images/figure1.png) + ![](./assets/diagram.png) + ``` + +2. **Check file exists:** + ```bash + ls -la images/figure1.png + ``` + +3. **Create images directory:** + ```bash + mkdir -p images + # Copy images there + ``` + +### Error: Image format not supported + +**Problem:** LaTeX can't handle certain formats + +**Supported formats:** +- PDF: PNG, JPEG, PDF +- HTML: PNG, JPEG, GIF, SVG + +**Solution:** Convert image format +```bash +# Convert SVG to PNG (for PDF output) +convert diagram.svg diagram.png + +# Or use ImageMagick +magick convert image.tiff image.png +``` + +## Conversion Errors + +### Error: Pandoc not found + +**Problem:** Pandoc not installed or not in PATH +``` +Error: pandoc: command not found +``` + +**Solution:** +```bash +# Fedora/RHEL +sudo dnf install pandoc + +# Ubuntu/Debian +sudo apt-get install pandoc + +# macOS +brew install pandoc + +# Verify installation +pandoc --version +``` + +### Error: Python not found (validation) + +**Problem:** Python3 not available +``` +Error: python3: command not found +``` + +**Solution:** +```bash +# Most Linux distributions have Python3 +# But if not: +sudo dnf install python3 + +# Or use python instead of python3 +python --version # Check if Python 3.x +``` + +### Error: YAML module not found + +**Problem:** PyYAML not installed (for validation) +``` +ModuleNotFoundError: No module named 'yaml' +``` + +**Solution:** +```bash +pip3 install pyyaml + +# Or system package +sudo dnf install python3-pyyaml +``` + +## Output Errors + +### Error: Permission denied writing output + +**Problem:** Can't write to output location +``` +Error: output.pdf: Permission denied +``` + +**Solutions:** + +1. **Check write permissions:** + ```bash + ls -la output.pdf # Check if file locked + ``` + +2. **Use different location:** + ```bash + pandoc doc.md -o ~/Documents/output.pdf + ``` + +3. **Close file in other program:** + - Close PDF viewer + - Close Word + - Close text editor + +### Error: Disk full + +**Problem:** No space for output file + +**Check:** +```bash +df -h . # Check disk space +``` + +**Solution:** +- Free up disk space +- Use different output location + +## Performance Issues + +### Slow Conversion + +**Causes:** +1. Large document +2. Many images +3. Complex LaTeX +4. Slow PDF engine + +**Solutions:** + +1. **Use faster engine:** + ```bash + # pdflatex is fastest + pandoc doc.md -o doc.pdf --pdf-engine=pdflatex + ``` + +2. **Optimize images:** + ```bash + # Compress images before embedding + convert large.png -resize 50% smaller.png + ``` + +3. **Split large documents:** + ```bash + # Convert chapters separately + pandoc chapter1.md -o chapter1.pdf + pandoc chapter2.md -o chapter2.pdf + ``` + +## Citation Issues + +### Citations not appearing + +**Checklist:** +1. ✅ Bibliography file exists +2. ✅ CSL file exists (or using default) +3. ✅ Using `--citeproc` flag +4. ✅ Citation keys match bibliography + +**Validate:** +```bash +PLUGIN_DIR="~/.claude/marketplaces/cadrianmae-claude-marketplace/plugins/pandoc" +python3 "$PLUGIN_DIR/skills/pandoc/scripts/validate.py" document.md +``` + +**Check citation syntax:** +```markdown +# ✅ Correct +[@smith2024] +@jones2023 found that... + +# ❌ Wrong +[smith2024] # Missing @ +``` + +### Wrong citation style + +**Problem:** Citations not in expected format + +**Solution:** Use correct CSL file +```yaml +csl: harvard.csl # Harvard +csl: apa.csl # APA +csl: ieee.csl # IEEE +``` + +**Download styles:** +```bash +curl -o style.csl https://raw.githubusercontent.com/citation-style-language/styles/master/[style-name].csl +``` + +## Debug Workflow + +### Step-by-Step Debugging + +1. **Validate first:** + ```bash + PLUGIN_DIR="~/.claude/marketplaces/cadrianmae-claude-marketplace/plugins/pandoc" + python3 "$PLUGIN_DIR/skills/pandoc/scripts/validate.py" document.md + ``` + +2. **Check Pandoc version:** + ```bash + pandoc --version + # Ensure version 2.0+ + ``` + +3. **Test minimal conversion:** + ```bash + # Create minimal test + echo "# Test" > test.md + pandoc test.md -o test.pdf + ``` + +4. **Add options incrementally:** + ```bash + # Start simple + pandoc doc.md -o doc.pdf + + # Add engine + pandoc doc.md -o doc.pdf --pdf-engine=pdflatex + + # Add citations + pandoc doc.md -o doc.pdf --pdf-engine=pdflatex --citeproc + ``` + +5. **Check LaTeX intermediate:** + ```bash + # Generate .tex file to see LaTeX + pandoc doc.md -o doc.tex + cat doc.tex # Inspect for errors + ``` + +## Get Help + +### Pandoc Documentation +- Manual: https://pandoc.org/MANUAL.html +- FAQ: https://pandoc.org/faqs.html +- Demos: https://pandoc.org/demos.html + +### Community Resources +- Pandoc Discussions: https://github.com/jgm/pandoc/discussions +- Stack Overflow: [pandoc] tag +- LaTeX Stack Exchange: https://tex.stackexchange.com/ + +### Validation Tool +```bash +PLUGIN_DIR="~/.claude/marketplaces/cadrianmae-claude-marketplace/plugins/pandoc" +python3 "$PLUGIN_DIR/skills/pandoc/scripts/validate.py" document.md +``` + +This tool catches most common errors before conversion. diff --git a/skills/pandoc/references/yaml_reference.md b/skills/pandoc/references/yaml_reference.md new file mode 100644 index 0000000..12c1c24 --- /dev/null +++ b/skills/pandoc/references/yaml_reference.md @@ -0,0 +1,579 @@ +# Pandoc YAML Variables Reference + +Comprehensive guide to YAML frontmatter variables for Pandoc document conversion. + +## Core Metadata + +### title +**Type:** String +**Usage:** Document title +**Example:** +```yaml +title: "My Research Paper" +``` + +### author +**Type:** String or List +**Usage:** Author name(s) +**Examples:** +```yaml +author: "John Smith" + +# Multiple authors +author: + - "John Smith" + - "Jane Doe" +``` + +### date +**Type:** String +**Usage:** Publication/document date +**Examples:** +```yaml +date: "November 2024" +date: "2024-11-16" +date: "16 November 2024" +``` + +### lang +**Type:** String (BCP 47 language code) +**Usage:** Document language for hyphenation, quotes, citations +**Examples:** +```yaml +lang: en-GB # British English +lang: en-US # American English +lang: en-IE # Irish English +lang: de # German +lang: fr # French +``` + +## Bibliography and Citations + +### bibliography +**Type:** String or List +**Usage:** Path to BibTeX (.bib) file(s) +**Examples:** +```yaml +bibliography: references.bib + +# Multiple files +bibliography: + - references.bib + - additional.bib +``` + +### csl +**Type:** String +**Usage:** Path to Citation Style Language (.csl) file +**Examples:** +```yaml +csl: harvard.csl +csl: apa.csl +csl: ieee.csl +``` + +**Download CSL styles:** https://github.com/citation-style-language/styles + +### link-citations +**Type:** Boolean +**Usage:** Make citations clickable links to bibliography +**Example:** +```yaml +link-citations: true +``` + +### citeproc +**Type:** Boolean (command-line option, not frontmatter) +**Usage:** Enable citation processing +**Command:** +```bash +pandoc doc.md -o doc.pdf --citeproc +``` + +## PDF Output Settings + +### documentclass +**Type:** String +**Usage:** LaTeX document class +**Options:** +- `article` - Short documents, papers +- `report` - Longer documents with chapters +- `book` - Books with front matter +- `beamer` - Presentations + +**Example:** +```yaml +documentclass: report +``` + +### fontsize +**Type:** String +**Usage:** Base font size +**Options:** `10pt`, `11pt`, `12pt` +**Example:** +```yaml +fontsize: 12pt +``` + +### geometry +**Type:** String +**Usage:** Page layout and margins +**Examples:** +```yaml +geometry: margin=1in +geometry: margin=2cm +geometry: "left=1.5in, right=1in, top=1in, bottom=1in" +geometry: "a4paper, margin=2.5cm" +``` + +### linestretch +**Type:** Number +**Usage:** Line spacing multiplier +**Examples:** +```yaml +linestretch: 1.0 # Single spacing +linestretch: 1.5 # 1.5 spacing +linestretch: 2.0 # Double spacing +``` + +### papersize +**Type:** String +**Usage:** Paper size +**Options:** `a4`, `letter`, `legal`, `executive` +**Example:** +```yaml +papersize: a4 +``` + +## Table of Contents + +### toc +**Type:** Boolean +**Usage:** Include table of contents +**Example:** +```yaml +toc: true +``` + +### toc-depth +**Type:** Integer (1-5) +**Usage:** Maximum heading level in TOC +**Example:** +```yaml +toc-depth: 3 # Include h1, h2, h3 +``` + +### toc-title +**Type:** String +**Usage:** Custom TOC heading +**Example:** +```yaml +toc-title: "Contents" +``` + +### lof +**Type:** Boolean +**Usage:** Include list of figures +**Example:** +```yaml +lof: true +``` + +### lot +**Type:** Boolean +**Usage:** Include list of tables +**Example:** +```yaml +lot: true +``` + +## Section Numbering + +### numbersections +**Type:** Boolean +**Usage:** Number section headings automatically +**Example:** +```yaml +numbersections: true +``` + +### secnumdepth +**Type:** Integer +**Usage:** Maximum heading level to number +**Example:** +```yaml +secnumdepth: 3 # Number up to h3 +``` + +## LaTeX Customization + +### header-includes +**Type:** String (multiline) +**Usage:** Custom LaTeX commands and packages +**Example:** +```yaml +header-includes: | + \usepackage{graphicx} + \usepackage{float} + \usepackage{hyperref} + \usepackage{amsmath} +``` + +### include-before +**Type:** String (multiline) +**Usage:** Content before document body +**Example:** +```yaml +include-before: | + \begin{abstract} + This is the abstract. + \end{abstract} +``` + +### include-after +**Type:** String (multiline) +**Usage:** Content after document body +**Example:** +```yaml +include-after: | + \appendix + # Appendix content +``` + +## Typography + +### mainfont +**Type:** String +**Usage:** Main document font (requires XeLaTeX or LuaLaTeX) +**Example:** +```yaml +mainfont: "Times New Roman" +``` + +### sansfont +**Type:** String +**Usage:** Sans-serif font +**Example:** +```yaml +sansfont: "Arial" +``` + +### monofont +**Type:** String +**Usage:** Monospace font for code +**Example:** +```yaml +monofont: "Courier New" +``` + +### fontfamily +**Type:** String +**Usage:** LaTeX font package +**Example:** +```yaml +fontfamily: palatino +``` + +## Presentation (Beamer) + +### theme +**Type:** String +**Usage:** Beamer theme +**Options:** Madrid, Berlin, Copenhagen, Dresden, Frankfurt, Singapore, Warsaw +**Example:** +```yaml +theme: Madrid +``` + +### colortheme +**Type:** String +**Usage:** Beamer color scheme +**Options:** default, dolphin, beaver, crane, seahorse +**Example:** +```yaml +colortheme: default +``` + +### fonttheme +**Type:** String +**Usage:** Beamer font theme +**Options:** default, serif, structurebold, structureitalicserif +**Example:** +```yaml +fonttheme: default +``` + +### aspectratio +**Type:** Integer +**Usage:** Slide aspect ratio +**Options:** `43` (4:3), `169` (16:9), `1610` (16:10) +**Example:** +```yaml +aspectratio: 169 +``` + +### navigation +**Type:** String +**Usage:** Navigation symbols +**Options:** horizontal, vertical, frame +**Example:** +```yaml +navigation: horizontal +``` + +## HTML Output + +### css +**Type:** String or List +**Usage:** CSS stylesheet path(s) +**Examples:** +```yaml +css: style.css + +# Multiple stylesheets +css: + - style.css + - syntax.css +``` + +### self-contained +**Type:** Boolean (command-line) +**Usage:** Embed all resources in HTML +**Command:** +```bash +pandoc doc.md -o doc.html --self-contained +``` + +## Code Highlighting + +### highlight-style +**Type:** String +**Usage:** Syntax highlighting theme +**Options:** tango, pygments, kate, monochrome, espresso, zenburn, haddock, breezedark +**Example:** +```yaml +highlight-style: tango +``` + +## Custom Variables + +### Custom Title Page Fields + +**For thesis/academic work:** +```yaml +supervisor: "Dr. Jane Smith" +institution: "University Name" +department: "Department of Computer Science" +degree: "BSc Computer Science" +``` + +**Student Information:** +```yaml +student-id: "C21348423" +programme: "TU856" +module: "COMP4060" +``` + +**Contact Information:** +```yaml +email: "student@example.com" +website: "https://example.com" +``` + +## BibTeX Reference + +### Entry Types + +**Article:** +```bibtex +@article{citekey, + author = {Smith, John and Doe, Jane}, + title = {Paper Title}, + journal = {Journal Name}, + year = {2024}, + volume = {42}, + number = {3}, + pages = {123--145}, + doi = {10.1234/example} +} +``` + +**Book:** +```bibtex +@book{citekey, + author = {Johnson, Alice}, + title = {Book Title}, + publisher = {Publisher Name}, + year = {2023}, + edition = {2nd}, + address = {City}, + isbn = {978-0-12-345678-9} +} +``` + +**Conference Paper:** +```bibtex +@inproceedings{citekey, + author = {Brown, Robert}, + title = {Paper Title}, + booktitle = {Conference Proceedings}, + year = {2024}, + pages = {45--52}, + publisher = {ACM}, + doi = {10.1145/example} +} +``` + +**PhD Thesis:** +```bibtex +@phdthesis{citekey, + author = {Williams, Michael}, + title = {Thesis Title}, + school = {University Name}, + year = {2023}, + address = {City, Country} +} +``` + +**Master's Thesis:** +```bibtex +@mastersthesis{citekey, + author = {Davis, Sarah}, + title = {Thesis Title}, + school = {University Name}, + year = {2024} +} +``` + +**Website:** +```bibtex +@misc{citekey, + author = {Organization}, + title = {Page Title}, + year = {2024}, + url = {https://example.com}, + note = {Accessed: 2024-11-16} +} +``` + +### BibTeX Field Reference + +**Required vs Optional varies by entry type** + +**Common Fields:** +- `author` - Author names (use "and" to separate) +- `title` - Work title +- `year` - Publication year +- `journal` - Journal name (article) +- `booktitle` - Book/conference name +- `publisher` - Publisher name +- `school` - University (thesis) +- `pages` - Page range (use double dash: 123--145) +- `volume` - Volume number +- `number` - Issue number +- `edition` - Edition (2nd, 3rd, etc.) +- `address` - Location (city, country) +- `doi` - Digital Object Identifier +- `url` - Web address +- `note` - Additional information + +**Author Formatting:** +```bibtex +author = {Lastname, Firstname} +author = {Lastname1, Firstname1 and Lastname2, Firstname2} +author = {Firstname Lastname} # Auto-parsed +``` + +**Special Characters:** +```bibtex +title = {Study of {DNA} Sequencing} # Protect caps +title = {Analysis of {IoT} Systems} +author = {M{\"u}ller, Hans} # Umlaut +``` + +## Example Complete Frontmatter + +### Academic Paper +```yaml +--- +title: "Research Paper Title" +author: "Author Name" +date: "November 2024" +lang: en-GB + +bibliography: references.bib +csl: harvard.csl +link-citations: true + +documentclass: report +fontsize: 12pt +geometry: margin=1in +linestretch: 1.5 +numbersections: true + +toc: true +toc-depth: 3 + +header-includes: | + \usepackage{graphicx} + \usepackage{float} + \usepackage{hyperref} +--- +``` + +### Thesis +```yaml +--- +title: "Thesis Title" +author: "Student Name" +date: "Month Year" +supervisor: "Dr. Supervisor Name" +institution: "University Name" +department: "Department Name" +degree: "BSc Computer Science" +lang: en-GB + +bibliography: references.bib +csl: harvard.csl +link-citations: true + +documentclass: report +fontsize: 12pt +geometry: margin=1in +linestretch: 1.5 +numbersections: true +secnumdepth: 3 + +toc: true +toc-depth: 3 +lof: true +lot: true +--- +``` + +### Simple Article +```yaml +--- +title: "Article Title" +author: "Author Name" +date: "Date" +lang: en-GB +documentclass: article +fontsize: 11pt +geometry: margin=1in +--- +``` + +## Variable Precedence + +1. **Command-line variables** (`-V key=value`) override +2. **Frontmatter variables** +3. **Defaults file variables** +4. **Pandoc built-in defaults** + +## Resources + +- **Pandoc Manual:** https://pandoc.org/MANUAL.html +- **CSL Styles:** https://github.com/citation-style-language/styles +- **BibTeX Reference:** https://www.bibtex.com/ +- **LaTeX Packages:** https://ctan.org/ diff --git a/skills/pandoc/scripts/validate.py b/skills/pandoc/scripts/validate.py new file mode 100644 index 0000000..d4c84e9 --- /dev/null +++ b/skills/pandoc/scripts/validate.py @@ -0,0 +1,168 @@ +#!/usr/bin/env python3 +"""Validate Pandoc markdown file with YAML frontmatter""" + +import yaml +import sys +import os +import re +from pathlib import Path + + +def validate_file(filepath): + """Validate markdown file with YAML frontmatter + + Returns: + tuple: (is_valid, errors, warnings) + """ + issues = [] + warnings = [] + + # Check file exists + if not os.path.exists(filepath): + return False, [f"File not found: {filepath}"], [] + + # Read file content + try: + with open(filepath, 'r', encoding='utf-8') as f: + content = f.read() + except Exception as e: + return False, [f"Failed to read file: {e}"], [] + + # Check for YAML frontmatter + if not content.startswith('---'): + issues.append("No YAML frontmatter found (should start with '---')") + return False, issues, warnings + + # Find end of YAML block + try: + yaml_end = content.index('---', 3) + yaml_content = content[3:yaml_end] + except ValueError: + issues.append("YAML frontmatter not properly closed (missing second '---')") + return False, issues, warnings + + # Check for tabs in YAML + if '\t' in yaml_content: + issues.append("YAML contains tabs - use spaces for indentation") + + # Parse YAML + try: + metadata = yaml.safe_load(yaml_content) + except yaml.YAMLError as e: + issues.append(f"YAML syntax error: {e}") + return False, issues, warnings + + if metadata is None: + metadata = {} + + # Get file directory for relative path resolution + file_dir = os.path.dirname(os.path.abspath(filepath)) + + # Validate bibliography file + if 'bibliography' in metadata: + bib_path = metadata['bibliography'] + # Handle relative paths + if not os.path.isabs(bib_path): + bib_path = os.path.join(file_dir, bib_path) + + if not os.path.exists(bib_path): + issues.append(f"Bibliography file not found: {metadata['bibliography']}") + + # Validate CSL file + if 'csl' in metadata: + csl_path = metadata['csl'] + # Handle relative paths + if not os.path.isabs(csl_path): + csl_path = os.path.join(file_dir, csl_path) + + if not os.path.exists(csl_path): + issues.append(f"CSL file not found: {metadata['csl']}") + + # Check for images in markdown content + markdown_content = content[yaml_end + 3:] + image_pattern = r'!\[.*?\]\((.*?)\)' + images = re.findall(image_pattern, markdown_content) + + missing_images = [] + for img_path in images: + # Skip URLs + if img_path.startswith(('http://', 'https://')): + continue + + # Handle relative paths + if not os.path.isabs(img_path): + img_path = os.path.join(file_dir, img_path) + + if not os.path.exists(img_path): + missing_images.append(img_path) + + if missing_images: + issues.append(f"Missing images: {', '.join(missing_images)}") + + # Check recommended fields + recommended_fields = ['title', 'author'] + for field in recommended_fields: + if field not in metadata or not metadata[field]: + warnings.append(f"Missing recommended field: {field}") + + # Check date format + if 'date' in metadata: + date_val = str(metadata['date']) + # Warn if date looks like it needs formatting + if date_val.lower() in ['date', 'todo', 'tbd']: + warnings.append(f"Date field needs to be filled in: '{date_val}'") + + # Check for common mistakes + if 'documentclass' in metadata: + valid_classes = ['article', 'report', 'book', 'beamer'] + if metadata['documentclass'] not in valid_classes: + warnings.append(f"Unusual documentclass: '{metadata['documentclass']}' (common: {', '.join(valid_classes)})") + + # Bibliography + CSL warning + if 'bibliography' in metadata and 'csl' not in metadata: + warnings.append("Bibliography specified but no CSL file (will use default citation style)") + + return len(issues) == 0, issues, warnings + + +def main(): + if len(sys.argv) < 2: + print("Usage: validate.py ") + sys.exit(1) + + filepath = sys.argv[1] + is_valid, errors, warnings = validate_file(filepath) + + print("Pandoc Markdown Validation") + print("=" * 40) + print(f"File: {filepath}") + print() + + # Print errors + if errors: + print("❌ Errors:") + for error in errors: + print(f" • {error}") + print() + + # Print warnings + if warnings: + print("⚠️ Warnings:") + for warning in warnings: + print(f" • {warning}") + print() + + # Print result + if is_valid: + if warnings: + print(f"✅ Validation passed with {len(warnings)} warning(s)") + else: + print("✅ Validation passed - ready to convert!") + sys.exit(0) + else: + print(f"❌ Validation failed with {len(errors)} error(s)") + sys.exit(1) + + +if __name__ == '__main__': + main()