Here is a summary of the updates introduced in SvelteKit Blog Engine v1.0.0.10.

As multilingual publishing grew, managing mixed-language articles in a single chronological list became increasingly tedious. In this update, we focused on implementing dynamic language filter tabs in the admin post management dashboard, refining the Blog Hub federation protocol, adding editor safeguards against formatting loss, and simplifying multi-account deployment commands.

1. Dynamic Multilingual Filter Tabs in Post Management

Previously, all posts were listed strictly in chronological order regardless of their language. Managing dozens of articles across Korean, English, and Japanese required unnecessary scrolling and searching.

Key Improvements

• Dynamic Language Detection & Live Count Badges: Instead of hardcoding language codes, the system queries active database languages and post entries in real time. Each tab displays live post counts (e.g., [All (24)], [Korean (10)], [English (8)], [Japanese (6)]).
• Smart Empty States: Clicking a language tab with zero posts (e.g., English (0)) shows a helpful prompt along with a direct [+ Write New Post in this language] button to streamline the authoring workflow.
• Single-Language Mode Support: For blogs operating in only one language, the tab bar remains hidden to keep the interface clean and minimal.
• Language Chips & Safe Pagination: Table rows now display crisp language badges (KR, EN, JA, etc.) next to titles, and switching tabs automatically resets the view to Page 1 to avoid blank pagination bugs.

2. Refined Blog Hub (hub.sveltekitblog.com) Integration

We polished several edge cases when syncing articles to the centralized feed platform, SvelteKit Blog Hub.

Improvements

