Dokumentasi Project: ngopidulur-astro

Blog pribadi statis menggunakan Frosti theme + Astro 6 + Decap CMS

Daftar Isi

• Overview
• Tech Stack
• Struktur Project
• Konfigurasi
• Content Management (Decap CMS)
• Menulis Artikel
• Development
• Deployment
• Perubahan yang Dilakukan
• Troubleshooting

Overview

Project ini adalah blog pribadi statis yang dibangun menggunakan:

• Frosti↗ v3.3.3 — template blog untuk Astro
• Astro↗ v6.3.6 — framework web untuk content-driven websites
• Decap CMS↗ — open-source, Git-based CMS untuk mengelola konten via browser

Blog ini menghasilkan file HTML statis saat di-build, sehingga sangat cepat dan bisa di-deploy di hosting manapun.

Tech Stack

Struktur Project

1
ngopidulur-astro/
2
├── public/                    # File statis (langsung di-serve)
3
│   ├── admin/                 # Decap CMS
4
│   │   ├── config.yml         # Konfigurasi CMS (collections, fields)
5
│   │   ├── index.html         # Entry point CMS
6
│   │   └── decap-cms.js       # Decap CMS bundle (pinned 3.3.3, lokal)
7
│   ├── image/                 # Gambar untuk artikel
8
│   ├── pagefind/              # Search index (auto-generated dari `pnpm search:index`)
9
│   ├── favicon.ico
10
│   ├── logo.png
11
│   ├── profile.png            # Avatar user
12
│   └── profile2.png           # Logo hero homepage
13
├── src/
14
│   ├── components/            # Komponen Astro
15
│   │   ├── mdx/               # Komponen untuk MDX (alerts, collapse, dll)
16
│   │   ├── sidebar/           # Sidebar components (profile, search, TOC)
17
│   │   ├── widgets/           # Widget (pagination, theme toggle, dll)
18
│   │   ├── Header.astro
19
│   │   ├── Footer.astro
20
│   │   ├── Navbar.astro
21
│   │   ├── PostCard.astro
22
│   │   └── Sidebar.astro
23
│   ├── content/
24
│   │   └── blog/              # Artikel blog (Markdown/MDX)
25
│   ├── i18n/                  # Internationalization
26
│   │   └── translations.yaml  # Teks UI multi-bahasa
27
│   ├── interface/             # TypeScript interfaces
28
│   ├── integration/           # Custom Astro integrations
29
│   ├── layouts/
30
│   │   └── BaseLayout.astro   # Layout utama
31
│   ├── pages/                 # Halaman-halaman situs
32
│   │   ├── blog/              # Blog routes (list, detail, category, tag)
33
│   │   ├── og/                # Auto-generated OG images
34
│   │   ├── admin.astro        # Decap CMS admin page
35
│   │   ├── index.astro        # Homepage
36
│   │   ├── about.astro        # About page
37
│   │   ├── project.astro      # Project page
38
│   │   ├── rss.xml.ts         # RSS feed
39
│   │   └── robots.txt.ts      # Robots.txt
40
│   ├── plugins/
41
│   │   └── remark-reading-time.ts  # Plugin estimasi waktu baca
42
│   ├── styles/
43
│   │   ├── global.scss        # Global styles
44
│   │   └── waline.scss        # Comment system styles
45
│   ├── utils/                 # Utility functions
46
│   ├── config.ts              # Membaca frosti.config.yaml
47
│   └── content.config.ts      # Definisi content collections
48
├── frosti.config.yaml         # KONFIGURASI UTAMA SITUS
49
├── astro.config.mjs           # Konfigurasi Astro
50
├── tsconfig.json              # TypeScript config (exclude pagefind & decap-cms.js)
51
├── biome.json                 # Linter/formatter config
52
├── package.json               # Dependencies & scripts
53
└── dist/                      # Output build (jangan edit manual)

Konfigurasi

File Konfigurasi Utama: frosti.config.yaml

Semua pengaturan situs ada di file ini:

1
site:
2
  tab: Frosti              # Teks di browser tab
3
  title: 💠 Frosti         # Judul situs
4
  description: ...         # Deskripsi SEO
