Translated by AI model deepseek-flash.
Source Language: Simplified Chinese, Target Language: english, Translation Time: 2026-10-27 10:22
.AI translation is for reference only. Accuracy is not guaranteed, please refer to the original text.
This article was written with AI assistanceThis article is entirely AI-written; human involvement: 0%
Introduction
Static blogs are nice and all, but updating posts is a real hassle.
Every time I want to change something, the process goes roughly like this: turn on the computer → open the editor → find that post → make the changes → commit → push → wait for CI to finish building before it's actually live. If it's just fixing a typo and I happen to be out, I can only note it down in my notes app and deal with it when I get home.
In 2024, I tinkered with Decap CMS and even wrote a step-by-step tutorial, which more or less solved the "edit posts while out" problem.
But after using it for a while, there were still a few things that felt less than ideal:
- The UI wasn't very good-looking (maybe I'm too picky)
- It was basically unusable on mobile
- Adding a frontmatter field meant going back to edit
config.ymland redeploying - Later I moved the blog from Hexo to Astro, and I'd long since stopped using Netlify Identity
So this project came to be—Astro Blog Studio.
It's now deployed at sakura.ksable.top; just open it and use it.
This article will cover what it is, what it looks like, what it can do, and how it differs from Decap CMS. Finally, I'll spell out the known limitations so you can judge whether it's right for you.
What Is It
In one sentence: a frontend-only, backend-free browser workbench that uses the GitHub API to directly read and write Markdown in a blog repository.
No server, no database, no third-party analytics. The whole app is a static web page that can be dropped onto any static hosting service; the browser talks directly to api.github.com.
A save roughly goes like this:
- Open the web page and unlock it (device fingerprint or password)
- Find the file in the index cards on the left
- Edit the body, or edit the frontmatter
- Click "Stamp Save" to commit to GitHub
- Receive a commit receipt (sha, path, time, GitHub link)
No need to open a local editor or terminal.
The source code is open-source on GitHub under AGPL-3.0; I've also deployed my own instance, ready to use:
- Live site: sakura.ksable.top
- Source code: God-2077/astro-blog-studio
The tech stack is roughly as follows:
| Part | What it uses |
|---|---|
| Framework | React 19 + TypeScript + Vite 7 |
| Editor | CodeMirror 6 + marked + DOMPurify |
| GitHub | Octokit (REST + GraphQL) |
| Styling | Tailwind CSS 4 |
| State | TanStack Query + Zustand |
| Offline | vite-plugin-pwa |
It also comes with 108 unit tests, 7 integration tests against real repositories, and 19 Playwright tests—after all, it edits my own blog repository, so I didn't dare be careless.
What It Looks Like
Before writing code, I had AI generate four visual directions and ultimately chose No. 01, "Sakura Sugar Journal".
The idea was to make blog editing feel like a sheet of journal paper spread out on a desk: files are index cards, editing is the paper, and committing is stamping.

Opening it greets you with "What are we writing today?":
- On the left is a stack of index cards: directory tree and path search
- In the middle are three handwritten sticky notes: All Posts, Drafts, Encrypted
- Below that is "Recently Touched," sorted by
updated/datein the frontmatter - On the right are commit receipts, today's small goal, and the GitHub API quota
There is only one solid sakura-pink button in the entire interface: "New Post"; the stamp is the only red element.
The editor, meanwhile, consists of "three sheets of paper":

The file header (path, status, GitHub / Move / Delete), the frontmatter form, and the Markdown body, with a live preview on the right. In the bottom-right corner of the footer is the stamp labeled "Stamp Save".
The theme follows the system by default; switching to night mode gives warm ink-colored paper—not an inversion, and not harsh on the eyes:

A Few Features I Find Handy
File Tree, Search, and "Recently Touched"
On the left is the repository's directory tree, showing only Markdown; the search box searches paths (Ctrl/Cmd + K to focus).
The workbench's "Recently Touched" doesn't just take the first few posts; it uses GraphQL to batch-read frontmatter across the whole repository, then sorts by updated / date. How many batches to read concurrently can be adjusted in settings (1–10, default 3); higher is faster, but too high may trigger GitHub rate limiting.
When there are more than 1000 posts, only the first 1000 are indexed, with a notice in the UI; if GraphQL is unavailable, it falls back to the Contents API.
Dual Mode: Form / Source File
This is one of my favorite designs.
Normally, you use "Form": frontmatter fields are generated dynamically, and names, types, and whether they're required can all be configured in settings; date has a format hint, list is comma-separated, and password is masked.
But sometimes you just need to edit the entire file directly, for example to adjust key order, change quotes, or add comments. That's when you switch to "Source File": a CodeMirror editor where you directly edit the --- fence + body, and saving writes it back exactly as entered—only restoring the original file's CRLF/LF and BOM, without parsing the frontmatter or "helpfully fixing" anything for you.
When switching back and forth, unsaved content is merged in first, so nothing is lost.
Stamp Save: Commit Messages, Commit Receipts, and Conflicts
Saving isn't a "Save" button; it's a "stamp".
Commit messages support templates such as update: {path}. Available placeholders include {path}, {title}, {newPath}, {dir}, {name}, {date}, etc., and they can be changed in settings.
After a successful save, you receive a receipt: commit sha, path, time, and GitHub link.
Updates and deletions both use sha for optimistic locking. If the remote has already changed, it returns 409 and shows "Reload / Overwrite Remote / Cancel"; it won't silently overwrite your changes.
Moves and renames are completed in a single commit using the Git Data API, so there is no intermediate "add then delete" state.
Refresh Without Saving? There's a Local Backup
The thing I fear most when writing is a slip of the hand.
After about 600ms of debounce, the editor writes a snapshot of the entire file to the browser's IndexedDB, and the footer shows "Backed up locally HH
".The next time you open the same file (including a new draft that hasn't been committed after a refresh), a dialog asks whether to restore it, with options "Later / Discard Backup / Restore Backup". After restoring an old draft, saving still goes through 409 conflict handling, so it won't overwrite newer remote changes.
After a successful save, move, or delete, the corresponding backup is automatically cleared; backups can also be turned off or cleared in settings. Backups exist only locally, are not uploaded, and do not enter the Service Worker cache.
Mobile and PWA
On mobile: the index is tucked into a left drawer, the preview is placed below the body, and the stamp button is fixed at the bottom of the paper.
It's also an installable PWA: the build output includes a manifest and a Service Worker, and the app shell (HTML/JS/CSS/fonts/icons) is precached, so on the second visit, on a weak network, or even offline, the interface can load first—though reading files and saving still require a network connection; api.github.com is always NetworkOnly.
When a new version is available, a dialog prompts you; it refreshes only after you click "Refresh Now," and never secretly auto-refreshes.
The PAT Lives Only in the Browser
Some may worry: is it really safe to put a GitHub token in the browser?
- The token is encrypted with AES-GCM-256 before being written to localStorage, and the key is derived via PBKDF2-SHA256 (600,000 iterations)
- After unlocking, the token exists only in memory; locking clears memory, the query cache, and the editing session
- There is only one external request:
api.github.com - No third-party scripts, analytics, or font CDNs; previews are sanitized with DOMPurify; external links automatically get
rel="noreferrer noopener" - The app itself is also set to
noindex, nofollow, so search engines won't index it
To be clear: device fingerprinting is not a security boundary. To be safer, set a password and enable "Password + Device" two-factor authentication, and remember to lock it after use on a public computer.
Compared with Decap CMS
I wrote a Decap CMS tutorial before, so here's a quick comparison.
| Decap CMS | Astro Blog Studio | |
|---|---|---|
| Deployment | Requires Netlify Identity + Git Gateway | Any static hosting + PAT |
| Login | Email invitation | Device fingerprint / password |
| UI | Generic CMS | Journal style, Chinese UI |
| Mobile | Not very friendly | Drawer index + fixed stamp |
| frontmatter | Edit config.yml and redeploy | Add/remove in settings, takes effect immediately |
| Editing | Rich text | Form + CodeMirror source file |
| Offline | None | PWA app shell |
Decap CMS actually has a more complete feature set (media library, editorial workflow, etc.), but it's aimed at all static websites, its configuration is heavy, and its interface isn't built around my habits. Astro Blog Studio only serves my own blog, so I can make every detail work the way I like—commit message templates, frontmatter fields, and local backups are all designed around my usage habits.
If you also maintain a static blog and:
- Your posts and source code are on GitHub
- You only want it for yourself
- You're willing to create and manage a PAT
then it might suit you too.
How to Use
I've deployed an instance at sakura.ksable.top; just open it and use it. You can also run your own copy or deploy it to your own domain.
1. Create a GitHub Token
On GitHub, create a fine-grained personal access token, granting it access only to your content repository:
Repository permissions → Contents: Read and writeMetadata: Read-only(added automatically)
No PR, Actions, or Pages permissions are needed. For detailed steps, see the official GitHub documentation.
2. Open the Website
Open sakura.ksable.top directly; the first visit lands on the Setup page.
A quick note first: this page is only the frontend; the repository, token, and settings all exist only in your own browser (the token is encrypted before being persisted to disk), and I can't see anyone's content from my side. If you mind entering a token under someone else's domain, deploy your own copy by following step 4—it's the same code.
If you want to see the interface first without entering a token, you can open demo mode; it uses fake data in memory, doesn't connect to the network, and doesn't write to the repository:
https://sakura.ksable.top/?demo=1
You can also run it locally:
git clone git@github.com:God-2077/astro-blog-studio.git
cd astro-blog-studio
pnpm install
pnpm dev
Just open http://localhost:5173.
3. Connect the Repository
On the Setup page, fill in:
- Repository:
owner/nameor a GitHub URL - Branch: leave blank to use the default branch
- Post root directory:
srcfor my blog - Exclusion rules: e.g.
src/content/blog/en,src/content/blog/ja
Then choose an unlock method: check device fingerprint to unlock automatically after a refresh, or set a password as well.
4. Deploy (Optional)
If you're using the live site directly, you can skip this step.
After pnpm build, just drop dist/ onto any static hosting (Cloudflare Pages, Vercel, GitHub Pages, and Netlify all work). It uses HashRouter, so no SPA rewrite rules are needed.
If deploying under a subpath, add STUDIO_BASE=/studio/ at build time.
It's recommended to add a CSP to the site, at least restricting
script-src 'self',connect-src 'self' https://api.github.com, andimg-src 'self' data: https:.
Known Limitations
It's not a silver bullet, so these limitations need to be stated upfront:
- Single-file editing; no image upload, no cross-file content search (path search only), and no version history UI
- Conflict handling only offers "Reload / Overwrite / Cancel"; no line-by-line merge
- Only UTF-8 Markdown / MDX is supported; binary files and very large files show an unsupported notice
- The GitHub Contents API has a per-file limit of about 1MB; branch protection and read-only tokens return 403 on writes
- Device fingerprinting is not a security boundary; on public computers, set a password + two-factor authentication
- Offline caching covers only the frontend: the interface can open offline, but the file tree, body, and commits still require a network connection; there is no offline save queue
- The preview is not 100% identical to the production site (differences are noted on the page, and the source file is always the fallback)
What I Want to Do Next
- Image paste upload
- Cross-file full-text search
- Command palette
- Cover / calendar views
- Offline editing and save queue
I'll note these down for now and see how far I get.
FAQ
Does it need a server or a database?
No. It's just a purely static web page; all reads and writes go directly from the browser to api.github.com. After pnpm build, put dist/ on static hosting and it's ready to use—there's no server-side runtime.
Can it only be used for Astro blogs?
No. The app only recognizes Markdown files in a GitHub repository; the post root directory, file extensions, exclusion rules, and frontmatter fields can all be changed in settings, so static blogs that write posts in Markdown, such as Hexo, Hugo, and Astro, can all work with it.
Is it safe to put a PAT in the browser?
The token is encrypted before being persisted to disk, and after unlocking it exists only in memory. The app loads no third-party scripts, and the only external request is to api.github.com. Device fingerprinting is not a security boundary; on public computers, it's recommended to set a password and enable two-factor authentication.
Can I write posts on my phone?
Yes. The file tree is tucked into a drawer, the preview is below the body, the save button is fixed at the bottom, and you can install it on your phone's home screen.
Will it damage the repository?
Saves and deletes both include sha validation; if the remote has changed, a dialog first lets you choose, so it won't silently overwrite. For frontmatter, only modified fields are written back, and CRLF/LF, BOM, and trailing newlines are preserved.
Related Links
- Live site: sakura.ksable.top
- Project repository: God-2077/astro-blog-studio
- Old post: Using Decap CMS as a Hexo Backend for Online Editing (Step-by-Step Tutorial)
The End
When I was writing this article, this project had just turned one day old.
If you also use a static blog and have been bothered by "updating posts is a hassle," I hope this gives you some reference.
If you have questions, feel free to comment below or open an issue on GitHub.
If you enjoyed this, leave a comment~