GitHub Pages serves .yaml as text/yaml with no charset, so browsers mis-decode UTF-8

[masiarek]

Summary

GitHub Pages serves .yaml files as content-type: text/yaml with no charset parameter. Because a text/* response without a charset falls back to the browser's legacy locale encoding (windows-1252 in en-US), every non-ASCII character in a served YAML file is mis-decoded. The bytes are correct UTF-8; only the header is missing.

Reproduction

https://masiarek.github.io/star-voting-library/03_STAR_PR/02_Examples/cases/lackner_skowron_shadow_star_pr_c7_b12.yaml

The file contains the line count_separator: "√ó" (U+00D7 MULTIPLICATION SIGN). Browsers display:

count_separator: "×"

The bytes served are correct. curl confirms UTF-8 c3 97:

$ curl -s <url> | grep count_separator | xxd
00000000: 2020 636f 756e 745f 7365 7061 7261 746f    count_separato
00000010: 723a 2022 c397 220a                      r: "..".

The browser reports the fallback itself. Evaluated on the live page:

document.contentType          // "text/yaml"
document.characterSet         // "windows-1252"   ‚Üê no charset given, so it guessed

C3 ‚Üí Ã, 97 ‚Üí — (em dash in windows-1252). Hence ×.

This is inconsistent with GitHub's own behavior elsewhere

Every other text type on the same Pages host gets a charset, and the same .yaml file gets one from GitHub's raw host:

Host	File type	content-type	Correct?
*.github.io	.yaml	text/yaml	no charset
*.github.io	.html	text/html; charset=utf-8	‚úÖ
*.github.io	.txt	text/plain; charset=utf-8	‚úÖ
*.github.io	.json	application/json; charset=utf-8	‚úÖ
*.github.io	.js	application/javascript; charset=utf-8	‚úÖ
*.github.io	.css	text/css; charset=utf-8	‚úÖ
raw.githubusercontent.com	.yaml	text/plain; charset=utf-8	‚úÖ

.yaml is the only type I could find that misses it, so this looks like a single missing parameter in one MIME-map entry rather than a design decision.

Precedent: this exact defect was already fixed for .js

github/pages-gem#52 (Feb 2014) reported the identical failure for a JavaScript file ‚Äî a stray Â before a degree symbol, correct UTF-8 in the repo, mis-decoded by the browser because the response carried no charset. Pages now serves .js as application/javascript; charset=utf-8, so that report was acted on. .yaml is the same bug in the same map, still open.

(Searched the Community discussions and the web before posting; the only prior report I found is the 2014 .js one above, which is closed and concerns a different file type.)

Requested fix

Serve .yaml / .yml as:

content-type: text/yaml; charset=utf-8

Please do not "fix" this by switching to application/yaml. RFC 9512 registers application/yaml and lists its optional parameters as "N/A; unrecognized parameters should be ignored" with encoding considerations "binary" ‚Äî so it cannot carry a charset, and browsers would download the file instead of rendering it. For a documentation site that publishes YAML as readable source, that is a regression. text/yaml is not itself an IANA-registered type, but since it is what Pages already sends and it renders in-browser, adding the charset parameter is the minimal, behavior-preserving fix.

Impact

Any Pages site publishing YAML as viewable source. On the site above, 590 of 661 .yaml files contain an em dash and 475 contain √ó; a 3-byte character such as —, ‚Üí or ‚â• garbles into three characters (—, →, ≥), so it is mostly prose that becomes unreadable, not just the odd symbol.

There is no workaround available to the site owner: Pages supports no custom-header mechanism (no _headers file), and the alternatives ‚Äî adding a UTF-8 BOM to every file, or renaming the extension ‚Äî either corrupt downstream tooling or break permanent URLs.

[github-actions[bot]]

💬 Your Product Feedback Has Been Submitted 🎉

Thank you for taking the time to share your insights with us! Your feedback is invaluable as we build a better GitHub experience for all our users.

Here's what you can expect moving forward ⏩

• Your input will be carefully reviewed and cataloged by members of our product teams. 
  • Due to the high volume of submissions, we may not always be able to provide individual responses.
  • Rest assured, your feedback will help chart our course for product improvements.
• Other users may engage with your post, sharing their own perspectives or experiences. 
• GitHub staff may reach out for further clarification or insight. 
  • We may 'Answer' your discussion if there is a current solution, workaround, or roadmap/changelog post related to the feedback.

Where to look to see what's shipping 👀

• Read the Changelog for real-time updates on the latest GitHub features, enhancements, and calls for feedback.
• Explore our Product Roadmap, which details upcoming major releases and initiatives.

What you can do in the meantime 💻

• Upvote and comment on other user feedback Discussions that resonate with you.
• Add more information at any point! Useful details include: use cases, relevant labels, desired outcomes, and any accompanying screenshots.

As a member of the GitHub community, your participation is essential. While we can't promise that every suggestion will be implemented, we want to emphasize that your feedback is instrumental in guiding our decisions and priorities.

Thank you once again for your contribution to making GitHub even better! We're grateful for your ongoing support and collaboration in shaping the future of our platform. ⭐

[Mr-Nilarnab]

This looks like a genuine Pages-side MIME/charset issue, and the reproduction you've provided makes the root cause pretty clear.

The important part is that the YAML bytes themselves are valid UTF-8, while the response is being served as text/yaml without an explicit charset. That leaves the browser to determine the encoding, which can result in the UTF-8 bytes being interpreted as Windows-1252 and producing exactly the kind of mojibake shown in the reproduction.

I also agree that application/yaml wouldn't be an equivalent fix here. If the goal is to preserve the current in-browser rendering behavior, the minimal change is:

Content-Type: text/yaml; charset=utf-8

What makes this particularly convincing is the comparison with .txt, .json, and .html on the same Pages host, as well as the behavior of the same YAML content through raw.githubusercontent.com. That strongly suggests the issue is isolated to the Pages MIME configuration rather than the files themselves.

The lack of a _headers-style mechanism is also important: site owners can't reliably correct the response header themselves, so this isn't really something that can be worked around cleanly at the repository level.

I'd consider this a solid bug report rather than expected browser behavior. The reproduction URL, curl byte dump, document.characterSet result, and comparison table give GitHub enough information to verify it without having to infer the failure from screenshots alone.

Hopefully the Pages team can fix this at the MIME mapping layer; it should be a relatively small change with a meaningful impact for sites publishing human-readable YAML.