Skip to content

Commit ca0bc5f

Browse files
Copilotmaehr
Copilot
and
maehr
committed
Complete Quarto migration with documentation and improved configurations
Co-authored-by: maehr <14755525+maehr@users.noreply.github.com>
1 parent 4fefbe1 commit ca0bc5f

File tree

3 files changed

+133
-0
lines changed

3 files changed

+133
-0
lines changed

‎QUARTO_MIGRATION.md

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
# Quarto Migration Guide
2+
3+
This document explains how to use the new Quarto-based workflow alongside the existing Pandoc/Make workflow.
4+
5+
## Prerequisites
6+
7+
To use the Quarto workflow, you need:
8+
9+
1. [Quarto CLI](https://quarto.org/docs/get-started/installation.html)
10+
2. [Pandoc](http://pandoc.org/installing.html) (typically installed with Quarto)
11+
3. [Tectonic](https://tectonic-typesetting.github.io/) or another LaTeX distribution for PDF output
12+
4. [pandoc-crossref](https://github.com/lierdakil/pandoc-crossref) for cross-references in the thesis
13+
14+
## Quick Start
15+
16+
### Render All Projects
17+
```bash
18+
quarto render
19+
```
20+
21+
### Render Individual Projects
22+
```bash
23+
# Article
24+
quarto render article/
25+
26+
# Presentation
27+
quarto render presentation/
28+
29+
# Thesis
30+
quarto render thesis/
31+
```
32+
33+
### Render Specific Formats
34+
```bash
35+
# Article as PDF only
36+
quarto render article/ --to pdf
37+
38+
# Presentation as HTML slides only
39+
quarto render presentation/ --to revealjs
40+
41+
# Thesis as DOCX only
42+
quarto render thesis/ --to docx
43+
```
44+
45+
## Project Configuration
46+
47+
Each project directory now contains a `_quarto.yml` file that configures:
48+
49+
- Output formats (PDF, DOCX, HTML, etc.)
50+
- Format-specific options (PDF engine, slide level, etc.)
51+
- Filters and extensions
52+
- File inclusion order (for multi-file projects like thesis)
53+
54+
### Article Project
55+
- **Type**: Default project
56+
- **Input**: `article.md`
57+
- **Formats**: DOCX, PDF, LaTeX
58+
- **Config**: `article/_quarto.yml`
59+
60+
### Presentation Project
61+
- **Type**: Default project
62+
- **Input**: `presentation.md`
63+
- **Formats**: RevealJS (HTML), PDF, PowerPoint, LaTeX
64+
- **Config**: `presentation/_quarto.yml`
65+
66+
### Thesis Project
67+
- **Type**: Book project
68+
- **Input**: Multiple chapters (00.md, 00_Introduction.md, etc.)
69+
- **Formats**: DOCX, EPUB, PDF, LaTeX
70+
- **Config**: `thesis/_quarto.yml`
71+
- **Special Features**: Custom filters, multiple bibliographies
72+
73+
## Migration Benefits
74+
75+
1. **Unified Build System**: Single command to render all formats
76+
2. **Modern Tooling**: Quarto provides advanced features like cross-references, code execution, and interactive content
77+
3. **Better Error Handling**: Clearer error messages and debugging
78+
4. **Extensibility**: Easy to add new formats or customize existing ones
79+
5. **IDE Integration**: Better support in RStudio, VS Code, and other editors
80+
81+
## Backward Compatibility
82+
83+
The original Pandoc/Make workflow is preserved:
84+
- All original YAML configuration files remain
85+
- Makefile continues to work
86+
- GitHub Actions support both workflows
87+
88+
This allows for gradual migration and comparison between approaches.
89+
90+
## Testing the Migration
91+
92+
To verify everything works:
93+
94+
1. Install Quarto
95+
2. Run `quarto render article/`
96+
3. Compare output with `make article`
97+
4. Check that all expected files are generated
98+
5. Verify content quality matches original output
99+
100+
## Common Issues and Solutions
101+
102+
### Missing pandoc-crossref
103+
If you get errors about pandoc-crossref, install it:
104+
```bash
105+
# On macOS with Homebrew
106+
brew install pandoc-crossref
107+
108+
# On Linux, download from GitHub releases
109+
wget https://github.com/lierdakil/pandoc-crossref/releases/latest/download/pandoc-crossref-Linux.tar.xz
110+
tar -xf pandoc-crossref-Linux.tar.xz
111+
sudo mv pandoc-crossref /usr/local/bin/
112+
```
113+
114+
### Lua Filter Errors
115+
The thesis project uses custom Lua filters. Ensure they're in the correct path (`thesis/filters/`) and have proper permissions.
116+
117+
### LaTeX Errors
118+
If you encounter LaTeX errors with PDF output:
119+
1. Ensure Tectonic or another LaTeX distribution is installed
120+
2. Check that all required LaTeX packages are available
121+
3. Consider using `--pdf-engine=xelatex` as an alternative
122+
123+
## Next Steps
124+
125+
1. Test the Quarto workflow with your content
126+
2. Customize `_quarto.yml` files as needed
127+
3. Report any issues or improvements needed
128+
4. Consider fully migrating once comfortable with the new workflow

‎README.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,8 @@ Each project type has a `_quarto.yml` configuration file:
100100

101101
These files define output formats, filters, and other project settings. Content and metadata are still configured in the Markdown files as before.
102102

103+
**For detailed migration instructions, see [QUARTO_MIGRATION.md](QUARTO_MIGRATION.md).**
104+
103105
### Pandoc Configuration (Legacy)
104106

105107
For backward compatibility, the original Pandoc configuration files are preserved:
@@ -157,6 +159,7 @@ This project is maintained by [@maehr](https://github.com/maehr). Please underst
157159
- [Pandoc](https://pandoc.org/) a universal document converter and
158160
- [Pandoc GitHub action](https://github.com/pandoc/pandoc-action-example)
159161
- [Prettier](https://prettier.io/) an opinionated code formatter
162+
- [Quarto](https://quarto.org/) an open-source scientific and technical publishing system
160163
- [Tectonic](https://tectonic-typesetting.github.io/en-US/) a modernized, complete, self-contained [TeX](https://www.tug.org/)/[LaTeX](https://www.latex-project.org/) engine, powered by [XeTeX](http://xetex.sourceforge.net/) and [TeXLive](https://www.tug.org/texlive/)
161164
- [Tectonic GitHub action](https://github.com/WtfJoke/setup-tectonic)
162165

@@ -165,6 +168,7 @@ This project is maintained by [@maehr](https://github.com/maehr). Please underst
165168
- [x] Refactoring of the article template
166169
- [x] Templates for presentation and thesis
167170
- [x] Change name of master branch to main
171+
- [x] **Migration to Quarto projects**
168172
- [ ] Improve documentation
169173
- [ ] Improve caching in `.github/workflows/pandoc.yml`
170174

‎presentation/_quarto.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ format:
55
revealjs:
66
output-file: presentation.html
77
slide-level: 2
8+
embed-resources: true
89
pdf:
910
output-file: presentation.pdf
1011
pdf-engine: tectonic

0 commit comments

Comments
 (0)