AGENTS.md — antoinelucasfra.github.io

Personal portfolio, blog, and projects website for Antoine Lucas. Inherits all rules from ~/project/AGENTS.md. This file documents project-specific overrides and workflows.

  • Live URL: https://antoinelucasfra.github.io
  • GitHub remote: https://github.com/antoinelucasfra/antoinelucasfra.github.io
  • Primary branch: main
  • Deployment: automatic — every push to main triggers quarto render → GitHub Pages

1. Tech Stack

Layer Tool
Static site generator Quarto (type: website)
R version 4.5.2 (managed by rig)
R dependencies renv — lockfile at renv.lock
R formatter air — config at air.toml
CI/CD GitHub Actions (.github/workflows/publish.yml)
Output directory docs/ (served by GitHub Pages)

2. Project Structure

antoinelucasfra.github.io/
├── _quarto.yml            # project config — output-dir: docs, theme, navbar
├── _brand.yml             # brand: fonts, colors, logo
├── air.toml               # R formatter config
├── renv.lock              # R dependency lockfile
├── renv/                  # renv activation scripts (commit; not library/)
├── .Rprofile              # activates renv automatically
├── index.qmd              # home page
├── blog.qmd               # blog listing page
├── cv.qmd                 # CV page
├── about.qmd              # about page
├── projects.qmd           # projects listing page
├── posts/                 # blog posts — one subdirectory per post
│   └── <post-slug>/
│       └── index.qmd
├── projects/              # project pages and resources catalog
│   └── resources_catalog.qmd
├── assets/
│   ├── images/            # profile pic, favicons
│   └── stylesheets/
│       ├── theme.scss     # light theme overrides
│       └── theme-dark.scss # dark theme overrides
├── _freeze/               # Quarto render cache — NEVER delete, NEVER commit manually
├── docs/                  # rendered site output — NEVER edit manually
├── data/                  # data files used in posts/pages
└── sandbox/               # local experiments — not part of the site

3. Build & Preview

# Render the full site
quarto render

# Preview locally with live reload
quarto preview

# Render a single file
quarto render posts/my-post/index.qmd

Output directory: docs/ — generated by quarto render. Never edit files in docs/ directly. They are overwritten on every render. The CI pipeline uploads docs/ to GitHub Pages after each render.

4. Adding Content

New blog post

# Create the post directory and skeleton
mkdir posts/my-new-post
# Create posts/my-new-post/index.qmd with YAML front matter:
---
title: "Post Title"
author: "Antoine Lucas"
date: "2026-02-18"
categories: [R, tools]
image: "cover.png"
description: "One-sentence description for the blog listing."
---
  • Place images in the post directory alongside index.qmd
  • Use execute: freeze: auto for posts with R/Python code (inherited from _quarto.yml)
  • The _freeze/ directory caches rendered code outputs — commit it so CI does not re-execute code it cannot reproduce

New project page

Add a .qmd file under projects/ and reference it in projects.qmd or the navbar in _quarto.yml.

5. Brand & Theming

The brand is defined in _brand.yml. Do not modify it without explicit instruction.

Fonts: - Headings: Sora - Body: DM Sans - Code: JetBrains Mono

Colors (deep navy + warm gold): defined in _brand.yml and overridden in assets/stylesheets/theme.scss (light) and theme-dark.scss (dark).

Quarto theme base: cosmo + brand overrides. Both light and dark themes are active.

When adding new SCSS, edit the existing files — never create new stylesheet files without updating _quarto.yml to reference them.

6. R Dependencies in Content

R packages used inside .qmd code chunks must be managed with renv:

# Add a package (run in R console at project root)
renv::install("ggplot2")
renv::snapshot()    # update renv.lock — commit this

Packages already in renv.lock (from CI): knitr, rmarkdown, ggplot2, dplyr. Any new package required by a post must be added to renv.lock and the CI workflow (.github/workflows/publish.yml → Install R packages step).

7. CI/CD — Publish Workflow

File: .github/workflows/publish.yml

Trigger: push to main

Steps: 1. actions/checkout@v4 2. quarto-dev/quarto-actions/setup@v2 — install Quarto CLI 3. r-lib/actions/setup-r@v2 — install R (use-public-rspm: true) 4. r-lib/actions/setup-r-dependencies@v2 — install R packages (knitr, rmarkdown, ggplot2, dplyr) 5. quarto render — render the full site to docs/ 6. actions/upload-pages-artifact@v3 — upload docs/ 7. actions/deploy-pages@v4 — deploy to GitHub Pages

Adding a new R package to CI: edit the packages: list in step 4 of publish.yml. Use any::pkg-name syntax.

8. Git Conventions — Website Specifics

Beyond the root AGENTS.md git rules, this project has one extra type:

  • render: — used exclusively for commits that contain only Quarto rendered output (i.e. changes to docs/ or _freeze/). Example: render: Render website after adding CV section

Commit workflow for content changes:

# 1. Edit or create .qmd files
# 2. Preview locally
quarto preview
# 3. Format any R code in chunks
air format .
# 4. Render to update docs/ and _freeze/
quarto render
# 5. Stage content and rendered output separately
git add posts/my-new-post/
git commit -m "feat(blog): Add post on reproducibility with renv"

git add docs/ _freeze/
git commit -m "render: Render website"

Always keep content commits (feat:, docs:) separate from render commits (render:).

9. Hard Rules — Website Specifics

  • Never edit files in docs/ — they are generated by quarto render
  • Never delete _freeze/ — it is the code execution cache; losing it forces CI to re-run all code
  • Never commit *.Rproj, .Rhistory, .DS_Store, .quarto/, renv/library/
  • Always run quarto render locally before pushing to verify the site builds
  • Always add new R packages to both renv.lock (renv::snapshot()) and publish.yml
  • The docs/ directory is committed in this repo (GitHub Pages source) — this is intentional
  • Never change output-dir in _quarto.yml — it must remain docs
Back to top