Get Started
About 618 wordsAbout 2 min
2026-08-31
Set up your own Shirone blog from scratch.
Don't want to clone the repository?
Shirone is also published as the shirones npm package — run npx shirones init in an empty folder to initialize your blog. See npm Package.
Requirements
Once installed, verify the versions in your terminal:
node -v # should be >= v22.12
pnpm -v # should be 9.xDon't have pnpm?
Enable it via corepack (bundled with Node.js):
corepack enableAlternatively, install it globally with npm: npm install -g pnpm.
Local Development
git clone https://github.com/LyraVoid/Shirone.git
cd Shirone
corepack enable
pnpm install
pnpm devOnce the server starts, open http://localhost:4321 in your browser.
Windows Users
If the PowerShell script execution policy blocks commands, use pnpm.cmd and npx.cmd instead.
Customize Your Site
- Set the official URL, title, language, theme, banner and display options in
src/config/siteConfig.ts. - Update your profile and navigation in
src/config/profileConfig.tsandsrc/config/navBarConfig.ts. - Go through the configuration files under
src/config/; inline comments explain the defaults and available options. - Replace the sample posts, personal data and media assets in
src/content/,src/data/andpublic/.
Core Configuration
| File | Purpose |
|---|---|
src/config/siteConfig.ts | Site URL, identity, language, dynamic colors, banner, textures, TOC and display settings |
src/config/profileConfig.ts | Author profile and social links |
src/config/navBarConfig.ts | Primary navigation |
src/config/sidebarConfig.ts | Sidebar layout, widgets and page filtering |
src/config/postListConfig.ts | Pagination and list/grid display |
src/config/articleConfig.ts | Update notices, related posts and article sharing |
src/config/commentConfig.ts | Optional comment service |
src/config/musicConfig.ts | Optional local, custom, Meting or mixed music sources |
src/config/animeConfig.ts | Anime page with local/Bangumi/Bilibili snapshot data sources |
See src/config/README.md in the theme repository for the full configuration contract.
Writing Posts
Posts live in src/content/posts/ and support both Markdown and MDX.
Create a new post with the scaffold command, then edit the file:
pnpm new-post my-first-postMinimal frontmatter example:
---
title: My First Post
published: 2026-08-26
description: A short summary shown in the post list and metadata.
image: ./cover.webp
tags: [Astro, Notes]
category: Writing
draft: false
---Common optional fields include updated, pinned, comment, lang, encrypted, password, passwordHint and hideHomeContent.
Images can be remote URLs, absolute paths starting from public/, or paths relative to the post file.
Common Commands
| Command | Purpose |
|---|---|
pnpm dev | Start the dev server |
pnpm new-post <filename> | Create a new post |
pnpm format | Format code with Biome (required before committing) |
pnpm check | Run Astro diagnostics |
pnpm type-check | Run TypeScript checks |
pnpm test | Run Playwright tests |
pnpm build | Build the site and Pagefind index into dist/ |
pnpm preview | Preview the production build |
Deployment
Shirone generates a static dist/ directory that can be deployed to Vercel, Netlify, GitHub Pages or any static hosting service.
Before deploying, update site and base in src/config/siteConfig.ts, then run:
pnpm install --frozen-lockfile
pnpm check
pnpm type-check
pnpm buildOn your hosting platform, set the build command to pnpm build and the output directory to dist.
Content Separation (Optional)
If you prefer to manage theme code and personal content in separate repositories (e.g. keep the content repo private), use the official companion repository Shirone-Content: put posts, moments, data, media and the config/*.yaml content overrides into an independent repository, then point the theme repo to it.
Most users can simply write inside src/content/ of the theme repo. See the Content Separation Overview for details.
Next Steps
- Review the Introduction to learn about Shirone's design philosophy and key features
- Read the Content Separation Overview to explore dual-repo decoupled architecture
Copyright
Copyright Ownership:matsuzaka-yuki
License under:Attribution 4.0 International (CC-BY-4.0)