Quarto with JamsEDU

JamsEDU lets you drop standard Quarto .qmd files into your project and have them rendered alongside your .jhp pages with the same site chrome. No extra build step on your part: JamsEDU calls Quarto internally, captures the HTML output, and wraps it in your template.

Use this page as your quick-start guide for authoring .qmd files in a JamsEDU project. See the companion demo for a live example of the finished output.

How It Works

1. You create content in *.qmd files.
2. JamsEDU calls Quarto to render each file. Quarto resolves its own features (e.g. {{< include >}}, fenced ::: blocks) and produces an HTML fragment.
3. JamsEDU injects that fragment into your quarto.template layout (quarto in .jamsedu/config.js), so the published page ships with the same header, footer, and styling as your .jhp pages.

By design, JamsEDU ignores any Quarto website-level configuration (navigation, search, listings, etc.) in your .qmd files and applies its own safe defaults.

Configuration

Quarto options live under the quarto key in .jamsedu/config.js and should be an object with the following properties:

quarto: {
    /**
     * The .jhp file used as the wrapper template for all .qmd pages.
     * A default template ships with a fresh JamsEDU install.
     */
    template: 'src/templates/quarto.jhp',

    /**
     * Output directory where Quarto-generated assets (images, figures, etc.) are placed.
     */
    assetsDir: 'quarto-assets',

    /**
     * Staging directory for temporary build files. Should be git-ignored.
     */
    workingDir: '.quarto'
}

The Template

The default template that ships with JamsEDU is minimal:

    $include('/header.html');
    $echo(quartoHtml);
    $include('/footer.html');

If you modify the template or create your own, you must include $echo(quartoHtml); somewhere in it. That call is where the rendered .qmd content gets placed.

Quarto Project YAML

You can provide your own Quarto project YAML to set global .qmd settings and metadata. Place one of the following files inside .jamsedu/ (only the first one found is used, checked in this order):

1. quarto.yml
2. _quarto.yml
3. quarto-project.yml

Note that some keys are managed internally by JamsEDU and cannot be overridden.

Using JamsEDU Features in .qmd Files

HTML Blocks

JamsEDU sites support Quarto’s built-in raw HTML blocks. These blocks must not be indented because Pandoc treats indented lines as code blocks and will break the rendered output:

```{=html}
<nav>
<ul>
<li>...</li>
</ul>
</nav>
```

For better results you can use JamsEDU’s raw HTML fenced block instead. We support the lazy HTML fenced block:

::: html
<nav>
    <ul>
        <li>...</li>
    </ul>
</nav>
:::

As well as the explicit HTML fenced block:

::: {.html}
<nav>
    <ul>
        <li>...</li>
    </ul>
</nav>
:::

Mermaid Diagrams

Quarto’s built-in Mermaid syntax will work in JamsEDU sites, but for best results use the JamsEDU fenced blocks instead. To add Mermaid diagrams in .qmd files, use either of the following:

::: {.jams-mermaid}
flowchart LR
  A --> B --> C
:::

::: {.jams-diagram}
sequenceDiagram
  A->>B: hello
:::

KaTeX math

To write math equations in .qmd files, use the standard $…$ for inline and $$…$$ for display (block) math.

Here is an example of $...$ (inline) math, followed by $$...$ (block) math:

If a formula misbehaves (money-like text, complex TeX, edge cases), you can use an explicit fenced block or inline shortcode instead.

Fenced blocks:

::: {.jams-katex .macro}
\f = #1f(#2)
:::

::: {.jams-math}
\f\relax{x} = \int_{-\infty}^\infty \f\hat\xi\,e^{2 \pi i \xi x} \,d\xi
:::

Inline shortcode:

For explicit inline math without $ delimiters, use the {{< jams-math-inline >}} shortcode (aliased as jams-katex-inline). You can add macro="true" for macro definitions. See the KaTeX guide for more details.

The sum {{< jams-math-inline formula="\alpha+\beta=\gamma" >}} appears in line.

Embedded PDF

To embed a PDF in .qmd files, use the following fenced block that contains only the URL to the PDF:

::: {.jams-pdf}
/assets/docs/jamsedu-demo.pdf
:::

Responsive video

To auto embed a responsive video in .qmd files, use the following fenced blocks based on your needs:

::: {.jams-video}
https://youtu.be/NpEaa2P7qZI
:::

::: {.jams-video cite="Sample video citation"}
https://youtu.be/NpEaa2P7qZI
:::

If you need to embed an unsupported video format you should use a standard HTML code block:

```{=html}
<iframe src="..." title="Embedded video" ...></iframe>
```

Rich Text

To add a rich text editor in .qmd files, use a fenced block with the {.jams-rich} class. The placeholder attribute is optional. To prepopulate the editor, put HTML inside an inner ```{=html} block (below), or omit that fence and paste HTML directly; JamsEDU inserts the inner fence before Quarto when it is missing.

::: {.jams-rich placeholder="Answer in a few sentences."}
<p>Draft answer goes here.</p>
:::

Tiny Document

To add a Tiny Document in .qmd files, use a fenced block with the {.jams-document} class. The canonical recipe wraps the body in an inner Pandoc raw HTML fence (three backticks and {=html}). JamsEDU also inserts that fence before Quarto when you omit it, so bare Tiny Document HTML inside the ::: is allowed; either way the inner markup must stay valid Tiny Document HTML and classes.

::: {.jams-document}
<div class="title">Worksheet</div>
<div class="header">
    <div><input type="text" placeholder="Your Name"></div>
    <div><input type="date"></div>
</div>
<div class="section">Reflection</div>
<p class="instructions">
    This is a simple demo document...
</p>
<textarea class="rich" placeholder="Write your thoughts here..."></textarea>
:::

Code highlighting

JamsEDU already supports code highlighting so code blocks (```) will automatically be highlighted with JamsEDU’s version of Highlight.js:

```javascript
const sum = (a, b) => {
    return a + b;
};

console.log(sum(10, 32));
```

Migration tips

• Put .qmd sources under srcDir from your JamsEdu configuration.
• Point quarto.template at a single JHP file for shared Quarto HTML (header, footer, scripts, styles).
• Place any extra files (images, CSS, scripts, etc.) from your Quarto project into your JamsEDU assetsDir so they stay available at their usual URLs.

Sample .qmd page

To see all of these examples running on a live page, visit the companion .qmd demo.