AGENTS.md

AGENTS.md

This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.

Repository Overview

Personal academic blog and research notes site for Tingde Liu, built with Jekyll (~4.3) using a custom jekyll-now-based theme. Hosted at https://tingdeliu.github.io. Content is primarily Chinese-language research survey posts on VLN, VLA, and robotics AI.

Development Commands

Serve locally:

ruby -S bundle exec jekyll serve

Accessible at http://127.0.0.1:4000/

Build:

bundle exec jekyll build

Install dependencies:

bundle install

Site Architecture

This is a custom jekyll-now theme (not Chirpy). Key configuration in _config.yml:

  • Permalink: /:title/ (post URL is based on slug, not path)
  • Paginate: 10 posts per page, paginate path /page:num/
  • Markdown: kramdown + MathJax + Rouge syntax highlighting
  • Plugins: jekyll-sitemap, jekyll-feed, jekyll-paginate, jekyll-seo-tag
  • Site URL: https://tingdeliu.github.io, baseurl is empty

Navigation tabs (defined in _config.yml under navigation:): Home, Archive, Tags, About.

Theme layout chain: _layouts/default.html → _layouts/post.html or _layouts/page.html. Components are in _includes/ (nav, footer, head, toc, gitalk, disqus, backtotop, svg-icons).

Content Structure

Blog posts (_posts/): Only 3 posts exist. Filename format: YYYY-MM-DD-title.md.

Images (images/): Post images organized by topic subdirectories (vln/, vla/, vlm/, agent/, llm-training/, ros2/, robotics_navigation/). The paper-summary skill moves renamed figures into these subdirectories.

Paper summaries (paper_summary/): Chinese paper summaries generated by the paper-summary skill, named paper-summary-*.md. Referenced from blog posts but not rendered as Jekyll posts themselves (no front matter).

Static pages: about.md, archive/, home/, tags/ — these render using layout: page.

Blog Post Front Matter

---
layout: post
title: "Post Title"
date:   YYYY-MM-DD
tags: [tag1, tag2]
comments: true
author: Tingde Liu
toc: true
excerpt: "Brief description shown in post list"
---

The excerpt separator is <!-- more --> (configured in _config.yml).

硬性规则 — 编辑任何 _posts/ 文章后必须更新 date:：

每当对 _posts/ 下已存在的文章做出任何内容修改（增删段落、插图、改写等），都必须把该文 front matter 的 date: 字段更新为修改当天的日期（格式 YYYY-MM-DD，以会话上下文中的 currentDate 为准）。这样文章列表始终按”最近更新”排序，反映最新维护时间。

  • 只改 front matter 的 date:，不要重命名文件（permalink 为 /:title/，URL 不受影响）。
  • 若同一天内多次编辑，日期已是当天则无需重复改动。
  • 新建文章时 date: 即为创建当天日期（与文件名日期一致）。

Markdown Conventions

Image insertion (used in all existing posts):

<div align="center">
  <img src="/images/filename/imagename.png" width="80%" />
<figcaption>Caption text</figcaption>
</div>

两条硬性规则，违反任意一条都会导致图片无法显示：

  1. <div> 内不能有空行：<div align="center"> 与 <img> 之间、/> 与 <figcaption> 之间、</figcaption> 与 </div> 之间均不能有空行。kramdown 遇到块内空行会切换到 markdown 解析模式，将 <img> 当文本输出而非渲染为图片。

  2. 所有 HTML 属性必须使用 ASCII 直引号 "（U+0022）：禁止使用 Unicode 弯引号 "（U+201C）或 "（U+201D）。弯引号会导致浏览器无法解析 src、width、align 等属性，图片完全不可见。编辑工具有时会自动将直引号替换为弯引号，批量操作后需用以下 PowerShell 命令检查：

    $c = Get-Content "file.md" -Raw
[regex]::Matches($c, '["“”]').Count  # 应为 0

Math: Block display math uses $$...$$ on its own line. Inline math rules:

  • Simple formulas (without subscripts following }, such as $T$, $t$, $w$): Use $...$ is fine.
  • Inline formulas with the }_ pattern (such as \mathbf{x}_T, \bar{\alpha}_t, \boldsymbol{\epsilon}_\theta): Must use $$...$$, not $...$.

Reason: kramdown (GFM mode) treats } as a word boundary, and the _ in }_ will be parsed as the start of Markdown italics, breaking the formula. When using $$...$$ instead, kramdown recognizes the entire content as a math span and does not perform internal Markdown processing, outputting \(...\) for MathJax to render correctly.

Decision rule: For any inline formula containing combinations like \mathbf{...}_, \mathcal{...}_, \boldsymbol{...}_, \bar{...}_, \hat{...}_ (closing brace followed by underscore), always use $$...$$.

Table of contents: Add * 目录\n{:toc} after front matter to auto-generate TOC from headings.

Deployment

GitHub Actions (.github/workflows/) deploys to GitHub Pages automatically on push to main. No manual deployment needed.

Social/Comments Configuration

  • Comments via Gitalk (requires GitHub OAuth App — clientID/clientSecret in _config.yml are blank)
  • Footer social links configured under footer-links: in _config.yml
  • Google Analytics ID field exists but is blank