• 1,500-Character Standard HTML Intro Extraction: Automatically parses and extracts clean 1,000–1,500 character HTML introductory excerpts from both Markdown and Visual HTML formats for feed summary cards.
• Absolute Image URL Conversion: Transforms relative image paths (/images/posts/...) into absolute URLs containing the canonical domain (https://yourdomain.com/images/...) so that thumbnails and in-article images render properly on external feeds.
• Publish Date Timeline Preservation: When updating an existing article, the original published_at timestamp is preserved instead of being overwritten by the edit date, keeping the Hub timeline chronological.
• Default Auto-Publish Setting: Added a toggle under Admin Settings (⚙️ Settings) to enable "Auto-Submit to Hub" by default for new posts.

3. Post Editor Data Loss Protection Guards

We added protective measures in the post editor to prevent accidental loss of content or formatting when switching modes.

• HTML to Visual Mode Warning: Switching from raw HTML to the Visual editor can cause non-standard tags, custom tables, or inline styles to be sanitized by the editor parser. A confirmation dialog now alerts you before the switch occurs.
• Editor Format Lock: Existing saved posts have their editor type (HTML vs. Markdown) locked to prevent accidental corruption, with warning prompts if changes are attempted.

4. Simplified Multi-Account Deployment CLI

The deploy-multi script arguments have been streamlined for faster and more intuitive operations:

# Previous format
npm run deploy:multi -- myaccount --admin-only

# New streamlined format
npm run deploy:multi -- myaccount admin   # Fast admin-only deploy
npm run deploy:multi -- myaccount blog    # Fast blog-only deploy
npm run deploy:multi -- myaccount         # Deploy both blog and admin

(Legacy flags like --admin-only and --blog-only remain 100% backward compatible.)

How to Apply the Update

Pull the latest repository commits and run your deployment command:

# Pull latest code
git pull origin main

# Deploy admin (example)
npm run deploy:admin
# Or for multi-account deployment
npm run deploy:multi -- <account_name> admin

We will continue to refine and enhance the engine based on real-world usage. Thank you!

When operating a standalone personal blog, the biggest challenge is "How can I introduce my articles to new readers?" Unlike commercial blogging platforms, a self-hosted blog gives you complete freedom over your data and design, but attracting initial traffic and achieving search engine visibility requires considerable time and effort.

SvelteKit Blog Hub (hub.sveltekitblog.com) is a decentralized federated feed platform designed to overcome the discoverability limitations of independent blogs, allowing creators to share readership, statistics, and mutual growth.

This guide provides a detailed walkthrough of everything you need to know—from obtaining an API Key and configuring the admin settings to managing the post lifecycle and leveraging Google AdSense synergies.

1. 🎯 Key Features and Working Principles

1. Complete Data Independence & Ownership:
   • The full article text and all database entries remain securely within your own Cloudflare D1 instance.
   • Only a standard HTML introduction (1,000–1,500 characters) and essential metadata (title, thumbnail, slug, etc.) are transmitted to the hub for feed card rendering.
2. Automatic Absolute URL Conversion for Images:
   • Relative image paths (/images/...) embedded in Markdown or HTML are automatically transformed into absolute URLs (https://yourdomain.com/...), ensuring crystal-clear previews on the hub feed without broken links.
3. Non-blocking & Fault-Tolerant Isolation:
   • Even if the hub server experiences network latency or temporary downtime, your blog's internal post-saving transaction is guaranteed to complete normally without any interruption.

2. 🔑 Step 1: Obtain a Hub API Key & Configure Settings

① Obtain an API Key from the Hub Platform

1. Visit SvelteKit Blog Hub 'Connect Blog (Get API Key)'.
   
2. Register your blog's canonical URL (e.g., https://myblog.com) and copy the uniquely generated Site API Key (sk_board_... or sk_hub_...).

② Configure Blog Admin Settings (⚙️ Settings)

1. Log in to your blog's admin dashboard and navigate to [Settings].
2. Locate the SvelteKitBlog Hub Syndication Settings section.
   

[ SvelteKit Blog Hub Integration Settings ]
* Hub Platform URL : https://hub.sveltekitblog.com (Fixed)
* Hub Issued API Key : sk_hub_live_... (Enter your issued key)
* 🌐 Enable Auto-Publish to Hub by Default : [ON / OFF Toggle]

3. Enabling Auto-Syndication by Default will pre-check the syndication option whenever you create a new post.
4. Click [Save Settings] at the bottom to apply the configuration.

3. ✍️ Step 2: Auto-Publishing from the Post Editor

At the bottom of the metadata sidebar in the post editor (New Post or Edit Post), you will find the Hub Auto-Submission checkbox.

[☑️] 🌐 Automatically submit to SvelteKit Blog Hub (hub.sveltekitblog.com)
     When checked, a summary card is automatically submitted to the Hub feed upon publishing.
     When unchecked, it is set to "Hidden" on the Hub to safely preserve like statistics;
     to delete completely from the Hub, you must delete the post on your blog.

• Publishing Public Posts (Status: Published):
  • When saved with the checkbox active, the HTML intro and thumbnail are dispatched to the hub simultaneously with the D1 database write, appearing instantly on the hub feed.
• Saving Drafts (Status: Draft):
  • Posts saved as drafts will never be exposed on the public hub feed, even if the checkbox is checked.

4. 🔄 Step 3: Lifecycle Management (Edit, URL Change, Hide, Delete)

As you maintain your blog, you may update article content, reclassify categories, or hide/delete posts. The blog engine automatically detects these lifecycle events and syncs with the hub flawlessly.

5. 💰 Google AdSense Readiness & Synergies

Traffic driven from the hub significantly accelerates Google AdSense approval and ad revenue generation.

1. Securing Initial Active Traffic:
   • Google crawlers index and rate websites with active, genuine reader traffic much faster than dormant sites with zero visitors.
2. Automated ads.txt Serving:
   • Entering your AdSense authorization snippet (google.com, pub-..., DIRECT, f08c47fec0942fa0) in the admin settings serves it immediately at https://yourdomain.com/ads.txt.
3. Content Quality Guidelines:
   • For primary AdSense approval, we recommend consistently publishing 15–20 high-quality technical or informative articles (1,500+ characters each) syndicated to the hub.

6. 🏁 Conclusion

By integrating with SvelteKitBlog Hub, you maintain 100% data sovereignty over your standalone blog while unlocking the powerful network synergy of a unified community feed!

When a new engine release arrives in the GitHub repository and you update your codebase, one natural question arises:

"Will this new core release and database migration apply smoothly to my live production blog without breaking anything?"

In SvelteKit Blog Engine, all your custom design settings (layouts, colors, fonts) and published posts are safely preserved in the D1 database, meaning updating the engine codebase will never wipe out your customized blog UI.

However, you may still want to verify that new backend features, D1 schema migrations, and deployment scripts run properly in your Cloudflare environment. The safest approach is to deploy to a free auxiliary Cloudflare account (or staging test instance) first, verify everything visually, and then deploy to your main production account with confidence.

Standard Cloudflare tools (Wrangler) traditionally required tedious browser re-logins, manual ID swapping in config files, and often suffered from local cache collisions. This guide outlines the one-click multi-account deployment pipeline that makes staged release verification seamless and risk-free.

🔄 1. Safe Release Deployment Workflow

With the multi-account deployment runner, you can establish a robust release cycle:

🔑 2. Prerequisites: Cloudflare API Tokens (Once per Account)

To deploy in the background without browser popups, create a dedicated API Token for each Cloudflare account once.

2-1. Creating a Least-Privilege API Token

1. Log in to the Cloudflare Dashboard ➔ Top-Right [My Profile] ➔ [API Tokens].
2. Click [Create Token] and select [Use template] next to Edit Cloudflare Pages.
3. Under Permissions, click + Add more to append the following two permissions:
   • Account - D1 - Edit (For automatic D1 database schema migrations)
   • Account - Workers KV Storage - Edit (For image storage bucket bindings)

💡 Security Tip: Instead of a Global API Key, issuing a token with only Pages, D1, and KV permissions (Principle of Least Privilege) is much safer.

4. Select your target account under Account Resources, then click [Continue to summary] ➔ [Create Token].
5. Copy the generated API Token string.

2-2. Locating Your 32-Character Account ID

From the browser address bar while inside your dashboard:

https://dash.cloudflare.com/1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d/workers-and-pages
                             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                             (This 32-character string is your Account ID)

📦 3. Instant Account Registration via Backup (deploy:sync)

Instead of manually copying D1 UUIDs and KV IDs from the dashboard, you can register accounts instantly using the built-in backup download feature in Admin.

1. In the target blog's Admin Dashboard ➔ [Settings] ➔ [Data Management], click [Download Deployment Config].
2. Rename the downloaded file to your desired account identifier and place it in the project root:
   • Example (Test account): wrangler.backup.test.json
   • Example (Main account): wrangler.backup.main.json
3. Run the sync command in your terminal:

npm run deploy:sync

======================================================
✅ [.deploy-accounts.json] Account Sync Completed!
======================================================
📋 [Registered Accounts]
  - main (Main Blog Account): 🟢 Ready
  - test (Test Blog Account): 🟡 token/accountId required

4. Open .deploy-accounts.json and fill in your token and accountId:

{
  "test": {
    "name": "Test Staging Account",
    "token": "YOUR_ACTUAL_API_TOKEN",
    "accountId": "YOUR_32_CHAR_ACCOUNT_ID",
    "blogProject": "test-blog-web",
    "adminProject": "test-blog-admin",
    "d1": {
      "BLOG_DB": { "name": "test-blog-db", "id": "11111111-2222-3333-4444-555555555555" },
      "USER_DB": { "name": "test-user-db", "id": "66666666-7777-8888-9999-000000000000" }
    },
    "kv": {
      "IMAGES_KV": "aaaaaaaaaabbbbbbbbbbccccccccccdd"
    }
  }
}

Safe Merge: deploy:sync safely preserves existing tokens and account IDs without overwriting them.

🚀 4. Real-World Release Deployment Scenarios

Scenario A. Test Staging Verification First (Recommended)

Deploy the new core code to your test account first to verify Blog (Web) and Admin operations:

npm run deploy:multi -- test

Scenario B. Safe Production Deployment

Once verified on staging, deploy to your main live blog:

npm run deploy:multi -- main

Scenario C. Batch Upgrade Across Multiple Blogs

If you operate multiple sub-blogs alongside your main blog, upgrade all registered instances at once:

npm run deploy:multi -- --all

Scenario D. Selective Deployment (Blog Web or Admin Only)

# Deploy only Blog frontend
npm run deploy:multi -- test --blog-only

# Deploy only Admin dashboard
npm run deploy:multi -- test --admin-only

🛡️ 5. 3-Stage Sandbox Isolation Architecture

1. Session Sandbox: Isolates APPDATA to an ephemeral sandbox folder, preserving your host machine's global login session.
2. Atomic Config Swap: Swaps in target wrangler.json bindings only during active deployment and restores originals in the finally block 100% reliably.
3. Automated Cache Purging: Purges local .wrangler caches immediately after execution, allowing seamless switching between native single-account commands (deploy:blog, deploy:admin) and multi-account runs.

📋 6. Command Reference

💡 7. Conclusion

With your custom design settings and post contents safely isolated in D1, having an automated staging-to-production deployment pipeline turns release upgrades into a worry-free, dependable experience.

Following the v1.0.0.8 release, v1.0.0.9 introduces Multi-Account One-Click Cloudflare Pages Smart Deployment, SvelteKit Blog Hub BLOG FEED Integration, Full SEO/Sitemap Optimization with Unified RSS/Sitemap Visual Styling for Google AdSense Approval, and i18n Multi-Language Dictionary Polish & Deployment Sync.

1. 🌐 Multi-Account Smart Auto-Sync & One-Click Cloudflare Pages Deployment

• Auto-Sync via wrangler.backup.json (npm run deploy:sync):
  • Simply placing downloaded backup files (wrangler.backup*.json) from admin into the project root and running sync automatically extracts D1 IDs, KV IDs, and project names into .deploy-accounts.json.
  • Existing user-defined API tokens and account IDs are 100% safely preserved (merged) without loss.
• One-Click Multi-Account Deployment Runner (npm run deploy:multi):
  • Automatically deploys Blog + Admin (2 CFPs per account) in sequence using npm run deploy:multi -- <accountKey>.
  • Supports --blog-only, --admin-only selective flags and full batch deployment across all registered accounts (--all).
• Complete Sandbox Isolation & Automated Cache Purging:
  • Protects host global Wrangler configs via isolated APPDATA: .wrangler-multi-temp.
  • Performs atomic in-memory wrangler.json swapping during deployment and restores original configs in finally.
  • Automatically purges local .wrangler and node_modules/.cache/wrangler caches immediately after deployment, guaranteeing zero contamination of native single-account deployments (npm run deploy:admin, npm run deploy:blog).
• Automated D1 Schema Migration (sync-secrets.js):
  • Automatically runs safe schema migrations (such as adding the is_syndicated column) during deployment pipelines.

2. 📡 SvelteKit Blog Hub Feed & Real-Time Post Integration

• Real-Time Hub Client Module (hub.ts, syndication.ts):
  • Establishes a real-time post transmission pipeline delivering published article metadata to SvelteKit Blog Hub BLOG FEED.
• Admin Editor Hub Integration Toggle (PostMetadataForm.svelte):
  • Added an intuitive UI toggle for hub feed delivery (is_syndicated) when creating or editing posts.
• Database Schema Expansion (schema-blog-db.sql):
  • Formally added is_syndicated INTEGER DEFAULT 0 column to the posts table.

3. 🔍 Google AdSense "Low Value Content" Resolution & SEO Optimization

• Pure Post-Centric Search Indexing:
  • Applied noindex, follow to category archive pages (/[category]), tag archive pages (/tags/[tag]), and guestbook (/guestbook) to eliminate thin content penalties while retaining full link traversal.
  • High-value article posts and essential legal/about CMS pages (about, privacy, contact) remain 100% indexed (index, follow) and are submitted via sitemap.xml with priority 0.9.
• Sitemap & RSS Query Sanitization with Unified Visual Styling (sitemap.xsl):
  • Sanitized DB queries for sitemap.xml and rss.xml to exclude CMS pages and category slugs, ensuring 100% pure published article posts are submitted.
  • Optimized published CMS page priority to 0.9 with complete multilingual alternate hreflang support.
  • Introduced static/sitemap.xsl designed to 100% match the visual aesthetic of rss.xsl, unifying browser rendering into clean, responsive English table layouts.
  • Adjusted sitemap.xml cache policy to public, max-age=3600 for guaranteed 1-hour freshness.

4. 🌐 i18n Multi-Language Dictionary Polish & Deployment Sync

• Translation Accuracy & Quality Polish:
  • Refined multilingual dictionary translations to improve UI consistency and correct translation inaccuracies (e.g., Japanese locale fixes).
• Interactive i18n DB Sync during Admin Deployment (deploy:admin):
  • Added an interactive prompt to easily synchronize local i18n dictionary updates to the D1 database (ui_dictionary) during admin deployment.
• Admin UI Localization:
  • Localized remaining hardcoded UI elements in Hub-related dialogs and settings.

• Unified Category Widget: Completely removed the legacy category_link option to eliminate confusion and unified all category displays under a single Category Menu widget.
• Post Count Display Option (showPostCount): Added a toggle checkbox in the admin design editor to show/hide post counts next to category names (e.g., Development (5)).
• Admin Design Live Preview Fix: Enhanced widget previews in the design editor so that Recent Posts, Popular Posts, and Category Menus render realistic placeholders accurately.
• Smart hreflang Filtering (SEO): Generates hreflang alternate tags only for languages that contain published posts, effectively preventing search engines (e.g., Google AdSense / Search Console) from indexing empty fallback pages as thin content.

🚀 Release v1.0.0.7

• Official Engine Version System (APP_VERSION): Introduced the APP_VERSION constant in @sveltekitblog/shared and displayed active engine version badges in the admin sidebar and blog footer.
• Full Multilingual Route Metadata: Completed hreflang alternates and canonical URL injection across all frontend routes (Home, Category, Tag, Search, Guestbook).
• Footer Mobile Readability Polish: Optimized version badge contrast and layout padding on mobile viewport widths.

🚀 Release v1.0.0.6

• Mobile Core Web Vitals & Performance: Improved mobile loading performance through dynamic OG image generation, Google Fonts API caching, and asset preloading.
• Sitemap 500 Fix: Removed non-existent legacy tag table queries from the sitemap.xml generator to guarantee uninterrupted sitemap indexing.
• Dynamic HTML lang Attribute: Ensured the root <html> tag dynamically reflects the correct lang attribute (ko, en, ja) based on route context.
• i18n Key Architecture: Standardized language badge translation keys under the common.lang.short_* namespace.

🚀 Release v1.0.0.5

• Svelte 5 Runes Warning Fix: Resolved reactive state compiler warnings in admin components.
• Default Admin Entry Route Refactor: Streamlined the admin dashboard entry point and feedback flow.
• Canonical URL Normalization: Fixed trailing slash discrepancies and multilingual canonical URL mismatches.

🚀 Release v1.0.0.4

• Naver Webmaster Advisor H1 Fix: Resolved duplicate <h1> tag detection by search engine bots by implementing Mobile-First SSR layout switching in LayoutRenderer.
• Footer Layout Alignment: Aligned blog footer width and border styles with the header for consistent shadow rendering.
• Repository Cleanup: Removed tracked temporary .bak files from git tracking.

After building a website or blog, the next big question is: "How do I deploy this to the internet so people can visit?"

In the past, you typically had to pay a monthly fee for a Virtual Private Server (VPS), configure an Nginx web server, and manually manage SSL certificates. Today, Cloudflare Pages (CFP) allows you to deploy web applications effortlessly with zero server management, blazing-fast global speeds, and a generous free tier.

This guide explains what Cloudflare Pages is, compares two deployment authentication methods (Interactive Browser Login vs. API Token), and introduces the core concepts of D1 Database and Workers KV Storage from an architectural perspective.

📂 1. What is Cloudflare Pages (CFP)?

In simple terms, Cloudflare Pages is a platform that hosts your website across hundreds of Cloudflare data centers worldwide, serving pages to visitors from the closest server at lightning speed.

It supports not only static assets (HTML/CSS/Images) but also full-stack frameworks like SvelteKit and Next.js that perform real-time Server-Side Rendering (SSR) and API routing.

Why Choose Cloudflare Pages Over Traditional VPS?

• Zero Server Maintenance: No need to worry about OS security patches, Nginx config tuning, or monitoring server health. Cloudflare manages the infrastructure 24/7.
• Global Edge Performance: User requests are served from the geographically closest data center, dramatically reducing latency.
• Cost-Effective: Standard personal blogs and portfolios run comfortably within the generous Free Tier.

🔑 2. Two Methods to Deploy to Cloudflare from Your Machine

When running a SvelteKit build (npm run build), @sveltejs/adapter-cloudflare outputs static assets and a server execution worker (_worker.js) into the .svelte-kit/cloudflare directory.

The standard command to deploy this build output is npx wrangler pages deploy .svelte-kit/cloudflare, and there are two primary authentication workflows:

[Method 1] Interactive Browser Login Workflow (Wrangler Default)

The most intuitive method for beginners with a single account. Running the command opens a web browser to grant permissions.

# Build SvelteKit and deploy to Pages (interactive browser login)
npm run build
npx wrangler pages deploy .svelte-kit/cloudflare --project-name=my-blog-web --branch=production

• How it works: When you run the deploy command, Wrangler automatically opens your default browser and prompts you to log in to Cloudflare. Once you click [Allow], the authentication session is saved to your local machine (~/.config/.wrangler), and deployment proceeds.
• Advantages: No need to generate API tokens manually; it works seamlessly in a few clicks for single-account personal projects.
• Limitations:
  • Switching between multiple Cloudflare accounts requires logging out and in via the browser each time.
  • Cannot be used in headless environments or CI/CD pipelines (e.g., GitHub Actions).

[Method 2] Non-Interactive API Token Deployment (Standard for CI/CD & Multi-Account)

The industry standard for multi-account management and automated pipelines. You supply pre-generated tokens via environment variables without browser popups.

# Deploy with environment variables (PowerShell example)
$env:CLOUDFLARE_API_TOKEN="YOUR_CLOUDFLARE_API_TOKEN"
$env:CLOUDFLARE_ACCOUNT_ID="YOUR_ACCOUNT_ID_32_CHARS"
npx wrangler pages deploy .svelte-kit/cloudflare --project-name=my-blog-web --branch=production

• How it works: You generate an API token with required permissions (Pages, D1, KV) in the Cloudflare dashboard. Supplying this token as an environment variable allows Wrangler to authenticate in the background without opening a browser.
• Advantages:
  • Runs quietly in the background without popups.
  • Allows sandboxed, multi-account deployments without session conflicts.
• Prerequisite: Requires creating an API token in the Cloudflare dashboard once beforehand.

💾 3. Where Are Posts and Images Stored? (Understanding D1 and KV)

A dynamic blog requires more than just frontend UI; it needs reliable storage for articles, metadata, and media. Cloudflare provides two dedicated serverless storage solutions:

1. Cloudflare D1 (Relational SQLite Database):
   • A distributed SQL database structured into clean rows and columns.
   • Stores structured data such as post titles, markdown/HTML content, published dates, categories, tags, and site settings with full SQL query capabilities.
2. Workers KV (Ultra-Fast Key-Value Storage):
   • A globally distributed key-value store optimized for high-read workloads.
   • Serves uploaded thumbnails and images across global edge locations with sub-millisecond response times.

🧩 4. Architecture Showcase: SvelteKit Blog Engine

SvelteKit Blog Engine leverages Cloudflare's serverless infrastructure with an intelligent two-tier architecture:

Why Separate Blog and Admin into Two Independent Pages?

Instead of bundling the entire application into a single monolithic app, SvelteKit Blog Engine decouples it into two standalone Cloudflare Pages projects:

1. Minimized Attack Surface: Admin login logic, markdown/rich-text editors, and management API endpoints are completely absent from the public blog bundle. Running on a separate subdomain ensures strong isolation.
2. Maximum Frontend Performance: The public blog bundle is extremely lightweight, containing zero admin or editor scripts. This results in blazing-fast First Contentful Paint (FCP) on mobile and desktop devices alike.

Data Flow

• When you write an article and upload images in the Admin Dashboard, the data is committed to the shared D1 Database and Workers KV.
• When a reader accesses the Public Blog, it retrieves the latest post data and images from the same D1 and KV instances to render the page instantly.

🚀 5. Conclusion

Cloudflare Pages empowers developers to run high-performance, full-stack web applications without the burden of server maintenance or costly hosting plans.

For single-site projects, starting with Interactive Browser Login (wrangler login) is fast and straightforward. As your infrastructure grows or requires multi-account automation, transitioning to API Token Deployment provides a scalable, conflict-free workflow.

This release includes several enhancements to improve the usability and functionality of the admin post editor.

🚀 Key Changes

1. Added Image Link Insertion and Editing in Post Body

   • Expanded the modal UI to allow linking custom URLs and configuring "Open in new tab" settings when inserting or editing images in the editor.
   • Integrated HTML pre/post-processing to prevent Tiptap editor from forcibly removing image link attributes upon loading.

2. Visualized Semantic Image Captions in Preview Mode

   • Synchronized body text processing utilities so that semantic image captions (<figcaption>) are rendered correctly in the post preview tab.

3. Integrated Real-time Character Counter with Multilingual Support

   • Added a real-time character counter UI at the bottom of the post editor/edit screen.
   • Automatically strips HTML tags and Markdown syntax to count raw text characters accurately with full multilingual support.

v1.0.0.3 Update Details

This release completely resolves structural flaws in the widget system and unifies the UI list styles for widgets.

🐛 Bug Fixes

1. Fixed Rendering Crash When Placing Newly Created Widgets

   • Fixed a critical crash where placing a newly created widget directly onto a layout caused rendering failure due to a missing master- prefix upon saving.

2. Fixed Data Loss of Widget config Across Desktop/Mobile Layouts

   • Fixed a bug where widget configuration settings (config) were completely omitted during layout placement, causing placed widgets to save as empty states.

3. Fixed config Reset Bug Upon Opening Widget Edit Modal

   • Fixed a bug where opening the edit modal for a placed widget triggered a SyntaxError by executing duplicate JSON.parse calls on an already parsed config object, resetting all modal settings (limit, shadow, etc.) to defaults.

4. Strengthened Input Validation for Invalid limit Values

   • Blocked vulnerability where invalid limit values (NaN, less than 1) could be saved during widget creation/editing, normalizing invalid inputs to the default value of 5.

5. Fixed Data Query Scope Error with Multiple Widgets of the Same Type

   • Fixed a structural bug where multiple widgets of the same type (e.g., Popular Posts) queried the database using only the first widget's limit, truncating data for the remaining widgets. Database queries now fetch up to the maximum limit among identical widgets, allowing each widget to render its data independently according to its own settings.

🎨 Styling

1. Unified List Divider Styles for Widgets
   • Resolved visual inconsistencies where RecentPostsWidget and PopularPostsWidget used different item divider styles. Both widgets are now unified with a border-bottom divider and 0.5rem padding.

🎨 Minor Layout & Design Adjustments

Refined overall style elements including blog layout and colors so that screen components blend naturally without breaking.

🛠️ Key Style Adjustments

1. Adjusted Theme Colors and Tones

   • Set an orange secondary color as an accent point while refining background colors, card borders, and shadow values to reduce visual fatigue.

2. Optimized Desktop 2-Column Layout Alignment

   • Re-adjusted the width ratio between the main content area and sidebar (categories, recent/popular posts, etc.) to ensure left/right margins and content alignment match smoothly.

3. Aligned Header/Footer & Mobile Menu Elements

   • Cleaned up top header transparency settings alongside mobile menu icon alignment and footer layout elements for a crisp presentation.

1.
To be honest, YouTube is largely to blame for how things turned out(?).
When I decided to try my hand as a solo developer later in life, I was flooded with an overwhelming amount of information.
The problem is that while the quantity of information is overflowing, the quality is often terrible.

2.
If it's just basic introductory stuff, a high volume of info isn't really a problem. But the moment things get slightly specialized or require a specific niche, I encounter completely useless information that leaves me wondering why it even popped up in my search results. Or worse, the title perfectly matches what I want, but the actual content is just a meaningless sequence of text generated to form valid sentences.
When this happens on a YouTube video, it genuinely makes me furious.

3.
Then, like finding an oasis in the desert, the rare pieces of truly valuable information almost always came from developer blog posts.
I felt so relieved, grateful, and inspired. And then, my focus—which makes me suspect I might have adult ADHD—led me to a sudden decision: "Hey, maybe I should build a dev blog too, help someone out, and maybe earn enough for a cup of coffee(?)."

4.
So I started evaluating existing blogging platforms, but every single one of them had a dealbreaker for me.
First, I ruled out anything that required hosting or maintenance costs.
Sure, earning a little coffee money would be nice, but I know that to actually pull that off, you have to work ridiculously hard. And I know myself—I'm just not that hard-working.
So right from the start, my absolute baseline rule was: Zero setup or recurring maintenance costs.
My initial plan was to host WordPress on a local Proxmox server.
To run that safely, I figured minimum security measures like an L2 switch and a firewall like pfSense were essential.
After setting all that up and looking at WordPress again, I realized customization was way too hard. When I realized I'd have to properly study PHP just to customize it, I abandoned that approach.

5.
I quickly looked for alternative solutions, but every option had its own catch.
No matter what solution I picked, having to study something completely new just to set it up felt mentally exhausting.
That mental fatigue eventually led me to a reckless thought: "Screw it, I'll just build a simple one myself."

6.
At the time, I was already messing around quite a bit with Svelte and SvelteKit.
Building a basic blog was easy enough. The real issue was that I couldn't trust my own design skills.
So I decided to architect it in a way that made swapping designs effortless—and that rabbit hole kept rolling until it became what it is today.

7.
In reality, I spent the vast majority of my time polishing the design editor and debugging.
Initially, I set out to build a "simple blogging tool" and finished about 90% of the code in just one day.
Then I actually built a blog with it and started running it.
That’s when the feature creep hit: "Oh, I need this too," "I should add this feature," "It'd be nice to have this," "This is a must-have." It felt like an endless flood of ideas.
What started as a mini-project in late November last year finally wrapped up feature implementation in March this year, and only in July did I finally open-source it on GitHub.

8.
Before I knew it, the codebase had grown way too large and complex, forcing me to modularize and refactor along the way.
I even overhauled the system architecture multiple times.
Initially, the admin panel was hosted on a Proxmox server accessible only locally, while the DB and auth relied on Supabase.
However, after experiencing terrible cold starts and seeing the project name exposed during auth on Supabase's free plan, I pivoted to going all-in on the Cloudflare ecosystem and integrated Better-auth, which I had used before.
After that, I continued making major changes to the internal logic and architecture.
On top of that, working in a Windows environment meant that every single code tweak required a full deployment to verify, leading to an astronomical amount of trial and error.

9.
Near the finish line, the codebase became so massive that I couldn't handle modifications alone anymore, so while I wrote a lot of it, I relied heavily on Gemini for the rest.
Since I hadn't documented anything, I had to compare the actual running features one by one to write the docs—and whenever I spotted a bug, I went right back into fixing code.
From March to July, it was an endless loop of: Documentation ➔ Bug Discovery ➔ Bug Fixing.
Meanwhile, thoughts like "Wait, I need this feature too!" and "Hold on, where did that feature I built go?" kept popping up, driving me absolutely insane.

10.
To make matters worse, Gemini frequently lost its mind.
Instead of fixing a single line of code, it would tear down completely unrelated modules and rewrite them. I'm convinced that if Gemini hadn't thrown so many tantrums, I would have finished at least two months earlier.
Anyway, right up to the GitHub release, I was under extreme stress until I finally decided to cut out all the "I should add this" features and just ship whatever was already working and cleaned up.
That became v1.0.0.0.

11.
And right after that, v1.0.0.1 was released.
I thought I only shipped the "cleaned up working parts," but I immediately noticed things that hadn't been cleaned up properly.
I'm fairly certain there are more hidden issues like this, which makes me a bit anxious. I guess I had a hunch even before uploading, which is why I prepared the v1.0.0.x versioning ahead of time.

12.
And that is how the SvelteKit Blog Engine came to be!
Ending a post is always awkward, so I'll wrap up by sharing my PageSpeed Insights score.
AdSense is currently pending approval, but the code script is already embedded. Also, CDN caching is set to a 2-minute TTL, so if a test runs while the cache is purged and regenerating, it might impact performance—though I'm not 100% sure of the exact cause, the scores fluctuate quite a bit.
Please treat these scores as a rough reference from an average run.
Once AdSense gets approved, I'll post an updated PageSpeed Insights report.
Have a great day! :)

This guide explains the easiest and safest way to build the Cloudflare edge infrastructure and deploy/sync both the admin and blog apps simultaneously by running a single automation command (npm run setup) in a terminal (CMD or PowerShell) environment.

🛠️ 1. Introduction to One-Click Deployment Automation

The SvelteKit blog engine has fully automated the complex process of server resource creation and configuration file editing through an interactive setup tool in the terminal.

After unpacking the blog source code or downloading it to your computer via git clone, open the terminal, navigate to the project root folder, and run the following commands in sequence:

# Install required packages
npm install

• Dependency Library Installation: Enter npm install in the terminal to install all required packages. If a security warning (vulnerabilities) message appears in the terminal after installation is complete, it is recommended to enter the npm audit fix command to safely apply the latest security patches.

Once the package installation is complete and you run npm run setup, the following processes will be handled automatically according to the terminal prompts:

• Easy Cloudflare Account Authentication: Link your deployment account with a single click.
• Create DB and Storage Resources: Automatically create 2 D1 databases dedicated to the blog and a KV store for storing images.
• Real-time Configuration File Update: Detect the unique IDs of the created databases and automatically inject them into the monorepo configuration files (wrangler.json).
• Database Seed Data Injection: Create tables and automatically register sample posts and basic configuration information according to the selected default language.
• Upload Secrets and Allowed IP: Automatically transmit the deployer's current public IP address (ALLOWED_IP) and password environment variables to the cloud for admin access.
• Integrated Build & Web Service Deployment: Bundle both the blog and admin SvelteKit projects and immediately deploy them to Cloudflare Pages.

📋 2. Pre-deployment Checklist

Please make sure all of the following are prepared before starting the safe installation:

1. Install Node.js: Node.js (version 22 or higher) must be working on your computer.
2. Cloudflare Account: A Cloudflare account (the free tier is sufficient) is required to host the blog site and databases.
3. Create Secret Environment Variable Files (.dev.vars) (Required):
   • Before starting deployment, you must manually create a .dev.vars file in each of the apps/admin/ and apps/blog/ folders.
   • In the apps/admin/.dev.vars file, write ADMIN_PASSWORD=YourAdminLoginPassword.
   • In the apps/blog/.dev.vars file, write BETTER_AUTH_SECRET=ArbitraryStringOfYourChoice.

   • [!WARNING]
     If these environment variables are not set, the installation tool will stop immediately for correct operation upon running npm run setup.

⚙️ 3. Step-by-Step Guide for npm run setup

Open the terminal, type npm run setup in the blog project root directory, and press Enter.

Step 0. Secrets Pre-Validation

• Immediately upon execution, it checks if the .dev.vars files and the required secret variables (ADMIN_PASSWORD, BETTER_AUTH_SECRET) are entered in the admin and blog folders.
• If any value is missing, the guide log is displayed and the script exits, so please make sure to fill them in advance.

Step 1. Configure Deployment Project Name (Domain URL)

• This step defines the URL that readers will use to access your blog (e.g., [entered-project-name].pages.dev).
• It takes two names: one for the blog and one for the admin app. If running in restore mode (--restore), it automatically reads the existing names from the backup configuration file (wrangler.backup.json).

Step 2. Cloudflare Account Authentication

• Verifies Cloudflare authentication. If you have logged in previously, it automatically detects the session and skips this step.
• If you are not logged in, a browser window will open showing the authentication request screen. Click [Allow] to approve the account integration.
• Security Information: This automation tool only requests the minimum account API permissions required for infrastructure creation and deployment, so you can proceed with confidence.

Step 3. Resource Creation & Configuration Binding

• This step creates the database and media storage in the cloud for the actual service to run. Look at the prompts in the terminal and enter the appropriate number.
  1. 1 (Fresh Install): Completely deletes previously created databases and storage and recreates them. Please note that all existing data will be lost.
  2. 2 (Keep Existing Data) [Recommended]: If resources already exist, it safely preserves the data and only links the connection information.
• Upon completion, the newly issued unique DB and KV IDs are automatically updated in each configuration file (wrangler.json) of the monorepo.

Step 4. Pre-create Web Projects

• To improve deployment reliability, it pre-registers and reserves empty web projects on Cloudflare Edge.
• If a domain with the same name is already occupied, it reuses the existing domain and automatically transitions to the next step safely.

Step 5. Remote Sync of Secrets

• Safely uploads and synchronizes the secret values, such as the master password written locally in .dev.vars, to Cloudflare.
• Automatic Access IP Registration: Especially in this step, it detects the public IP address of the administrator's computer running the deployment in real-time and automatically injects it as the ALLOWED_IP variable. This prevents the administrator from being blocked upon accessing the login screen immediately after deployment.

Step 6. Database Table Configuration & Default Theme Setup

• Configure the database tables needed for the blog to function and inject default settings.
• Following the on-screen prompts, choose your primary language (Korean, English, Japanese). This sets up the translation system, sample categories, header menu structure, and a default welcome post automatically.

Step 7. Build Web Services & Final Deployment

• Performs the integrated build of all monorepo apps and automatically runs the deployment command to Cloudflare servers to complete the installation process. Once deployment is complete, the Pages URLs for both the blog and admin will be displayed.

[!TIP]

💡 Automatic Secret Settings and Immediate Connection Support

The installation process of this project seamlessly handles resource creation, web project provisioning, and secret environment variable transmission.
Upon completion, the login password and IP permission settings are perfectly configured on the remote server, so it works immediately without any additional manual configuration.

🔄 4. Blog Update & Data Restore Deployment (npm run restore)

When a new patch version or a bug-fixed release code is deployed while running your blog, this process allows you to safely transfer your existing post data and URLs without data loss while replacing the screen with the new code.

💡 4-Step Migration Procedure for New Versions

You can safely complete the upgrade without data loss by using the admin data backup and the npm run restore command.

1. [Step 1] Backup Existing Data & Deployment Settings:
   • Access the Backup menu and the backup section at the bottom of the Theme Editor menu of your active admin app, and download the post content data and theme design settings to your computer respectively.
   • Also, click the 'Download Settings Backup' button in the Backup menu to save the [wrangler.backup.json] file to your PC. (This is the most critical file for maintaining the link to your existing production database's unique ID.)
2. [Step 2] Isolated Testing of New Code:
   • In the newly downloaded version's code folder, run npm run setup and enter a temporary DB for testing and a temporary Pages deployment name for testing to deploy it separately.
   • Log in to the newly deployed test admin, and import the backup data files saved in Step 1 to verify that the data loads successfully in advance.
3. [Step 3] Restore Bindings to Existing Production Server (npm run restore):
   • Once verification is complete, copy and paste the wrangler.backup.json file saved in Step 1 into the root directory of the new version's project folder.
   • Run the npm run restore command in the terminal. The tool script will read the existing production DB and KV unique ID information written in the backup file and automatically connect them to the new code's configuration files via override.
4. [Step 4] Schema Synchronization & Override Deployment:
   • The restore script safely updates only the table structure schema of the existing production DB to the latest specifications, so actual posts or data already stored will not be corrupted or deleted and will be perfectly preserved.
   • Next, run npm run deploy:blog and npm run deploy:admin respectively. The latest upgraded blog system will be safely deployed, overwriting the system while keeping the same URLs you were using.

📦 5. Backup File Types and Functions

Refer to the table below for the roles of individual files that can be safely imported and exported from the admin backup menu.

This document guides administrators on how to safely access the admin page, maintain login sessions, and easily manage various site-wide text strings (multilingual dictionary) to control the blog system.

🔒 1. IP Security Control Policy before Admin Login

This blog engine adheres to a strict Access IP Filtering security policy to completely prevent unauthorized external access or hijacking of posting permissions. Only the administrator's public IP address detected at the time of deployment is registered in the server's allowlist (ALLOWED_IP) to permit access.

[!IMPORTANT]

🛡️ Safe-Zone Centered Operation Principle (No Use in Public Places)

Admin management of this blog must be performed only in places where physical and network security are secured, such as home or a trusted private office.
To prevent security leaks, accessing the admin page is strictly discouraged and should be avoided in public places such as PC cafes (PC bangs), libraries, or under public Wi-Fi networks, as they are exposed to high security risks.

If you encounter a 403 Forbidden block screen because your public IP address changed due to router rebooting or network conditions within your safe zone, you must manually update the allowlist according to the following procedure.

⚙️ Allowed IP List Renewal Procedure (Redeployment Required)

1. Open the terminal under the changed internet environment, and run the command to redeploy the blog service admin app once again.
2. Workflow Guide: While this is safer than forcedly editing the database internals (which is a risky operation), it is a somewhat tedious and inconvenient process because it requires the build process and file upload waiting time of several minutes each time.
3. While the deployment script is running, it detects the new public IP address of your currently connected computer and replaces the remote server's allowed IP list with the latest one.
4. Once the deployment process is finalized, reconnecting to the admin URL will re-enable the normal login screen.
5. You only need to redeploy the admin page.

🔑 2. Admin Login & Session Management

Once the login block is normal, enter the master password (ADMIN_PASSWORD) configured during setup to log in.

• Secure Session Maintenance: By utilizing dedicated secure cookies, the admin login session remains safely maintained for 30 days.
• Prohibition of Access from Public Computers and Risky Areas:
  The most secure practice is to never attempt logging in to the admin console on unverified public computers or PC cafes. If you must log in under public conditions, make sure to click the [Logout] button at the bottom left of the admin page immediately after completing work, and also enter npx wrangler logout in your terminal to completely sign out from the Cloudflare management credentials on that computer to prevent any credential leaks.

[!WARNING]

🔒 Minimize Exposure of Admin Access Address (Domain)

While the admin console is double-protected by the IP allowlist, minimizing the attack surface itself is the most robust security practice.

Therefore, we strongly recommend that you do not bind an obvious custom domain like admin.myblog.com, but instead use the randomized subdomain URL (e.g., [project-name].pages.dev) provided default by Cloudflare Pages to keep the admin entry hidden.

🌐 3. Multilingual Dictionary (i18n) Settings Guide

Fixed common UI text strings (menu labels, comment buttons, login prompts, etc.) outside of post contents can be modified instantly in English, Korean, or Japanese using the admin dictionary editor without editing a single line of source code.

You can register a new language by using the Add Language feature. However, for the newly added language to display correctly on the site, you must translate all existing dictionary keys into that language.

1. Go to the Languages menu on the left sidebar of the admin console.
2. A list of all dictionary keys and their saved translations used across the site is provided in the UI Dictionary Editor section at the bottom.
3. Enter your desired text (Korean, English, Japanese) directly into the input field for the key you wish to modify, and click the Save icon on the far right of that row.
4. Changes apply to the live site immediately upon saving. When visitors switch languages on the blog, the modified texts will be displayed seamlessly in real-time.

This document provides a brief overview of the core features in the admin console, including multi-language simultaneous publishing, device-specific layout configuration, and real-time design theme settings.

📝 1. Multi-Language Writing and Dual Editor Support

When entering the writing menu, a multi-language editor layout is provided, with multiple language tabs arranged side-by-side on a single screen.

① Batch Multi-Language Writing and Saving

• Writing Flow: Switch between the language tabs (KO, EN, JA, etc.) at the top to write titles, excerpts, slugs (URL paths), and body content for each language.
• Batch Saving: Click the [Save All Tabs Simultaneously] button at the bottom to save the content of all languages to the database at once. Languages not explicitly set to Publish will be saved as Drafts, and any empty language tabs will be skipped.

② Dual Editor Support (Visual vs. Markdown)

• Visual HTML Editor (Visual): A rich-text editor that allows direct formatting and media embedding. Image files can be easily uploaded and inserted via the toolbar button.

• Markdown Editor (Markdown): Provided for users who prefer markdown syntax. Metadata such as titles, excerpts, categories, and tags are automatically managed in the header using YAML Front Matter (---). Both markdown source and parsed HTML are stored in the database upon saving.

③ Automatic Thumbnail Selection

• If no thumbnail image is manually specified, the system automatically analyzes the content to assign a representative image:
  • 1st Priority: The first image element found in the body text.
  • 2nd Priority: If no images are present but a YouTube video link or iframe embed is found, the official high-resolution YouTube thumbnail URL of the video is used.

🧱 2. Device-Specific (Desktop/Mobile) Independent Widget Placement

The layout editor supports drag-and-drop widget arrangement for sidebars and content areas, allowing you to configure independent widget exposure based on whether visitors are on desktop or mobile devices.

⚙️ Device Exposure Options

1. Choose the column layout and width ratio in the Blog Structure tab under the Design Editor menu.
2. Assign device exposure conditions (Device) when adding or modifying widgets:
   • Desktop: Displays the widget only on wider PC screens, preventing unnecessary resource loads on mobile devices.
   • Mobile: Hides the widget on PC screens and limits visibility to mobile viewport resolutions.
3. Effect: Skipping heavy or redundant widget rendering for mobile visitors optimizes page load times and mobile scrolling performance.

🎨 3. Real-Time Design Editor and Theme Settings

Design theme changes and background configurations apply instantly via CSS variables in the visitor's browser without requiring server rebuilds or redeployments.

• 4 Background Types: Select from Solid color, Gradient, Background Image, or interactive HTML5 Canvas animations (Canvas).
• Glassmorphism Effect: When using background images, adjust opacity and blur to ensure text readability with glassmorphism overlays.
• Interactive Canvas: Renders motion artwork (snowflakes, waves, constellations) inside a sandboxed canvas.

[!TIP]
Information on background configuration options and script templates can be found in the Design Editor Settings Introduction document.

💾 4. Media Storage Support

You can switch the active cloud storage provider for uploading and serving media based on your needs.

1. Navigate to the Storage Settings area at the bottom of the Media Library menu.
2. Select your storage provider and configure the credentials:
   • Cloudflare KV: Stores assets in edge KV storage for fast global delivery.
   • Cloudflare R2: Cost-effective large object storage for managing mass images.
   • Supabase Storage: Securely uploads and stores media assets in Supabase storage buckets.
   • ImageKit.io: Connects global image CDN platforms for real-time optimization and compressed formatting.
3. Real-time Switch: Saving changes instantly shifts the active upload engine to the chosen storage provider.

[!NOTE]
Limitations of default storage (Cloudflare KV) in media explorer
Cloudflare KV does not support directory listing (read APIs) in the image explorer to minimize Workers usage and costs. Other external storages, such as Cloudflare R2, Supabase Storage, and ImageKit.io, fully support listing and previewing uploaded images.

This document introduces the system that applies theme configurations in real time without requiring server rebuilds or redeployments, and outlines the 4 background settings: Solid, Gradient, Background Image, and Custom JavaScript Canvas.

🌌 1. Real-Time Design Editor Overview

When you modify and save configuration values in the design editor, there is no need to rebuild or redeploy the blog server or CDN services. The database updates instantly, and the CSS variables and background rendering module reflect in the visitor's browser within seconds.
Before applying the design to the live blog, you can check the style changes through the preview screen inside the admin panel.

[!WARNING]

⚠️ Notice: Differences Between Admin Preview and Live Blog Design

The preview feature in the design editor does not guarantee a 100% identical environment to the live visitor page. Microscopic rendering differences (such as CSS variable evaluation or JavaScript Canvas rendering conditions) may occur between the admin preview and the actual blog.

Therefore, after changing any design configuration, we strongly recommend visiting your live blog directly and refreshing the page (F5) to verify the final rendering output.

🧱 Layout & Theme Configuration Settings

① Layout Customization

• Blog Structure: Select the base layout structure of the main page (e.g., 2-column, 3-column, etc.).
• Column Width Ratios: Fine-tune the width ratios of the main content column and sidebars (e.g., 1:2:1, 2:1:2, etc.).
• Maximum Width: Limit the maximum horizontal resolution of the entire layout container (e.g., 1200px, 1400px, etc.).
• Detailed Layout Values: Control the container side margins, card border radius, and box shadow depth effects.

② Basic Theme Colors

• Customize the Primary theme color, Secondary color, body Text color, Accent highlight color, Card Background (Card Bg), and Border colors.

③ Typography Settings

• Apply web fonts by entering font family names from the Google Fonts directory, and set the base font size.

④ Widget Arrangement Management

• Drag and drop available widgets to position them in different columns and arrange their render orders.

🧱 2. Device-Specific Independent Widget Placement

Configure widget positioning in the sidebar and content areas using drag-and-drop. You can customize layouts differently based on the visitor's screen size.

• Desktop: Displays selected widgets (e.g., tag clouds, category trees) only on wider screens. For mobile access, elements are omitted at the HTML transmission stage to maintain fast loading times.
• Mobile: Hides the widget on desktop viewports and restricts exposure exclusively to smartphone-sized mobile resolutions.

🌈 3. 4 Background Customization Options

Customize the sensory atmosphere of the blog using four supported background types:

① Solid (Solid Background)

• Choose a HEX code (e.g., #3b82f6) or HSL color code to create a clean, distraction-free screen that helps readers focus on the post content.

② Gradient (Gradient Background)

• Create linear gradients where multiple colors blend smoothly using the Gradient Builder tool.
• Adjust the gradient angle (Direction) slider and add or slide color stops to customize starting, intermediate, and ending colors.

③ Image (Background Image & Glassmorphism)

• Specify a remote image URL or use the upload button to add media assets to your library.
• Upload Optimization: Uploaded images are automatically converted to WebP format to prevent initial page load delays.
• Glassmorphism Overlay: Adjust the controls below to build a glassmorphism aesthetic that ensures text readability over background images.

④ Custom JavaScript (Custom JavaScript & Canvas Background)

• Supports custom JavaScript execution to render interactive Canvas animations on the client's browser background.
• Provides direct rendering control over the background canvas element (canvas id="bg-canvas"). Detailed security restrictions and power-saving policies are explained in [4. Custom JavaScript Integration Specifications] below.

⚡ 4. Custom JavaScript Integration Specifications

To prevent security risks and conserve mobile battery life, the following sandbox environment and battery-saving systems are applied.

🔒 Security Sandbox and CSP

The following security measures protect against malicious script injections:

1. Isolated Sandbox Structure: Canvas code runs inside an isolated iframe with limited execution privileges. Access to the parent page DOM, session cookies, or login credentials is blocked.
2. Content Security Policy (CSP): Outbound network calls and external script injections are completely blocked. Sensitive data cannot be leaked to external servers.
3. JS API Restrictions: Disallowed APIs, including fetch, XMLHttpRequest, WebSocket, eval, new Function, document.cookie, and localStorage, are intercepted and commented out (/* f_e_t_c_h (blocked) */) by the validator script (jsValidator.ts).

🔋 Power and Performance Optimization

• Out-of-View Auto-Pause: If a visitor scrolls and the background animation leaves the viewport, the render loop enters sleep mode to conserve CPU and GPU cycles. The animation resumes instantly when scrolled back into view.
• Mobile Frame Throttling: Background scripts are paused on mobile devices by default to prevent device overheating. Enabling the "Run animation on mobile devices" option scales down particle counts automatically to match mobile processing thresholds.

📝 5. Sample Background Script Code (3 Types)

Choose [Custom JavaScript] in the background settings and copy one of the templates below into the code editor.

[!NOTE]
Scripts must acquire the target canvas context using document.getElementById('bg-canvas').

❄️ Sample A. Winter Snowfall (Snowfall)

A background animation where snowflakes drift slowly down the screen.

(function() {
  const canvas = document.getElementById('bg-canvas');
  if (!canvas) return;
  const ctx = canvas.getContext('2d');
  
  let width = canvas.width = window.innerWidth;
  let height = canvas.height = window.innerHeight;
  
  // Mobile throttle detection
  const divisor = (window.bgConfig && window.bgConfig.mobileThrottleDivisor) || 1;
  const maxSnowflakes = Math.floor(100 / divisor);
  const snowflakes = [];
  
  class Snowflake {
    constructor() {
      this.reset();
      this.y = Math.random() * height; // Initial random altitude
    }
    
    reset() {
      this.x = Math.random() * width;
      this.y = -10;
      this.radius = Math.random() * 3 + 1;
      this.speed = Math.random() * 1 + 0.5;
      this.opacity = Math.random() * 0.6 + 0.2;
    }
    
    update() {
      this.y += this.speed;
      // Gentle swaying motion
      this.x += Math.sin(this.y / 30) * 0.5;
      
      if (this.y > height || this.x < 0 || this.x > width) {
        this.reset();
      }
    }
    
    draw() {
      ctx.beginPath();
      ctx.arc(this.x, this.y, this.radius, 0, Math.PI * 2);
      ctx.fillStyle = `rgba(25, 25, 255, ${this.opacity})`;
      ctx.fill();
    }
  }
  
  // Particle instantiation
  for (let i = 0; i < maxSnowflakes; i++) {
    snowflakes.push(new Snowflake());
  }
  
  function animate() {
    ctx.clearRect(0, 0, width, height);
    
    for (let i = 0; i < snowflakes.length; i++) {
      snowflakes[i].update();
      snowflakes[i].draw();
    }
    requestAnimationFrame(animate);
  }
  
  // Resize handler
  window.addEventListener('resize', () => {
    width = canvas.width = window.innerWidth;
    height = canvas.height = window.innerHeight;
  });
  
  animate();
})();

🕸️ Sample B. Constellation Network

An IT-inspired constellation pattern where floating node particles link with thin translucent lines when they drift close to one another.

(function() {
  const canvas = document.getElementById('bg-canvas');
  if (!canvas) return;
  const ctx = canvas.getContext('2d');
  
  let width = canvas.width = window.innerWidth;
  let height = canvas.height = window.innerHeight;
  
  const divisor = (window.bgConfig && window.bgConfig.mobileThrottleDivisor) || 1;
  const particleCount = Math.floor(80 / divisor);
  const particles = [];
  const connectionDistance = 100;
  
  class Particle {
    constructor() {
      this.x = Math.random() * width;
      this.y = Math.random() * height;
      this.vx = (Math.random() - 0.5) * 0.8;
      this.vy = (Math.random() - 0.5) * 0.8;
      this.radius = Math.random() * 2 + 1.5;
    }
    
    update() {
      this.x += this.vx;
      this.y += this.vy;
      
      // Boundary collision
      if (this.x < 0 || this.x > width) this.vx *= -1;
      if (this.y < 0 || this.y > height) this.vy *= -1;
    }
    
    draw() {
      ctx.beginPath();
      ctx.arc(this.x, this.y, this.radius, 0, Math.PI * 2);
      ctx.fillStyle = 'rgba(99, 102, 241, 0.4)'; // Pastel indigo
      ctx.fill();
    }
  }
  
  for (let i = 0; i < particleCount; i++) {
    particles.push(new Particle());
  }
  
  function drawLines() {
    for (let i = 0; i < particles.length; i++) {
      for (let j = i + 1; j < particles.length; j++) {
        const dx = particles[i].x - particles[j].x;
        const dy = particles[i].y - particles[j].y;
        const dist = Math.sqrt(dx * dx + dy * dy);
        
        if (dist < connectionDistance) {
          const alpha = (connectionDistance - dist) / connectionDistance * 0.18;
          ctx.beginPath();
          ctx.moveTo(particles[i].x, particles[i].y);
          ctx.lineTo(particles[j].x, particles[j].y);
          ctx.strokeStyle = `rgba(99, 102, 241, ${alpha})`;
          ctx.lineWidth = 1;
          ctx.stroke();
        }
      }
    }
  }
  
  function animate() {
    ctx.clearRect(0, 0, width, height);
    for (let i = 0; i < particles.length; i++) {
      particles[i].update();
      particles[i].draw();
    }
    drawLines();
    requestAnimationFrame(animate);
  }
  
  window.addEventListener('resize', () => {
    width = canvas.width = window.innerWidth;
    height = canvas.height = window.innerHeight;
  });
  
  animate();
})();

🌊 Sample C. Fluid Sine Waves

A relaxing animation showing multiple overlapping pastel wave ripples flowing smoothly near the bottom of the screen.

(function() {
  const canvas = document.getElementById('bg-canvas');
  if (!canvas) return;
  const ctx = canvas.getContext('2d');
  
  let width = canvas.width = window.innerWidth;
  let height = canvas.height = window.innerHeight;
  
  let wave1 = {
    y: height * 0.85,
    length: 0.005,
    amplitude: 25,
    frequency: 0.012
  };
  
  let wave2 = {
    y: height * 0.88,
    length: 0.008,
    amplitude: 15,
    frequency: 0.022
  };
  
  let increment = 0;
  
  function animate() {
    ctx.clearRect(0, 0, width, height);
    
    // Draw background wave (translucent teal)
    ctx.beginPath();
    ctx.moveTo(0, height);
    for (let i = 0; i < width; i++) {
      ctx.lineTo(i, wave1.y + Math.sin(i * wave1.length + increment) * wave1.amplitude);
    }
    ctx.lineTo(width, height);
    ctx.fillStyle = 'rgba(45, 212, 191, 0.1)';
    ctx.fill();
    
    // Draw foreground wave (translucent sky-blue)
    ctx.beginPath();
    ctx.moveTo(0, height);
    for (let i = 0; i < width; i++) {
      ctx.lineTo(i, wave2.y + Math.sin(i * wave2.length - increment * 1.5) * wave2.amplitude);
    }
    ctx.lineTo(width, height);
    ctx.fillStyle = 'rgba(56, 189, 248, 0.15)';
    ctx.fill();
    
    // Adjust speed according to device configuration
    const speedFactor = (window.bgConfig && window.bgConfig.mobileThrottleDivisor) ? 0.3 : 1;
    increment += wave1.frequency * speedFactor;
    
    requestAnimationFrame(animate);
  }
  
  window.addEventListener('resize', () => {
    width = canvas.width = window.innerWidth;
    height = canvas.height = window.innerHeight;
    wave1.y = height * 0.85;
    wave2.y = height * 0.88;
  });
  
  animate();
})();

📱 6. Device-Specific Mobile Background Configuration

Customize your background settings depending on the user environment to optimize system performance.

1. Desktop Background: Choose Custom JavaScript on PC displays to run beautiful canvas animations.
2. Enable Independent Mobile Settings: Check the "Use different background for mobile devices" toggle located at the bottom of the design editor.
3. Mobile Optimization: Under the separate mobile configuration panel, select Solid or Gradient backgrounds to minimize processor workloads.
4. Outcome: Conserves mobile batteries by running lightweight background styles on smartphones, while maintaining visually rich interactive motion rendering for desktop browsers.

❓ Admin Frequently Asked Questions (FAQ) and Troubleshooting

This document provides solutions to common troubleshooting issues that may arise during the installation, deployment, and operation of the blog, as well as a guide to safely upgrading to the latest version.

🗄️ Q1. How do I safely upgrade to the latest version or restore my data?

To preserve database integrity and prevent unexpected build crashes, we strongly recommend following the safe upgrade procedures below.

1. Safe Upgrade and Verification Procedure (Recommended)

To prevent database schema mismatches or template conflicts, do not deploy immediately to your production server. Instead, perform verification in a test environment first (applicable to non-Git users as well).

1. Preserve Settings Backup:
   • Copy wrangler.backup.json and .dev.vars from your current development folder to a safe temporary location.
   • ※ Note: The .dev.vars file contains critical credentials (passwords, OAuth keys, etc.) but is excluded from Git tracking (.gitignore) for security. Therefore, it is easily lost when updating or pulling source code. Be sure to back it up.
2. Back Up Production Data:
   • Go to the Content Backup menu in your active blog admin panel and download the complete posts and settings backup file.
3. Clone/Download the New Version in an Isolated Folder:
   • Do not overwrite the existing folder. Download or clone the latest release source code in an entirely new directory.
4. Deploy a Temporary Test Server:
   • Navigate to the new folder, install dependencies (npm install), create a temporary database, and perform a test deployment.
5. Test Backup Restore:
   • Access the newly deployed test admin panel and load the backup file downloaded in Step 2. Verify thoroughly that all posts and configurations display correctly without errors.
6. Apply Upgrade to Production Server:
   • Only after validating that everything functions correctly on the test server, return to your original development folder, update the codebase (git pull or overwrite source), and run the individual app deployment commands (npm run deploy:blog, npm run deploy:admin) to complete the official upgrade.

2. Last Resort for Data Loss

• Using the npm run restore Command:
  • If the infrastructure settings or database are severely damaged and require a fresh restoration, use the backed-up wrangler.backup.json file as a last resort for data recovery to rebuild the entire infrastructure.

📂 Q2. What are the mandatory keys required when changing image storage to R2, Supabase, or ImageKit?

Below is a checklist of mandatory environment variables and configurations required when using each external image storage provider.

📊 Q3. Dashboard analytics charts display only demo data.

• Cause: If Google Analytics 4 (GA4) API environment variables are missing or invalid, placeholder demo data is shown to prevent dashboard crashes.
• Setup: Add the following environment variables to the Cloudflare Pages settings and redeploy:
  • GA4_PROPERTY_ID: Google Analytics Property ID
  • GA4_CLIENT_EMAIL: Google Cloud Service Account Email
  • GA4_PRIVATE_KEY: Google Service Account Private Key
• Caution: When writing GA4_PRIVATE_KEY in .dev.vars, ensure the entire key string is enclosed in double quotes (") so that line break codes (\n) are preserved correctly during parsing.

⚡ Q4. I cannot access the admin page, or some data sync seems to be missing after the initial setup deployment.

• Cause: Even if environment variable settings are successfully guided during the one-click setup, temporary network errors or system glitches may cause some encryption keys or secret variables (Secrets) to be partially missing or corrupted during deployment.
• Solution: Double-check the values in each app's .dev.vars file. Then, navigate to each folder and manually execute the deployment commands (npm run deploy:blog and npm run deploy:admin) once. The secret environment variables stored in your local .dev.vars will overwrite the environment variables on Cloudflare, resolving the issue.

🔒 Q5. An "Forbidden (IP Not Allowed)" or 403 Forbidden error occurs when accessing the admin page.

Due to the security specifications of this blog, the deployment script automatically detects the public IP address of your deployment PC and injects it as the allowed IP (ALLOWED_IP) into the Pages Secret.

⚠️ Admin Security Recommendation

• To prevent account hijacking and unauthorized access, it is strongly recommended to restrict admin access and writing operations on public networks (e.g., cafes, libraries) or untrusted public PCs.

💡 Situation-Specific Troubleshooting

• Situation A. Change in home or office IP address (e.g., router reboot):
  • Execute npm run deploy:admin once from your main development PC in the home/office. It will automatically detect the new public IP and redeploy, restoring your access immediately.
• Situation B. Relocating development environment to post from an external location:
  • Clone/download the project and execute a new setup deployment using your backed-up configuration file (wrangler.backup.json).
  • ※ Note: When returning to your original home/office, you must execute npm run deploy:admin again from your original development PC to restore the allowed IP back to your primary fixed IP.

🔐 Q6. Better Auth (social login or signup) errors or infinite login loops occur.

• Cause: Session verification fails and loops if authentication-related secrets are missing or incorrect.
• Solution:
  1. Check apps/blog/.dev.vars and ensure that BETTER_AUTH_SECRET is set to a secure random string of at least 32 characters.
  2. After correcting it, run npm run deploy:blog to overwrite and sync the secrets, which will restore normal authentication functionality.

This document provides a brief overview of the blog (apps/blog) homepage layout and basic login/registration methods.

🎨 1. Blog Layout and Navigation

The blog layout is designed to help visitors locate information efficiently (Header, Sidebar, Main Content, and Footer).

1. Navigation Header (Header):
   • Site Logo: Click to return to the homepage at any time.
   • Shortcut Menu: Lists primary links configured by the administrator (e.g., categories, external channels).
   • Language Selector: Click the globe icon to switch both menu languages and post translations instantly.
2. Sidebar:
   • Displays category lists, the author profile card, and popular tags on desktop screens.
   • Automatically hidden on mobile resolutions to optimize readability and scrolling.
3. Main Content:
   • Shows category filters and the latest published articles in card format.

🔑 2. Registration and Login

Supports account registration and login for writing comments or guestbook entries.

⚙️ Supported Login and Sign-Up Methods

• Default Email Login/Sign-Up (Default):
  • Enabled by default post-installation. Users can sign up by providing an email address, display name (nickname), and password. Auto-login applies immediately upon successful registration.

• Social Login (Better-Auth):
  • Powered by the Better-Auth engine, supporting 21 social login providers including Google, GitHub, Kakao, and Naver.
  • Social login buttons will only appear and function on the login screen after the administrator configures the respective client IDs and secrets as environment variables on the backend. (Integration details for social providers will be detailed in separate upcoming documents.)

• Login Status Display:
  • Upon logging in, the top-right button switches to your profile image icon and a link to my-page.
  • Note: The user profile photo integration is currently in progress and may display a default profile icon instead.

This document introduces core features of the blog, including viewing multi-language post translations and communicating via comments and the guestbook.

🌐 1. Real-Time Multi-Language Body Switching (i18n)

This blog features a real-time multi-language viewer that updates not just basic UI labels but the actual post content itself to the selected language.

⚙️ How It Works & Key Features

• Language-Specific URL Routing: Clicking the globe icon at the top or the language buttons near the post title directs the browser to the language-specific URL (e.g., prefixing with /en or /ja). In addition to default languages (Korean, English, Japanese), administrators can expand and publish in other languages by configuring the translation dictionary.

• Manually Authored Data Loading (Not Machine Translation): The system does not automatically machine-translate text in real time. Instead, it queries and loads the specific post data manually translated and saved by the author under each language tab (such as content translated using AI or translation services and stored in the database).
• Simultaneous Content & Metadata Loading: More than simple text replacement, the database-stored title, excerpt, tags, and body HTML are completely swapped with the datasets of the selected language.
• Untranslated Post Fallback: If the author has not registered a translation for a specific language, the system shows a notice stating the translation is unavailable and falls back to rendering the default authoring language (e.g., Korean text) to ensure the reader's flow is uninterrupted.

💬 2. Comment and Nested Reply Hierarchy

A clean comment section is placed below each article to facilitate discussion for both guest visitors and registered members.

• Sharing Thoughts: Logged-in users can write and post comments to share ideas.
• Hierarchical Replies (Nested Comments): Users can reply to a specific comment, organizing discussions in an easy-to-read tree structure.
• Security & Integrity Preservation: Users can delete their own comments. However, if a comment with active replies is deleted, the system masks the content with the text "This comment has been deleted" to prevent breaking the overall thread hierarchy.

📖 3. Guestbook and Private Posts

Provides communication features through the blog guestbook page.

⚙️ Private Guestbook Features

• Writing Private Posts: Checking the [🔒 Private Post] checkbox hides the message from the general public.
• Exposure Restriction: Private guestbook posts are completely excluded from the lists of third-party visitors and logged-out users.
• Secure Communication: The post body is visible only to the author (when logged in) and the site administrator, ensuring private communication.

❓ Reader Policy and Frequently Asked Questions (FAQ)

This document introduces the basic principles of personal information and data processing upon account deletion, and the service activity restriction policy.

🚪 Q1. What happens to my comments and guestbook posts when I delete my account?

The blog system applies an author anonymization policy to simultaneously protect the user's privacy and maintain the integrity of dialogue threads within the site.

💡 Data Processing Principles Upon Deletion

1. Personal Identification Data Removal:
   • When you delete your account, your active session and social login connection information are immediately and safely removed from the authentication system. However, for preventing abuse and security audits, minimal data containing the email and social ID connection information at the time of deletion is backed up in a segregated internal deletion log table (deleted_users). This log information is for internal administrative use only, and is completely anonymized and hidden on public pages to prevent any reverse-tracking of the author.
2. Content Data Retention:
   • Your comments and guestbook messages remain on the screen to preserve the context of past discussions and conversations.
3. Nickname Anonymization:
   • The link between your account and your posts is severed, and the author name automatically switches to "Unknown". This prevents reverse-tracking of the actual author's identity.

• Note: If the administrator manually deletes your membership record entirely, your comments and guestbook entries may also be removed.

🚪 Q2. Can I sign up again immediately after deletion or withdrawal?

• Voluntary Withdrawal:
  • If you voluntarily delete your account, you can sign up again immediately using the same email or social account without any grace period.
• Activity Ban (Ban) State:
  • If your account is banned due to policy violations, you cannot sign up again with the same email because the email information still exists in the database.
• Forced Deletion (Kick) State:
  • If your account is forcibly deleted (Hard Deleted) by an administrator, the existing information is completely removed from the authentication tables, making it technically possible to sign up again with the same email immediately.
  • Although the email and social ID information from the time of the kick are preserved in the internal deletion log (deleted_users), there is currently no automated system block logic that compares this log at the time of registration to restrict sign-ups.
  • Therefore, to physically and completely prevent a malicious user from signing up again, the account should be kept in a 'Banned' state rather than being forcibly deleted. (In a banned state, the email remains in the database, preventing re-registration due to the unique email constraint.)

🚫 Q3. My account has been restricted (banned) or forced out (kicked).

Checklist when your service usage is restricted (banned) or deleted (kicked) due to policy violations (such as posting spam or offensive content).

💡 Core Checklist for Activity Restrictions

1. Activity Ban (Ban):
   • Status: Your login state remains active, but direct interactions such as posting comments, nested replies, or guestbook entries are temporarily or permanently restricted.
   • Checking Reasons: When restricted, a notice saying "Banned users cannot write comments." will appear in the comment form area, and you can view the specific reason and the expiration date of the restriction.
2. Forced Deletion (Kick/Delete):
   • Status: The login account itself is completely deleted (Hard Deleted) from the database.
   • Behavior: Once kicked, your active login session is immediately terminated. Subsequent login attempts will treat you as a new user with no registration history. Depending on the deletion behavior set by the administrator, comments you wrote may either be deleted entirely or anonymized as 'Unknown'.

📖 Blog and Admin Feature Integration Overview

This document links individual feature overview pages to provide a structured map of the blog service and administration (admin) features.

Note: Detailed connection guidelines and technical manuals for each feature will be published individually in future posts.

📂 Feature Overview Index

• Admin Features
  • CMD One-Click Installation and Cloudflare Deployment Guide: Deploying the blog edge infrastructure to Cloudflare with a single terminal command.
  • Admin First Access and Configuration Guide: Master password login, IP whitelist management, and multi-language UI dictionary configuration.
  • Core Admin Features and Dual Editors: Introduces Visual HTML and Markdown editors, batch-saving, and column layouts for desktop/mobile viewports.
  • Real-Time Design Editor and Background Showcase: Four background modes (solid, gradient, image, canvas scripts) applied in real-time without rebuilds.
  • Admin FAQ and Troubleshooting: Version upgrades, image storage key checks, post-deployment troubleshooting, and IP security unblock procedures.
• Blog Features
  • Blog Homepage Layout and Login: Highlights homepage widgets, multi-language UI switches, and login integrations.
  • Blog Core Features and Multi-Language Service: Real-time multi-language content switching, translation fallback logic, nested comment threads, and private guestbook communication.
  • Reader Policy and FAQ: Data processing upon account deletion, re-registration policies, and ban/kick restriction details.

🚀 Core Process of Blog Management

An overview of the setup and authoring workflow for blog administrators.

1. IP Whitelisting and Master Login

• The admin panel requires the user's public IP address to be registered in the ALLOWED_IP whitelist before access is granted. (A 403 Forbidden page is shown if unregistered.)
• Enter the master password on the secure login screen to establish your session.

2. Multi-Language Batch Saving

• Switch between the translation tabs in the writing editor to write content, and click the save button to publish or draft all languages simultaneously to the database.

3. Real-Time Theme Updates

• Configure styles, colors, and interactive canvas backgrounds in the design editor. Saving changes propagates parameters as CSS variables in visitors' browsers instantly, without redeployment.

💬 Closing Remarks

The content covered in this document is a brief overview of the features offered by the blog and admin systems. In reality, there are many more detailed features and convenience options that we couldn't cover here, and discovering them on your own as you explore the system can be quite an enjoyable experience.

We plan to publish in-depth guides with detailed usage instructions and tips for each feature in future posts, so please feel free to visit again whenever you need them. If you have any questions or feedback, don't hesitate to leave a message via the guestbook or comments section at any time.

🚀 SvelteKit Monorepo + Cloudflare: One-Click Deploy & Auto-Setup Detailed Manual

This project is built on top of a SvelteKit monorepo architecture and seamlessly integrates with serverless infrastructures like Cloudflare D1, KV Namespace, and Cloudflare Pages.

To prevent configuration omissions or database connection loss common in multi-app monorepos, a one-click automated setup script is built-in. This manual guides you through the local environment configuration required before running the script, and explains the terminal prompt options for each installation mode.

📂 1. Pre-requisites Before Running the Script

To prevent unexpected runtime halts, the setup script performs a pre-validation check (Step 0) on local secret variables (.dev.vars). You must complete the following configuration steps before triggering the command.

🔑 1-1. Create and Configure .dev.vars Files

Duplicate .dev.vars.example in both app directories to create .dev.vars files and fill in the necessary keys.

1. Blog App Secrets

   • Location: apps/blog/.dev.vars
   • Required Key:

     BETTER_AUTH_SECRET="your_long_random_secret_string"
     

     (Provide a complex, unique secret string to encrypt authorization sessions and tokens. Leaving it empty or just double quotes will fail the validation.)

2. Admin App Secrets

   • Location: apps/admin/.dev.vars

   • Required Key:

     ADMIN_PASSWORD="your_admin_dashboard_password"
     

     (Set the password for accessing the admin panel dashboard.)

   • Google Analytics 4 (GA4) & Google AdSense Dummy Data:
     If you want to test the widgets on the dashboard landing page with dummy (simulated) data instead of a live API connection, you must leave the Google integration variables (GA4_PROPERTY_ID, ADSENSE_ACCOUNT_ID, etc.) blank or completely remove them from both local .dev.vars and the Cloudflare Pages remote environment settings. The dashboard automatically falls back to dummy simulation mode if any of these configuration keys are missing.

[!WARNING]
If these files do not exist or the required credentials are empty, the CLI will output an error and halt immediately:

❌ apps/admin/.dev.vars file does not exist.
   (Please copy apps/admin/.dev.vars.example to create it and configure ADMIN_PASSWORD.)

🛠️ 2. Command Reference

💬 3. Terminal Prompt Step-by-Step Guide

Here is a comprehensive breakdown of the actual prompts (English & Korean) printed during execution and their corresponding impacts.

🌐 3-1. Shared Initial Prompts (Common for both setup & setup:select)

Q1. Select Default Blog Language (Database Seeding Language)

Determines the language of the default guide posts and configurations inserted into your Cloudflare D1 database.

  [EN] Select default blog language:
  [KO] 기본 블로그 언어를 선택하세요:
  1) Korean / 한국어 (ko) [Default]
  2) English / 영어 (en)
  3) Japanese / 日本語 (ja)
  [EN] Choose option (1/2/3) [Default: 1]
  [KO] 옵션을 선택하세요 (1/2/3) [기본값: 1]
  > 

• Guide: Press 1 for Korean, 2 for English, or 3 for Japanese. It seeds the D1 database with translated mock posts and system settings according to the selection.

Q2. Select Setup Mode for Remaining Steps

Decide whether to execute a fully automated pipeline or customize every single bind variable.

  [EN] Choose setup mode for the remaining steps:
  [KO] 나머지 설정의 진행 방식을 선택하세요:
  1) Full Auto Setup & Deploy / 풀 자동 설정 및 배포 [Default]
  2) Custom Interactive Setup / 사용자 지정 직접 선택 설정
  [EN] Choose option (1/2) [Default: 1]
  [KO] 옵션을 선택하세요 (1/2) [기본값: 1]
  > 

