调色板
通过 themeColor / themeColorLight 覆盖深色或浅色调色板:
blogTheme({
themeColor: {
primary: string;
secondary: string;
bg: string;
surface: string;
}
themeColor: {
primary: stringprimary: '#fb923c',
secondary: stringsecondary: '#dc2626',
bg: stringbg: '#1a0a00',
surface: stringsurface: '#2d1200',
},
themeColorLight: {
primary: string;
bg: string;
surface: string;
}
themeColorLight: {
primary: stringprimary: '#c2410c',
bg: stringbg: '#fef9f0',
surface: stringsurface: '#fde8c8',
},
}) 未设置的字段保持主题默认。运行时会作为 CSS 自定义属性注入到 [data-theme="dark"] .sp-blog-root 和 [data-theme="light"] .sp-blog-root 作用域。
CSS 自定义属性
所有组件都读取这些变量,你可以在自己的样式里覆盖以做精细调整:
| 变量 | 用途 |
|---|---|
--sp-blog-bg | 页面背景 |
--sp-blog-surface | 卡片/侧边栏背景 |
--sp-blog-border | 分隔线、卡片边框 |
--sp-blog-text | 主文本(标题) |
--sp-blog-content | 正文 |
--sp-blog-muted | 元信息文本(日期、计数) |
--sp-blog-primary | 主色(链接、标签、按钮) |
--sp-blog-secondary | 辅色 |
替换组件
src/routes/ 下的脚手架文件会从 @sveltepress/theme-blog/components/* 导入组件。要替换其中任意一个——比如文章卡片——编辑 src/routes/+page.svelte,换上你自己的组件:
<script lang="ts">
import
type MyGrid = SvelteComponent<Record<string, any>, any, any>
const MyGrid: LegacyComponentType
MyGrid from '$lib/MyGrid.svelte'
const { const data: anydata } =
function $props(): any
namespace $props
Declares the props that a component accepts. Example:
let { optionalProp = 42, requiredProp, bindableProp = $bindable() }: { optionalProp?: number; requiredProps: string; bindableProp: boolean } = $props();
$
function $props(): any
namespace $props
Declares the props that a component accepts. Example:
let { optionalProp = 42, requiredProp, bindableProp = $bindable() }: { optionalProp?: number; requiredProps: string; bindableProp: boolean } = $props();
props()
</script>
<const MyGrid: LegacyComponentTypeMyGrid posts: anyposts={const data: anydata.posts} /> 主题重新导出了以下可复用组件:
@sveltepress/theme-blog/GlobalLayout.svelte@sveltepress/theme-blog/PageLayout.svelte@sveltepress/theme-blog/PostLayout.svelte@sveltepress/theme-blog/components/MasonryGrid.svelte@sveltepress/theme-blog/components/Timeline.svelte@sveltepress/theme-blog/components/Pagination.svelte@sveltepress/theme-blog/components/Sidebar.svelte@sveltepress/theme-blog/components/SearchModal.svelte@sveltepress/theme-blog/components/ReadingProgress.svelte@sveltepress/theme-blog/components/GiscusComments.svelte@sveltepress/theme-blog/components/RelatedPosts.svelte@sveltepress/theme-blog/components/TaxonomyHeader.svelte@sveltepress/theme-blog/components/AuthorCard.svelte@sveltepress/theme-blog/components/AuthorProfile.svelte
数据模块
包内为脚手架路由使用的虚拟模块提供了 TypeScript 声明。主要自定义入口如下:
| 模块 | 导出 |
|---|---|
virtual:sveltepress/blog-posts-meta | posts: BlogPostMeta[] |
virtual:sveltepress/blog-tags-index | tags: Array<{ name, count }> |
virtual:sveltepress/blog-categories-index | categories: Array<{ name, count }> |
virtual:sveltepress/blog-config | blogConfig: BlogThemeOptions |
单篇文章、标签和分类数据也可通过 virtual:sveltepress/blog-post/<slug> 等字面量模块 ID 访问。virtual:sveltepress/blog-runtime 包含服务端 load 使用的绝对缓存路径,不能导入客户端组件。
子路径部署
在 svelte.config.js 读取 BASE_PATH,在 vite.config.ts 读取 SITE_URL:
export default {
kit: {
paths: {
base: process.env.BASE_PATH ?? '',
relative: false,
},
},
} blogTheme({
base: stringbase: var process: NodeJS.Processprocess.NodeJS.Process.env: NodeJS.ProcessEnvThe process.env property returns an object containing the user environment.
See environ(7).
An example of this object looks like:
{
TERM: 'xterm-256color',
SHELL: '/usr/local/bin/bash',
USER: 'maciej',
PATH: '~/.bin/:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin',
PWD: '/Users/maciej',
EDITOR: 'vim',
SHLVL: '1',
HOME: '/Users/maciej',
LOGNAME: 'maciej',
_: '/usr/local/bin/node'
}
It is possible to modify this object, but such modifications will not be
reflected outside the Node.js process, or (unless explicitly requested)
to other Worker threads.
In other words, the following example would not work:
node -e 'process.env.foo = "bar"' && echo $foo
While the following will:
import { env } from 'node:process';
env.foo = 'bar';
console.log(env.foo);
Assigning a property on process.env will implicitly convert the value
to a string. This behavior is deprecated. Future versions of Node.js may
throw an error when the value is not a string, number, or boolean.
import { env } from 'node:process';
env.test = null;
console.log(env.test);
// => 'null'
env.test = undefined;
console.log(env.test);
// => 'undefined'
Use delete to delete a property from process.env.
import { env } from 'node:process';
env.TEST = 1;
delete env.TEST;
console.log(env.TEST);
// => undefined
On Windows operating systems, environment variables are case-insensitive.
import { env } from 'node:process';
env.TEST = 1;
console.log(env.test);
// => 1
Unless explicitly specified when creating a Worker instance,
each Worker thread has its own copy of process.env, based on its
parent thread's process.env, or whatever was specified as the env option
to the Worker constructor. Changes to process.env will not be visible
across Worker threads, and only the main thread can make changes that
are visible to the operating system or to native add-ons. On Windows, a copy of process.env on a Worker instance operates in a case-sensitive manner
unlike the main thread.
env.string | undefinedSITE_URL ?? 'http://localhost:4173',
// ...
}) 同时设置两个变量进行构建,例如部署到 GitHub Pages 项目站点 user.github.io/repo/blog:
BASE_PATH=/repo/blog SITE_URL=https://user.github.io/repo/blog \
pnpm build 主题组件中的所有内部链接都使用 SvelteKit 的 $app/paths base,因此在子路径下也能正确解析。OG 图片 URL 与 RSS 条目 URL 使用 SITE_URL,确保社交平台爬虫拿到的是完整绝对路径。
增加页面
src/routes/ 下脚手架未占用的一切都是你的。保持 src/routes/+layout.svelte 不动即可让自定义页面自动被 GlobalLayout 包裹——每个路由都会渲染在侧边栏 + 主网格之内。