November 18, 2026
Writing Guide: How to Publish on dafinsa.id/writings
A practical cheatsheet for writings, tagging, and publishing articles on the dafinsa.id writings system built with Astro Content Collections and Tailwind CSS v4.
This is the internal reference for publishing content on /writings. It covers file placement, frontmatter schema, image handling, tagging rules, and the publish workflow.
Where to Put Files
There are three categories, each with its own folder under src/content/:
| Category | Location | Example |
|---|---|---|
| Blog | src/content/blog/ |
src/content/blog/why-self-host.md |
| Wiki | src/content/wiki/ |
src/content/wiki/nginx-reverse-proxy.md |
| Paper | src/content/paper/ |
src/content/paper/network-analysis.md |
Naming rules: lowercase only, separate words with hyphens, no spaces or special characters. The filename becomes the URL slug.
✅ why-self-host.md → /writings/blog/why-self-host
✅ nginx-reverse-proxy.md → /writings/wiki/nginx-reverse-proxy
❌ Why Self Host.md → spaces, uppercase
❌ why_self_host.md → underscore
Frontmatter
Every file must start with a frontmatter block delimited by ---. The schema is validated by Zod at build time, so a missing or mistyped field will fail the build with a clear error.
For blog and wiki:
---
title: "Article Title"
description: "One or two sentences for preview and SEO."
pubDate: 2026-11-19
tags: ["linux", "devops"]
draft: false
---
For paper, add pdfUrl:
---
title: "Paper Title"
description: "Short summary of the paper."
pubDate: 2026-11-19
tags: ["network", "research"]
draft: false
pdfUrl: "/files/paper-name.pdf"
---
For an updated article, add updatedDate:
---
title: "Title"
description: "Summary."
pubDate: 2026-11-01
updatedDate: 2026-11-19
tags: ["linux"]
draft: false
---
Field reference:
| Field | Required | Type | Notes |
|---|---|---|---|
title |
Yes | string | Article title |
description |
Yes | string | Max 200 characters |
pubDate |
Yes | date | Format YYYY-MM-DD |
updatedDate |
No | date | Optional, shown in header |
tags |
No | string[] | Default [], auto-lowercased |
draft |
No | boolean | Default false, true means hidden |
pdfUrl |
No | string | Paper only, absolute path |
Writing Content
Standard Markdown is supported. Use ## for section headings and ### for subsections. Inline formatting uses **bold**, *italic*, and `inline code`. Lists can be unordered (hyphens) or ordered (numbers). Blockquotes use >. Code blocks use triple backticks with a language identifier for syntax highlighting. Tables use pipe syntax.
Internal links should point to /writings/... paths. External links can use full URLs.
## Heading 2
Regular paragraph. **Bold**, *italic*, `inline code`.
### Heading 3
- List item
- List item
- Nested item
1. Ordered
2. List
> Blockquote for important notes.
```bash
# Code block with syntax highlighting
sudo systemctl restart nginx
```
| Column | Value |
|---|---|
| A | 1 |
| B | 2 |
[Internal link](/writings/blog/other-article)
[External link](https://example.com)
Images
Save the image in public/images/ and reference it with an absolute path:

Folder structure:
public/
├── images/
│ ├── topology.png
│ └── nginx-screenshot.png
└── files/
└── research-paper.pdf
Path rules: use /images/topology.png (absolute from root, correct). Do not use images/topology.png (relative, may 404) or ../public/images/x.png (relative, wrong).
PDF Files
Paper only. Save the PDF in public/files/ and set pdfUrl in frontmatter:
pdfUrl: "/files/research-paper.pdf"
A “Download PDF” button will appear automatically on the article page.
Tags
Write tags in lowercase (auto-normalized). Reuse existing tags to avoid duplicates. Keep it to 3–5 tags per article. Browse existing tags at /writings/tag.
tags: ["linux", "devops", "nginx"]
Draft Mode
While writings, set draft: true so the article stays hidden. Draft articles do not appear on /writings, /writings/blog, Recent Posts, or tag pages, but are still accessible via direct URL for preview. Switch to draft: false when ready to publish.
Daily Workflow
Start the dev server with npm run dev. Create a new file with touch src/content/blog/new-article.md. Edit the file, fill in frontmatter and content. Preview in browser at http://localhost:4321/writings. When done, set draft: false. Build for production with npm run build.
Common Errors
| Error | Cause | Fix |
|---|---|---|
title is required |
Missing title in frontmatter |
Add title: "..." |
Invalid date |
Wrong date format | Use YYYY-MM-DD |
description too long |
Over 200 characters | Shorten the description |
Unknown tag |
Typo in tag name | Check /writings/tag |
| Article not showing | draft: true |
Change to false |
| Image 404 | Wrong path | Use /images/name.png |
| PDF 404 | File missing in public/files/ |
Check file location |
SEO Checklist
Before publishing, confirm that title is descriptive (50–60 characters), description is informative (150–160 characters), pubDate is correct, at least one relevant tag is set, at least one ## heading exists in the content, images have descriptive alt text, and internal links to related articles are added if relevant.
Writing Tips
Good article structure: a hook that grabs attention, context on why the topic matters, body with main points under ## headings, examples with code blocks or screenshots, and a brief conclusion.
Avoid paragraphs longer than 5 lines, headings deeper than necessary (#### is rarely needed), walls of text without lists or code blocks, and links without descriptive text.
Full Article Example
---
title: "Setup Nginx Reverse Proxy for Multiple Domains"
description: "A configuration guide for running Nginx as a reverse proxy for multiple domains on a single server."
pubDate: 2026-11-19
tags: ["nginx", "devops", "linux"]
draft: false
---
Nginx is one of the most popular reverse proxies for self-hosted infrastructure. In this article, I'll share the configuration I use to manage multiple domains on a single VPS.
## Why Reverse Proxy?
With a reverse proxy, a single server can serve many domains...
## Basic Configuration
Create a config file in `/etc/nginx/sites-available/`:
```nginx
server {
listen 80;
server_name example.com;
location / {
proxy_pass http://localhost:3000;
}
}
```
## Enable the Site
```bash
sudo ln -s /etc/nginx/sites-available/example.com /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
```
## Conclusion
With this setup, you can manage many domains...