5
  language: en             # Bahasa (en/zh/dll)
6
  favicon: /favicon.ico
7
  theme:
8
    light: winter          # Tema terang (daisyUI)
9
    dark: dracula          # Tema gelap (daisyUI)
10
    code: github-dark      # Tema code block (Shiki)
11
  date_format: ddd MMM DD YYYY
12
  blog:
13
    pageSize: 8            # Artikel per halaman
14
  menu: [...]              # Navigasi menu sidebar/navbar
15

16
user:
17
  name: Rifky Awalul Huda  # Nama yang ditampilkan
18
  site: "https://..."       # URL situs
19
  avatar: /profile.png      # Path avatar
20
  sidebar:
21
    social: [...]           # Social links di sidebar
22
  footer:
23
    social: [...]           # Social links di footer

Penting: Setelah edit frosti.config.yaml, restart dev server (Ctrl+C lalu npm run dev lagi) karena file ini dibaca via fs.readFileSync yang tidak hot-reload.

Catatan Konfigurasi yang Sedang Dipakai

• Menu Friend, Contact, dan Examples sudah dihapus dari site.menu. Halaman friend.astro juga dihapus dari codebase.
• Kategori sidebar yang aktif: Tulisan Random, Teknologi, Documentation.
• Social icon sidebar dan footer saat ini memakai Facebook, GitHub, LinkedIn, dan X.
• Format icon yang benar mengikuti pola collection:name, misalnya ri:linkedin-line atau ri:facebook-line.
• user.site saat ini mengarah ke profil LinkedIn.

Astro Config: astro.config.mjs

Integrasi yang aktif:

• expressiveCode — syntax highlighting
• mdx — support file .mdx
• icon — icon library (Iconify)
• terser — JS minification
• sitemap — auto-generate sitemap.xml
• playformCompress — compress output

Markdown plugins:

• remarkMath + rehypeKatex — rumus matematika
• remarkReadingTime — estimasi waktu baca
• rehypeExternalLinks — tambah ↗ di link eksternal

Content Management (Decap CMS)

Apa itu Decap CMS?

Decap CMS adalah admin UI berbasis web yang memungkinkan kamu membuat dan mengedit artikel blog langsung dari browser, tanpa perlu buka code editor. Perubahan disimpan langsung sebagai file Markdown di repository.

Cara Akses (Lokal)

1. Buka terminal pertama, jalankan proxy server:

   1
   npx decap-server

2. Buka terminal kedua, jalankan dev server:

   1
   npm run dev

3. Buka browser: http://localhost:4321/admin↗

4. Langsung masuk tanpa login (local mode)

Konfigurasi CMS: public/admin/config.yml

1
backend:
2
  name: git-gateway       # Backend untuk production (Netlify)
3
  branch: main
4

5
local_backend: true       # Enable untuk development lokal (tanpa auth)
6

7
media_folder: "public/image"   # Folder upload gambar
8
public_folder: "/image"        # Path gambar di situs
9

10
collections:
11
  - name: "blog"
12
    label: "Blog Posts"
13
    folder: "src/content/blog"
14
    create: true
15
    fields:
16
      - title (string, required)
17
      - description (string, required)
18
      - pubDate (datetime, required)
19
      - updated (datetime, optional)
20
      - image (image, optional)
21
      - badge (string, optional) — set "Pin" untuk pin artikel
22
      - draft (boolean, optional) — true = tidak tampil di list
23
      - categories (list, optional)
24
      - tags (list, optional)
25
      - body (markdown)

Catatan: File .md vs .mdx di CMS

Decap CMS hanya menampilkan file dengan ekstensi .md (dikonfigurasi via extension: "md" di config.yml). File .mdx tidak muncul di CMS dan memang sengaja dikelola terpisah.

Konvensi:

• File .md — Artikel biasa, dikelola via Decap CMS (/admin) atau langsung edit file.
• File .mdx — Artikel yang menggunakan komponen interaktif (import custom components seperti <Collapse>, <Info>, <LinkCard>, dll). Dikelola langsung via code editor karena Decap CMS tidak bisa merender syntax JSX/import.

