This text was translated by Gemini 3.5 Flash. Please be advised that some expressions may be unnatural. We appreciate your understanding.

📖 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.

❓ 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'.

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.

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.

❓ 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 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.

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 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 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 18 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.