• 1) Full Auto Setup & Deploy (Default): Automatically provisions Pages projects (svelteblog and svelteadmin), detects active Cloudflare sessions, runs migrations, and triggers a build-and-deploy flow without asking questions.
• 2) Custom Interactive Setup: Transitions to custom configuration mode (equivalent to running npm run setup:select directly) and prompts you with questions Q3 through Q8.

🎨 3-2. Custom Interactive Prompts (npm run setup:select only)

[!TIP]
All prompts during the custom interactive phase can be answered by simply pressing Enter to fall back to the safe, standard defaults displayed inside the brackets [Default: ...]. You do not have to manually fill out every field.

Q3. Custom Deploy Project Names

Specify unique project names to register on Cloudflare Pages. (The service URLs will default to https://[project-name].pages.dev.)

  [EN] Enter Blog project name [Default: svelteblog]
  [KO] 블로그 배포명을 입력하세요
  > 

  [EN] Enter Admin project name [Default: svelteadmin]
  [KO] 어드민 배포명을 입력하세요
  > 

• Guide: Press enter to use the defaults. If you already have existing projects with these names in your Cloudflare dashboard, type a unique name to avoid conflicts. (This also updates deployment scripts inside package.json dynamically.)

Q4. Cloudflare Wrangler Login

Triggers authorization checks.

  [EN] Run wrangler login?
  [KO] Wrangler 로그인을 진행할까요?
  [EN] (Y/n) [Default: Y]
  [KO] (Y/n) [기본값: Y]
  > 

• Guide: If no active session is detected, it redirects you to the browser. If a valid login exists, the script skips it automatically. Select Y if you wish to switch or re-authenticate Cloudflare accounts.

Q5. Database Initialization Mode (Fresh vs Keep)

Specify whether to keep your remote database tables or clear them.

  [EN] Select Initialization Mode:
    1: Fresh Install (DELETE existing Cloudflare D1/KV databases and start clean)
    2: Keep Existing Data (Use existing Cloudflare databases to preserve your posts/data)
  [KO] 초기화 모드 선택:
    1: 완전 초기화 (기존 클라우드플레어의 D1/KV 데이터베이스를 모두 삭제하고 새로 생성합니다. 데이터 유실 주의!)
    2: 기존 데이터 유지 (기존에 구축된 클라우드플레어 리소스를 그대로 유지하고 연동합니다.)

  [EN] Choose an option (1/2) [Default: 2]
  [KO] 옵션을 선택하세요 (1/2) [기본값: 2]
  > 

• Fresh Install (1): Permanently deletes existing D1 databases and KV namespaces on Cloudflare. Do not choose this unless you are setting up a test environment from scratch.
• Keep Existing Data (2, Recommended/Default): Re-uses your active D1 tables and KV records. Your articles and visitor logs will remain intact.

Q6. Custom Cloudflare Resource Labels

Customize the actual names of the D1 databases and KV namespace instances.

  [EN] Enter Blog DB name [Default: blog-db-xxxxxx]
  [KO] 블로그 DB 이름을 입력하세요
  > 

  [EN] Enter User DB name [Default: user-db-xxxxxx]
  [KO] 유저 DB 이름을 입력하세요
  > 

  [EN] Enter Images KV name [Default: blog-images-kv-xxxxxx]
  [KO] 이미지 KV 이름을 입력하세요
  > 

• Guide: Leave blank and press enter to generate unique labels with random suffixes (xxxxxx), or type custom names to match your naming guidelines.

Q7. Cloudflare CDN Cache Purge Integration

Configure automatic edge cache invalidation when posts are modified.

  [EN] Configure Cloudflare CDN cache purge credentials?
  [KO] CDN 캐시 퍼지 설정을 등록하시겠습니까?
  [EN] (y/N) [Default: N]
  [KO] (y/N) [기본값: N]
  > 

• Guide: Selecting y triggers prompt inputs for your Cloudflare Zone ID and API Token. These credentials will be written to local .dev.vars files and synchronized as remote secrets automatically.

Q8. Direct Deployment Confirmation

Choose whether to immediately compile the code and ship it to Cloudflare Pages.

  [EN] Deploy directly?
  [KO] 지금 바로 배포하시겠습니까?
  [EN] (Y/n) [Default: Y]
  [KO] (Y/n) [기본값: Y]
  > 

• Guide: Press Y to trigger immediate builds and deployments. The script will output the resulting live URLs. Press n if you only want to update configuration files (wrangler.json) locally.

🔒 3-3. Post-Build Synchronization Prompts (IP Whitelisting & Translations)

During the compilation stage (sync-secrets.js), you may encounter additional prompts concerning admin security and i18n synchronization.

Q9. Admin IP Mismatch Warning

The admin panel uses a strict IP whitelist (ALLOWED_IP) for security. The script dynamically checks your machine's current public IP address and flags a mismatch if it is not in the whitelist:

  1) Keep existing allowed IPs / 기존 목록 유지 (현재 기기 미등록) [Default]
  2) Add current machine IP to list / 현재 기기 IP를 목록에 추가 (복수 허용)
  3) Replace with current machine IP / 현재 기기 IP로만 갱신 (기존 목록 제거)

  [EN] Select option (1/2/3) [Default: 1]
  [KO] 옵션을 선택하세요 (1/2/3) [기본값: 1]
  > 

