project.render glob fails to match .qmd files in underscore-prefixed directories

[jsbryaniv]

I have:

• searched the issue tracker for similar issues
• installed the latest version of Quarto CLI
• formatted my issue following the Bug Reports guide

Bug description

Make this clearer. How about

I ran into an issue setting the project files when my qmd documents are within a folder with an underscore prefix. For context, I am building a website with Jekyll, where underscore prefixes are required for certain behavior. I am building tutorials for my website using qmd, placing all of my tutorials under a folder called _tutorials.

The issue is that when setting my global config, _quarto.yml, If I set the project files using blog like

project:
  type: default
  render:
    - "_tutorials/**/*.qmd"

format:
  ... my format here...

None of my formatting options would be carried over into the rendered html. This is possibly because the quarto documents paths include _tutorials/..., which has an underscore prefix, which quarto ignores by default.

However I was able to get around this block by changing my project specification to the full dir rather than a glob search

project:
  type: default
  render:
    - "_tutorials"

format:
  ... my format here...

This passed all formatting through to my documents with no issue.

To me, specifying _tutorials and _tutorials/**/*.qmd should have equivalent behavior. I am surprised one works when the other doesnt. Also I would expect that a glob path would be more stable, since you specify exactly what files to include.

Expected behavior:
"_tutorials" and "_tutorials/**/*.qmd" should be equivalent in this case (both target the same .qmd files). I’d expect the glob form to work reliably, especially since it explicitly selects renderable files.

Steps to reproduce

Create _quarto.yml config, and place quarto document inside _example

project:
  type: default
  render:
    - "_example/**/*.qmd"

format:
  ... some formatting ...

Actual behavior

If the project render files specify the folder vs specify the glob search you get different behavior.

Expected behavior

Expected behavior:
"_tutorials" and "_tutorials/**/*.qmd" should be equivalent in this case (both target the same .qmd files). I’d expect the glob form to work reliably, especially since it explicitly selects renderable files.

Your environment

OS: macOS 26.3 (build 25D125)
Kernel/Arch: Darwin 25.3.0, arm64 (Apple Silicon)
Quarto: 1.9.36
Python: 3.13.6
Ruby: 2.6.10p210
Bundler: 2.4.22
Jekyll CLI: not currently available in this shell (jekyll not found / bundle exec jekyll not installed yet)

Quarto check output

jbryaniv@Js-MacBook-Air-4 jsbryaniv.github.io % quarto che
ck
Quarto 1.9.36
[✓] Checking environment information...
Quarto cache location: /Users/jbryaniv/Library/Caches/quarto
[✓] Checking versions of quarto binary dependencies...
Pandoc version 3.8.3: OK
Dart Sass version 1.87.0: OK
Deno version 2.4.5: OK
Typst version 0.14.2: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
Version: 1.9.36
Path: /Applications/quarto/bin

(|) Checking tools...........(/) Checking tools...........(-) Checking tools...........
[✓] Checking tools....................OK
TinyTeX: (not installed)
Chromium: (not installed)
Chrome Headless Shell: (not installed)
VeraPDF: (not installed)

(|) Checking LaTeX...........(/) Checking LaTeX...........(-) Checking LaTeX...........() Checking LaTeX...........(|) Checking LaTeX...........(/) Checking LaTeX...........(-) Checking LaTeX...........() Checking LaTeX...........(|) Checking LaTeX...........(/) Checking LaTeX...........
[✓] Checking LaTeX....................OK
Using: Installation From Path
Path: /Library/TeX/texbin
Version: 2025

[✓] Checking Chrome Headless....................OK
Using: Chrome found on system
Path: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome
Source: MacOS known location

(|) Checking basic markdown r(/) Checking basic markdown r(-) Checking basic markdown r() Checking basic markdown r(|) Checking basic markdown r(/) Checking basic markdown r
[✓] Checking basic markdown render....OK

[✓] Checking R installation...........(None)

  Unable to locate an installed version of R.
  Install R from https://cloud.r-project.org/

