giban

Minimal blog starter with AstroJS

Overview

• Quick Start
  • With cloudflare
  • Without cloudflare
  • Troubleshoot
• Introduction
  • Who can use this
  • Stack
  • Features
  • Why giban
• Guides
  • How to change color set
  • How to use icon
• Refs

Quick Start

With cloudflare

$ bun create cloudflare@latest

╭ Create an application with Cloudflare Step 1 of 3
│
├ In which directory do you want to create your application?
│ dir ./my-blog
│
├ What would you like to start with?
│ category Template from a GitHub repo
│
├ What's the url of git repo containing the template you'd like to use?
│ repository msisdev/giban
│
├ Cloning template from: msisdev/giban
│
...

Without cloudflare

1. $ bun create astro --template msisdev/giban
2. Remove cloudflare adapter

   // astro.config.mjs
   export default defineConfig({
     // ↓ Remove this block ↓
     adapter: cloudflare({
       platformProxy: {
         enabled: true
       }
     }),
   })

3. $ bun rm @cloudflare/workers-types
4. Remove/edit cloudflare specific codes
5. Search codes by CLOUDFLARE_ONLY keyword
6. Edit codes

Troubleshoot

If you get error Cannot find module 'astro:content' or its corresponding type declarations

• $ bunx astro sync

Introduction

giban (Korean, 기반): a foundation, or the foundation of a thing

giban is a minimal, fully functional blog. It has minimal style and CSS-in-JS boilerplates.
Start building your own style from this theme. Or swap color set and ready to go.

Who can use this?

• Bloggers: swap color set and ready to go
• CSS Beginners: launch blog and develop style progressively
• CSS Pros: save time by skipping tokens & scripts
• Developers: just explore patterns and implementations in AstroJS

Stack

• AstroJS
• Markdoc
• Pagefind
• PandaCSS
• Iconify

Features

Common blog patterns

• Tags
• Table of content
• Reading time
• Search by pagefind
• Image optimization by Cloudflare Images
• Dark mode switch

Styling kit

• Instant color swap (read the github guide)
• PandaCSS boilerplates
• Icon by Iconify

I didn't add comment system because it is not minimal and easy to be added. Checkout discus or utterances.

Checkout either giscus or utterances.

Why giban?

AstroJS

AstroJS is a new contender of FrontEnd framework.

• Meta-framework
• Built-in SSG support
• Best performance by Server island

MDX vs Markdoc

MDX is like JSX.

import Callout from '../components/Callout.astro'

I'm normal markdown line.

<Callout type="check">
  I'm custom component
</Callout>

While Markdoc is like expressive markdown.

I'm normal markdown line.

{% callout type="check" %}
  I'm custom component
{% /callout %}

But you should aware that @astrojs/markdoc integration is in experimental stage.

PandaCSS

PandaCSS is a zero runtime CSS-in-JS that generates static css files at build stage.
PandaCSS uses helper function to write styles fast.

Writing styles in PandaCSS is like:

---
// Footer.astro
import urls from "@/config/urls"
import { Icon } from "astro-icon/components"
import { css } from "styled-system/css"

const root = css({
  padding: 4,
})

const root__line1 = css({
  display: "flex",
  alignItems: "center",
  gap: 4,
  
  "& a": {
    display: "flex",
    alignItems: "center",
    gap: 2,
  },
})
---
<footer class={root}>
  <p class={root__line1}>
    &copy;2025 by msisdev All rights reserved.
    <a href={urls.github} aria-label="Github repository">
      <Icon name="iconoir:github" /> Github
    </a>
  </p>
  
</footer>

vs Obsidian Digital Garden

You may find Obsidian Digital Garden is more useful, if you like Obsidian.

But you don't need Digital Garden if-

• you want to keep things simple.
• you don't need Obsidian.
  • With help of Github Mobile app, you can create/edit files anywhere.

Guides

How to change color set

You can change colors instantly by using Realtime Colors.
Please follow this guide.

How to use icon

This project is using Astro Icon and Iconify.
Currently iconoir is installed. To replace this, follow this guide.

Refs

AstroJS discussion

• When you encounter compile error on astro:content

Rodney

• Astro markdoc for blog

ymcheung

• Astro markdoc configs

Trung Vo

• Cloudflare Images troubleshoot

bharath kumar

• Demo image

Anca I/O

• reading time

shishkin

• astro-pagefind

Thomas Ledoux

• how to use pagefind

Realtime Colors

• Automate color change

astro-icon

• Iconify usage