• 1) Keep existing allowed IPs (Default): Keeps your whitelist configurations unchanged. You might be blocked from the dashboard if your current network environment differs from the registered one.
• 2) Add current machine IP to list: Appends your current public IP using a comma separator. Recommended for admins managing the blog from multiple locations (e.g., home and office).
• 3) Replace with current machine IP: Clears all registered IPs and sets only your current IP as the sole allowed address.

Q10. Force Sync i18n Translations to D1 Database

Decide whether to overwrite remote translation tables with local code definitions:

[EN] Force sync remote D1 ui_dictionary with local index.ts? (Web changes will be lost)
[KO] D1 DB의 ui_dictionary를 로컬 index.ts 기준으로 강제 덮어쓰시겠습니까? (웹 수정본 유실 주의)
  [EN] Select option (y/N) [Default: N]
  [KO] 옵션을 선택하세요 (y/N) [기본값: N]
  > 

• Guide: Select N if you have edited translations directly in the admin dashboard settings page to prevent losing changes. Select y if you want to overwrite database values with local source code files (packages/shared/src/i18n/index.ts).

🔄 4. Backup & Restore Mechanism (npm run restore)

Once a setup finishes successfully, a wrangler.backup.json configuration backup file is automatically generated in your root directory.

{
    "d1": {
        "BLOG_DB": { "name": "blog-db-xxxxxx", "id": "d1-uuid-value" },
        "USER_DB": { "name": "user-db-xxxxxx", "id": "d1-uuid-value" }
    },
    "kv": {
        "IMAGES_KV": "kv-namespace-id"
    },
    "blogProjectName": "svelteblog",
    "adminProjectName": "svelteadmin"
}

