Skip to content

Commit 38b0dc6

Browse files
michael-borckclaude
andcommitted
Implement optional Quarto integration for advanced users (sub-task 5.6)
Added comprehensive Quarto integration system for high-quality educational document generation: - Feature-flagged Quarto integration to maintain optional dependency - Complete QuartoConverter with system detection and capability assessment - Support for multiple output formats (HTML, PDF, PowerPoint, Word, Book, Website) - Educational content-type aware formatting with specialized handling - Integration with existing export manager and unified interface - Comprehensive documentation and working examples - Graceful degradation when Quarto unavailable 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent fcb533b commit 38b0dc6

File tree

9 files changed

+1524
-3
lines changed

9 files changed

+1524
-3
lines changed

src-tauri/Cargo.toml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -98,9 +98,10 @@ custom-protocol = ["tauri/custom-protocol"]
9898
chrome-pdf = ["headless_chrome"]
9999
wkhtml-pdf = ["wkhtmltopdf"]
100100
image-processing = ["image"]
101+
quarto-integration = []
101102

102103
# Full feature set for advanced users
103-
full = ["chrome-pdf", "wkhtml-pdf", "image-processing"]
104+
full = ["chrome-pdf", "wkhtml-pdf", "image-processing", "quarto-integration"]
104105

