快速上手
纸面与引擎都不发 npm、零构建、直指 TS/CSS 源码。站点以 git submodule 的方式把两个仓装进来,导入三张样式表,再把一个函数接进 astro.config——本站就是这么搭起来的。
§1.1一对 submodule
把两个仓装进来,再用 file: 依赖指过去:
git submodule add https://github.com/ventusff/astro-inkstone.git packages/astro-inkstone
git submodule add https://github.com/ventusff/astro-inkbrush.git packages/astro-inkbrush{
"dependencies": {
"@astrojs/mdx": "^7.0.5",
"astro": "^7.1.6",
"astro-inkstone": "file:packages/astro-inkstone",
"astro-inkbrush": "file:packages/astro-inkbrush"
}
}§1.2样式接入
站点全局样式表里,先 token、再阅读列、有导览页的站再加书架,之后只写你自己的 chrome:
@import 'astro-inkstone/styles/tokens.css';
@import 'astro-inkstone/styles/base.css';
@import 'astro-inkstone/styles/browse.css'; /* 落地页 / 分类页,挂在 body.wb-root 上 */
/* 身份定制:只覆盖第 1 层颜料,两套语义语境与组件层跟着走 */
:root {
--p-shi: #b03a48; /* 换成你的阅读列强调色 */
--p-zhu: #3b4a7a; /* 换成你的书架强调色与字标色 */
--p-shi-n: #e0919b; /* 夜间对应色:深色主题读的是 --p-*-n */
--p-zhu-n: #9fb0e4;
}书架用的衬线是 --font-display(Source Serif 4 + 思源宋体);像本站一样自托管,版头就和这里一模一样:
@import '@fontsource-variable/source-serif-4/opsz.css';
@import '@fontsource-variable/source-serif-4/opsz-italic.css';
@import '@fontsource-variable/inter/index.css';
@import '@fontsource/noto-serif-sc/400.css';
@import '@fontsource/noto-serif-sc/600.css';KaTeX 的样式在布局组件里补一行(数学站点必需,否则公式排版是散的):
import 'katex/dist/katex.min.css';§2.1markdown 管线一行接入
照本站形状写的最小配置——章节编号、数学、callout、图表,外加对着笔记集解析的 [[双链]](带全部钩子的完整版就是仓库里的 astro.config.mjs):
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import { normalizeBase } from 'astro-inkstone';
import { siteMarkdown } from 'astro-inkstone/markdown-preset';
import { buildWikilinkResolver, cachedScan } from 'astro-inkbrush/wikilinks';
const WIKI_MODE = process.env.WIKI === '1';
const inkbrush = WIKI_MODE ? (await import('astro-inkbrush')).inkbrush : null;
const BASE = normalizeBase(process.env.DEMO_BASE || '/'); // '/docs' 和 '/docs/' 都行
export default defineConfig({
site: 'https://example.com',
base: BASE || '/',
integrations: [mdx(), ...(inkbrush ? [inkbrush()] : [])],
markdown: siteMarkdown({
numbering: 'chapters', // Part/章节编号 + ToC 经 remarkPluginFrontmatter 取用
math: true, // remark-math + KaTeX
codeFrame: true, // 代码框:标题栏/复制/折叠/行标注
mermaid: true, // mermaid 代码块转客户端渲染
callouts: true, // Obsidian 风格 > [!note] 语法
wikiBlocks: WIKI_MODE, // 编辑模式:块↔源码行号映射,恒排管线最后
guard: { autoNumberedHeadings: true }, // 内容守门:拦手写编号
wikilinks: {
resolve: buildWikilinkResolver({
notes: cachedScan('src/content/notes'),
urlFor: (id) => `${BASE}/${id}/`,
locales: [{ code: 'en', prefix: '' }, { code: 'zh', prefix: 'zh/' }],
}),
},
}),
});siteMarkdown 的底座是引擎的方言(GFM、对中文友好的强调解析、内容守门),预设只负责站点侧插件的装配与顺序——管线顺序即契约,站点不必再关心谁先谁后。每个开关的效果,全要素演示一页全部演过一遍;包的三分边界见 boundaries。想要中文的 callout 标签?传 calloutLabels 即可——默认是英文。
§2.2跑起来
脚本就是本 demo package.json 里定义的那几个(build 的 postbuild 跑引擎 check-dist;wiki 即 WIKI=1 astro dev):
npm install
npm run dev # 园地本体
npm run build # 静态构建 + 引擎 check-dist 产物检查(postbuild)
npm run wiki # WIKI=1 astro dev,CMS 编辑模式静态构建里没有一个字节来自引擎:非 WIKI 模式下,引擎的集成代码连 import 都不会发生,编辑元数据也不输出。产物里唯一与 CMS 有关的,是站点自己的停靠位——导航栏里那几个空的 data-inkbrush-slot span 和对应的 CSS——CMS 不在时它们什么也不做。