Project Structure

About 930 wordsAbout 3 min

2026-09-01

Shirone is a high-performance modern static blog system powered by Astro 7 + Svelte 5 + Tailwind CSS + TypeScript. The project strictly adheres to Separation of Concerns (SoC) and Atomic Design principles, featuring clear modular boundaries and strongly-typed configuration contracts.

This article explores Shirone's architectural skeleton and component interactions using interactive file trees, code trees, and visual workflows.

Root Directory Architecture

The repository root contains public assets, build tooling configurations, automated scripts, and core source code:

Shirone Project Root

public# Pure static assets (favicon, custom fonts, robots.txt, etc.)

src# Core source code

scripts# Build automation and offline data sync scripts

astro.config.mjs# Top-level Astro configuration (Svelte, Swup, Tailwind)

svelte.config.js# Svelte 5 compiler settings (Runes reactivity)

tsconfig.json# TypeScript strict path aliases

package.json# Project dependencies and script shortcuts

pnpm-lock.yaml# Pnpm lockfile

Source Layering & Modules (`src/`)

The src/ directory is decomposed into seven functional domains:

src Directory Breakdown

components# UI Component Library

config# Centralized Strongly-Typed Configs

content# Content Layer

layouts# Skeleton Layouts

pages# File-system Routing

styles# Design System

utils# Utility Modules

Configuration-Driven Architecture

Shirone uses a strongly-typed configuration model. All feature toggles, author profiles, and widget placements are centralized under src/config/:

Configuration Driven Modules

src

config

siteConfig.ts

sidebarConfig.ts

musicConfig.ts

src/config/siteConfig.ts
import { withUserConfig } from "../utils/config-overlay";

export const siteConfig = withUserConfig("site", {
  title: "Shirone",
  subtitle: "Seeing the world from scratch",
  description: "Modern static blog powered by Astro 7 + Svelte 5",
  author: "Matsuzaka Yuki",
  avatar: "/avatar.webp",
  favicon: "/favicon.svg",
  themeColor: "#6750a4", // Material 3 Seed Color
  enableSwup: true,       // SPA smooth page transitions
  enablePagefind: true,   // WASM local full-text search
});
src/config/sidebarConfig.ts
import { withUserConfig } from "../utils/config-overlay";

export const sidebarConfig = withUserConfig("sidebar", {
  position: "left", // "left" | "right" | "none"
  widgets: [
    { type: "profile", enable: true },
    { type: "announcement", enable: true },
    { type: "music", enable: true, sticky: true },
    { type: "tags", enable: true, maxCount: 20 },
    { type: "categories", enable: true },
  ],
});
src/config/musicConfig.ts
import { withUserConfig } from "../utils/config-overlay";

export const musicConfig = withUserConfig("music", {
  enable: true,
  provider: "mixed", // "local" | "meting" | "custom" | "mixed"
  meting: {
    server: "netease",
    type: "playlist",
    id: "14164869977",
  },
  defaultVolume: 0.7,
  defaultMode: "sequence",
});

Content Organization Strategies (`src/content/posts/`)

Shirone supports two post organization strategies that can be freely mixed in a single repository:

Folder Mode (Recommended)

Folder Organization (Recommended)

2026-09-01-shirone-architecture

2026-09-02-webcrypto-guide

Self-Contained: Media, code snippets, and assets reside right next to the post.
Relative Path Referencing: Use straightforward relative paths like ./cover.webp or ./diagram.png.

Single File Mode

Single File Organization

2026-08-31-hello-world.md

2026-09-01-material-design-3.md

2026-09-02-typescript-tips.md

Lightweight & Flat: Ideal for text-only essays or articles utilizing cloud image hosting / CDN URLs.

Build Output Artifacts (`dist/`)

Running pnpm build compiles the codebase into pure static artifacts ready for instant edge deployment:

dist Build Output

_astro# Compiled JS/CSS asset chunks (with content hashing)

pagefind# Static WASM Pagefind search indexes

posts# Pre-rendered HTML post pages

rss.xml# RSS 2.0 Feed

atom.xml# Atom 1.0 Feed

sitemap-index.xml# SEO Sitemap index

llms.txt# LLM-friendly documentation summary

index.html# Site homepage

Architecture Interaction Workflow

Key Architectural Strengths

Instant First-Contentful Paint (FCP): Articles are pre-rendered into static HTML on the server with Zero Client-Side JavaScript footprint for reading.
Progressive Hydration: Interactive widgets (music player, modals, settings) hydrate on-demand via Svelte 5 Runes (client:idle / client:visible).
Seamless Navigation: Swup client runtime intercepts page navigations, providing an app-like SPA feel with smooth Material 3 transition curves.

Copyright

License under:Attribution 4.0 International (CC-BY-4.0)

Deployment

Markdown

Organization

Advanced

Code Blocks

Charts

Media Embeds

User

Components

Project Structure

Root Directory Architecture

Source Layering & Modules (`src/`)

Configuration-Driven Architecture

Content Organization Strategies (`src/content/posts/`)

Build Output Artifacts (`dist/`)

Architecture Interaction Workflow

Copyright

Project Structure

Root Directory Architecture

Source Layering & Modules (src/)

Configuration-Driven Architecture

Content Organization Strategies (src/content/posts/)

Build Output Artifacts (dist/)

Architecture Interaction Workflow

Copyright

Source Layering & Modules (`src/`)

Content Organization Strategies (`src/content/posts/`)

Build Output Artifacts (`dist/`)