Kenapa tidak membuat collection kedua untuk MDX?

1. Di sisi Astro, semua post (.md dan .mdx) sudah satu content collection blog. Memisahkan di CMS membingungkan.
2. Decap CMS tetap tidak bisa mengedit syntax MDX (import/JSX) dengan benar.
3. Duplikasi konfigurasi fields tanpa manfaat nyata.

Jadi jika ada post yang hanya muncul di situs tapi tidak di CMS, kemungkinan besar itu file .mdx — dan itu memang by design.

Catatan Production

Untuk deploy dengan Decap CMS aktif:

• Deploy ke Netlify dan aktifkan Netlify Identity
• Hapus/comment local_backend: true di config.yml
• User bisa login via email di /admin

Menulis Artikel

Via Decap CMS (Recommended)

1. Buka /admin di browser
2. Klik “Blog Posts” → “New Blog Post”
3. Isi field-field yang tersedia
4. Klik “Publish”
5. File Markdown otomatis dibuat di src/content/blog/

Via File Manual

Buat file .md di src/content/blog/ dengan format:

1
---
2
title: "Judul Artikel"
3
description: "Deskripsi singkat"
4
pubDate: 2025-01-15
5
image: "/image/cover.jpg"
6
categories:
7
  - Documentation
8
tags:
9
  - astro
10
  - tutorial
11
draft: false
12
---
13

14
Isi artikel di sini menggunakan Markdown...

Frontmatter Fields

Development

Prerequisites

• Node.js >= 18
• pnpm (recommended) atau npm
• Untuk pnpm v10+: jalankan pnpm approve-builds saat install pertama untuk approve build scripts dari esbuild, sharp, swup, dan @parcel/watcher.

Commands

Project ini pakai pnpm. Semua command bisa dijalankan via pnpm <script>. Kalau pakai npm, ganti pnpm dengan npm run.

1
# Running Decap Server (terminal 1)
2
npx decap-server
3
# Install dependencies
4
pnpm install
5

6
# Development server (http://localhost:4321) — terminal 2
7
pnpm dev
8

9
# Build untuk production (build + generate Pagefind index)
10
pnpm build
11

12
# Preview build result
13
pnpm preview
14

15
# Type checking
16
pnpm check
17

18
# Linting (Biome)
19
pnpm lint
20

21
# Format code (Biome)
22
pnpm format
23

24
# Generate search index lalu copy ke public/
25
pnpm search:index

Pertama Kali Setup

1
pnpm install
2
pnpm approve-builds        # Approve build scripts (pilih semua dengan 'a')
3
pnpm search:index          # Generate Pagefind search index
4
pnpm dev                   # Start dev server

Workflow Harian

1
pnpm dev                   # Start dev server
2
# Edit artikel via /admin atau langsung di file
3
# Ctrl+C untuk stop

Setelah Tambah/Edit Artikel

Search index Pagefind tidak auto-update saat dev. Setelah konten berubah signifikan, regenerate index:

1
pnpm build
2
npx cpy-cli "dist/pagefind/**" "public/pagefind"

Deployment

Opsi 1: Netlify (Recommended — gratis + Decap CMS)

1. Push repo ke GitHub
2. Connect repo di netlify.com↗
3. Build command: npm run build
4. Publish directory: dist
5. Aktifkan Netlify Identity untuk Decap CMS login
6. Hapus local_backend: true di public/admin/config.yml

Opsi 2: Shared Hosting / cPanel

Persiapan sebelum build

