AGENTS.md

AGENTS.md

Guidance for AI coding agents working in this repository.

Project overview

HarmonyHu's Notes is a personal technical blog built with Jekyll (static site generator, Ruby) using a custom, hand-rolled theme — there is no upstream Jekyll theme gem dependency. The site is published at https://harmonyhu.com (see CNAME) and contains mostly Chinese-language notes on AI compilers, deep learning, systems, and software engineering.

  • Jekyll version: >= 3.7, < 5.0 (currently locked to 4.4.1 in Gemfile.lock).
  • Markdown engine: kramdown (GFM input); syntax highlighting: rouge.
  • Plugins (see Gemfile and _config.yml): jekyll-paginate, jekyll-sitemap, jekyll-seo-tag, jekyll-include-cache.
  • There is no JavaScript/CSS build pipeline, bundler, or package.json — files under assets/js/ and assets/css/ are served as-is, and SCSS in _sass/ is compiled by Jekyll’s built-in Sass support (via assets/css/main.scss, style: compressed).

Key configuration files

  • _config.yml — site metadata (Chinese locale, Asia/Shanghai timezone), kramdown/sass settings, plugin list, permalink scheme (/:year/:month/:day/:title/), pagination (10 per page), front-matter defaults, top navigation.
  • Gemfile / Gemfile.lock — Ruby dependencies (Gemfile.lock is git-ignored, so it is regenerated per machine; note tzinfo/tzinfo-data and webrick are needed on Windows).
  • search.json — Liquid template (not data) that Jekyll renders into the JSON search index consumed by assets/js/search.js.
  • .gitignore — excludes _site, .jekyll-cache, .jekyll-metadata, Gemfile.lock, editor dirs.

Build and serve commands

bundle install            # install Ruby dependencies
bundle exec jekyll serve  # local dev server at http://127.0.0.1:4000
bundle exec jekyll build  # static build into _site/

There is no test suite and no CI: the .github/ directory is empty and there are no linters or automated checks. Verify changes by building the site and, when behavior matters, viewing the rendered pages locally. The checked-in _site/ directory is build output — never edit it by hand.

Deployment

Deployment is via GitHub Pages: pushing to the default branch publishes the site (the repo is HarmonyHu/harmonyhu.github.io, served under the custom domain harmonyhu.com via CNAME). Keep plugin choices within the GitHub Pages–supported set unless you also add a build workflow.

Code organization

  • _posts/ — blog posts, 109 Markdown files named YYYY-MM-DD-Title.md. Subdirectories hold post attachments, not posts: audio/ (mp3), books/ (pdf/epub/txt), meta/ (.eddx diagram sources), other/ (archives/scripts).
  • _pages/ — standalone pages: About, Archive, Categories, Tags, 404.
  • _layouts/ — default.html is the base; home, page, archive, categories, tags extend it; post.html renders a full article (header/meta, TOC sidebar, tags, post navigation, comments); single.html is a thin wrapper over post.
  • _includes/ — reusable snippets: head, header, footer, comments, paginator, post-nav, search-modal, svg-icons.
  • _sass/ — SCSS partials (_variables, _reset, _base, _layout, _components, _post, _syntax, _responsive), imported by assets/css/main.scss.
  • assets/js/ — main.js (theme switch, TOC generation, reading progress bar, mobile nav) and search.js (search modal backed by /search.json).
  • img/ — images referenced by posts; favicon.ico, baidu_verify_*.html — site-root assets.
  • temporary/ — drafts and reference PDFs. It is listed in _config.yml’s exclude, so nothing here is built or published. Draft posts live here before being moved to _posts/.

Conventions for writing posts

Posts are the most common change in this repo. Follow the existing pattern (see _posts/2000-01-01-Article-Type.md for a template):

  • Front matter: layout: single, title, categories: (list), tags: (list). All 109 existing posts use layout: single; do not introduce layout: post directly.
  • Body starts with the kramdown TOC block: ```

    ``` (The rendered sidebar TOC is also auto-generated by assets/js/main.js from headings.)

  • Use <!--more--> to mark the excerpt boundary (configured as excerpt_separator).
  • Headings start at ## (the <h1> is the post title rendered by the layout).
  • Images are stored in img/ and referenced with absolute site URLs like ![](https://harmonyhu.github.io/img/example.png) (older posts use this form; root-relative /img/example.png also works).
  • Post content is primarily Chinese; filenames use English/ASCII slugs.
  • _config.yml front-matter defaults already enable comments and toc for posts.

Theme behavior worth knowing

  • Comments are rendered through Giscus (GitHub Discussions backed) in _includes/comments.html. The # Comments (Valine) line in _config.yml is stale — Valine is no longer used; only the comments.enabled flag there matters.
  • Light/dark theme switching is in assets/js/main.js, persisted in localStorage; the initial theme is applied by an inline script in _includes/head.html to avoid a flash of the wrong theme.
  • SEO via jekyll-seo-tag; sitemap via jekyll-sitemap.

Security considerations

  • Do not commit secrets; there are none expected in this repo (no .env, no API keys — the only third-party integrations are Giscus and public CDNs).
  • The repo contains binary attachments (PDFs, archives, media under _posts/*/ and temporary/); treat them as data, do not execute them.
  • Pin/upgrade gems only through the Gemfile and verify with a local bundle exec jekyll build.