If you relocate or switch development environments:

• Running npm run restore reads this backup file to lock project names and restore exact resource bindings automatically.
• It safely skips database seeding to prevent overwriting or wiping your operational articles and visitor data.

❓ 5. Troubleshooting

🚨 1. Wrangler Whoami Session or Authorization Failure

• Symptom: CLI prints authentication or access errors when provisioning D1/KV resources.
• Solution: Run npm run setup:select and enter Y at the Q4. Run wrangler login prompt to trigger a fresh browser authentication. The script only requests minimal account permissions (account:read, user:read, workers:write, pages:write, d1:write, workers_kv:write) for security.

🚨 2. Windows Script Execution Policy Blocked

• Symptom: PowerShell restricts script executions due to authorization policies.
• Solution: The setup script automatically overrides paths and uses npx.cmd on Windows. We recommend running commands via Git Bash or CMD (Command Prompt) rather than standard PowerShell.

🔑 Cloudflare Wrangler Login and API Token Configuration Guide in CLI Environments

This project provides an automated setup script that provisions Cloudflare databases, storage, and build pipelines in a single execution.

While this script internally runs the Cloudflare wrangler CLI, local development environments typically trigger an interactive web browser login (npx wrangler login). However, in headless CLI-only environments (such as remote SSH Linux servers, headless virtual machines, or CI/CD build pipelines), establishing an interactive browser session is impossible.

