Skip to content

Commit b37b085

Browse files
ZhuoranYangclaude
ZhuoranYang
and
claude
committed
docs: add CLAUDE.md and skills for Claude Code blog deployment
- CLAUDE.md: repo overview auto-loaded by Claude Code - skills/deploy-markdown-post.md: step-by-step for adding markdown posts - skills/deploy-html-site.md: step-by-step for deploying pre-built HTML sites Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 0657e34 commit b37b085

3 files changed

Lines changed: 324 additions & 0 deletions

File tree

‎CLAUDE.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Y-Agent Research Blog
2+
3+
Hugo-based research blog. **Live site:** https://Y-Agent.github.io/
4+
5+
## Branch Model
6+
7+
| Branch | Purpose |
8+
|--------|---------|
9+
| `source` | Hugo source files — all edits go here |
10+
| `main` | Built HTML — auto-generated by GitHub Actions, never edit directly |
11+
12+
Push to `source` triggers CI: Hugo build → deploy to `main` → GitHub Pages.
13+
14+
## Key Paths
15+
16+
- `content/posts/` — blog post markdown files
17+
- `static/images/<post-name>/` — post images (cover + inline)
18+
- `static/<post-name>/` — static HTML sites (for redirect posts)
19+
- `layouts/_default/summary.html` — blog card template
20+
- `hugo.toml` — site config
21+
22+
## Two Blog Types
23+
24+
### Markdown posts
25+
Standard markdown in `content/posts/name.md`. Uses site theme, LaTeX via MathJax, TOC.
26+
Cover image goes in `static/images/name/cover.png`, referenced as `/images/name/cover.png`.
27+
28+
### HTML redirect posts
29+
Pre-built HTML site (e.g., Quarto output) in `static/name/`.
30+
A stub markdown file in `content/posts/name.md` redirects via `<script>window.location.href = "/name/index.html";</script>`.
31+
Still needs frontmatter with `cover:` for the blog card.
32+
33+
## Required Frontmatter
34+
35+
```yaml
36+
---
37+
title: "Post Title"
38+
date: YYYY-MM-DD
39+
author: "Author One, Author Two"
40+
cover: /images/post-name/cover.png
41+
categories:
42+
- "Research Blog"
43+
tags:
44+
- "tag1"
45+
draft: false
46+
math: true
47+
toc: true
48+
---
49+
```
50+
51+
## Deployment
52+
53+
```bash
54+
git checkout source
55+
git pull origin source
56+
# make changes
57+
git add <files>
58+
git commit -m "Add blog: Post Title"
59+
git push origin source
60+
# CI auto-deploys within ~1 minute
61+
```
62+
63+
## Skills
64+
65+
See `skills/` directory for step-by-step Claude Code workflows:
66+
- `skills/deploy-markdown-post.md` — add a new markdown blog post
67+
- `skills/deploy-html-site.md` — deploy a pre-built HTML site (Quarto, etc.)