105106
# Development features
106107
dev = ["tracing/max_level_debug"]
Lines changed: 307 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,307 @@
1+
# Quarto Integration for Advanced Users
2+
3+
The Curriculum Curator provides optional integration with [Quarto](https://quarto.org), a scientific and technical publishing system that enables creation of high-quality educational documents, presentations, and websites.
4+
5+
## Overview
6+
7+
Quarto is the next-generation version of R Markdown, built on Pandoc, that supports multiple programming languages and output formats. For educational content creators, Quarto offers:
8+
9+
- **Single Source, Multiple Outputs**: Generate HTML, PDF, PowerPoint, and Word documents from one source
10+
- **Interactive Features**: Code execution, embedded widgets, and dynamic content
11+
- **Professional Typography**: High-quality typesetting with LaTeX integration
12+
- **Academic Features**: Citations, cross-references, and bibliographies
13+
- **Template System**: Customizable templates for institutional branding
14+
15+
## Prerequisites
16+
17+
### System Requirements
18+
19+
1. **Quarto Installation**: Download and install Quarto from [quarto.org](https://quarto.org/docs/get-started/)
20+
2. **Optional Dependencies** (for enhanced features):
21+
- **Python**: For interactive Python code blocks
22+
- **R**: For statistical computing and visualization
23+
- **Julia**: For high-performance computing
24+
- **LaTeX**: For PDF generation (TeXLive or MiKTeX)
25+
26+
### Feature Flag
27+
28+
Quarto integration is disabled by default to avoid requiring Quarto for basic usage. Enable it when building:
29+
30+
```bash
31+
# Enable Quarto integration only
32+
cargo build --features quarto-integration
33+
34+
# Enable all advanced features
35+
cargo build --features full
36+
```
37+
38+
## Supported Export Formats
39+
40+
The Quarto integration provides these export formats:
41+
42+
| Format | Description | Output | Use Case |
43+
|--------|-------------|---------|----------|
44+
| `QuartoHtml` | Interactive HTML | `.html` | Online learning, interactive content |
45+
| `QuartoPdf` | High-quality PDF | `.pdf` | Print materials, formal documents |
46+
| `QuartoPowerPoint` | Presentation slides | `.pptx` | Classroom presentations |
47+
| `QuartoWord` | Word document | `.docx` | Collaborative editing |
48+
| `QuartoBook` | Multi-chapter book | `.html/.pdf` | Course textbooks, comprehensive guides |
49+
| `QuartoWebsite` | Multi-page website | `.html` | Course websites, online resources |
50+
51+
## Usage Examples
52+
53+
### Basic Export
54+
55+
```rust
56+
use curriculum_curator::export::{ExportFormat, ExportOptions, QuartoConverter, FormatConverter};
57+
58+
// Check if Quarto is available
59+
if QuartoConverter::is_available() {
60+
let converter = QuartoConverter::new()?;
61+
62+
let options = ExportOptions {
63+
format: ExportFormat::QuartoHtml,
64+
output_path: PathBuf::from("output.html"),
65+
template_name: None,
66+
include_metadata: true,
67+
};
68+
69+
let result = converter.convert(&content, &options).await?;
70+
}
71+
```
72+
73+
### Checking Capabilities
74+
75+
```rust
76+
let converter = QuartoConverter::new()?;
77+
let capabilities = converter.get_capabilities();
78+
79+
println!("Quarto version: {}", capabilities.version);
80+
println!("Python support: {}", capabilities.has_python);
81+
println!("R support: {}", capabilities.has_r);
82+
```
83+
84+
## Quarto Document Structure
85+
86+
The converter generates `.qmd` files with this structure:
87+
88+
```yaml
89+
---
90+
title: "Content Title"
91+
date: "2024-01-15"
92+
author: "Curriculum Curator"
93+
format:
94+
html:
95+
toc: true
96+
toc-location: left
97+
code-tools: true
98+
theme: cosmo
99+
pdf:
100+
documentclass: article
101+
geometry:
102+
- margin=1in
103+
execute:
104+
echo: false
105+
warning: false
106+
---
107+
108+
# Content Title
109+
110+
::: {.callout-note}
111+
## Content Information
112+
- **Content Type**: Presentation Slides
113+
- **Word Count**: 487 words
114+
- **Estimated Duration**: 90 minutes
115+
- **Difficulty Level**: Beginner
116+
:::
117+
118+
## Slide 1
119+
120+
Content here...
121+
122+
::: {.callout-tip collapse="true"}
123+
## Speaker Notes
124+
Additional notes for instructors...
125+
:::
126+
```
127+
128+
## Content Type Handling
129+
130+
The converter processes different content types optimally for Quarto:
131+
132+
### Slides
133+
- Converts slide separators to Quarto sections
134+
- Transforms speaker notes into collapsible callouts
135+
- Maintains slide hierarchy
136+
137+
### Quizzes
138+
- Creates interactive question blocks
139+
- Uses collapsible callouts for answers
140+
- Formats multiple choice options
141+
142+
### Worksheets
143+
- Converts exercises to structured sections
144+
- Creates answer spaces with proper formatting
145+
- Maintains exercise numbering
146+
147+
### Instructor Notes
148+
- Organizes content into themed callouts
149+
- Uses appropriate icons and styling
150+
- Preserves timing and preparation information
151+
152+
## Template Customization
153+
154+
Quarto supports extensive customization through:
155+
156+
### YAML Configuration
157+
```yaml
158+
format:
159+
html:
160+
theme: custom.scss
161+
css: styles.css
162+
toc: true
163+
pdf:
164+
documentclass: book
165+
template: custom-template.tex
166+
```
167+
168+
### Custom Templates
169+
- Create institutional templates
170+
- Apply consistent branding
171+
- Customize typography and layout
172+
173+
### CSS Styling
174+
- Override default themes
175+
- Add custom styling
176+
- Ensure accessibility compliance
177+
178+
## Error Handling
179+
180+
The integration includes robust error handling:
181+
182+
```rust
183+
match converter.convert(&content, &options).await {
184+
Ok(result) => {
185+
if result.success {
186+
println!("Export successful: {}", result.output_path.display());
187+
} else {
188+
eprintln!("Export failed: {}", result.error_message.unwrap_or_default());
189+
}
190+
},
191+
Err(e) => {
192+
eprintln!("Conversion error: {}", e);
193+
}
194+
}
195+
```
196+
197+
## Best Practices
198+
199+
### For Educators
200+
1. **Start Simple**: Begin with basic HTML output, then explore advanced features
201+
2. **Template Libraries**: Create reusable templates for your institution
202+
3. **Version Control**: Use Git to track template and content changes
203+
4. **Batch Processing**: Generate multiple formats simultaneously
204+
5. **Quality Assurance**: Preview outputs before distribution
205+
206+
### For Developers
207+
1. **Feature Detection**: Always check if Quarto is available before use
208+
2. **Graceful Degradation**: Provide fallbacks when Quarto is unavailable
209+
3. **Resource Management**: Clean up temporary files after processing
210+
4. **Error Logging**: Log Quarto execution errors for debugging
211+
5. **Testing**: Test with various content types and formats
212+
213+
## Troubleshooting
214+
215+
### Common Issues
216+
217+
**Quarto Not Found**
218+
```
219+
Error: Quarto executable not found
220+
```
221+
- Ensure Quarto is installed and in PATH
222+
- Try specifying full path to quarto executable
223+
224+
**LaTeX Errors (PDF Generation)**
225+
```
226+
Error: LaTeX compilation failed
227+
```
228+
- Install complete LaTeX distribution (TeXLive/MiKTeX)
229+
- Check for special characters requiring escaping
230+
- Use `--debug` flag to see LaTeX output
231+
232+
**Template Errors**
233+
```
234+
Error: Template not found
235+
```
236+
- Ensure template files are in correct location
237+
- Check template path in configuration
238+
- Validate template syntax
239+
240+
### Debug Mode
241+
242+
Enable verbose logging for troubleshooting:
243+
244+
```rust
245+
// Set environment variable for debug output
246+
std::env::set_var("QUARTO_DEBUG", "1");
247+
248+
let result = converter.convert(&content, &options).await?;
249+
```
250+
251+
## Integration with Export Manager
252+
253+
The Quarto converter integrates seamlessly with the existing export system:
254+
255+
```rust
256+
use curriculum_curator::export::{ExportManager, ExportFormat, ExportOptions};
257+
258+
let manager = ExportManager::new();
259+
260+
// Quarto formats are automatically available if Quarto is installed
261+
let supported_formats = manager.supported_formats();
262+
263+
// Use through the unified interface
264+
let result = manager.export_content(&content, &options).await?;
265+
```
266+
267+
## Performance Considerations
268+
269+
- **Cold Start**: First Quarto execution may be slower due to initialization
270+
- **Resource Usage**: LaTeX PDF generation is memory-intensive
271+
- **Batch Processing**: Process multiple documents in sequence for efficiency
272+
- **Caching**: Quarto caches computations for faster subsequent builds
273+
274+
## Limitations
275+
276+
- **Dependency**: Requires Quarto installation on target system
277+
- **Complexity**: More complex than basic export formats
278+
- **File Size**: Generated documents may be larger due to embedded features
279+
- **Compatibility**: Output quality depends on Quarto version and dependencies
280+
281+
## Future Enhancements
282+
283+
Planned improvements for Quarto integration:
284+
285+
- **Template Marketplace**: Shareable template repository
286+
- **Live Preview**: Real-time preview during editing
287+
- **Custom Extensions**: Support for Quarto extensions
288+
- **Cloud Rendering**: Optional cloud-based rendering service
289+
- **Multi-language**: Enhanced support for international content
290+
291+
## Resources
292+
293+
- [Quarto Documentation](https://quarto.org/docs/)
294+
- [Quarto Gallery](https://quarto.org/docs/gallery/)
295+
- [Template Repository](https://github.com/quarto-dev/quarto-cli/tree/main/src/resources/formats)
296+
- [Community Templates](https://github.com/topics/quarto-template)
297+
- [Academic Writing Guide](https://quarto.org/docs/authoring/scholarly-writing.html)
298+
299+
## Contributing
300+
301+
To contribute to Quarto integration:
302+
303+
1. Test with various Quarto versions
304+
2. Create educational-specific templates
305+
3. Improve error handling and user experience
306+
4. Add support for additional Quarto features
307+
5. Write comprehensive documentation and examples

0 commit comments

Comments
 (0)