47  46. GitHub Markdown vs. Quarto (.qmd) Comparison

This page was generated by AI (after some back and forth prompting). I didn’t check the contents for accuracy (yet).

-YR

47.1 Feature Comparison Tables

47.1.1 Features Supported by Both GitHub and Quarto

Feature GitHub Markdown Quarto (.qmd) Notes
Basic Markdown ✅ ✅ Standard Markdown syntax (headers, lists, links, etc.)
YAML Front Matter ⚠️ Basic support (click here for more info) ✅ Extensive support Used for metadata and document configuration
Math Notation ⚠️ Basic LaTeX (click here for more info) ✅ Advanced LaTeX Mathematical equations and formulas
Task Lists ✅ Advanced ⚠️ Basic support (click here for more info) Checkboxes for task items
HTML Support ⚠️ Restricted (click here for more info) ✅ Extensive Embedding raw HTML within Markdown

47.1.2 Features Only in GitHub Markdown

Feature Description
Auto-linking Automatically converts issue numbers, commit SHAs, and usernames to links
Emoji Shortcodes Supports emoji codes like :smile:
User Mentions Supports @username mentions
Issue References Links to issues with #123
PR References Links to pull requests with #123
Commit References Links to commits with SHA hashes

47.1.3 Features Only in Quarto Markdown

Feature Description
Code Execution Can execute code chunks and display results inline
Multiple Languages Supports multiple programming languages in one document
Citations BibTeX/CSL integration for academic referencing
Cross-references References to figures, tables, sections, and equations
Multi-format Output Publishes to PDF, HTML, DOCX, presentations
Callouts/Admonitions Special highlighted boxes for notes, warnings, tips
Tabsets Tab interfaces for organizing content
Layout Options Column layouts, panel arrangements, page breaks
Execution Options Control over code visibility, evaluation, and caching

47.2 Feature Examples Table

Feature GitHub Markdown Example Quarto (.qmd) Example
YAML Front Matter 
---
title: Document Title
---
 
---
title: "Document Title"
author: "Author Name"
date: "2023-01-15"
format: 
  html:
    toc: true
    code-fold: true
  pdf:
    geometry: margin=1in
bibliography: references.bib
---
Code Blocks 
```python
def hello_world():
    print("Hello, world!")
```
 
```{python}
#| label: fig-scatter
#| fig-cap: "A scatter plot"
#| echo: false

import matplotlib.pyplot as plt
import seaborn as sns

mpg = sns.load_dataset("mpg")
sns.scatterplot(data=mpg, 
                x="horsepower", y="mpg")
```
Math Notation 
When $a \ne 0$, there are two 
solutions to $ax^2 + bx + c = 0$:
$x = {-b \pm \sqrt{b^2-4ac} \over 2a}$
 
When $a \ne 0$, there are two 
solutions to $ax^2 + bx + c = 0$:

$$x = {-b \pm \sqrt{b^2-4ac} 
\over 2a}$$ {#eq-quadratic}

As shown in @eq-quadratic...
Citations Not supported natively 
According to @smith2020, the 
analysis shows significant results.

# References {.unnumbered}
Task Lists 
- [x] Complete documentation
- [ ] Write tests
- [ ] Deploy to production
 
::: {.task-list}
- [x] Complete documentation
- [ ] Write tests
- [ ] Deploy to production
:::
Auto-linking 
See issue #42 for details.
@username can you review this?
See commit 8a3f79e for the fix.
 Not supported natively
Cross-references Not supported natively 
See @fig-scatter for the visualization.

As shown in @sec-methods and 
@tbl-results, the approach works.
Callouts/Admonitions Not supported natively 
::: {.callout-note}
This is an important note.
:::

::: {.callout-warning}
Warning: Proceed with caution!
:::
Tabsets Not supported natively 
::: {.panel-tabset}
### Tab A
Content for tab A

### Tab B
Content for tab B
:::
Column Layout Not supported natively 
:::: {.columns}
::: {.column width="40%"}
Left column content
:::
::: {.column width="60%"}
Right column content
:::
::::

47.3 Potential Conflicts Table

Element GitHub Markdown Quarto (.qmd) Potential Issue
Code Blocks ```python ```{python} with options Code blocks from one system may not execute in the other
Table Formatting Basic pipe tables Enhanced tables with options Complex tables may not render correctly across systems
Heading IDs Auto-generated Can be explicitly set with {#id} Links to headings may break when moving between systems
Image Handling ![alt](src) ![alt](src){width=50%} Image formatting options won't work in GitHub
Footnotes [^1] with note at bottom Similar but with more options Minor syntax differences may cause rendering issues
HTML Elements Limited, sanitized More extensive support HTML that works in Quarto may be stripped in GitHub

47.4 Self-Contained Example

Here’s how you might reference different sections of this document in Quarto:

As we can see in Section 47.1, Quarto offers many capabilities that GitHub Markdown doesn’t support.

The Section 47.2 section demonstrates syntax differences between the two formats.

Section 47.3 highlights potential issues when converting between formats.

47.5 Notes and Details

47.5.1 Note 1: Basic YAML Front Matter Support in GitHub

GitHub recognizes YAML front matter primarily for Jekyll integration. It supports basic metadata like title, description, and permalink, but lacks Quarto’s extensive formatting controls, bibliography management, execution options, and multi-format configuration capabilities.

In GitHub, YAML front matter is primarily used for Jekyll site generation, while in Quarto it controls virtually every aspect of document rendering and behavior.

[Return to table]

47.5.2 Note 2: Basic LaTeX Support in GitHub

GitHub’s LaTeX support is implemented through MathJax and handles basic equations well, but lacks features such as equation numbering, cross-referencing of equations, alignment environments (like align, gather), and theorem environments.

It also doesn’t support LaTeX packages or custom commands that Quarto can handle through the full LaTeX engine it uses for PDF output.

[Return to table]

47.5.3 Note 3: Restricted HTML in GitHub

GitHub sanitizes HTML for security reasons, restricting certain tags (like <script>, <style>, some <iframe> usages) and attributes (especially JavaScript event handlers). Many advanced HTML features that work in Quarto will be stripped in GitHub.

GitHub also doesn’t support custom styling through CSS classes to the extent Quarto does. Quarto allows direct HTML integration with much fewer restrictions when generating HTML output.

[Return to table]

47.5.4 Note 4: Basic Task List Support in Quarto

While Quarto does support task lists with checkbox syntax, GitHub’s implementation is more feature-rich and integrated with its platform capabilities:

  1. GitHub Task List Features:
    • Integration with GitHub Issues and Pull Requests
    • Interactive checkboxes that can be toggled directly in the interface
    • Automatic task tracking and progress reporting
    • Task assignment and project management integration
    • Notifications when tasks are completed
  2. Quarto Task List Limitations:
    • Primarily for display purposes
    • No interactive toggling in standard output formats
    • Lacks integration with project management systems
    • No automatic tracking or status updates
    • Requires a div container with the .task-list class for proper rendering

Quarto’s task lists are functionally static in most output formats, while GitHub’s implementation provides a more interactive, workflow-oriented experience.

[Return to table]