1. Edit frosti.config.yaml: ganti user.site ke domain produksi (misal https://ngopidulur.my.id). Pastikan ada https:// dan tanpa trailing slash.
2. Edit public/admin/config.yml: comment baris local_backend: true (# local_backend: true). Decap CMS local backend cuma untuk dev.

Build dan compress

Di lokal:

1
pnpm install
2
pnpm search:index
3
pnpm build

Lalu compress isi dist/:

1
Compress-Archive -Path dist\* -DestinationPath dist.zip -Force

Upload dan extract

1. Login ke cPanel → File Manager.

2. Navigate ke public_html/ (atau folder subdomain).

3. PENTING — sebelum upload baru, hapus folder lama yang berpotensi konflik:

   Lewat cPanel Terminal, jalankan:

   1
   cd ~/public_html
   2
   rm -rf blog _astro admin image og pagefind

   Kalau cPanel kamu tidak punya Terminal, hapus folder-folder ini lewat File Manager.

4. Upload dist.zip ke public_html/.

5. Extract via File Manager (atau Terminal: unzip -o dist.zip).

6. Hapus dist.zip setelah extract sukses.

Pasang .htaccess

Buat file .htaccess di public_html/ dengan isi:

1
RewriteEngine On
2

3
# Force HTTPS
4
RewriteCond %{HTTPS} !=on
5
RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]
6

7
# Custom 404
8
ErrorDocument 404 /404.html
9

10
# Pretty URLs
11
RewriteCond %{REQUEST_FILENAME} !-f
12
RewriteCond %{REQUEST_FILENAME} !-d
13
RewriteRule ^(.+?)/?$ $1.html [L]
14

15
DirectoryIndex index.html
16

17
# Compression
18
<IfModule mod_deflate.c>
19
  AddOutputFilterByType DEFLATE text/html text/css text/javascript application/javascript application/json image/svg+xml
20
</IfModule>
21

22
# Cache
23
<IfModule mod_expires.c>
24
  ExpiresActive On
25
  ExpiresByType image/jpeg "access plus 1 year"
26
  ExpiresByType image/png "access plus 1 year"
27
  ExpiresByType image/webp "access plus 1 year"
28
  ExpiresByType text/css "access plus 1 year"
29
  ExpiresByType application/javascript "access plus 1 year"
30
  ExpiresByType font/woff2 "access plus 1 year"
31
</IfModule>
32

33
# Security
34
<IfModule mod_headers.c>
35
  Header set X-Content-Type-Options "nosniff"
36
  Header set X-Frame-Options "SAMEORIGIN"
37
  Header set Referrer-Policy "strict-origin-when-cross-origin"
38
</IfModule>

Catatan penting

• ⚠️ Decap CMS /admin tidak akan berfungsi penuh di shared hosting tanpa Netlify Identity atau OAuth proxy. Untuk update konten, edit di lokal lalu re-deploy.
• Setelah deploy, test halaman kategori (/blog/category/Teknologi) dan tag (/blog/tag/...). Kalau muncul 404, baca section Troubleshooting di bawah.

Opsi 3: Vercel / Cloudflare Pages

1. Connect GitHub repo
2. Build command: npm run build
3. Output directory: dist
4. Untuk Decap CMS, perlu setup external OAuth client↗

Perubahan yang Dilakukan

Integrasi Decap CMS (Mei 2025)

File baru:

• public/admin/config.yml — Konfigurasi Decap CMS dengan field mapping ke blog collection
• public/admin/index.html — Entry point HTML untuk Decap CMS (CDN)
• src/pages/admin.astro — Astro page route untuk /admin

Tujuan: Menambahkan admin UI berbasis web untuk mengelola artikel blog tanpa perlu edit file Markdown secara manual.

Percobaan CMS yang Tidak Jadi

Selama proses setup, beberapa CMS dicoba tapi tidak kompatibel:

1. Storyblok — Berbayar (tidak ada free tier yang mudah diakses)
2. Keystatic — Belum support Astro 6 (peer dependency conflict, crash di production)

Kedua percobaan ini sudah di-revert sepenuhnya. Tidak ada sisa kode dari Storyblok atau Keystatic di project.

Penyesuaian UI dan Konfigurasi (Mei 2026)

Homepage

• src/pages/index.astro: section Features diganti menjadi Blog Terbaru.
• Homepage sekarang menampilkan maksimal 6 post terbaru dari collection blog.
• Layout daftar post di homepage diubah menjadi grid card ringkas 3 kolom di desktop dan tetap responsif di layar kecil.

About page

• src/pages/about.astro: tombol sosial pertama di section profil diubah dari GitHub menjadi LinkedIn.
• Link sosial yang dipakai di halaman About sudah menyesuaikan profil LinkedIn dan Facebook terbaru.

Navigasi

• frosti.config.yaml: menu Friend dan Contact dihapus dari site.menu.
• Halaman src/pages/friend.astro masih ada di codebase, tetapi tidak lagi muncul di navigasi utama.

Footer dan social icons

• src/components/Footer.astro tetap menjadi komponen footer utama yang dipakai oleh src/layouts/BaseLayout.astro.
• Data social footer tetap dibaca dari frosti.config.yaml melalui src/config.ts.
• Icon ri:cup-line di konfigurasi social footer diganti menjadi ri:facebook-line.
• Icon LinkedIn di konfigurasi memakai format yang benar: ri:linkedin-line.

Maintenance & Code Quality (Mei 2026)

Update dependency untuk kompatibilitas Astro 6

• @astrojs/rss di-update ke ^4.0.18 (fix error z.function().returns is not a function).
• @astrojs/sitemap di-update ke ^3.7.2 (fix error Cannot read properties of undefined (reading 'reduce')).

Fix prioritas High dari hasil code review

• Decap CMS pinned & lokal: dependency dari CDN (https://unpkg.com/decap-cms@^3.3.3) di src/pages/admin.astro dan public/admin/index.html diganti ke file lokal public/admin/decap-cms.js (versi 3.3.3 di-pin). Mencegah breaking change upstream dan mengurangi attack surface.
• Race condition di search page: src/pages/blog/search.astro di-refactor agar tidak append script tag duplikat saat user navigate via View Transitions. Ada pengecekan window.PagefindUI dan attribute data-pagefind-loader untuk reuse instance.
• A11y/SEO homepage: src/pages/index.astro heading <h1> ditambah lagi (sr-only agar tetap visual-friendly), gambar hero profile2.png ditambah width, height, dan fetchpriority="high" untuk cegah CLS dan prioritaskan loading.

Schema content collection lebih toleran

• src/content.config.ts: field updated sekarang menerima string kosong "" dari Decap CMS dan otomatis convert ke undefined. Mencegah error Expected type "date", received "object" saat post baru dibuat lewat CMS tanpa mengisi tanggal update.

TypeScript config

• tsconfig.json: tambah exclude untuk public/admin/decap-cms.js (5.3 MB minified) dan public/pagefind/**. Mencegah astro check out-of-memory saat scan vendor files.

Cleanup file tidak terpakai

• Dihapus 14 file yang sudah tidak terpakai:
  • Static assets duplikat: favicon1.ico, profile1.png, image/l.png, image/r.png, image/image2.jpg, image/uploaded-screenshot.png.
  • Frosti updater scripts: frosti.update.sh, .updateignore, src/i18n/en.sh, src/i18n/zh.sh.
  • Halaman friend dan komponen pendukungnya: src/pages/friend.astro, src/components/mdx/FriendCard.astro, src/components/mdx/Showcase.astro, src/components/mdx/LinkCard.astro.

Setup MCP Astro Docs (global Kiro)

• File ~/.kiro/settings/mcp.json ditambah server astro-docs dengan autoApprove: ["search_astro_docs"]. AI agent sekarang punya akses ke dokumentasi Astro versi terbaru via MCP tanpa konfirmasi manual.

Troubleshooting

Config tidak update setelah edit frosti.config.yaml

Penyebab: File dibaca via fs.readFileSync saat module di-import, tidak terdeteksi oleh Vite hot-reload. Solusi: Restart dev server (Ctrl+C → npm run dev).

Decap CMS minta login di localhost

Penyebab: local_backend: true belum di-set, atau npx decap-server belum jalan. Solusi:

1. Pastikan local_backend: true ada di public/admin/config.yml
2. Jalankan npx decap-server di terminal terpisah sebelum akses /admin

/admin page not found

Penyebab: Astro dev server tidak auto-resolve index.html di subfolder public/. Solusi: Gunakan route src/pages/admin.astro (sudah dibuat). Akses via http://localhost:4321/admin.

Build error setelah install package baru

Solusi: Jalankan npm run check untuk melihat error. Pastikan astro.config.mjs tidak ada import yang broken.

Search tidak berfungsi

Penyebab: Search index belum di-generate. Solusi: Jalankan pnpm search:index (atau npm run search:index) sebelum pnpm dev. Setelah build, copy index ke public/:

1
npx cpy-cli "dist/pagefind/**" "public/pagefind"

Search page error: “Cannot import non-asset file”

Penyebab: Pagefind UI di-import via dynamic import() yang diproses Vite, padahal file ada di public/. Solusi: Sudah di-fix. src/pages/blog/search.astro sekarang load /pagefind/pagefind-ui.js via document.createElement("script") agar bypass Vite.

Decap CMS error: “data does not match collection schema (updated: Expected date, received object)”

Penyebab: Decap CMS menyimpan field datetime kosong sebagai string "", sementara schema Zod lama strict. Solusi: Sudah di-fix di src/content.config.ts. Field updated sekarang menerima "" dan otomatis convert ke undefined. Tidak perlu action manual.

astro check JavaScript heap out of memory

Penyebab: Astro mencoba scan file vendor besar di public/ (decap-cms.js, file Pagefind). Solusi: Sudah di-fix di tsconfig.json via exclude. Kalau muncul lagi setelah tambah file vendor baru, tambahkan ke exclude array.

Build error: z.function(...).returns is not a function

Penyebab: @astrojs/rss versi lama tidak kompatibel dengan Zod yang dibawa Astro 6. Solusi: Sudah di-fix dengan update ke @astrojs/rss@^4.0.18. Kalau ketemu di package lain, update ke versi terbaru.

pnpm install gagal: [ERR_PNPM_IGNORED_BUILDS]

Penyebab: pnpm v10+ memblokir postinstall scripts secara default. Solusi: Jalankan pnpm approve-builds, pilih semua dengan a lalu Enter, lalu pnpm install lagi.

Deploy cPanel: kategori atau tag muncul 404 setelah upload

Gejala: Halaman seperti /blog/category/Teknologi atau /blog/tag/php muncul 404, padahal halaman lain (homepage, detail post) jalan normal.

Penyebab: Saat extract dist.zip di cPanel, folder seperti blog/category/, blog/tag/ sudah ada dari deploy sebelumnya tapi dengan permission/ownership yang rusak. Extract membuat folder tujuan tapi gagal extract index.html di dalamnya. Folder kosong = 404.

Indikator: Saat extract via Terminal cPanel muncul error seperti:

1
checkdir error: cannot create blog/category/Teknologi
2
Permission denied
3
unable to process blog/category/Teknologi/index.html.

Solusi: Hapus folder bermasalah dulu sebelum re-extract.

Via cPanel Terminal:

1
cd ~/public_html
2
rm -rf blog/category blog/tag
3
# atau lebih bersih: rm -rf blog
4
unzip -o dist.zip

Kalau rm -rf juga gagal dengan permission denied:

1
chmod -R 755 blog/category blog/tag 2>/dev/null
2
rm -rf blog/category blog/tag

Kalau tetap denied, kontak support hosting untuk reset ownership folder ke akun cPanel kamu.

Pencegahan: Sebelum upload deploy baru, selalu hapus folder lama dulu. Jangan extract overwrite di atas folder lama.

Deploy cPanel: situs blank putih atau asset tidak load

Penyebab umum:

• index.html tidak ada di root public_html/ (mungkin nested di public_html/dist/)
• Folder _astro/ tidak lengkap (file CSS/JS hilang)
• USER_SITE di frosti.config.yaml salah saat build

Solusi:

1. Pastikan index.html ada langsung di public_html/, bukan di subfolder
2. Cek Console browser (F12) untuk error 404 spesifik
3. Build ulang dengan USER_SITE yang benar di frosti.config.yaml

Referensi

• Astro Documentation↗
• Frosti Theme↗
• Decap CMS Documentation↗
• daisyUI Themes↗
• Iconify Icons↗
• Tailwind CSS↗

Thanks for reading!

Ngopidulur Astro Blog Doc

Fri May 22 2026

2469 words · 17 minutes

Documentation documentation astro

---

© Rifky Awalul Huda | CC BY-NC-SA 4.0

Share

Share this article

X (Twitter) Telegram WhatsApp LinkedIn Reddit Facebook Email Copy Link

Close

Close