This manual explains how to bypass this limitation and safely configure a non-interactive Wrangler session using a Cloudflare API Token.

📂 1. Permission Scopes: Before vs. After Domain Setup

Before issuing a token, it is crucial to understand your current deployment stage. To follow security best practices, separate your permissions based on your custom domain connection state.

🔌 1-1. Initial Deployment (Before Custom Domain Setup)

If you are deploying for the first time and only using the default *.pages.dev domains provided by Cloudflare Pages, you do not need any Zone (domain) level permissions. The setup script, database migrations, and resource bindings will function perfectly with only Account-level permissions.

• Required Minimum Permissions:
  • D1 — Edit (Required to create, query, and migrate D1 databases)
  • Workers KV Storage — Edit (Required to manage KV namespaces for media uploads)
  • Cloudflare Pages — Edit (Required to build and deploy SvelteKit applications)
  • Workers Scripts — Edit (Required for CLI script management)

🌐 1-2. Custom Domain Mapping & CDN Edge Cache Purging (Future Setup)

When you bind a custom domain to your blog and enable edge CDN cache purging for better performance, you will then require Zone-level permissions.

• Additional Required Permission:
  • Zone: Cache Purge — Edit (Required to invalidate CDN edge caches when content changes)
• Security Best Practice: When limiting token scopes, do not set Zone Resources to "All Zones". Restrict it to the specific custom domain (Zone) you are currently using.
• *Note: The custom domain setup and edge CDN cache configuration will be discussed in detail in the upcoming 'Custom Domain Setup Detailed Manual'. You can safely skip these settings during your initial setup.*

