AGENTS.md — Blog setup & authoring for giorgionicoletti.github.io

This file is context for working on the blog section of my personal academic website. It covers both the one-time setup and the recurring workflow for adding new posts. Read it fully before making changes.

The site

• Personal academic website, published at https://giorgionicoletti.github.io
• Built with Jekyll, using the AcademicPages template (a fork of Minimal Mistakes). Hosted on GitHub Pages.
• I have never used the blog/posts feature before. As of this writing:
  • There is no _posts/ folder in the repo.
  • There is a _pages/ folder, but no posts.md / blog listing page in it.
  • The top navigation currently has: Research & Media, Publications, Curriculum, Talks, Teaching — and no Blog link.

Important: verify before creating

AcademicPages often ships blog scaffolding in a latent / half-configured state. Before creating anything, check the actual state of the repo — do not assume, and do not create duplicate scaffolding. Specifically check:

1. _config.yml — Is the posts collection already declared? Is there already a paginate / paginator setting? Are post permalinks/defaults configured under defaults:? AcademicPages usually has a collections: and defaults: block already — confirm what’s there rather than adding a conflicting one.
2. _data/navigation.yml — This controls the top menu. Adding the “Blog” link happens here, not in HTML. Match the existing entry format exactly.
3. _pages/ — Check whether a year-archive or posts-listing page already exists under a different name before creating posts.md. AcademicPages sometimes includes year-archive.html or similar.
4. _layouts/ — Confirm a single or post-style layout exists (it almost certainly does in AcademicPages). New posts will use it.

One-time setup task

Goal: enable the blog so posts render and are reachable from the top nav.

1. Confirm/complete the posts collection config in _config.yml (only if not already present — see above).
2. Create the _posts/ directory.
3. Add the first post file (see naming + front matter below).
4. Ensure a blog listing page exists (either reuse AcademicPages’ built-in archive, or create _pages/posts.md with the appropriate layout — check which the template expects).
5. Add a “Blog” entry to _data/navigation.yml, matching existing format.
6. Build locally and confirm it renders before pushing:

   bundle exec jekyll serve
   

   Check: the post renders, the nav link works, the listing page shows the post, and the LaTeX equations display (see below).

Post file conventions

• Filename: _posts/YYYY-MM-DD-short-slug.md (Jekyll requires the date prefix; the date must not be in the future at build time or the post won’t render on GitHub Pages.)
• Front matter (this is what the first post already uses — keep this shape): ```yaml — title: ‘Talking to each other, or just reacting to the same thing?’ date: 2026-07-19 permalink: /posts/2026/07/mutual-information-disentangling/ tags:
  • information theory
  • stochastic processes

  • statistical physics

    ```

• Confirm the permalink pattern matches whatever _config.yml defaults specify for the posts collection. If _config.yml already defines a permalink default for posts, an explicit per-post permalink may be redundant or conflicting — reconcile the two.

Math rendering (important)

The posts use LaTeX equations (inline $...$ and display $$...$$). AcademicPages supports MathJax, but it may need to be enabled:

• Check whether MathJax is already loaded (look in _includes/scripts.html, _layouts/, or a _config.yml mathjax flag).
• If equations don’t render after the first build, this is almost certainly why — enabling MathJax is the fix, not rewriting the equations.

Images

The first post has two figures. Store post images in a stable location the template already uses for assets:

• Check where existing site images live (likely images/ at repo root, since AcademicPages uses /images/).
• Reference them in the markdown with the site’s expected path, e.g. ![caption](/images/fig_switching_regimes.png).
• Figures for the first post:
  • fig_switching_regimes.png — the trajectory sketch (slow vs fast switching)
  • fig_hidden_environment.svg — the “hidden environment” schematic
• The figure is generated by a script (make_trajectory_fig.py) — keep that script somewhere in the repo (or a scripts/ folder) so figures are reproducible for future edits.

Recurring workflow (future posts)

For each new post:

1. Add _posts/YYYY-MM-DD-slug.md with correct front matter.
2. Add any figures to the images folder; reference with site-root paths.
3. Build locally (bundle exec jekyll serve), confirm rendering + math.
4. Commit and push.
5. (Separately, by hand) post a short teaser on LinkedIn pointing to the post URL — the LinkedIn post is written per-post, not automated.

Style notes for the writing (not Codex’s job, but for context)

• Each post has two independent sections: a plain-language version first (no equations, understandable by non-academics — friends, family), then a technical version (1–2 undergrad-level equations) that stands on its own.
• Tone: direct, not promotional, no “excited to share” framing.
• Do not invent results, citations, or coverage. Every factual claim about a paper must be checkable against the actual paper.