‎skills/deploy-html-site.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
# Skill: Deploy a Pre-Built HTML Site as a Blog Entry
2+
3+
Use this when the user has a pre-built HTML site (Quarto, custom HTML/JS, etc.) and wants it to appear as a blog card on Y-Agent.github.io.
4+
5+
## Inputs
6+
7+
Ask the user for:
8+
- **Title** — the post title
9+
- **Authors** — comma-separated names
10+
- **Tags** — topic tags
11+
- **Cover image** — path to a cover image for the blog card
12+
- **Site directory** — path to the built HTML site (e.g., a Quarto `_site/` directory)
13+
14+
## Steps
15+
16+
### 1. Switch to source branch
17+
18+
```bash
19+
cd /Users/zhuoran_cisco/Documents/code/Y-Agent.github.io
20+
git checkout source
21+
git pull origin source
22+
```
23+
24+
### 2. Create the post slug
25+
26+
Derive a kebab-case slug from the title, e.g., "Inside Claude Code" → `inside-claude-code`.
27+
28+
### 3. Copy the HTML site to static/
29+
30+
```bash
31+
cp -r <site-directory> static/<slug>
32+
```
33+
34+
Files in `static/` are served as-is. `static/<slug>/index.html` becomes `https://Y-Agent.github.io/<slug>/index.html`.
35+
36+
### 4. Copy the cover image
37+
38+
```bash
39+
mkdir -p static/images/<slug>/
40+
cp <cover-image> static/images/<slug>/cover.png
41+
```
42+
43+
### 5. Create the redirect stub
44+
45+
Write `content/posts/<slug>.md`:
46+
47+
```yaml
48+
---
49+
title: "<title>"
50+
date: <today YYYY-MM-DD>
51+
author: "<authors>"
52+
cover: "/images/<slug>/cover.png"
53+
categories:
54+
- "Research Blog"
55+
tags:
56+
- "<tag1>"
57+
- "<tag2>"
58+
draft: false
59+
readingTime: <estimate>
60+
---
61+
```
62+
63+
Then add the redirect script and fallback content:
64+
65+
```html
66+
<script>
67+
window.location.href = "/<slug>/index.html";
68+
</script>
69+
70+
<noscript>
71+
<meta http-equiv="refresh" content="0;url=/<slug>/index.html">
72+
<p>Please click <a href="/<slug>/index.html">here</a> to view the post.</p>
73+
</noscript>
74+
```
75+
76+
Then add metadata (authors, links) and a brief overview below the redirect. This content is used by search indexing and RSS even though users are redirected immediately.
77+
78+
### 6. Commit and push
79+
80+
```bash
81+
git add content/posts/<slug>.md static/images/<slug>/ static/<slug>/
82+
git commit -m "Add blog: <title>"
83+
git push origin source
84+
```
85+
86+
### 7. Verify deployment
87+
88+
```bash
89+
gh run list --repo Y-Agent/Y-Agent.github.io --limit 1
90+
```
91+
92+
Confirm success. The blog card appears at `https://Y-Agent.github.io/` and clicking it redirects to `/<slug>/index.html`.
93+
94+
## Example: Quarto Site
95+
96+
For a Quarto-generated blog series:
97+
98+
```bash
99+
# 1. Build the Quarto site
100+
cd /path/to/quarto-project
101+
quarto render
102+
103+
# 2. Copy _site to the blog repo
104+
cp -r _site /Users/zhuoran_cisco/Documents/code/Y-Agent.github.io/static/<slug>
105+
106+
# 3. Copy cover image
107+
mkdir -p /Users/zhuoran_cisco/Documents/code/Y-Agent.github.io/static/images/<slug>
108+
cp cover.png /Users/zhuoran_cisco/Documents/code/Y-Agent.github.io/static/images/<slug>/cover.png
109+
110+
# 4. Create the redirect stub (see step 5 above)
111+
# 5. Commit and push to source
112+
```
113+
114+
## Updating an Existing HTML Site
115+
116+
To update the content of a previously deployed HTML site:
117+
118+
```bash
119+
cd /Users/zhuoran_cisco/Documents/code/Y-Agent.github.io
120+
git checkout source && git pull origin source
121+
122+
# Remove old version and copy new build
123+
rm -rf static/<slug>
124+
cp -r /path/to/new/_site static/<slug>
125+
126+
git add static/<slug>/
127+
git commit -m "Update blog: <title>"
128+
git push origin source
129+
```
130+
131+
## Size Considerations
132+
133+
Pre-built HTML sites can be large. Keep total repo size reasonable:
134+
- Optimize images before copying (use WebP or compressed PNG)
135+
- Avoid including unnecessary build artifacts
136+
- The `inside-claude-code` site is ~24 MB as a reference point

