Content Separation Overview

About 1327 wordsAbout 4 min

2026-09-01

Shirone provides native support for decoupled content separation, allowing you to isolate the theme frontend engine and your personal content repository into two independent Git repositories.

Core Concepts

Think of a personal blog as a residence:

Theme Code Repository: The architectural framework, plumbing, electrical grid, and rendering pipeline: responsible for UI animations, dark mode, responsive layout, image optimization, and static building—maintained and continuously upgraded upstream;
Personal Content Repository: The furniture, family photo albums, books, and diary entries: contains all your posts, moments, album photos, data entities, and configuration overlays—under your complete ownership and kept private.

In traditional monolithic repositories, posts, media assets, and theme source code are tightly coupled. Upstream updates frequently trigger painful Git merge conflicts, or inadvertently publish private drafts to public repositories.

Shirone's content separation architecture eliminates these pain points: your content is securely housed in a private content repository, while the theme code repository simply pulls content during builds.

Core Value of Dual-Repo Setup

By decoupling content from theme mechanics, you can author posts and configure your site like using a lightweight headless CMS while seamlessly syncing upstream theme enhancements.

Content Repository Structure (Shirone-Content)

Under the content separation architecture, all personal articles, media assets, structured data, and configuration overlays are organized in an independent repository based on the official template repository LyraVoid/Shirone-Content:

LyraVoid/Shirone-Content Standard Structure

.github

config# Declarative configuration overlay YAML files

content# Blog articles, moments, and spec pages

data# Structured data entities (TypeScript modules)

assets# Your own high-resolution images (Synced to src/assets/, compressed at build time)

public# Static assets (Published as-is without re-encoding)

.gitignore

README.md

shirone.content.json# Content repo metadata identifier & mount manifest

The assets/ folder is optional

The template ships with a set of sample images (banners, avatar, and music covers) you can use as-is. You can also delete the whole folder — the site will simply fall back to the theme's built-in images, and nothing breaks.

To use your own images, put them in the same locations and make sure the filenames match the paths written in config/site.yaml and config/profile.yaml (replacing files with the same names is easiest, or update those config files to point to your new files).

One important thing: as soon as this folder contains any image, the theme's built-in images no longer act as a fallback. So either provide the full set your site is using (banners, avatar, and covers — do not leave any out) or delete the folder entirely. Leaving only an empty .gitkeep placeholder inside would leave broken images on your site.

Functional Area Breakdown

config/ (Declarative Config Overlays): Lightweight YAML files partitioned by domain, strictly adhering to the minimal overlay principle;
content/ (Core Authoring Workspace): Houses all Markdown/MDX posts, microblog moments, and spec pages;
data/ (Structured Data Entities): TypeScript data files managing projects, hardware, skills, timeline events, and friend links;
assets/ (Auto-Compressed Images): Stores high-resolution originals such as avatars, banners, music covers, and game covers; they are synced to src/assets/ in the code repository and compressed automatically at build time. Reference them in config files with simple relative paths (e.g., assets/images/...);
public/ (Static Media & Galleries): Stores raw photos, anime cover caches, and gallery albums published directly to the static root;
shirone.content.json (Mount Manifest): Declares repository metadata, mount points, and protected file rules.

Dual-Repo Architecture & Automation Pipeline

The synchronization, config merge, and release workflow is fully automated:

Authoring in Content Repo
Draft posts or update YAML configs in your favorite Markdown editor, then push to your private repository.
Automated Pipeline Trigger
A lightweight GitHub Actions workflow sends a dispatch event to the theme repository, or a cloud deploy hook captures the push.
Content Materialization & Config Overlay
The theme repository pulls the content payload and executes recursive deep merge between YAML overlays and theme defaults.
Build & Global Deployment
The theme repository performs Chinese font subsetting, static page generation, asset compression, and deploys to global CDNs.

Key Advantages

1. Conflict-Free Theme Upgrades

Open-source themes evolve rapidly with new features and bug fixes. Under content separation, your posts, albums, and custom configs reside outside the theme repository. Syncing upstream releases yields zero Git merge conflicts.

2. Safeguard Private Content & Drafts

Many authors wish to keep their theme repository open-source while keeping:

Unfinished drafts and private journals;
Family albums and high-res photography;
Private analytics tokens or unpublished metadata.

With dual repos, you can set your content repository to Private and your theme repository to Public, enjoying the open-source ecosystem without exposing sensitive data.

Privacy Isolation

Storing posts in a private repository ensures that even if your theme repository is completely open-source, your drafts and media assets remain strictly confidential.

3. Lightweight Authoring Experience

Authors do not need to install complex Node.js dependencies, build tooling, or bundlers on their writing devices. Simply focus on:

Authoring Markdown posts and microblogs inside content/;
Tweaking lightweight YAML configs inside config/.

Monolithic vs Dual-Repo Comparison

Metric	Monolithic Setup Starter	Content Separation Recommended
Target Audience	Beginners seeking single-repository simplicity	Long-term bloggers needing private drafts and seamless theme updates
Repo Count	1 (Code and content coupled)	2 (Public theme repo + Private content repo)
Upgrade Friction	Manual upstream merge with potential Git conflicts	Direct upstream pull with zero merge conflicts
Privacy	Drafts exposed if repository is open-sourced	Content repo completely private, theme repo safely public
Writing Tools	Must run within the theme project	Independent editing with Obsidian, VS Code, Typora
Onboarding	Zero setup, clone and run	One-time setup for access token or deploy hook

Next Steps

Head to Initializing Private Content Repo: Learn one-click eject and template initialization

Copyright

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

Deployment

Markdown

Organization

Advanced

Code Blocks

Charts

Media Embeds

User

Components