Xiatao Sun

AGENTS.md

AGENTS.md

Guidance for AI coding agents working in this repository. Human-facing docs: README.md / README-zh.md.

What this is

A personal website: a Jekyll site on the TeXt theme with a custom dark Snowflake skin. Published via GitHub Pages on push to main — there is no separate deploy step.

Environment facts (don’t relearn these the hard way)

  • No local Ruby/Jekyll/Node toolchain. Do all builds inside Docker.
  • Docker is available and running. Use the ruby:3.3 image directly.
  • The theme’s docker/*.yml compose files are broken here: they target Ruby 2.7 and COPY Gemfile.lock, but Gemfile.lock is git-ignored and absent, and Ruby 2.7 is too old for current transitive deps (ffi ≥ 3.0). Don’t use them — run the container directly (below).
  • Platform is Windows; the shell is Git Bash. Docker volume mounts need a Windows-style path ($(pwd -W)) and the MSYS_NO_PATHCONV=1 prefix.

Build & preview locally

WINPATH="$(pwd -W)"
docker rm -f jekyll-snowflake 2>/dev/null
MSYS_NO_PATHCONV=1 docker run -d --name jekyll-snowflake \
  -v "${WINPATH}:/usr/src/app" -w /usr/src/app \
  -p 4000:4000 -e JEKYLL_ENV=development \
  ruby:3.3 \
  sh -c "bundle install && bundle exec jekyll serve -H 0.0.0.0 -P 4000"

Then verify:

docker logs jekyll-snowflake 2>&1 | tail -30   # look for "Server running"; watch for "Conversion error" / "Liquid Exception"
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:4000/

The container auto-regenerates on file changes. DEPRECATION WARNING: Using / for division from Dart Sass is harmless (upstream theme SCSS). A Conversion error / expected "{" means broken SCSS — check any skin file you edited (e.g. stray characters at end of file).

Key facts about the site

  • Permalinks: permalink: date → a post dated 2023-05-01 lives at /2023/05/01/slug.html. Use this format when linking between pages.
  • Skin: _sass/skins/_snowflake.scss (deep navy #0B1220 + Snowflake blue #29B5E8), selected via text_skin: snowflake in _config.yml. If you add a new skin, define exactly the same variables as an existing skin (e.g. _dark.scss) or the build fails.
  • Tab title vs. banner: _config.yml title_tab drives only the <title> tag (_includes/head.html); title drives the header banner, footer, and RSS. Keep them decoupled.
  • Browser/OS chrome colors live in _includes/head/favicon.html, assets/site.webmanifest, assets/browserconfig.xml — keep them consistent with the navy background if you retheme.

The _temp_resources → post workflow

_temp_resources/ is the owner’s staging area for raw material (LaTeX sources, figures, screenshots, PDFs, notes), organized in dated subfolders like _temp_resources/2023-05-01 Master Thesis/…. It is not published. Your job is to convert a staged item into a published post.

When asked to “turn _temp_resources/<...> into a post”:

  1. Read the raw material in that folder (LaTeX .tex, figure files, any PDFs). Extract the actual technical content — do not fabricate results.
  2. Create postresources/<YYYY-MM-DD>/ and copy in only the images/PDFs the post will reference. (Copy, don’t move — leave _temp_resources/ intact unless told otherwise.) URL-encode spaces in referenced filenames as %20.
  3. Write _posts/<YYYY-MM-DD>-<slug>.md with front matter matching the site convention: 
    ---
layout: article
title: "..."
tags: [...]
cover: /postresources/<YYYY-MM-DD>/cover.png
article_header:
  type: overlay
  theme: dark
  background_image:
    src: /postresources/<YYYY-MM-DD>/background.png
show_edit_on_github: false
---
    • All asset paths are absolute: /postresources/<YYYY-MM-DD>/....
    • Put <!--more--> after the intro (the site sets excerpt_separator: <!--more-->).
    • Images: ![alt](/postresources/<date>/fig.png); two-up comparisons use a 2-column Markdown table (see existing posts).
    • Embeds: `<div class="extensions extensions--video">

</div> , <div class="extensions extensions--slide">

</div> `.

  1. Cross-link if relevant. E.g. the Master’s thesis post is also linked from the UPenn entry in about.md.
  2. Build and verify in Docker; confirm the post renders at its permalink URL before committing.

Reference example already in the repo: _posts/2023-05-01-master-thesis-quadrotor-il.md with assets in postresources/2023-05-01/, generated from _temp_resources/2023-05-01 Master Thesis/.

Committing

  • Work on a branch, not directly on main, unless told otherwise. Commit only when the user asks.
  • Note that postresources/ PDFs and images are committed to the repo (they’re served statically). _temp_resources/ may be large; only commit it if the owner wants the raw material archived.

</content>

Search