D3V-Server/blog-starter/README.md

# D3V Blog

This repository contains the source for `🥷 D3V Blog`, a bilingual Hugo blog
that uses the LoveIt theme and deploys to `https://blog.d3v.ac/`.

## What This Repository Includes

- Hugo site structure
- LoveIt bootstrap script pinned to a known good tag
- bilingual content in Vietnamese and English
- a manual Forgejo workflow to create bilingual post files
- a Forgejo Actions workflow that builds and deploys to `/opt/blog/public`
- an AI context file for future maintenance and content publishing

## Important Content Model

This blog is bilingual.

Every article must be created as a pair of files under `content/posts/`:
- `<slug>.vi.md`
- `<slug>.en.md`

Use the same `slug`, `tags`, and `categories` for both language versions.
Use TOML front matter with exactly `+++` and save files as UTF-8 without BOM.

## Local Writing Workflow

1. Bootstrap the theme:

```bash
./scripts/bootstrap-theme.sh
```

2. Create the paired post files under `content/posts/`.

3. Start the local preview server:

```bash
hugo server
```

4. Edit both language files.
5. When ready to publish, set `draft = false`, commit, and push.

## Forgejo Web Workflow

If you want to create posts directly from the Forgejo web UI, use the manual
workflow in `.forgejo/workflows/create-post.yml`.

From the Actions page:

1. Run `Create Blog Post`
2. Fill in:
   - `title_vi`
   - `title_en`
   - `slug`
   - optional `summary_vi`
   - optional `summary_en`
   - optional comma-separated `tags`
   - optional comma-separated `categories`
   - `draft`
3. The workflow creates:
   - `content/posts/<slug>.vi.md`
   - `content/posts/<slug>.en.md`
4. The normal deploy workflow publishes the post on the next push

This keeps you out of front matter for most day-to-day writing.

## Forgejo Secrets

The deploy workflow expects these repository secrets:

- `BLOG_DEPLOY_HOST`: server hostname or IP
- `BLOG_DEPLOY_PORT`: SSH port, usually `22`
- `BLOG_DEPLOY_USER`: deploy user on the server
- `BLOG_DEPLOY_KEY`: private SSH key for the deploy user
- `BLOG_DEPLOY_PATH`: target directory, usually `/opt/blog`
- `BLOG_DEPLOY_KNOWN_HOSTS`: optional `known_hosts` entry for stricter SSH

## Expected Server State

- Blog host installed from `D3V-Server/install.sh`
- `d3v-blog` container running
- deploy user created by `install.sh blog-install` or `install.sh blog-update`
- `install.sh blog-deploy-info` prints the exact secret values to paste into Forgejo
- Nginx Proxy Manager forwards `blog.d3v.ac` to `d3v-blog:80`

## Notes

- Theme bootstrap is handled by `scripts/bootstrap-theme.sh`.
- Deployment uses `rsync --delete` to keep `/opt/blog/public` in sync with the latest generated `public/` output.
- Read `AI_CONTEXT.md` before making automation, workflow, or content-structure changes.