Skip to content

OPERATING_GUIDE.md

Latest commit

 

History

History
240 lines (160 loc) · 9.42 KB

OPERATING_GUIDE.md

File metadata and controls

240 lines (160 loc) · 9.42 KB
Raw

Signal & Silence — Blog Operating Guide

This guide explains how to run the blog, write posts, add images, check the result, and publish safely. The site uses Hugo, so normal posts are Markdown files. You do not need to edit HTML templates for everyday writing.

The blogger's workflow

Think of the blog as three shelves. Choose the shelf before you begin; the rest of the process stays the same.

When your idea sounds like this Put it in Language
“I built, tested, or learned something from a technical project.” Project English
“I noticed something about how I think, learn, decide, or live.” Personal Vietnamese
“I practised a Chinese sentence, song, character, or study method.” Languages Vietnamese, with Chinese examples

Every post moves through this simple cycle:

  1. Catch the idea. Write one sentence as soon as the idea appears. It does not need to be polished.
  2. Choose one promise. Finish this sentence: “After reading, the reader will understand…” If the answer contains two big ideas, save one for another post.
  3. Make a rough draft. Explain what happened, show one concrete example, and say what changed in your thinking. Keep draft: true while the work is unfinished.
  4. Read it as a visitor. Preview the post. Check that the title is clear, the opening gives a reason to continue, and each paragraph leads naturally to the next.
  5. Add only useful detail. Include an image, quotation, code sample, or Chinese breakdown when it helps the reader understand. Decoration is optional; clarity is not.
  6. Publish. Set draft: false, run the final check, and push the change. GitHub publishes the site automatically.
  7. Return and improve. If a reader is confused or your understanding grows, edit the same post and publish the revision. A post does not need to stay frozen.

Three common use cases

A quick personal insight — about 15–30 minutes

You notice that writing by hand exposes gaps that flash cards hide. Capture the idea, tell one true moment, explain what it taught you, and publish it in Personal. A short, honest post is enough.

A project retrospective — collect evidence before writing

You finish a RAG evaluation experiment. Put the question, the choice you made, what happened, and what you would change next time into a Project draft. Add a result or code example only when it supports the story. Write the final article in English.

A Chinese learning session — turn practice into a reusable note

You learn a line from the Xuanling Bird song or practise with Thảo Nguyên. Start with the real moment that made the phrase memorable. Then show the Chinese sentence, Pinyin, an easy sound guide, and the Vietnamese meaning. End with how you will use the sentence again, update the learning dashboard if your progress changed, and publish it in Languages.

The sections below explain the practical steps for completing this cycle.

1. Install the tools

Install Git and Node.js 24 or newer. The project installs its own pinned Hugo Extended binary through npm, so a separate system-wide Hugo installation is optional.

Clone the repository and install its dependencies:

git clone https://github.com/MathematicGuy/Personal-Blog.git
cd Personal-Blog
npm install

2. Know where things live

Path Purpose
content/project/ English project articles
content/personal/ Vietnamese personal articles
content/languages/ Vietnamese language-learning articles
data/projects.yaml The three featured project rows
data/chinese.yaml Vocabulary, study steps, and daily-practice data
assets/css/styles.css The visual design
layouts/ Hugo page templates
static/images/ Shared images used by several pages
.github/workflows/hugo.yml Automatic GitHub Pages deployment

For normal blogging, most changes belong only in content/.

3. Create a post

Choose the section and use a short lowercase filename with hyphens.

# English project article
npm run new:project -- project/my-project-title.md

# Vietnamese personal article
npm run new:personal -- personal/ten-bai-viet.md

# Vietnamese Chinese-learning article
npm run new:language -- languages/ten-bai-viet.md

Hugo creates a file with front matter at the top:

---
title: "Tên bài viết"
date: 2026-09-05T15:00:00+07:00
description: "Một câu ngắn giúp người đọc hiểu bài viết nói về điều gì."
category: "Cá nhân"
article_lang: "vi"
draft: true
---