‎skills/deploy-markdown-post.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# Skill: Deploy a Markdown Blog Post
2+
3+
Use this when the user wants to add a new blog post written in Markdown.
4+
5+
## Inputs
6+
7+
Ask the user for:
8+
- **Title** — the post title
9+
- **Authors** — comma-separated names with homepage URLs
10+
- **Tags** — topic tags (e.g., "LLM", "reinforcement-learning")
11+
- **Cover image** — path to a cover image file (will be shown on the blog card)
12+
- **Content** — the markdown content, or a source file to convert
13+
14+
## Steps
15+
16+
### 1. Switch to source branch
17+
18+
```bash
19+
cd /Users/zhuoran_cisco/Documents/code/Y-Agent.github.io
20+
git checkout source
21+
git pull origin source
22+
```
23+
24+
### 2. Create the post slug
25+
26+
Derive a kebab-case slug from the title, e.g., "Modular Addition" → `modular-addition`.
27+
28+
### 3. Copy the cover image
29+
30+
```bash
31+
mkdir -p static/images/<slug>/
32+
cp <user-provided-image> static/images/<slug>/cover.png
33+
```
34+
35+
If the user provides multiple figures, copy them all to `static/images/<slug>/`.
36+
37+
### 4. Create the markdown file
38+
39+
Write `content/posts/<slug>.md` with this structure:
40+
41+
```yaml
42+
---
43+
title: "<title>"
44+
date: <today YYYY-MM-DD>
45+
author: "<authors>"
46+
cover: /images/<slug>/cover.png
47+
categories:
48+
- "Research Blog"
49+
tags:
50+
- "<tag1>"
51+
- "<tag2>"
52+
draft: false
53+
math: true
54+
toc: true
55+
---
56+
```
57+
58+
Then add the metadata block:
59+
60+
```html
61+
<strong style="font-size: 0.85em; letter-spacing: 1px; color: #3B9DD9;">AUTHORS:</strong>
62+
<small>
63+
<a href="<url>">Author One</a>, <a href="<url>">Author Two</a>
64+
</small>
65+
66+
<strong style="font-size: 0.85em; letter-spacing: 1px; color: #3B9DD9;">AFFILIATIONS:</strong>
67+
<small>Department of Statistics and Data Science, Yale University</small>
68+
69+
<strong style="font-size: 0.85em; letter-spacing: 1px; color: #3B9DD9;">LINKS:</strong>
70+
<span style="font-size: 0.9em;">
71+
<strong style="color: #D98C3B;">arXiv:</strong> <a href="<arxiv-url>" target="_blank"><strong>Paper</strong></a> &nbsp;|&nbsp;
72+
<strong style="color: #4CAF7D;">GitHub:</strong> <a href="<github-url>" target="_blank"><strong>Code</strong></a>
73+
</span>
74+
```
75+
76+
Then the post content in Markdown. Reference images with absolute paths: `/images/<slug>/figure.png`.
77+
78+
### 5. Commit and push
79+
80+
```bash
81+
git add content/posts/<slug>.md static/images/<slug>/
82+
git commit -m "Add blog: <title>"
83+
git push origin source
84+
```
85+
86+
### 6. Verify deployment
87+
88+
```bash
89+
# Wait ~1 minute for CI
90+
gh run list --repo Y-Agent/Y-Agent.github.io --limit 1
91+
```
92+
93+
Confirm the run succeeded, then tell the user the post is live at `https://Y-Agent.github.io/posts/<slug>/`.
94+
95+
## Image Reference Rules
96+
97+
- Store images in `static/images/<slug>/`
98+
- Reference with absolute paths: `/images/<slug>/image.png`
99+
- Never use relative paths
100+
- For side-by-side images:
101+
102+
```html
103+
<div style="display: flex; justify-content: center; gap: 4px; flex-wrap: nowrap;">
104+
<img src="/images/<slug>/fig_a.png" style="width: 48%; min-width: 0;">
105+
<img src="/images/<slug>/fig_b.png" style="width: 48%; min-width: 0;">
106+
</div>
107+
```
108+
109+
## LaTeX
110+
111+
Set `math: true` in frontmatter. Use `$...$` for inline, `$$...$$` for display. Underscores inside math delimiters are safe (passthrough enabled in hugo.toml).
112+
113+
## Styled Boxes
114+
115+
```html
116+
<div class="obs-box">
117+
<strong>Observation 1.</strong> Content here.
118+
</div>
119+
```
120+
121+
Available: `.question-box` (gold), `.obs-box` (blue), `.result-box` (green), `.theorem-box` (gray). Define the CSS `<style>` block at the top of the post if using these.

0 commit comments

Comments
 (0)