为什么 GitHub Pages 的文章标题不能以 @ 开头?

本文记录了一个 GitHub Pages 博客网页上文章标题以 @ 开头导致的问题,并分析了原因,提供了解决方法。

TL;NR:因为 YAML 的语法规则,GitHub Pages 的文章标题不能直接以 ,[]{}#&*!|>'"%@` 或 -?:加空格 开头。可以用引号将标题括起来,或者修改标题,将这些字符不放在开头。

接到问题

接网友提问:

有一篇文章在 GitHub Pages 博客网页上不显示,初步排查可能与 title 有关------替换成其它文章的 title 可以正常显示,并附上了原始文件的头部:

yaml 复制代码
---
layout: post
title: @EnableconfigurationProperties注解使用方式与作用
categories: [Java]

复现

乍一看看不出什么问题,我在本地启动 Jekyll 预览,以本文件作为测试,也复现了该现象。

使用 title「为什么 GitHub Pages 的文章标题不能以 @ 开头?」时,正常:

使用 title「@EnableconfigurationProperties注解使用方式与作用」时,文章标题与摘要显示空白:

并可以在控制台看到如下错误:

sql 复制代码
Error: YAML Exception reading /Users/mazhuang/github/mzlogin.github.io/_posts/2024-10-11-why-github-pages-post-title-cannot-start-with.md: (<unknown>): found character that cannot start any token while scanning for the next token at line 3 column 8

分析

报错信息里提到是 YAML Exception------Jekyll 的文章头部是 YAML Front Matter,是 Jekyll 用来定义文章元数据的部分。报错提示 line 3 column 8,即 title 的第一个字符 @,is character that cannot start any token。

根据这个信息,其实已经可以想办法规避这个问题------将 title 里的 @ 去掉,或者换个位置,经验证可以正常显示了。

继续深究一下,为什么 YAML 里的 title 不能以 @ 开头呢?

然后找到了如下链接:

提炼一下要点:

  • YAML 里有一些指示字符,具有特殊语义,如 -?:,[]{}#&*!|>'"%@` ;

  • 这些特殊(或保留)字符不能用作不带引号的标量的第一个字符:,[]{}#&*!|>'"%@` ;

  • ?:- 后面如果跟着非空格字符,可以放在字符串的开头,但 YAML 处理器的不同实现可能带来不同行为,稳妥起见最好也用引号括起来。

解决方法

  • 将 title 用引号括起来,如 title: "@EnableconfigurationProperties注解使用方式与作用";(推荐)

  • 修改 title ,将上述不能直接放在开头的字符换个位置。


注:本文封面图片由 Stable Diffusion 生成,模型:SDXL-Lightning 4-Step,提示词:GitHub, Blog, GitHub Pages, Geek, Master Piece, High Quality。

相关推荐
dong_junshuai5 小时前
每天一个开源项目#162 NGINX:流式响应背后的缓冲、背压与重试
github
测试员周周5 小时前
【agent评测】:真实系统演示工具调用长什么样,用例怎么设计,怎么测
前端·后端·github
吴长建先生重名了6 小时前
Laravel 项目中使用 Eloquent 实现 IM
github
网易云信7 小时前
三折叠 IM 怎么适配?云信鸿蒙 UIKit 的分栏、导航与状态保留实践
github
guuguo8 小时前
【做个开源软件】Mac 上 node 进程莫名吃掉 6G 内存?给 AI / MCP 做了个深度归因和安全回收工具
人工智能·开源·github
一条Go9 小时前
源新生代雷达 · 第 16 期
github
一条Go9 小时前
SSH 命令审核流:为什么「能执行」必须先「被批准」
后端·架构·github
杨凯凡11 小时前
IT日报|2026-11-19:Oracle Java 紧急补丁、Optimizely 供应链攻击、GitHub 安全评估升级
java·oracle·github
徐小夕11 小时前
深度拆解 Design Agent:LangChain 出品,AI 设计从「好看」走向「可用」
前端·vue.js·github
严肃小白兔12 小时前
GitHub Copilot 团队级 Agent Plugins 正式发布:插件架构、共享配置与实战
github·copilot