🛠️ 2. Cloudflare API Token Creation Steps

You can generate a token for non-interactive logins in the Cloudflare dashboard by following these steps:

1. Log in to the Cloudflare Dashboard:
   • Navigate to the Cloudflare Dashboard and log in.
2. Access the API Tokens Menu:
   • Click the user icon in the top right corner of the dashboard and select My Profile.
   • In the left-hand navigation sidebar, click API Tokens.
   • Click the Create Token button on the right.
3. Select Custom Token:
   • Under the templates list, locate the Create Custom Token section at the bottom and click Get Started.
4. Configure Permissions:
   • Token Name: Enter a descriptive name (e.g., sveltekit-blog-cli-token).
   • Permissions:
     • Account -> D1 -> Edit
     • Account -> Workers KV Storage -> Edit
     • Account -> Cloudflare Pages -> Edit
     • Account -> Workers Scripts -> Edit
5. Restrict Resources (Scope):
   • Account Resources: Set to Include -> Select your Cloudflare Account (Restricts the token's scope to your account only to isolate security risks).
6. Generate and Save:
   • Click Continue to summary, then click Create Token.
   • Copy the generated API token (a long alphanumeric string) and store it in a secure location. (Note: You cannot view this token again after leaving the page. If lost, you must generate a new one.)

💻 3. Setting the Environment Variable

Since the browser login is bypassed, you must inject the token value into your system's environment variables. Wrangler will automatically detect it and establish an active session.

3-1. Terminal Command by Operating System

Run the appropriate command in your terminal session before executing any setup script:

• Linux / macOS / Git Bash (Bash/Zsh Shell):

  export CLOUDFLARE_API_TOKEN="your_generated_api_token"
  

• Windows Command Prompt (CMD):

  set CLOUDFLARE_API_TOKEN=your_generated_api_token
  

• Windows PowerShell:

  $env:CLOUDFLARE_API_TOKEN="your_generated_api_token"
  

[!NOTE]
💻 Compatibility and macOS Testing Note

• This guide has been fully verified and tested on Windows 10/11 and Linux (Ubuntu 22.04 LTS) console environments.
• Due to the author's lack of physical macOS hardware, a hands-on verification on macOS (MacBook) was not performed. However, since Node.js CLI executes cross-platform binaries identically, this will work seamlessly on macOS using the standard Zsh/Bash export command.

3-2. Local Development (.dev.vars) and CI/CD Integrations

• Local Development:
  To avoid typing the variable in every terminal session, add the token to the .dev.vars files in apps/blog/ and apps/admin/. Wrangler will parse it automatically:

  CLOUDFLARE_API_TOKEN="your_generated_api_token"
  

• CI/CD Pipelines (GitHub Actions):
  Register the token under Settings -> Secrets and variables -> Actions -> Repository secrets as CLOUDFLARE_API_TOKEN and map it in your workflow file:

  - name: Build and Deploy SvelteKit Apps
    env:
      CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
    run: npm run deploy:blog
  

🔍 4. Verification and Debugging

You can verify that the environment variable has been correctly injected and linked to your Cloudflare account using the following diagnostic tools.

4-1. wrangler whoami

Run this command in your terminal:

npx wrangler whoami

• Success Output: If valid, the CLI will output your account details (Account Name, Account ID) and the list of permitted bindings (D1, KV, Pages, etc.).
• Clearing Sessions (wrangler logout):
  If an existing interactive browser session interferes with your token environment variable, clear the local cache and reset the state using the logout command:

  npx wrangler logout
  

⚠️ 5. Troubleshooting

🚨 1. Authentication Error (Code: 10000)

• Symptom: The CLI prints authentication errors when executing the provisioning scripts.
• Solution: Double-check for typos or leading/trailing spaces in your CLOUDFLARE_API_TOKEN string. Verify that the Account Resources scope matches the account ID of the active project.

🚨 2. Forbidden (Access Denied)

• Symptom: D1 migrations work fine, but Pages deployments or KV namespace creations fail with access denied errors.
• Solution: Ensure your token has all four required edit permissions (Pages -> Edit, Workers KV -> Edit, etc.) in the Cloudflare API Tokens dashboard. If any are missing, update the token permissions and try again.

✍️ Web Font Settings and Load Optimization Architecture in Blog Admin

This project provides an intuitive design editing tool within the admin panel to easily customize fonts, improving the visual appeal and readability of your blog.

Beyond simply applying font names, a specialized performance optimization engine runs behind the scenes to maintain top loading speeds and high performance scores (Lighthouse Performance) even in mobile or bandwidth-constrained environments.

This manual details how to configure fonts in the admin design editor and explains the underlying concepts of how fonts are optimized and served rapidly to your visitors.

📂 1. Detailed Font Settings in the Design Editor

In the admin design editor settings menu, you can finely tune font families, sizes, and weights to match your blog layout.

✍️ 1-1. Global Web Font Settings (Affects Entire Pages)

Manages the global fonts that bind as defaults across all text areas and the basic interface of the blog.

• Base Font Family (Font Family):
  • Specifies the main typeface for the entire blog.
  • How to enter: Enter the font name recognized by browsers. If left blank, the system default font Inter is inherited across the entire blog. (e.g., 'Noto Serif KR', serif or Pretendard)
• Add Google Web Fonts (Google Font Name):
  • Registers the English names of Google Fonts to apply to specific areas like the logo text or key widget titles.
  • How to enter: List multiple fonts separated by commas (,) or semicolons (;). (e.g., Noto Serif KR, Newsreader)
  • Integration effect: The custom font names entered here will automatically populate as select options in the header's logo font dropdown and other individual font family options.
• Base Font Size & Base Font Size (Mobile):
  • Defines the base font size for the desktop and mobile views respectively.
  • How to enter & Tips: It fully supports not only absolute units (px, e.g., 16px or 14px) but also relative units (rem, em) that dynamically scale according to the user's browser settings. (e.g., Desktop 1rem or 16px / Mobile 0.875rem or 14px)

🎨 1-2. Header and Logo Font Settings

Applies independent typography to the branding logo text displayed in the top navigation header.

• Font Family:
  • Selects the typeface for the logo text.
  • Choosing Inherit will follow the global base font. Custom fonts registered in the [Add Google Web Fonts] field will automatically appear in this dropdown for individual assignment.
• Font Size & Mobile Font Size:
  • Assigns distinct sizes for desktop and mobile views to ensure the logo text does not break layouts or lose legibility under different viewports. (e.g., Desktop 1.5rem / Mobile 1.2rem)
• Logo Weight:
  • Provides a dropdown menu with weights from 100 (thinnest) to 900 (boldest) in increments of 100 to customize the visual presence of the logo.
  • Caution: The actual rendered thickness depends on the selected font family's capabilities. If the web font does not support a specific weight (e.g., 100 or 900), the browser will render using the closest available weight. It is best to check the font's specifications beforehand.

🧩 1-3. Global Widget Style Settings

Adjusts the text styling of individual widget titles and contents assembled in the sidebars or footer areas.

• Global Widget Title Style: Configures the font family, size, weight, and color of the widget card headers.
• Global Widget Item Style: Sets the styling for the individual content items and links inside the widget card.
• Inheritance rule: If the font family field is left blank, it inherits the global font, maintaining layout consistency.

⚡ 2. Font Loading Performance Optimization and Mechanism

Font loading delays are a primary cause of low performance scores on websites. To prevent this, the engine features a built-in font acceleration pipeline optimized for serverless environments.

🛡️ 2-1. System Built-in Font Filtering

Fonts likely already installed on the visitor's device (e.g., Pretendard, Arial, system-ui) are filtered out on the server side. This prevents the blog server from making unnecessary requests to Google Font servers, saving bandwidth.

🔄 2-2. Blocking External Requests and Self-Proxying

If a visitor's browser connects directly to external Google Font URLs (fonts.googleapis.com and gstatic.com), DNS queries and SSL handshakes introduce several hundred milliseconds of rendering delay.

• Proxying Stylesheets: The blog requests the stylesheet (CSS) through its own internal API rather than calling external Google servers during page render.
• Rewriting Internal Paths: The engine analyzes the font download links (.woff2) inside the CSS and replaces all external URLs with internal domain proxy paths.
• Security Filters: The proxy API restricts access exclusively to official Google Font domain hosts to prevent malicious redirection or relaying of unverified code.

💾 2-3. Cloudflare Pages CDN and Local Browser Caching

All proxy-requested font definitions and font files (.woff2) are cached on Cloudflare's global edge servers (CDN) for 24 hours.

• It also responds with strong browser caching headers. When a user clicks a link to another post or returns next time, the font renders instantly in 0ms from the local device memory, eliminating flashes of unstyled text (FOUT) or layout shifts (CLS).

🚀 2-4. Pretendard Font Acceleration

When Pretendard, a typeface optimized for Korean readability, is set as the base font, the engine opens a dedicated bypass path to maximize rendering speed.

• Parallel Download: It loads the font files in parallel with other scripts through a high-speed global open-source CDN (jsDelivr), bypassing Google Font proxying.
• Rendering Optimization: This ensures the heavy Korean font package is retrieved as quickly as possible, avoiding delayed text display on initial page entry.

💡 3. Important Notes for Configuration

[!IMPORTANT]
💡 Key Guidelines When Modifying Admin Font Settings

1. Enter Exact Google Font Names:
   • The English font names entered in the Google Font Name field must match Google Font Library's official names exactly. Typos or incorrect spaces will cause the loader to fail, falling back to system generic fonts (Sans-serif).
2. Balance Desktop and Mobile Font Sizes:
   • Keeping the desktop font size on mobile views degrades mobile legibility. Ensure you configure a slightly smaller value (e.g., 2px less) for the mobile base size to maintain a responsive interface.