Frequently Asked Questions
Getting Started
How do I install sorting-hat?
Run this command in your Quarto project’s directory:
quarto add coatless-quarto/sorting-hatThis installs the extension into _extensions/coatless-quarto/sorting-hat/. If you use version control, check in the _extensions directory.
What version of Quarto do I need?
Quarto 1.11 or later. Check your version with:
quarto --versionsorting-hat is a Lua filter, so it doesn’t need anything else.
How do I turn it on?
Add the filter and your options to the document’s front matter:
---
title: "My Document"
filters:
- sorting-hat
extensions:
sorting-hat:
keep: python
---Without keep or remove, sorting-hat leaves every code block in place.
Choosing Languages
Should I use keep or remove?
Use keep to list the languages to show; everything else is filtered. Use remove to list the languages to filter; everything else stays. Both take one language or a list:
extensions:
sorting-hat:
keep: [python, bash]If you set both, keep wins and remove is ignored.
What name do I use for a language?
The name from the code block, exactly as written: python for {python} cells and r for {r} cells. Names are case-sensitive, so keep: Python doesn’t match {python} cells, and bash and sh count as different languages.
Which code blocks does it look at?
Both executed cells, such as {python}, and plain code blocks that name a language, such as a ```bash block. Code blocks without a language are always kept, and inline code is never changed.
What happens to a cell’s output?
When sorting-hat filters a cell, the code and its output go together. To hide a cell’s code but keep its output, use Quarto’s echo: false instead.
A cell with echo: false shows no code, so sorting-hat can’t tell its language and always keeps its output. To filter one of those cells, give it a cell override with #| sorting-hat: remove.
Cell Overrides
Can I make an exception for one cell?
Yes. Add the sorting-hat cell option to that cell:
```{r}
#| sorting-hat: keep
cat("This R cell stays, even with keep: python\n")
```It takes one of three values:
| Cell option | Effect |
|---|---|
#| sorting-hat: keep |
Always keep this cell |
#| sorting-hat: remove |
Always remove this cell |
#| sorting-hat: collapse |
Always collapse this cell |
An override wins over keep and remove, and works even when you set neither. It can go anywhere among the cell’s other options, and its value isn’t case-sensitive.
Why isn’t my override working?
Check that:
- The cell is an executed cell, such as
```{python}. Overrides are cell options, so a plain```pythonblock ignores them. - The value is
keep,remove, orcollapse. sorting-hat ignores any other value and filters the cell by its language as usual.
Placeholders and Collapsing
Can I show a note where code was removed?
Yes, with placeholder. {language} becomes the removed block’s language:
extensions:
sorting-hat:
remove: r
placeholder: "[{language} code hidden]"This shows [r code hidden] in place of each R block. Without placeholder, removed code leaves nothing behind.
How do I change the placeholder’s look?
Set placeholder-style to the CSS you want:
extensions:
sorting-hat:
remove: r
placeholder: "[{language} code hidden]"
placeholder-style: "color: #b45309; font-weight: bold;"The default style is color: #888; font-style: italic; padding: 0.5em; border-left: 3px solid #ddd; margin: 1em 0;. The style applies to HTML output. Other formats show the placeholder as italic text.
Can I collapse filtered code instead of removing it?
Yes, with action: collapse:
extensions:
sorting-hat:
keep: python
action: collapseEach filtered block or cell goes into a collapsed section, labeled with its language in capitals, such as “R code (click to expand)”. Readers click the label to see the code and its output. The label’s wording is fixed.
placeholder has no effect with action: collapse, because nothing is removed.
Does collapsing work outside HTML?
No. Collapsing needs HTML. In PDF, Typst, and Word output, a collapsed block shows its code in full, without the label. To leave filtered code out of those formats, give them action: remove with options for each output format.
Projects and Formats
Can I set the options once for a whole project?
Yes. Put the filter and the options in _quarto.yml, and they apply to every page in the project:
filters:
- sorting-hat
extensions:
sorting-hat:
keep: pythonA page can set its own extensions: sorting-hat: options too. Quarto combines them with the project’s: anything the page doesn’t set still comes from _quarto.yml, and a single value the page sets, such as action: collapse or keep: r, replaces the project’s. Lists are joined instead, so with keep: [python] in _quarto.yml, a page with keep: [r] keeps both languages. To switch languages on one page, write keep as a single name, without brackets, in both places.
To turn the options off for one page, so that it keeps every block:
extensions:
sorting-hat: falseCan I use different options for each output format?
Yes. Put extensions: under each format:
filters:
- sorting-hat
format:
html:
extensions:
sorting-hat:
keep: python
action: collapse
docx:
extensions:
sorting-hat:
keep: python
placeholder: "[{language} code is in the online version]"How do I make a Python version and an R version from one source?
Use Quarto profiles in a project with filters: [sorting-hat] in its _quarto.yml. Each profile is a _quarto-<name>.yml file next to _quarto.yml, and its settings are merged into the project’s:
# _quarto-python.yml
project:
output-dir: _site-python
extensions:
sorting-hat:
keep: python# _quarto-r.yml
project:
output-dir: _site-r
extensions:
sorting-hat:
keep: rThen render each profile:
quarto render --profile python
quarto render --profile rGiving each profile its own output-dir keeps the two versions from overwriting each other.
Troubleshooting
Nothing is filtered. What should I check?
- The front matter lists
sorting-hatunderfilters. - The options sit under
extensions: sorting-hat:and includekeeporremove. - The language names match your code blocks exactly, including case.
- The extension is installed, in
_extensions/coatless-quarto/sorting-hat/.
If that all looks right, turn on debug.
How do I see what sorting-hat is doing?
Set debug: true:
extensions:
sorting-hat:
keep: python
debug: trueWhile rendering, sorting-hat then prints its settings and its decision for each code block to the console.
How can I get help?
Open an issue on GitHub with a small document that shows the problem and the console output from debug: true.