Initial commit
This commit is contained in:
Zhongwei Li
375
SKILL.md
Normal file
375
SKILL.md
Normal file
@@ -0,0 +1,375 @@
|
||||
# Markdown to PDF Converter Skill
|
||||
|
||||
This skill helps you convert Markdown files to PDF format with support for both document-style and presentation-style outputs using Marp.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Use this skill when the user wants to:
|
||||
- Convert Markdown (.md) files to PDF presentations
|
||||
- Generate slide decks from Markdown
|
||||
- Create professional PDFs from documentation
|
||||
- Export README files as PDFs
|
||||
- Generate presentation-ready slides with Marp themes
|
||||
|
||||
## Available Conversion Methods
|
||||
|
||||
### Method 1: Marp Presentation (Recommended)
|
||||
Best for: Presentations, slide decks, visual content
|
||||
|
||||
**Command:**
|
||||
```bash
|
||||
python marp_to_pdf.py input.md
|
||||
```
|
||||
|
||||
**Features:**
|
||||
- Beautiful presentation slides from Markdown
|
||||
- Multiple built-in themes (default, gaia, uncover)
|
||||
- Automatic slide breaks with `---`
|
||||
- Support for presenter notes
|
||||
- Code syntax highlighting
|
||||
- Chinese/CJK character support
|
||||
- Outputs: `input.pdf`
|
||||
|
||||
### Method 2: Marp with Custom Theme
|
||||
Best for: Branded presentations, custom styling
|
||||
|
||||
**Command:**
|
||||
```bash
|
||||
python marp_to_pdf.py input.md --theme gaia
|
||||
```
|
||||
|
||||
**Supported Themes:**
|
||||
- `default` - Clean and simple
|
||||
- `gaia` - Modern and colorful
|
||||
- `uncover` - Minimalist and elegant
|
||||
|
||||
## Required Dependencies
|
||||
|
||||
The skill requires Marp CLI via npm:
|
||||
|
||||
```bash
|
||||
# Install Node.js first (if not installed)
|
||||
# Then install Marp CLI globally
|
||||
npm install -g @marp-team/marp-cli
|
||||
|
||||
# Or use npx (no installation needed)
|
||||
npx @marp-team/marp-cli --version
|
||||
```
|
||||
|
||||
## Marp Markdown Syntax
|
||||
|
||||
### Basic Slide Structure
|
||||
|
||||
```markdown
|
||||
---
|
||||
marp: true
|
||||
theme: default
|
||||
---
|
||||
|
||||
# Title Slide
|
||||
|
||||
Your presentation content
|
||||
|
||||
---
|
||||
|
||||
## Second Slide
|
||||
|
||||
- Bullet point 1
|
||||
- Bullet point 2
|
||||
|
||||
---
|
||||
|
||||
## Code Example
|
||||
|
||||
\`\`\`python
|
||||
def hello():
|
||||
print("Hello, World!")
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### Slide Directives
|
||||
|
||||
```markdown
|
||||
<!-- _class: lead -->
|
||||
# Centered Title Slide
|
||||
|
||||
<!-- _class: invert -->
|
||||
## Inverted Color Slide
|
||||
|
||||
<!-- backgroundColor: #123456 -->
|
||||
## Custom Background
|
||||
```
|
||||
|
||||
### Presenter Notes
|
||||
|
||||
```markdown
|
||||
## Slide Title
|
||||
|
||||
Slide content here
|
||||
|
||||
<!--
|
||||
These are presenter notes
|
||||
They won't appear in the PDF
|
||||
-->
|
||||
```
|
||||
|
||||
## Step-by-Step Instructions
|
||||
|
||||
### For Standard Marp Presentation:
|
||||
|
||||
1. **Create Markdown file with Marp frontmatter:**
|
||||
```markdown
|
||||
---
|
||||
marp: true
|
||||
theme: default
|
||||
---
|
||||
|
||||
# Your Title
|
||||
|
||||
---
|
||||
|
||||
## Content
|
||||
```
|
||||
|
||||
2. **Run the converter:**
|
||||
```bash
|
||||
python ~/.claude/skills/markdown-to-pdf/marp_to_pdf.py presentation.md
|
||||
```
|
||||
|
||||
3. **Open the result:**
|
||||
```bash
|
||||
open presentation.pdf
|
||||
```
|
||||
|
||||
### For Custom Themed Presentation:
|
||||
|
||||
1. **Run with theme option:**
|
||||
```bash
|
||||
python ~/.claude/skills/markdown-to-pdf/marp_to_pdf.py slides.md --theme gaia
|
||||
```
|
||||
|
||||
2. **View the PDF:**
|
||||
```bash
|
||||
open slides.pdf
|
||||
```
|
||||
|
||||
## Supported Markdown Features
|
||||
|
||||
✅ **Headers** (slide titles)
|
||||
✅ **Bold, Italic, Strikethrough**
|
||||
✅ **Lists** (ordered, unordered, nested)
|
||||
✅ **Code blocks** with syntax highlighting
|
||||
✅ **Inline code**
|
||||
✅ **Tables**
|
||||
✅ **Images** (auto-scaled to fit slides)
|
||||
✅ **Links**
|
||||
✅ **Blockquotes**
|
||||
✅ **Math equations** (KaTeX)
|
||||
✅ **Emojis** 😊
|
||||
✅ **Slide backgrounds**
|
||||
✅ **Custom CSS**
|
||||
✅ **Chinese/CJK characters**
|
||||
|
||||
## Marp-Specific Features
|
||||
|
||||
### Two-Column Layout
|
||||
|
||||
```markdown
|
||||
<div class="columns">
|
||||
<div>
|
||||
|
||||
## Left Column
|
||||
|
||||
Content here
|
||||
|
||||
</div>
|
||||
<div>
|
||||
|
||||
## Right Column
|
||||
|
||||
Content here
|
||||
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
### Image Sizing
|
||||
|
||||
```markdown
|
||||
|
||||
|
||||
|
||||
```
|
||||
|
||||
### Slide Backgrounds
|
||||
|
||||
```markdown
|
||||
|
||||
|
||||
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Issue: Marp CLI not found
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
npm install -g @marp-team/marp-cli
|
||||
# Or use npx without installation
|
||||
npx @marp-team/marp-cli --version
|
||||
```
|
||||
|
||||
### Issue: Slides not breaking correctly
|
||||
|
||||
**Solution:** Ensure you use `---` to separate slides:
|
||||
```markdown
|
||||
# Slide 1
|
||||
|
||||
---
|
||||
|
||||
# Slide 2
|
||||
```
|
||||
|
||||
### Issue: Theme not applied
|
||||
|
||||
**Solution:** Add Marp frontmatter at the top:
|
||||
```markdown
|
||||
---
|
||||
marp: true
|
||||
theme: gaia
|
||||
---
|
||||
```
|
||||
|
||||
### Issue: Chinese characters not displaying
|
||||
|
||||
**Solution:** Marp automatically handles system fonts for CJK characters.
|
||||
|
||||
## Output Files
|
||||
|
||||
After conversion, you'll get:
|
||||
|
||||
**Marp Method:**
|
||||
- `filename.pdf` - Presentation-style PDF with slides
|
||||
|
||||
**Optional HTML output:**
|
||||
- `filename.html` - Interactive HTML presentation
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **For presentations:** Use Marp with clear slide breaks
|
||||
- One main idea per slide
|
||||
- Use `---` to separate slides
|
||||
- Choose appropriate theme
|
||||
|
||||
2. **For code demonstrations:**
|
||||
- Use syntax highlighting with language tags
|
||||
- Keep code snippets concise per slide
|
||||
|
||||
3. **For visual impact:**
|
||||
- Use background images
|
||||
- Apply custom themes
|
||||
- Use the `_class: lead` for title slides
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Simple Presentation
|
||||
```bash
|
||||
python ~/.claude/skills/markdown-to-pdf/marp_to_pdf.py slides.md
|
||||
# Output: slides.pdf
|
||||
```
|
||||
|
||||
### Example 2: Gaia Theme Presentation
|
||||
```bash
|
||||
python ~/.claude/skills/markdown-to-pdf/marp_to_pdf.py slides.md --theme gaia
|
||||
```
|
||||
|
||||
### Example 3: Generate HTML and PDF
|
||||
```bash
|
||||
python ~/.claude/skills/markdown-to-pdf/marp_to_pdf.py slides.md --html
|
||||
# Output: slides.pdf and slides.html
|
||||
```
|
||||
|
||||
### Example 4: Batch Convert Multiple Presentations
|
||||
```bash
|
||||
for file in *.md; do
|
||||
python ~/.claude/skills/markdown-to-pdf/marp_to_pdf.py "$file"
|
||||
done
|
||||
```
|
||||
|
||||
## Sample Marp Markdown
|
||||
|
||||
```markdown
|
||||
---
|
||||
marp: true
|
||||
theme: gaia
|
||||
paginate: true
|
||||
---
|
||||
|
||||
<!-- _class: lead -->
|
||||
|
||||
# My Presentation
|
||||
## Subtitle Here
|
||||
|
||||
Your Name
|
||||
Date
|
||||
|
||||
---
|
||||
|
||||
## Agenda
|
||||
|
||||
1. Introduction
|
||||
2. Main Content
|
||||
3. Conclusion
|
||||
|
||||
---
|
||||
|
||||
## Code Example
|
||||
|
||||
\`\`\`python
|
||||
def fibonacci(n):
|
||||
if n <= 1:
|
||||
return n
|
||||
return fibonacci(n-1) + fibonacci(n-2)
|
||||
\`\`\`
|
||||
|
||||
---
|
||||
|
||||
<!-- _class: lead -->
|
||||
|
||||
# Thank You!
|
||||
|
||||
Questions?
|
||||
```
|
||||
|
||||
## Performance Expectations
|
||||
|
||||
- **Processing Speed**: ~2-5 seconds for typical presentations
|
||||
- **Memory Usage**: ~100-200 MB during conversion
|
||||
- **PDF File Size**: 500KB - 5MB depending on images
|
||||
|
||||
## Success Criteria
|
||||
|
||||
A successful conversion should:
|
||||
1. ✅ Generate PDF without errors
|
||||
2. ✅ Create proper slide breaks
|
||||
3. ✅ Apply theme correctly
|
||||
4. ✅ Display code with syntax highlighting
|
||||
5. ✅ Handle Chinese/CJK characters correctly
|
||||
6. ✅ Scale images appropriately
|
||||
7. ✅ Maintain visual consistency
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Need | Command | Output |
|
||||
|------|---------|--------|
|
||||
| Default theme | `marp_to_pdf.py file.md` | PDF with default theme |
|
||||
| Gaia theme | `marp_to_pdf.py file.md --theme gaia` | PDF with Gaia theme |
|
||||
| Uncover theme | `marp_to_pdf.py file.md --theme uncover` | PDF with Uncover theme |
|
||||
| HTML output | `marp_to_pdf.py file.md --html` | PDF + HTML presentation |
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Marp Official Documentation](https://marp.app/)
|
||||
- [Marp CLI Documentation](https://github.com/marp-team/marp-cli)
|
||||
- [Marp Themes Gallery](https://github.com/marp-team/marp-core/tree/main/themes)
|
||||
Reference in New Issue
Block a user