rchou/blogs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

codex rebase
Deploy on push / deploy (push) Successful in 16s
Details

Browse Source
This commit is contained in:
Ryan Chou
2026-06-10 22:46:25 -07:00
parent bbc2dc6b58
commit 3c2dd93d0b
25 changed files with 7225 additions and 281 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+722
View File
@@ -0,0 +1,722 @@
# Ryan's Blog
This repository contains a static blog built with [Astro](https://astro.build/).
Markdown files are the source of truth for every post. Astro validates the post
metadata, converts the Markdown to HTML, creates the homepage and post routes,
and writes the finished website to `dist/`.
The production site is deployed automatically by Gitea Actions whenever a
commit reaches the `main` branch.
## How the site works
The publishing pipeline has four stages:
1. A post is written as Markdown in `src/content/posts/`.
2. Astro reads and validates its frontmatter using `src/content.config.ts`.
3. `npm run build` renders all non-draft posts into static HTML in `dist/`.
4. Gitea Actions copies `dist/` into the website directory on the VPS.
The VPS serves ordinary HTML, CSS, and image files. Astro and Node.js are only
needed while developing or building the site; they do not run as part of the
production website.
```text
src/content/posts/my-post.md
|
| npm run build
v
dist/posts/my-post/index.html
|
| Gitea Actions and rsync
v
/home/cab/docker/websites/blog-src/
|
| web server
v
https://the-blog-domain.example/posts/my-post/
```
## Repository structure
```text
.
├── .gitea/workflows/pipeline.yml Automatic build and deployment workflow
├── assets/ Images, icons, and the web manifest
├── posts/template.md Template used when starting a post
├── src/
│ ├── content/posts/ Published posts and drafts in Markdown
│ ├── content.config.ts Frontmatter schema and content loader
│ ├── layouts/BaseLayout.astro Shared HTML document, fonts, and icons
│ └── pages/
│ ├── index.astro Homepage and date ordering
│ └── posts/[slug].astro Generated page for each published post
├── astro.config.mjs Astro static-output configuration
├── package.json Commands and development dependencies
├── package-lock.json Exact dependency versions used by CI
├── styles.css Site-wide styles
└── tsconfig.json TypeScript settings used by Astro
```
### Content and source files
- `src/content/posts/` contains the actual blog posts. Each Markdown file has
frontmatter followed by the post body. The filename is for organization; the
public URL comes from the `slug` field.
- `posts/template.md` is the starting point for new posts. It is outside the
content collection, so it can never accidentally become a page.
- `src/content.config.ts` defines the required post metadata. The build fails
when metadata is invalid instead of silently publishing a broken page.
- `src/pages/index.astro` loads non-draft posts and sorts them by date, newest
first. No post list or manual ordering file needs to be maintained.
- `src/pages/posts/[slug].astro` creates one static route for every non-draft
post. A post with the slug `my-post` becomes `/posts/my-post/`.
- `src/layouts/BaseLayout.astro` contains shared document markup, metadata,
font loading, favicons, and the global stylesheet import.
- `assets/` is Astro's public directory. Its contents are copied to the root of
`dist/`, so `assets/cabby.jpg` is available as `/cabby.jpg`.
### Generated directories
Do not edit or commit these directories:
- `node_modules/` contains packages installed by npm.
- `.astro/` contains generated content indexes and type information.
- `dist/` is the complete production website generated by `npm run build`.
Deployment copies it to the VPS. It can be deleted and rebuilt at any time.
These directories are listed in `.gitignore`.
## Requirements
Local development requires:
- Node.js 22.12 or newer
- npm 9.6 or newer
- Git
Check the installed versions:
```sh
node --version
npm --version
git --version
```
## Initial setup
Clone the repository and install the exact locked dependencies:
```sh
git clone <repository-url>
cd blogs
npm ci
```
Use `npm ci` for normal work and CI because it reproduces
`package-lock.json` exactly. Use `npm install` when intentionally adding or
updating a dependency.
## Development commands
Start the local development server:
```sh
npm run dev
```
Astro prints the local URL, normally `http://localhost:4321`. The development
server watches source and Markdown files and refreshes the site as they change.
Validate the Astro source and content without producing a deployment build:
```sh
npm run check
```
Create a production build:
```sh
npm run build
```
This runs `astro check` first and then generates the static site in `dist/`.
Always run it before opening a pull request.
Preview the generated production build:
```sh
npm run preview
```
The preview command serves `dist/` locally. It is useful for checking the exact
files that would be deployed.
## Post frontmatter
Every file in `src/content/posts/` begins with YAML frontmatter:
```yaml
---
title: Post title
date: "2026-06-10"
excerpt: A short description shown on the homepage.
slug: post-title
draft: true
---
```
### Frontmatter fields
- `title` is required. It is displayed on the homepage, post page, and browser
tab.
- `date` is required. Use the ISO format `YYYY-MM-DD`, quoted as a string. The
homepage sorts posts by this value from newest to oldest.
- `excerpt` may be an empty string. A non-empty excerpt appears on the homepage
and is used as the page description.
- `slug` is required and becomes the public URL. It may contain lowercase
letters, numbers, and single hyphens between words.
```text
slug: the-weight-of-wanting
URL: /posts/the-weight-of-wanting/
```
Keep slugs unique. Do not change a published slug without intentionally
changing its URL and accepting that old links will stop working.
- `draft` should be `true` while a post is excluded from the homepage and
generated routes. Set it to `false` when the post is ready to publish.
Branches other than `main` do not deploy, so it is safe to set `draft: false`
on a post branch while testing the final homepage and URL locally.
## Markdown formatting
Post bodies use standard Markdown.
### Paragraphs
Separate paragraphs with a blank line:
```md
This is one paragraph.
This is another paragraph.
```
A single newline within normal prose does not create a visible line break.
This allows source text to wrap without changing the rendered paragraph.
### Headings
```md
# Main heading
## Section heading
### Smaller heading
```
The post title already appears above the body, so body sections should normally
begin with `##`.
### Emphasis
```md
**bold text**
*italic text*
***bold and italic text***
```
Do not put spaces inside the markers. Write `**bold**`, not `** bold **`.
### Links and quotations
```md
[Link text](https://example.com)
> This is a blockquote.
```
### Lists
```md
- First item
- Second item
1. First step
2. Second step
```
Leave a blank line before a list when it follows a paragraph.
### Code
Inline code uses backticks:
```md
Run `npm run build` before merging.
```
Use a fenced block for multiple lines:
````md
```js
const message = "Hello";
console.log(message);
```
````
### Horizontal rules
```md
---
```
Place a blank line before and after a horizontal rule. The first `---` at the
top of a post belongs to YAML frontmatter and has a different purpose.
### Poetry and intentional line breaks
Normal Markdown joins single source newlines into a paragraph. End a line with
a backslash when the rendered text must break at that exact point:
```md
I lost something irreplaceable,\
and I was the one who ended it.
```
Use a blank line between stanzas:
```md
The first line,\
the second line.
A new stanza begins here.
```
This keeps normal prose correctly formatted while still supporting poetry.
## Creating and publishing a new post
The standard publishing workflow uses one Git branch and one Gitea pull request
per post. Branches use the naming convention `post/<title-slug>`.
Merging the pull request into `main` publishes the post automatically.
### 1. Update local `main`
Start from a clean, current `main` branch:
```sh
git switch main
git pull --ff-only origin main
git status
```
Do not start a post branch while unrelated uncommitted changes are present.
### 2. Create the post branch
Choose a short lowercase slug and create the branch:
```sh
git switch -c post/my-new-post
```
Examples:
```text
post/my-new-post
post/notes-on-community
post/the-cost-of-convenience
```
### 3. Copy the post template
Copy the template into the content collection:
```sh
cp posts/template.md src/content/posts/my-new-post.md
```
The Markdown filename should normally match the slug because that makes the
repository easier to navigate, even though Astro does not require it.
Edit the frontmatter and write the post:
```yaml
---
title: My New Post
date: "2026-06-10"
excerpt: A concise summary for the homepage.
slug: my-new-post
draft: true
---
```
### 4. Preview while writing
Install dependencies if necessary and start Astro:
```sh
npm ci
npm run dev
```
With `draft: true`, the post is intentionally absent from the website. Set
`draft: false` when you want to test the homepage card and generated route.
This does not deploy anything while working on a non-`main` branch.
Check:
- title, date, and excerpt;
- homepage ordering;
- `/posts/my-new-post/`;
- paragraphs and poetic line breaks;
- links, lists, quotations, and code;
- desktop and narrow-screen layouts.
### 5. Validate the production build
Before committing:
```sh
npm run build
npm run preview
```
The build must complete without errors. Confirm that the post appears in
`dist/posts/my-new-post/index.html` when `draft` is `false`.
### 6. Commit and push the branch
Review what will be committed:
```sh
git status
git diff
```
Then commit and push:
```sh
git add src/content/posts/my-new-post.md
git commit -m "Add My New Post"
git push -u origin post/my-new-post
```
If the post includes new images, add those files from `assets/` to the same
commit.
### 7. Open a Gitea pull request
In Gitea:
1. Open the repository.
2. Create a pull request from `post/my-new-post` into `main`.
3. Review the changed Markdown and confirm `draft: false`.
4. Confirm the branch builds locally and any configured checks pass.
5. Merge the pull request.
The merge pushes a new commit to `main`. That push triggers the deployment
workflow. No `[deploy]` text or manual deployment command is required.
### 8. Confirm deployment
Open the repository's **Actions** page in Gitea and inspect the deployment job.
It should complete these steps:
1. check out the merged commit;
2. run `npm ci`;
3. run `npm run build`;
4. mirror `dist/` into `/deploy/websites/blog-src/`.
After the job succeeds, open the homepage and the new post URL in a browser.
### 9. Clean up the branch
Gitea may offer to delete the source branch after merging. If it does not,
clean it up manually:
```sh
git switch main
git pull --ff-only origin main
git branch -d post/my-new-post
git push origin --delete post/my-new-post
```
Deleting the branch does not delete the post because the merged post is now
part of `main`.
## Updating a pull request
Continue editing on the same post branch:
```sh
git switch post/my-new-post
```
Commit and push additional changes:
```sh
git add src/content/posts/my-new-post.md
git commit -m "Revise My New Post"
git push
```
Gitea adds those commits to the existing pull request automatically.
## Updating a branch from `main`
If `main` changes while a post is being written, update the branch before
merging:
```sh
git switch main
git pull --ff-only origin main
git switch post/my-new-post
git merge main
```
Resolve any conflicts, then validate and push:
```sh
npm run build
git push
```
This repository uses a normal merge in the documented workflow because it is
easy to understand and does not rewrite a branch that may already be under
review.
## Editing an existing post
Use the same branch and pull-request process:
```sh
git switch main
git pull --ff-only origin main
git switch -c post/revise-my-post
```
Edit the existing file, run `npm run build`, commit it, push the branch, and
open a pull request into `main`.
Avoid changing the slug unless a URL change is intentional.
## Removing a post
Choose one of two approaches on a branch:
- Set `draft: true` to keep the Markdown in Git but remove it from the website.
- Delete the Markdown file to remove both the source and generated page.
After the change is merged, `rsync --delete` removes the old generated route
from the deployment directory.
## Automatic deployment
The workflow is defined in `.gitea/workflows/pipeline.yml` and runs on every
push to `main`.
```text
Pull request merged
|
v
Push to main
|
v
Gitea creates an Actions job
|
v
alpine-rsync runner starts a temporary job container
|
v
npm ci
|
v
npm run build
|
v
rsync dist/ /deploy/websites/blog-src/
```
### Why deployment does not use SSH
Gitea, the Actions runner, and the website are hosted on the same VPS. Runner
job containers receive this bind mount:
```text
VPS host: /home/cab/docker/websites
Job container: /deploy/websites
```
Writing to this path in the job container:
```text
/deploy/websites/blog-src
```
therefore writes directly to this path on the VPS:
```text
/home/cab/docker/websites/blog-src
```
SSH would send files over the network only to return to the same server. The
bind mount is simpler and requires no deployment key or Gitea secret.
### What the deployment command does
The workflow runs:
```sh
mkdir -p /deploy/websites/blog-src
rsync -r --delete dist/ /deploy/websites/blog-src/
```
The trailing slash on `dist/` means "copy the contents of `dist`." Without it,
the destination could contain an unwanted nested `dist` directory.
`--delete` makes the production directory exactly mirror the current build.
When a route or asset is removed from the repository, its old generated file is
also removed from production.
The destination must contain only generated website output. Do not place
uploads, databases, or manually maintained files there because `--delete` will
remove anything not present in `dist/`.
### Runner requirements
The Gitea runner must:
- provide the `alpine-rsync` label;
- use an image containing Node.js 22.12 or newer, npm, Bash, and rsync;
- mount `/home/cab/docker/websites` at `/deploy/websites`;
- have write permission for `/deploy/websites/blog-src`;
- have network access to Gitea and the npm registry.
The web server must read
`/home/cab/docker/websites/blog-src` as its document root, either directly or
through its own read-only bind mount.
## Manual deployment
Normal deployments should always go through a pull request and Gitea Actions.
For troubleshooting on the VPS, the equivalent operations are:
```sh
npm ci
npm run build
mkdir -p /home/cab/docker/websites/blog-src
rsync -r --delete dist/ /home/cab/docker/websites/blog-src/
```
Only run this from a checked-out copy of the repository on the VPS. A later
successful Actions run will replace the destination with the build from
`main`.
## Troubleshooting
### A post does not appear
Check:
- the file is inside `src/content/posts/`;
- `draft` is `false`;
- the date and other frontmatter fields are valid;
- the build completed successfully;
- the pull request was merged into `main`;
- the deployment job succeeded.
### The build reports a content error
Run:
```sh
npm run check
```
Compare the post frontmatter with `posts/template.md`. Common causes include:
- a missing required field;
- an unquoted or malformed date;
- uppercase letters, spaces, or repeated separators in the slug;
- a non-boolean value for `draft`;
- invalid YAML punctuation.
### The post is in the wrong homepage position
The homepage sorts the `date` field newest first. Correct the frontmatter date;
do not manually reorder files or rename them to control ordering.
### The URL is wrong or returns 404
Confirm the `slug` and look for:
```text
dist/posts/<slug>/index.html
```
If the slug changed after publication, the old URL is not redirected
automatically.
### A Gitea job never starts
Confirm:
- Gitea Actions is enabled;
- the runner is online;
- the runner advertises the `alpine-rsync` label;
- the workflow exists on `main`;
- the event is a push to `main`.
### Deployment fails with `Permission denied`
The job container's user cannot write through the bind mount. On the VPS,
inspect the destination numerically:
```sh
ls -ldn /home/cab/docker/websites
ls -ldn /home/cab/docker/websites/blog-src
```
Set ownership or an ACL deliberately for the runner's job user. Do not solve
the problem by making the directory world-writable.
### Deployment succeeds but the site is stale
Check:
- the Actions log shows the expected merged commit;
- `/home/cab/docker/websites/blog-src/index.html` has a current timestamp;
- the web server mounts that exact directory;
- a reverse proxy or browser cache is not serving an older response.
### Files disappear from the deployment directory
This is expected for files that are not in `dist/` because deployment uses
`rsync --delete`. Keep all public static files in `assets/` so Astro includes
them in every build.
### Dependencies differ locally and in CI
Use:
```sh
rm -rf node_modules
npm ci
```
Commit `package-lock.json` whenever dependencies are intentionally changed.
## Production safety
- Protect `main` because every push to it deploys immediately.
- Merge reviewed pull requests rather than committing posts directly to
`main`.
- Do not expose this runner to untrusted repositories. Access to the Docker
socket and deployment bind mount is highly privileged.
- Keep each repository in a separate deployment directory.
- Keep generated production output separate from persistent application data.
- Inspect failed or unexpected jobs in Gitea's **Actions** page before retrying.