Quarto Preview Fails on Windows (os error 123) Due to Hugo Shortcode in _quarto.yml

[KomatiBhavaniSankar]

❗ Quarto Preview Fails on Windows (os error 123) Due to Hugo Shortcode in _quarto.yml

Description

Running quarto preview on Windows results in a fatal error because Quarto tries to interpret a Hugo shortcode inside _quarto.yml as a file path, which is invalid on Windows. This causes Windows to throw:

ERROR: The filename, directory name, or volume label syntax is incorrect. (os error 123)

Exact Error Output

ERROR: The filename, directory name, or volume label syntax is incorrect. (os error 123): 
stat '[{{< fa heart >}} Support GRASS]({{< var grass.support >}}){.btn .btn-outline-support .btn role="button" align="center"}'

Cause

The _quarto.yml file contains Hugo-style shortcodes, which Quarto does not support:

margin-header: |
  [{{< fa heart >}} Support GRASS]({{< var grass.support >}}){.btn .btn-outline-support .btn role="button" align="center"}

Quarto attempts to process this value and passes it to the filesystem stat() call.
Windows interprets this as an invalid path and throws os error 123.

Impact

This issue specifically affects Windows users.
Windows contributors are unable to run quarto preview, which prevents them from testing or building documentation locally.

Steps to Reproduce

1. Clone the repository on Windows

2. Run:

   quarto preview

3. The build fails with the error above.

---

Suggested Fix

Replace Hugo syntax ({{< >}}) with Quarto-compatible HTML or FontAwesome syntax.

Example fix:

margin-header: |
  [<i class="fa fa-heart"></i> Support GRASS](https://numfocus.org/donate-to-grass){.btn .btn-outline-support align="center"}

---

✅ Expected Behavior (After Fix)

After applying the fix:

• Quarto should preview the website normally across all operating systems (Windows, macOS, Linux).
• Unsupported icon or shortcode syntax should no longer break the build.
• Windows contributors should be able to work on documentation without errors.

---

Environment

• OS: Windows 10 / Windows 11
• Command: quarto preview
• Affected file: _quarto.yml

[petrasovaa]

Isn't the problem the extra tab there?

margin-header	: |

[KomatiBhavaniSankar]

Isn't the problem the extra tab there?

margin-header	: |

I believe the issue isn’t the indentation — it’s the Hugo shortcodes in _quarto.yml.
These shortcodes are the problem:
{{< fa heart >}}
and
{{< var grass.support >}}.
Quarto doesn’t support Hugo-style {{< … >}} syntax on any OS, but on Windows it fails with an OSError 123 because characters like <, > and {} are not allowed in file paths.
On Linux/macOS the same shortcodes still don’t work, but they don’t trigger the same hard error because those characters are allowed.

This is what I found while trying to understand the codebase. If possible, please check this on Windows as well. I believe it may cause some problems for Windows users who want to contribute to the project. Thank you.

[petrasovaa]

Isn't the problem the extra tab there?

margin-header	: |

I believe the issue isn’t the indentation

Did you test it? I don't use windows so I can't easily test it myself. But this suggests the shortcodes should work:
https://quarto-ext.github.io/fontawesome/

On Linux/macOS the same shortcodes still don’t work, but they don’t trigger the same hard error because those characters are allowed.

It seems to work for me.

[KomatiBhavaniSankar]

Isn't the problem the extra tab there?

margin-header	: |

I believe the issue isn’t the indentation

Did you test it? I don't use windows so I can't easily test it myself. But this suggests the shortcodes should work: https://quarto-ext.github.io/fontawesome/

On Linux/macOS the same shortcodes still don’t work, but they don’t trigger the same hard error because those characters are allowed.

It seems to work for me.

Yes, I have tested this on Windows, and I’m also sharing a video of the error. The extra tab is not the issue. This error seems to occur mainly on Windows, and I think Linux or macOS might not produce the same hard error because those characters are allowed or not might cause error at all. Sorry for late response.

Screen.Recording.2025-12-08.212313.mp4

[petrasovaa]

From the video I can see your code has still the tab in there, so it doesn't help with identifying the problem.

[KomatiBhavaniSankar]

From the video I can see your code has still the tab in there, so it doesn't help with identifying the problem.

I’m sending the screenshots of the error without any tabs. I’ve checked it in various ways, but I’m still getting the same error. Sorry for not mentioning this before. I hope this will help us to understand the error better.

1. Removed Extra Tab and still got the same error :

**2. I removed the tab before the | and this Syntax error: **

** 3. I removed all the tabs before the margin-header : **

Let me know your opinion on this error. I’m ready to share the video of the errors if needed, and I’m open to any suggestions or feedback ma'am

[petrasovaa]

Thanks, the last example clarifies it. I think I would prefer to put the code into a separate file named _support-button.md rather than what you were suggesting.

[KomatiBhavaniSankar]

Thanks, the last example clarifies it. I think I would prefer to put the code into a separate file named _support-button.md rather than what you were suggesting.

Thanks for the clarification. I completely understand your preference for placing the code into a separate _support-button.md file.

_support-button.qmd works fine as it is. From what I observed, the issue seems to come from the formatting in _quarto.yml, not from the support button file itself.

I just wanted to share the solution I found, in case it’s helpful. Instead of modifying _support-button.qmd, we can use the following line directly in the YAML, and it works correctly on Windows without triggering the 123 OS error:

margin-header: '[{{< fa heart >}} Support GRASS]({{< var grass.support >}}){.btn .btn-outline-support .btn role="button" align="center"}'

The fix involved two main changes:

1. Replaced the | multiline block with a single quoted string
   This avoids YAML misinterpreting special characters and removes indentation-related issues that often caused the error.

2. Saved the file in UTF-8 encoding
   Windows sometimes saves files as ANSI/Windows-1252, which can cause the “123 error.” Switching the file encoding to UTF-8 ensures YAML and Quarto parse everything correctly.

I believe error happening in the quarto.yml and we need change formate of the 1 line of code and rest are working fine. I’m happy to follow your suggestion. I just wanted to respectfully share what worked on my end. Thank you for reading.

[petrasovaa]

Thanks for more testing! if that works, yes please create a PR with the quotes.