[✓] Checking Python 3 installation....OK
Version: 3.13.6
Path: /Library/Frameworks/Python.framework/Versions/3.13/bin/python3
Jupyter: 5.9.1
Kernels: project-env, python3

(|) Checking Jupyter engine r(/) Checking Jupyter engine r(-) Checking Jupyter engine r() Checking Jupyter engine r(|) Checking Jupyter engine r(/) Checking Jupyter engine r(-) Checking Jupyter engine r() Checking Jupyter engine r(|) Checking Jupyter engine r(/) Checking Jupyter engine r(-) Checking Jupyter engine r() Checking Jupyter engine r(|) Checking Jupyter engine r(/) Checking Jupyter engine r(-) Checking Jupyter engine r() Checking Jupyter engine r(|) Checking Jupyter engine r(/) Checking Jupyter engine r(-) Checking Jupyter engine r() Checking Jupyter engine r(|) Checking Jupyter engine r
[✓] Checking Jupyter engine render....OK

(|) Checking Julia installati(/) Checking Julia installati(-) Checking Julia installati() Checking Julia installati(|) Checking Julia installati(/) Checking Julia installati(-) Checking Julia installati() Checking Julia installati(|) Checking Julia installati(/) Checking Julia installati(-) Checking Julia installati() Checking Julia installati(|) Checking Julia installati(/) Checking Julia installati(-) Checking Julia installati() Checking Julia installati(|) Checking Julia installati(/) Checking Julia installati(-) Checking Julia installati() Checking Julia installati(|) Checking Julia installati(/) Checking Julia installati(-) Checking Julia installati() Checking Julia installati(|) Checking Julia installati(/) Checking Julia installati(-) Checking Julia installati() Checking Julia installati(|) Checking Julia installati
[✓] Checking Julia installation...
jbryaniv@Js-MacBook-Air-4 jsbryaniv.github.io %

[mcanouil]

Files and directories with leading underscore are ignored by Quarto, so you cannot use globs.
If you want to go against the leading underscore policy, then you have to be explicit with full paths.

edit: read too quickly, the issue is about _dir not being equivalent to _dir/**/*.qmd

[mcanouil]

When you specify _directory, Quarto's special directory detection logic overrides the default ignore rules for underscore-prefixed directories. However, _directory/**/*.qmd gets filtered out by the ignore patterns because it's treated as a literal glob pattern rather than a directory path.

From my understanding, that's by design to ensure _ files/directories remain "private" when you give "wrong" glob.

[jsbryaniv]

I see so this behavior is intensional. This issue can be closed then

[mcanouil]

I'll reopen to let the maintainers decide if there is something to reconsider/improve.

[cderv]

I can reproduce and have traced the root cause.

Two code paths diverge

