为什么 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。

相关推荐
金融数据出海1 小时前
黄金金融期货数据API对接技术文档
开发语言·金融·github
hfd19902 小时前
GitHub 宕机自救指南:保障开发工作连续性
github
绝无仅有3 小时前
未来教育行业的 Go 服务开发解决方案与实践
后端·面试·github
逛逛GitHub7 小时前
这 4 个牛逼 GitHub 开源项目,太优质了。
github
知行力8 小时前
【GitHub每日速递】不止 TeamViewer 替代!RustDesk 与 PowerToys,Windows 效率神器
windows·github·teamviewer
杨杨杨大侠9 小时前
实战案例:商品详情页数据聚合服务的技术实现
java·spring·github
杨杨杨大侠9 小时前
实战案例:保险理赔线上审核系统的技术实现
java·spring·github
FutureUniant10 小时前
GitHub每日最火火火项目(9.5)
人工智能·microsoft·计算机视觉·ai·github
CoderJia程序员甲10 小时前
GitHub 热榜项目 - 日榜(2025-09-05)
ai·开源·github·ai编程·github热榜
绝无仅有10 小时前
从拉取代码到前端运行访问:Vue 前端项目的常规启动流程
后端·面试·github