The fields mean:

  • title: the headline shown on the section and article pages.
  • date: publication time. Keep the generated value or use an ISO date.
  • description: one natural sentence used as the article preview.
  • category: a short label such as RAG evaluation, Phản tư, or Phương pháp.
  • article_lang: use en for Project and vi for Personal or Languages.
  • draft: keep true while writing; change it to false when ready to publish.
  • weight: optional ordering value. Smaller values appear first where weight ordering is used.

Write the article below the closing ---. Do not put the body inside the front matter.

4. Preview while writing

Start the local server:

npm run dev

Open the URL printed by Hugo. Drafts are hidden by default. To preview drafts, run:

npm run sync:vendor
npx hugo server --buildDrafts

Hugo watches your files and refreshes the page after each save. Stop the server with Ctrl+C.

5. Format an article

Use normal Markdown:

## A section heading

Write paragraphs with a blank line between them. Use **bold text** for emphasis and *italic text* for titles or light emphasis.

- A short list item
- Another list item

> A quotation or one idea that deserves more space.

[Link text](https://example.com)

Keep paragraphs focused on one idea. Prefer direct sentences and concrete examples. Project articles stay in English. Personal and Languages articles stay in natural Vietnamese.

For every Chinese example sentence, include all four parts:

**你喜欢我吗？**  
*Nǐ xǐhuan wǒ ma?*  
“Nee shee-hwan wuh ma?”  
Bạn có thích tôi không?

6. Add images

For an image used by one post, use a Hugo page bundle. Instead of one Markdown file, create a folder containing index.md and the image:

content/personal/chuyen-di-cua-toi/
├── index.md
└── ho-guom.jpg

Inside index.md, reference the image with a relative path:

![Hồ Gươm vào buổi sáng](ho-guom.jpg)

This is the safest method for GitHub Pages because the image moves with the post. Use descriptive lowercase filenames, compress large photographs before committing, and always write useful alt text inside [].

For an image shared by several pages, place it in static/images/ and reference it through Hugo’s relURL shortcode in a template. Page bundles are simpler for ordinary articles.

7. Update the landing-page data

Writing a post automatically adds it to its section list. Two dashboard areas are managed separately:

  • Edit data/projects.yaml to change the three featured project rows or their article links.
  • Edit data/chinese.yaml to update vocabulary status, learning steps, and daily-practice squares.

Keep these files valid YAML. Preserve indentation and use spaces, not tabs.

8. Check the production build

Before publishing, run:

npm run build:pages -- --gc --baseURL /Personal-Blog/

A successful build creates public/ and reports the number of generated pages. Open several routes during local preview, especially the new article and any image it contains.

9. Publish

Set draft: false, then commit and push:

git status
git add content data static
git commit -m "Add new blog post"
git push origin main

If you changed files outside those folders, stage them explicitly or use git add -A after reviewing git status.

GitHub Actions automatically installs dependencies, builds Hugo with the correct /Personal-Blog/ base path, and deploys GitHub Pages. Check the repository’s Actions tab. When both build and deploy are green, the update is live at:

https://mathematicguy.github.io/Personal-Blog/

10. Common problems

My post does not appear

Check that the file is inside the correct content/ section, the front matter closes with ---, the date is not in the future, and draft is false.

The image works locally but not on GitHub Pages

Use a page bundle and a relative image path. Avoid links beginning with /images/... because this site is hosted below /Personal-Blog/.

The build fails after editing YAML

Look for uneven indentation, tabs, or a missing quote. Restore the last working indentation and build again.

I renamed a post and the old URL stopped working

Changing the filename changes the URL. Avoid renaming published posts unless necessary. If you must preserve an old URL, add an aliases list to the front matter and test it before pushing.

11. A safe writing routine

  1. Pull the newest version with git pull --ff-only.
  2. Create the post with the correct npm command.
  3. Write with draft: true and preview with drafts enabled.
  4. Add formatting and images only after the basic article reads well.
  5. Set draft: false and run the production build.
  6. Review git status, commit, and push.
  7. Confirm the GitHub Actions deployment is green.

Continue with docs/example.md for a small exercise that follows this routine.