Home

The sorting-hat Quarto extension selectively includes or excludes code blocks based on programming language. Like the magical Sorting Hat, it sorts your code blocks into the houses (languages) you want to see. This is useful when you want to create language-specific versions of your documents from a single source.

Installation

To install the sorting-hat Quarto extension, follow these steps:

Open your terminal.
Execute the following command:

quarto add coatless-quarto/sorting-hat

This command will download and install the Quarto extension under the _extensions subdirectory of your Quarto project. If you are using version control, ensure that you include this directory in your repository.

Usage

Add the sorting-hat filter to your document’s YAML front matter alongside the desired configuration options. For example, to keep only Python code blocks:

---
title: "My Document"
filters:
  - sorting-hat
extensions:
    sorting-hat:
        keep: python
---

All code blocks not written in Python will be removed from the document.

Configuration Options

Global Options

Option	Type	Description	Default
`keep`	string or list	Languages to include (all others filtered)	none
`remove`	string or list	Languages to exclude (all others kept)	none
`action`	string	How to handle filtered code: `"remove"` or `"collapse"`	`"remove"`
`placeholder`	string	Text to show when content is removed (use `{language}` for language name)	none
`placeholder-style`	string	CSS styles for placeholder	default styling
`verbose`	boolean	Enable debug logging	`false`

Notes

If you specify both keep and remove, the keep option takes precedence
Code blocks without a language class are always kept
The filter only affects code blocks, not inline code

Cell-Level Attributes

Add to individual code cells to override global settings:

Attribute	Description
`#\\| sorting-hat: keep`	Always keep this cell
`#\\| sorting-hat: remove`	Always remove this cell
`#\\| sorting-hat: collapse`	Always collapse this cell

Examples of Configuration

Keep Specific Languages

Use the keep option to specify which languages should be included (all others will be removed):

---
title: "My Document"
format: html
filters:
  - sorting-hat
extensions:
  sorting-hat:
    keep: python
---

Or keep multiple languages:

---
title: "My Document"
format: html
filters:
  - sorting-hat
extensions:
  sorting-hat:
    keep:
      - python
      - bash
---

Remove Specific Languages

Use the remove option to specify which languages should be excluded (all others will be kept):

---
title: "My Document"
format: html
filters:
  - sorting-hat
extensions:
  sorting-hat:
    remove: r
---

Or remove multiple languages:

---
title: "My Document"
format: html
filters:
  - sorting-hat
extensions:
  sorting-hat:
    remove:
      - r
      - julia
---

Cell-Level Overrides

Override global settings for specific cells:

---
filters: [sorting-hat]
extensions:
  sorting-hat:
    keep: python
---


::: {.cell sorting-hat='keep'}

```{.r .cell-code}
# This R cell is kept despite global Python-only setting
cat("Hello from R\n")
```

::: {.cell-output .cell-output-stdout}

```
Hello from R
```


:::
:::



::: {.cell sorting-hat='remove'}

```{.python .cell-code}
# This Python cell is removed despite being in keep list
print("This won't appear")
```

::: {.cell-output .cell-output-stdout}

```
This won't appear
```


:::
:::

Placeholder Text

Show a message where content is removed:

extensions:
  sorting-hat:
    remove: r
    placeholder: "[{language} code hidden]"
    placeholder-style: "color: #888; font-style: italic;"

Collapse Instead of Remove

Hide code in expandable sections:

extensions:
  sorting-hat:
    remove: r
    action: collapse  # Code becomes clickable to expand (in HTML output)

Debug Mode

Enable debug logging to see which code blocks are being processed:

---
title: "My Document"
format: html
filters:
  - sorting-hat
extensions:
  sorting-hat:
    keep: python
    debug: true
---