When render: targets are resolved in projectInputFilesInternal(), they go through resolvePathGlobs() which applies underscore exclusion patterns (**/_*, **/_*/**) from projectHiddenIgnoreGlob().

The behavior depends on whether the target is a bare directory name or a glob pattern, because the internal asFullGlob() function prepends **/ to all glob patterns:

quarto-cli/src/core/path.ts

Lines 281 to 283 in ebafc3a

	if (!glob.startsWith("/")) {
	if (smartGlob && (!options || !options.explicitSubfolderSearch)) {
	return "**/" + glob;

Bare directory (_tutorials): Not a glob, so smartGlob=false and no **/ prepend. The literal path goes to expandGlobSync which consumes it as a fixed root path — exclude patterns are never checked against it.

Glob (_tutorials/**/*.qmd): Contains glob characters, so smartGlob=true and **/ is prepended → **/_tutorials/**/*.qmd. The ** at the start forces expandGlobSync to walk the entire project tree with the exclude patterns active. _tutorials matches **/_* and the directory is skipped entirely.

Verified scenarios

Using a test project with this layout:

_tutorials/lesson.qmd
_tutorials/sub/deep.qmd
_tutorials/_private/secret.qmd
docs/_helpers/util.qmd
index.qmd

render: config	Files found
["_tutorials"]	lesson, sub/deep (but NOT _private/secret)
["_tutorials/**/*.qmd"]	(none)
["_tutorials/lesson.qmd"]	lesson (direct path, not a glob)
["**/*.qmd"]	index only
["docs/_helpers/**/*.qmd"]	(none)

The bare directory form works because addDir() walks the directory with paths relative to _tutorials/ itself — files like lesson.qmd don't match **/_*, while nested _private/secret.qmd is still properly filtered.

[cderv]

There's a second layer to this. The leading / in render patterns skips the **/ prepend, so /_tutorials/**/*.qmd should work as a root-relative glob. It doesn't — walkSync in the Deno stdlib independently blocks it.

When expandGlobSync processes _tutorials/**/*.qmd, it consumes _tutorials as a fixed root (no exclude check). But the ** segment then calls walkSync(project/_tutorials, {skip: excludePatterns}). The Deno walkSync checks the root directory itself against skip patterns before walking — if the root matches, it returns immediately without entering the directory. Since the exclude patterns are resolved to absolute-path regexes, project/_tutorials matches resolve(project, "**/_*") and the walk exits.

So there are two independent layers preventing glob patterns from reaching underscore directories:

1. asFullGlob prepends **/, causing the directory to be skipped during the initial tree walk

quarto-cli/src/core/path.ts

Lines 281 to 283 in ebafc3a

	if (!glob.startsWith("/")) {
	if (smartGlob && (!options || !options.explicitSubfolderSearch)) {
	return "**/" + glob;

2. Even without **/, walkSync refuses to walk a root that matches the skip patterns (the underscore excludes from projectHiddenIgnoreGlob)

quarto-cli/src/project/project-context.ts

Lines 878 to 886 in 45102d2

	function projectHiddenIgnoreGlob(dir: string) {
	return projectIgnoreGlobs(dir) // standard ignores for all projects
	.concat(["**/_*", "**/_*/**"]) // underscore prefix
	.concat(["**/.*", "**/.*/**"]) // hidden (dot prefix)
	.concat(["**/README.?([Rrq])md"]) // README
	.concat(["**/CLAUDE.md", "**/CLAUDE.local.md"]) // Anthropic claude code file
	.concat(["**/AGENTS.md", "**/AGENTS.local.md"]) // https://agents.md/
	.concat(["**/*.llms.md"]); // llms.txt companion markdown files
	}

[cderv]

Both layers point to the same fix: remove the underscore patterns (**/_*, **/_*/**) from the exclude list passed to expandGlobSync when resolving explicit render: targets. The underscore convention is for auto-discovery — when the user specifies render targets, they are taking control of what gets rendered.

There is a subtlety with nested underscore directories though. With this project layout:

_tutorials/lesson.qmd
_tutorials/sub/deep.qmd
_tutorials/_private/secret.qmd

render: ["_tutorials"] finds lesson.qmd and sub/deep.qmd but not _private/secret.qmd — the directory walk computes paths relative to _tutorials/, so _private still triggers the underscore filter. With underscore excludes removed from glob expansion, render: ["_tutorials/**/*.qmd"] would match all three files including _private/secret.qmd, since individual file results bypass the directory-relative filtering.

Should both forms behave consistently for nested underscore subdirs? Or is it acceptable that the glob form is a direct file match where the user controls exclusions via ! patterns?

Still thinking through the best approach here.

[mcanouil]

As long as directory/**/*.qmd does not match directory/_private/*.qmd or directory/public/_private.qmd, I guess that's correct.

[cderv]

I understand problem is only with _directory/ not directory, because it is trying to match an ignored pattern. So

directory/**/.qmd does not match directory/_private/.qmd or directory/public/_private.qmd

is probably already true as long as no _.

Supporting _ is the hard part currently with the implementation...

• _directory/**/*.qmd could be considering explicit as provided by user, and this would then require !_directory/_private/*.qmd for any other underscore-prefixed folder.

• or the automatic glob logic needs to be modified towards a more explicit logic probably. 🤔

[mcanouil]

Only mentioning the pattern to avoid breaking many projects and ensure changes do not affect that pattern.

[cderv]

Do you mean pattern with _directory or directory ? Just to clarify your intent as I am not sur to get it right