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

相关推荐
油泼辣子多加7 小时前
2025年06月30日Github流行趋势
github
ai小鬼头7 小时前
AIStarter如何快速部署Stable Diffusion?**新手也能轻松上手的AI绘图
前端·后端·github
寻月隐君11 小时前
Rust 异步编程实践:从 Tokio 基础到阻塞任务处理模式
后端·rust·github
bingGO5499112 小时前
github 集成CICD自动化部署
github
超龄超能程序猿12 小时前
Bitvisse SSH Client 安装配置文档
运维·ssh·github
Natsume171015 小时前
嵌入式开发:GPIO、UART、SPI、I2C 驱动开发详解与实战案例
c语言·驱动开发·stm32·嵌入式硬件·mcu·架构·github
荔枝吻16 小时前
【AI总结】Git vs GitHub vs GitLab:深度解析三者联系与核心区别
人工智能·git·github
幻凡ss16 小时前
github pages使用免费CDN加速-netlify
github·github pages·github cdn·github pages加速·netlify加速github·hexo博客免费cdn加速·个人博客免费cdn加速
我是哪吒19 小时前
分布式微服务系统架构第155集:JavaPlus技术文档平台日更-Java线程池实现原理
后端·面试·github
DeepSeek-大模型系统教程1 天前
推荐 7 个本周 yyds 的 GitHub 项目。
人工智能·ai·语言模型·大模型·github·ai大模型·大模型学习