# Converting blogdown to Quarto Guide for converting blogdown (Hugo-based) sites to Quarto websites or blogs. ## Overview Key differences: 1. Configuration: `config.toml` or `config.yaml` → `_quarto.yml` 2. Content: Hugo templates → Quarto layouts 3. Shortcodes: Hugo → Quarto shortcodes 4. Themes: Hugo themes → Quarto themes ## Quick Start ### 1. Create Quarto Config Replace `config.toml` or `config.yaml` with `_quarto.yml`: ```yaml project: type: website website: title: "My Site" navbar: left: - href: index.qmd text: Home - href: about.qmd text: About - href: blog.qmd text: Blog format: html: theme: cosmo ``` ### 2. Rename Files ```bash for f in content/**/*.Rmd; do mv "$f" "${f%.Rmd}.qmd" done ``` ### 3. Update Front Matter #### Blogdown ```yaml title: "Post Title" author: "Author" date: "2024-01-15" slug: "post-slug" categories: ["R"] tags: ["data"] ``` #### Quarto ```yaml title: "Post Title" author: "Author" date: 2024-01-15 categories: - R - data ``` ## Project Structure ### blogdown ```txt config.toml (or config.yaml) content/ _index.md about.md post/ 2024-01-01-first/ index.Rmd static/ images/ themes/ hugo-theme/ public/ ``` ### Quarto ```txt _quarto.yml index.qmd about.qmd posts/ first-post/ index.qmd images/ _site/ ``` ## Configuration Mapping ### Basic Site Config #### Blogdown (`config.yaml`) ```yaml baseURL: "https://example.com/" title: "My Site" theme: "hugo-theme" params: description: "Site description" author: "Author Name" menu: main: - name: "Home" url: "/" weight: 1 - name: "About" url: "/about/" weight: 2 ``` #### Quarto (`_quarto.yml`) ```yaml project: type: website output-dir: _site website: title: "My Site" description: "Site description" site-url: https://example.com/ navbar: left: - href: index.qmd text: Home - href: about.qmd text: About - href: blog.qmd text: Blog format: html: theme: cosmo author: "Author Name" ``` The same mapping applies to `config.toml` --- convert TOML keys to the equivalent Quarto YAML. ## Blog Setup ### Listing Page Create `blog.qmd`: ```yaml title: "Blog" listing: contents: posts type: default sort: "date desc" categories: true feed: true ``` ### Post Structure ```txt posts/ 2024-01-15-first-post/ index.qmd images/ figure1.png 2024-01-20-second-post/ index.qmd ``` ### Post Front Matter ```yaml title: "Post Title" description: "Brief description for listing" author: "Author Name" date: 2024-01-15 categories: - R - Tutorial image: images/preview.png draft: false ``` ## Hugo Shortcodes ### Figure #### Hugo ````markdown {{}} ```` #### Quarto ````markdown  ```` ### Tweet #### Hugo ````markdown {{}} ```` #### Quarto (with extension) ````markdown {{< tweet username 1234567890 >}} ```` Install extension: `quarto add sellorm/quarto-social-embeds` ### YouTube #### Hugo ````markdown {{}} ```` #### Quarto ````markdown {{< video https://www.youtube.com/embed/VIDEO_ID >}} ```` ### Gist #### Hugo ````markdown {{}} ```` ### Highlight #### Hugo ````markdown {{}} code here {{}} ```` #### Quarto ````markdown ```{.r} code here ``` ```` or ````markdown ```r code here ``` ```` ### Ref/Relref #### Hugo ````markdown [Link]({{}}) ```` #### Quarto ````markdown [Link](other-post.qmd) ```` ## Taxonomies ### blogdown Categories and Tags ```yaml categories: ["R", "Data Science"] tags: ["ggplot2", "visualization"] ``` ### Quarto Categories ```yaml categories: - R - Data Science - ggplot2 - visualization ``` Enable category listing: ```yaml # In blog.qmd listing: contents: posts categories: true ``` ## Static Files ### blogdown Static files in `static/` are copied to site root. ### Quarto Put files in project root or use `resources`: ```yaml # _quarto.yml project: resources: - images/ - files/ ``` ## Themes and Styling ### blogdown Uses Hugo themes from `themes/` directory. ### Quarto Use built-in themes or custom SCSS: ```yaml format: html: theme: - cosmo - custom.scss ``` ### Custom SCSS ```scss // custom.scss $body-bg: #ffffff; $body-color: #333333; $link-color: #0066cc; // Custom rules .quarto-title { font-size: 2.5rem; } ``` ## RSS Feed ### blogdown Hugo generates RSS automatically. ### Quarto Enable in listing: - `blog.qmd` ````markdown --- listing: feed: true --- ```` Or in `_quarto.yml`: ```yaml website: site-url: https://example.com listing: feed: title: "My Blog" description: "Blog description" ``` ## Comments ### Quarto In `_quarto.yml`: ```yaml website: comments: giscus: repo: username/repo category: "Comments" ``` Or per-post: ```yaml comments: giscus: repo: username/repo ``` ## Syntax Highlighting ### blogdown Configured in Hugo config or theme. ### Quarto ```yaml format: html: highlight-style: github code-line-numbers: true code-fold: true ``` ## Draft Posts ### blogdown ```yaml draft: true ``` ### Quarto Same syntax: ```yaml draft: true ``` Render drafts with: ```bash quarto render --profile drafts ``` With profile config: ```yaml # _quarto-drafts.yml execute: echo: true website: drafts: true ``` ## Deployment ### Netlify ```yaml # netlify.toml [build] command = "quarto render" publish = "_site" ``` ### GitHub Pages ```yaml # .github/workflows/publish.yml name: Publish on: push: branches: [main] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: quarto-dev/quarto-actions/setup@v2 - run: quarto render - uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./_site ``` ## Common Issues ### Missing Shortcodes Install Quarto extensions for missing functionality. ### Broken Internal Links Update `.md` and `.Rmd` extensions to `.qmd`. ### Theme Differences Quarto themes differ from Hugo themes; expect visual changes. ### Build Errors Check for Hugo-specific template syntax in content files. ## Resources - [Quarto Websites](https://quarto.org/docs/websites/) - [Quarto Blogs](https://quarto.org/docs/websites/website-blog.html) - [Quarto Themes](https://quarto.org/docs/output-formats/html-themes.html)