本地运行的静态网站创建器,文档站与博客皆宜。
在本地写 Markdown，一键构建、本地预览、发布到 GitHub Pages。
- 两类站点 —— 新建时可选文档站点(侧栏目录导航,适合知识库与产品手册)或博客站点(首页为按日期排序的文章流,文章页带目录指引);站点类型可随时在站点设置中切换,主题列表自动按类型过滤,互不混用
- 内容管理 —— 文件夹与 Markdown 文档的树形管理,新建(可自定义标题)/重命名/删除(进回收站)/导入;拖拽移动带插入位置指示(行边缘 = 移动到该行所在目录,文件夹中部 = 移入该文件夹),拖到目标行上/下边缘即可手动排序(同目录重排、跨目录插入到目标位置,多选成组移动),顺序保存在
.plainstruct/order.json,构建站点的导航、目录页与上/下篇均按此顺序输出;支持多选:Shift 范围选择、Ctrl/⌘ 点选、批量拖拽移动,拖过折叠的文件夹稍候自动展开;「主页」固定置顶在文件树顶部;底部新增独立分割的资产栏(集中列出站点asset/中的图片,旧站点的images/同样识别,不进入站点输出),支持卡片与列表两种视图,按住任意图片拖入正文即可插入 Markdown 图片引用;文件按类型显示图标(Markdown 文档 / 图片);文档、文件夹与「主页」的悬停快捷按钮均含**「编辑配置头」(文件夹经其index.md,没有时自动创建文件夹页),文件夹另有「编辑文件夹页」**直达该文件夹的index.md编辑;右键文档与「主页」入口均可直接打开「编辑配置头」表单;文件树、编辑器与输入框均有专属右键菜单(新建/导入/重命名/删除、剪切/复制/粘贴/全选) - 编辑与实时预览 —— CodeMirror 6 编辑器与渲染预览左右对照,比例滚动同步,自动保存(停止输入后延迟落盘,延迟用滑块在设置中调整,保存状态区实时显示倒计时);格式工具栏一键插入标题/加粗/斜体/删除线/引用/列表/链接/图片/表格/代码块/首行缩进/硬换行,光标所在格式对应按钮自动亮起(标题按级别区分);点击链接按钮(或
⌘K)弹出插入链接配置窗口 —— 链接地址、显示文本与「在新窗口打开」可选({: target="_blank"}属性块自动转写,站外链接推荐),另有文字左/中/右对齐与图片左/中/右对齐按钮(以 HTML 对齐容器包裹,全部主题的正文样式显式支持,选区为图片时自动包裹、未选中时插入模板);插入图片可配置:插入图片时弹出配置窗口 —— 插入方式可选 Markdown 图片或 HTML 代码嵌入(HTML 下可设置图片位置(居中/左对齐/右对齐)、宽度与高度(百分比或像素)与图片 class,如mws_ps_imgpreview配合图片预览插件,宽度与高度直接填写80%、640px等带单位的值),并可确认/修改复制到站点的目标路径(content/相对,可含子目录,重名自动加序号)与 alt 文本;选取的本地图片自动复制进站点,光标处插入按当前文档位置换算的相对路径(子目录文档自动加../前缀),光标落在 front-matter 内时自动移到其后的正文区,构建与预览都能正确显示;从资产栏拖图到正文同样弹出配置窗口,确认后按落点插入;完整快捷键:⌘/Ctrl+1..6标题、⌘B加粗、⌘I斜体、⌘E行内代码、⌘K链接、⌘⇧X删除线、⌘⇧C代码块、⌘⇧7/8/9有序/无序/引用、⌘⇧T任务列表,Enter默认为硬换行(行尾两空格,空行同样生效,列表行自动续行)、Tab默认为添加首行缩进(Shift+Tab移除,缩进符数量可配置,中文常用 2 个全角空格),硬换行(¶)与首行缩进(⇥)支持可见标记显示,键位与标记均可在设置中调整;「编辑配置头」以表单弹窗可视化调整 front-matter(标题/描述输入框、自定义日期时间选择器(精确到秒)、封面图从站点资产(asset)建议中选择或一键导入,确认后写回,留空字段不写入,自定义字段保留;博客站点另可设页面目录三态 —— 跟随主题 / 强制显示 / 强制隐藏);新建文档弹窗内嵌配置头设置(标题/描述/日期/封面/作者署名/AIGC 一次填好,另含隐藏文档开关与博客站点的页面目录开关,署名输入框自动下拉列出站内已用过的作者署名供快速选择);配置头另支持作者署名与 AIGC 声明(author/aigc,三档:不显示/无任何 AIGC/存在 AIGC),十款主题在日期同一行渲染署名与 AIGC 徽标(「内容显示」配置组可分别开关);预览与构建共用同一渲染管线,所见即所得 - 资产管理 —— 文件树底部的资产栏(含各层子文件夹中的图片)与「资产」页集中管理站点
asset/文件夹(兼容旧images/)中的图片:左侧卡片网格、右侧悬浮圆角详情面板(大图预览与引用文档列表,点击直达对应文档,可折叠/展开,左缘把手可拖拽调宽);页面右上角提供**「导入图片」按钮**(选取图片文件统一复制进asset/,导入后自动选中,便于顺手移动到子文件夹),资产页接纳全部文件类型(不限于图片,仅可执行类被拒),也支持把文件从访达/资源管理器直接拖到资产页任意位置快速导入 —— 拖入时出现落点遮罩,松手即导入(重名自动加序号,不支持的文件类型自动跳过并提示);支持多选:在空白处按住拖动框选、Ctrl/⌘ 点选、Shift 连选,选中项可整批拖到文件夹标题上移动(或走「移动到文件夹…」弹窗),移动后文档中的引用路径自动重定向,右栏在多选时转为批量操作面板(合计大小、已选清单、批量移动与删除);新建的文件夹即使还没有图片也会列出(可往里拖图);子文件夹可整夹移出至系统回收站(弹窗二级确认,含引用失效提示);重命名时自动同步更新引用文档中的路径(有未保存修改的文档除外),删除提供引用失效提示与移入回收站的二级确认 - 站点管理 —— 站点名称、描述、两个独立 Logo、站点语言(写入
<html lang>,可选预设或自定义语言代号)与浏览器标题格式({page} · {site}占位符)均可配置;Logo 分为站点内 Logo(显示在网站页面里,尺寸与圆角由主题配置决定)与站点外图标(只用于浏览器标签页与收藏夹),两者独立设置、可分别移除,站点外图标未设置时自动沿用站点内 Logo - 一键构建 —— 产物为纯静态 HTML;所有站内链接与资源使用相对路径,部署到 GitHub Pages 仓库子路径、自定义域名或本地直接打开都不会乱;站点图片统一存放在
content/asset/文件夹(插入图片时自动复制进去,旧站点沿用images/),构建后原样输出为站点根下的asset/,Markdown 中的引用按所在页面位置自动换算;没有 index.md 的文件夹自动生成目录列表页;构建时全量链接校验,失效链接在报告中列出;报告含页面数、资源数、耗时与站点总占用大小;独立预览窗口升级为自绘壳层(不再用原生标题栏):浏览器式后退/前进/刷新与站点内路径地址栏;可在桌面端/移动端两种模拟环境间随时切换(切换不重载当前页) —— 桌面端模式即全幅浏览器视口,移动端模式把站点约束进机型预设的设备视口(默认 Google Pixel 8 412×915;机型预设按品牌分组,覆盖 2024–2026 常见机型 —— iPhone 16 / 17 系列、Galaxy S25 / S26、Pixel 9 系列、小米 15、荣耀 Magic7、Find X8、X200 等,同视口相邻代合并一项,也可自定义宽高与 DPR;随窗口缩放),指针点击以真实触摸事件送达页面,并支持安卓左缘侧滑返回(1:1 跟手,按位移与松手速度裁决提交/取消,已到首页时阻尼回弹);窗口右上角提供**「立即重新构建」按钮**(点击请求主窗口立即重建,不受防抖延迟影响,完成后原位刷新);窗口记忆位置与尺寸,构建刷新原位重载当前页(可开启「刷新时禁用动画」:应用内全部站点预览在自动重建刷新或重新渲染时跳过页面进场/加载动画,写作阅读不被反复打扰);内容页右上角的预览按钮:未开启时点击自动构建并弹出独立预览窗口,已开启时点击切换到独立窗口(最小化先还原)而不关闭 —— 独立窗口只有用户主动关窗这一条关闭途径,窗口右上角的**「返回软件界面」按钮**点击切回主窗口(同样不关闭独立窗口);构建失败时不弹出预览窗口,避免壳层加载到过期或缺失的产物;文档保存与主题/主题配置变更后自动防抖重建,构建预览与产物始终保持最新;预览中正文手写的 iframe 内嵌显示占位提示(发布站点后正常渲染,外链与站内地址均在构建时按页面相对地址正确改写) - 主题系统 —— 内置十款主题:文档站点用「素构 · 浅色」「素构 · 暗色」(侧栏布局)、「墨阅」(报刊衬线风)、「终端」(命令行风)、「画廊」(卡片现代风),博客站点用「素记 · 浅色」「素记 · 深色」(卡片式文章流)、「专栏」(杂志衬线报头)、「日志」(极客等宽深色)、「留白」(极简黑白居中),全部支持卡片/列表式文章流、每页篇数配置与页码切换、文章页 TOC;博客主题的右上角导航可自定义(选择显示哪些文章/文件夹,并可设最多显示数量,顶栏不再被挤满;选择器中文件夹默认折叠、点箭头展开,文件夹内的页面也可直接勾选;每个选中项可自定义顶栏显示名(输入框以原名称为占位提示,改了名也对得回原文),与页面真实标题独立,留空显示原标题;每个选中项可拖动把手调节顶栏顺序(悬停实时重排),「归档」常驻选择器并默认参与排序与重命名,行内眼睛开关控制其显示/隐藏),未设置封面图的文章默认显示文档图标占位封面,另提供文章卡片并排列数、封面图高度、固定封面图显示比例(按 16:9 / 3:2 / 4:3 / 1:1 统一裁切,开启后替代封面图高度)、顶栏宽度(百分比,随窗口自适应)与顶栏变形后宽度(均与正文宽度解绑) —— 卡片并排、封面图高度、顶栏宽度、顶栏变形后宽度(窄屏以百分比替代桌面端像素值)与正文字号、卡片流字号(文章卡片标题/日期/描述随其等比缩放,配置在「卡片外观」组)均区分桌面端 / 移动端(≤640px)两档独立设置,主页分类卡片流可设每组最多显示篇数(超出时组尾出现「查看更多」进入该分类页);可选移动端顶栏目录按钮 —— 开启后窄屏时顶栏导航收进按钮(与搜索按钮同款扁圆角矩形条,按钮大小/圆角/填充色/填充不透明度与下拉列表文字对齐均可配置),另有站点标识顶栏居中(移动端专属,Logo 与站点名在顶栏水平居中)以及文章目录设置(启用开关、目录树风格、目录悬停动画预设;博客文档可在配置头中按篇覆盖 —— 强制显示 / 强制隐藏 / 跟随主题,隐藏(或正文无标题)后正文占满整行不留空位)等布局配置 —— 「顶栏变形后宽度」仅在顶栏滚动形态为药丸或圆角矩形时出现,独立控制顶栏浮起时收成多宽;顶栏可选显示当前页面标题(文章页显示、首页不显示、窄屏自动隐藏);顶栏滚动动画可调(变形曲线、变形时长、触发滚动的安全区与顶栏背景 —— 背景颜色、模糊程度与填充不透明度均支持);主页卡片流宽度可调(50–100%,相对窗口内容宽 —— 100% 即窗口全宽,与正文宽度解绑,移动端可单独设置);以及品牌与动效配置 —— Logo/站点标题单独开关、Logo 宽/高(像素)与圆角可调(移动端 Logo 宽/高 ≤640px 可单独设置)、Logo/标题/导航各自的悬停反馈(淡化/放大/强调色/下划线/底色等)与正文链接悬停反馈(无/加深/底色)、文章卡片一般与悬停两态阴影(预设无/轻/中/深,或自定义 X/Y 偏移、模糊、扩散与不透明度;两态的阴影颜色各自可设,用自定义取色器选色 —— 预设档位同样生效,深色主题可换成浅色阴影)与卡片悬停反馈(无/上浮/下沉/放大/缩小/淡化/倾斜)及其过渡曲线与时长(标准/缓出/缓入/线性/弹性,或自定义 cubic-bezier 与 80–800ms)、卡片入场动画(关闭/淡入/上浮/交错上浮,交错上浮按卡片顺序依次浮现)与封面图悬停反馈(无/微放大/放大/淡化)、跳转页面时的页面加载动画(转圈/点点/进度条,可关闭);博客主题的页脚可配置 —— 页脚说明文字、构建日期与时间显示(格式可自定义,
{date}/{time}/{version}令牌按钮一键插入,构建与预览时自动替换为实际值,缺省展示构建时刻、可按需加回版本令牌)与友情链接(可视化逐条编辑,名称可留空(有图标时渲染为纯图标链接),图标可选、支持从站点资产选择,也兼容外链 URL);全部主题支持正文字体切换(系统/衬线/等宽/自定义 font-family);文档可显示 front-matter 日期(主题内可开关);目录支持折叠(跨页记忆展开状态,当前页所在目录自动展开),页面过渡动画预设(十款主题齐备),可选「由 Plainstruct 创建」底部署名;文档主题的悬停反馈与动效 —— 「素构 · 浅色 / 暗色」「墨阅」「终端」「画廊」同样提供导航 / Logo / 站点名 / 正文链接 / 上下页卡片的悬停反馈档位(默认与各主题原样式一致)、页面加载动画与正文字号桌面端 / 移动端(≤900px)双档独立设置;侧栏当前文档效果可选(默认 / 无 / 底色 / 强调色 / 加粗 / 下划线,默认保持主题原样式,强调色下划线随主题强调色);侧栏折叠开关位置可配置 —— 桌面端可选侧栏内部右下角(缺省)/ 左下角 / 隐藏,移动端可选抽屉顶部(缺省,抽屉头部的圆形收起按钮,与点击遮罩等效)/ 隐藏,双端独立设置;顶栏扩展 —— 「顶栏下拉变形」(无/药丸/圆角矩形,向下滚动后顶栏浮起变形,移动端顶栏与桌面端顶栏同步生效)、「顶栏显示」(桌面端:列表栏折叠时自动显示顶栏[缺省]/常显/不显示,顶栏自顶部非线性下移出现、展开时收回,过渡连贯)与「当前文档标题对齐」(移动端顶栏第二行右对齐/居中/左对齐);站点标识配置 —— 站点 Logo 与站点标题的显示开关、Logo 大小(像素)与 Logo 位置(标题左侧 / 标题上方),桌面端与移动端(≤900px,含抽屉头部与顶栏)双端独立设置,「墨阅」的块式站点标识也可切换为横向;移动端顶栏的目录按钮与搜索按钮同款(60×36 扁圆角矩形条,同毛玻璃材质、描边与阴影),当前文档标题显示在站点标识正下方(顶栏第二行右对齐,与站点标题 / Logo 同轴,站名过长自动截断);「终端」「画廊」「墨阅」可调侧栏宽度,素构 · 浅色 / 暗色可调正文宽度,五款文档主题均可设移动端抽屉宽度(%)(≤900px);文档主题也有**「页脚」配置组**(页脚说明、构建信息显示与格式、友情链接,与博客主题同构);可视化配置面板按分类分组,顶部有吸顶的分类按钮,点击即跳到对应分组;支持颜色/字号/选项/开关(颜色改用自定义取色器 —— 触发器即色块加十六进制值,面板内含饱和度/明度区与色相条,拖动取色、也可直接键入色值;数值支持双击原地直接输入与偏离默认值时的一键重置);主题制作器(代码编辑 + 实时预览,右侧预览可点击站内链接直接浏览各页面);主题以 ZIP 包导入导出 - 站点插件 —— 插件与主题解耦,以站点为单位在主题配置面板的「插件」分组统一管理,对所有主题(含自定义主题)全局生效;内置两款,默认开启:站内搜索(搜索入口形式与位置可配置 —— 按钮式 / 长条文本框,页面右下角 / 左下角 / 顶栏最右侧,PC 与移动端可分别设置,移动端未设置时沿用 PC 配置,顶栏入口与目录按钮同款扁圆角矩形条,
⌘/Ctrl+K呼出;长条文本框可直接在入口输入文本,回车或点击搜索后才弹出结果面板,宽度双端独立可调(160–420px,移动端缺省沿用 PC,窄屏自动收窄不溢出);文档站点主题在「顶栏最右侧」时,PC 端搜索框改在侧栏站点标题下方整行展示,窄屏自动迁回顶栏;构建时自动生成全站搜索索引(标题/描述/正文),输入即搜、结果高亮命中片段,↑↓选择、Enter打开;面板明暗跟随站点配色,强调色沿用主题配置)与图片预览(点击正文图片进入灯箱 —— 从源图位置展开、关闭原路返回;滚轮/双指/双击缩放、1:1 拖拽平移带惯性(预览期间背景页面滚动锁定,移动端拖动只作用于图片,并禁用网页本身的双指/双击缩放,双指缩放只作用于图片),±90°旋转、渲染方式切换(像素渲染为点对点显示 —— 关闭插值直接放原图,与抗锯齿模式同一套缩放/拖拽/旋转手势与动画,无额外倍率限制,重绘按帧合批,移动端也流畅;抗锯齿渲染为默认平滑放大)、同源下载,Esc或点击背景关闭;灯箱内显示文件名 · 分辨率 · 文件大小;可选 class 标记模式 —— 配置后仅 class 含该标记的图片可预览,未标记的图片也不再显示放大光标);支持导入自定义插件:任意.js/.css(可多选合并为一个条目)保存到.plainstruct/plugins/,构建时拷入产物并在每个页面加载,可逐条启用/停用与删除 - 个性化外观 —— 应用本身提供浅色、暗色、素笺、青瓷、深海、紫檀六套配色与跟随系统,设置页以配色预览卡片挑选,即改即生效;弹窗背景模糊可开关(默认开,系统「减弱透明度」时自动退化为纯色);弹窗空白区域点击可配置(个性化设置可选) —— 默认点击两次空白区域关闭弹窗(首次点击轻提示「再次点击空白区域即可关闭窗口」,点进弹窗内重新计数,防误触),也可改为点击一次关闭或点击后不关闭;关窗前若弹窗内表单有未保存改动,先弹窗询问保存并关闭 / 不保存 / 取消(适用于配置头编辑、插入图片/链接、重命名与新建、文件夹页面配置等表单弹窗,新建站点向导等自绘弹窗同样支持空白点击关窗);界面与编辑器字体可选系统默认/衬线/等宽/自定义,另提供界面字号(预设档位或自定义 85–130%)与界面字重(预设档位或自定义 400–600)设置
- GitHub Pages 发布 —— 使用个人访问令牌,通过 GitHub API 把构建结果作为单次原子提交推送到仓库,自动创建仓库/分支/开启 Pages,无需安装 Git;发布配置可直接设置自定义域名(发布时写入 CNAME,格式即时校验,「查看站点」直达域名;留空则保留云端已有的自定义域名与 .nojekyll,覆盖发布不会清掉域名);发布前先选账户类型 —— 个人用户的仓库建在自己账号下(走
/user/repos),组织的仓库建在组织下(走/orgs/{组织}/repos),两种账户不再混用一条接口;「验证连接」会核对账户类型与 GitHub 上的实际账号是否相符(组织名填成个人、反之亦然,都会当场点明),组织仓库无权访问(403)时给出具体原因(令牌未授权该组织、组织不允许成员建仓或组织禁用了 Pages,均逐条落到运行日志);发布失败时提示 GitHub 返回的具体原因;发布成功的一刻有短暂的纸屑庆祝动效(程度可在设置中调整:轻/标准/夸张,或关闭),随后自动监听 Pages 构建 —— 完成后亮起「查看站点」并弹出提示,发布按钮居中加宽,发布中为外圈纯扩散 + 中心加载环的非线性动效(两道错相圆环长尾渐隐,循环无缝);发布成功后大按钮转为绿色打勾,此时点击它不再重新发布,而是先看 Pages 构建状态:已完成则弹窗询问「是否前往查看已发布的站点？」(前往查看 / 稍后再说),未完成则提示「请耐心等待 Pages 构建完成,稍后方可访问已发布的站点。」(状态未知时点击先单次检测再分流);重新发布由下方浮现的专用圆形按钮承担,点击先弹确认询问(确认后重新提交全站,防误触覆盖);主界面左上角的状态区同步即时显示这些进展 —— 标题栏品牌区即时呈现保存状态(自动保存倒计时、保存中、已保存、未保存提醒)与发布进展(发布中 done/total、Pages 构建中、失败提示),空闲时轮换显示素构吉祥物的问候语,发布成功后播报祝福语(片刻后回到问候);鼠标悬停品牌区浮现快捷入口 —— 「返回主菜单」固定在 logo 所在角落(Windows 左上角 / macOS 右上角),「查看发布状态」「预览站点」依次排在其后(竖线分隔并留出空隙,存在发布上下文时才出现查看入口),点击直达对应功能;站点构建完毕后追加的**「预览站点」**点击打开/切到独立预览窗口;macOS 顶栏左右各留 12px 边距 —— 左上角原生红绿灯与右上角品牌区(问候语与 logo)以对称内缩在两角对角呼应、不贴边,并保持垂直居中 - 应用更新检查 —— 设置页一键检查更新,对比 GitHub 最新 Release,提示新版本、发布说明与发布时间;检测到新版本可一键下载(支持暂停与断点续传),完成后「重启并更新」拉起更新向导 —— 由向导关闭应用、覆盖安装并自动启动新版本
- 启动自愈 —— 启动失败自动分级恢复:先自动重载,仍失败则清理浏览器缓存后重载,依旧失败才显示诊断信息交人工反馈,界面层数据损坏导致的白屏多数无需手动处理;设置 → 数据另提供「清除浏览器缓存」一键急救
- 本地优先 —— 所有数据保存在你选择的站点文件夹内,备份即复制;无后端、无遥测
- 中英双语界面 —— 标题栏一键切换
素即素净,构即结构:灰白主色、单一墨色强调、系统字体栈、4px 基准网格、8px 圆角、统一缓动 cubic-bezier(0.23, 1, 0.32, 1)。无渐变、无发光、无多余装饰,层级全部来自字号、字重与留白。表单控件统一自绘 —— 下拉选择以浮出面板呈现,方向键即可选择、选中项带对勾标记;滑动条以 4px 轨道与墨色进度填充呈现,拇指按压即放大并泛出光圈;勾选框勾选时以墨色实底填充、对勾弹性弹出;取色器为自绘浮层,触发器是色块加十六进制值,面板内饱和度/明度区与色相条按下即取色、拖动 1:1 跟随指针(拖动中的取样值节流落盘,视觉零延迟);键盘焦点圈都落在控件本身。
从 GitHub Releases 下载对应平台的安装包:
- Windows x64:免安装版 zip(
Plainstruct-版本号-Windows-x64-Portable.zip,解压后双击plainstruct.exe),自动更新也以此包覆盖升级 - macOS(Apple Silicon):dmg 磁盘镜像(拖入「应用程序」)或 zip 压缩包(解压后移入「应用程序」),两者均附「损坏修复.command」。应用为 ad-hoc 签名、未经 Apple 公证,首次打开若提示「已损坏」,双击包内的**「损坏修复.command」**并输入开机密码(仅用于移除隔离标记)即可;也可在终端手动执行
sudo xattr -r -d com.apple.quarantine /Applications/Plainstruct.app。本软件开源,该修复仅移除 Gatekeeper 对未公证应用的「隔离」标记,不改动应用内容
首次使用:
- 「新建站点」—— 选择文档站点或博客站点,填写站点名称,选择一个空文件夹
- 在左侧文件树新建文档,开始写作(用
---包裹的 front-matter 声明标题/描述/日期;把文档拖到目标行的上/下边缘即可排序) - 「构建」页一键构建,即可实时预览最终站点
- 「主题」页挑选或定制主题(列表会按站点类型过滤)
- 「发布」页选择账户类型(个人用户 / 组织),填入用户名(或组织名)/仓库名/访问令牌,一键发布
在 GitHub Settings → Developer settings → Personal access tokens 创建,勾选 repo 权限即可。令牌仅保存在站点文件夹的 .plainstruct/github.json 中,不会上传到任何地方;请在私人设备上使用。
发布到组织时请在发布页把账户类型切到「组织」,并让令牌获得该组织的授权:经典令牌创建时勾选组织;细粒度令牌需选择该组织并授予仓库读写权限(Administration / Contents),且组织需允许成员创建仓库。若组织禁用了 GitHub Pages,内容仍会正常推送,但需在组织设置中放开 Pages 或手动开启。
<你的站点文件夹>/
├── content/ # 文档与资源(可随时用其他编辑器打开)
│ ├── index.md # 站点首页
│ └── asset/ # 站点图片资产(插入图片自动复制到这里)
│ └── guide/
│ ├── index.md # 目录落地页(导航里文件夹标题取自它的 title)
│ └── setup.md
├── .plainstruct/ # 素构配置
│ ├── site.json # 站点配置(名称/描述/双 Logo/主题/语言)
│ ├── github.json # 发布配置(含令牌,注意保密)
│ ├── order.json # 文档手动排序(拖拽内容树自动生成)
│ ├── themes/ # 自定义主题
│ └── plugins/ # 站点插件(导入的 .js/.css,构建时拷入产物)
└── build/ # 构建输出(可整删重建)
路径映射规则:index.md → index.html、foo.md → foo.html、foo/index.md → foo/index.html;文档间链接直接写 .md 相对路径,构建时自动改写为 .html。没有 index.md 的文件夹会在构建时自动生成目录列表页(<目录>/index.html),列出该文件夹下的全部文档与子目录;导航与目录页中的文件夹标题均可点击跳转。
Front-matter 支持 title(标题)、description(描述)、date(日期)、cover(封面图,写图片路径或外链,博客站点的文章流会展示,如 2026-09-26,原样展示,可在主题配置中开关显示)、author(作者署名,文档页展示)与 aigc(AIGC 声明:none = 无任何 AIGC、present = 存在 AIGC,缺省不显示;主题以徽标呈现「本文由 AI 辅助生成」或「本文无任何 AIGC」,与日期同行展示)、hidden(隐藏文档:不进文章流与侧栏导航、不入搜索索引,仅可通过链接访问,博客顶栏自定义导航仍可展示);博客站点首页的文章流按日期倒序排列,无日期的文章排在有日期之后)。文档排序不依赖 front-matter:在内容树中把文档拖到目标行的上/下边缘即可手动排列,顺序保存在 .plainstruct/order.json(旧版 front-matter 的 order 字段已不再参与排序)。
博客站点的首页即文章流:文章以卡片呈现(标题、日期与副标题),新建文档时可填写副标题(写入 front-matter 的 description),每篇文章可在配置头用 cover: 指定封面图(相对文档路径或外链),文章流卡片会展示封面;每页文章数可在主题配置中调整(3–30 篇),超出时自动生成 page/N/ 分页页并提供页码与上/下页切换;文章页右侧提供页内目录(TOC,自动提取 h1–h6 各级标题,滚动时高亮当前章节)——目录可在主题配置中整体开关,另有目录树风格(缩进线 / 树形分支 / 极简,悬停小彩条按形状适配)与目录悬停动画(无 / 滑入 / 微移 / 底色)可选;点按目录即时滚动到对应标题,并停在吸顶顶栏之下,点按跳转动画(滑动 / 淡化过渡 / 无动画)与曲线、时长均可在主题配置中调整;博客主题提供置顶按钮(位置可选,与搜索入口同角时自动竖列并排);首页若存在根目录 index.md,其正文会显示在文章流上方,可作为博客公告栏使用;主页的「编辑配置头」提供主页专属配置:开启**「卡片流按分类分组」后卡片流按分类分组展示(分类取自顶层文件夹,有 index.md 的以其标题命名,组标题可点击进入分类页;分组显示整流展示不再分页),并可开关「显示未分类文章」与自定义「未分类」的组标题**;写入 front-matter 的 homeGroups / homeUncategorized / homeUncategorizedLabel 字段,预览与构建同源生效。每个没有 index.md 的文件夹自动生成独立落地页,缺省以文章卡片流展示文件夹内的文章,页内可在卡片流 / 目录列表两种视图间切换(初始高亮与默认视图一致),卡片流顶部有筛选框(按文本即时过滤)与排序控件(默认排序 / 更新日期 / 发布日期 / 标题,正序倒序一键切换);文件夹页可直接编辑 —— 「编辑文件夹页」打开该文件夹的 index.md(没有时自动创建),博客站点的文件夹页保留卡片流、正文渲染在卡片流上方;文件树右键文件夹可把显示方式设为该页的默认视图;站点还自动生成归档页(全部非隐藏文章,支持列表 / 分类 / 卡片流三种视图切换),主题配置可开关顶栏的**「归档」入口**。顶栏右上角的导航默认显示全部顶层文章与文件夹,可在主题配置中改为自定义选择(勾选要显示的项,顺序随内容树),并受「最多显示」数量(1–12 项,默认 6)约束,任何模式下超出一律截断,顶栏不会被挤满。编辑器实时预览中,点击按钮或预览无法呈现的链接(如分页页)会提示仅供预览,查看完整站点请前往「构建」页。
主题是一个 ZIP 包,结构如下:
theme.zip
├── theme.json # 元数据与配置面板 schema(必填)
├── templates/
│ ├── layout.hbs # 整页布局(必填)
│ └── page.hbs # 正文区模板(可选,默认直接输出 content)
├── partials/ # Handlebars 局部模板,按文件名注册(可选)
└── assets/ # 样式/脚本等资源,经 {{asset}} 引用
{
"id": "my-theme",
"name": "我的主题",
"version": "1.0.0",
"author": "you",
"description": "主题说明",
"type": "docs",
"config": [
{ "key": "accentColor", "label": "强调色", "type": "color", "default": "#333333", "category": "颜色与字体" },
{ "key": "sidebarWidth", "label": "侧栏宽度", "type": "number", "default": 260, "min": 200, "max": 360, "step": 10 },
{ "key": "bodyFont", "label": "正文字体", "type": "select", "default": "system", "options": ["system", "serif"] },
{ "key": "showDescription", "label": "显示站点描述", "type": "boolean", "default": true }
]
}字段类型:color / text / number / select / boolean。config 数组会自动生成可视化配置面板;每个字段可加 "category": "分组名",面板会按分类分组并在顶部提供快速跳转按钮。type 声明主题适用的站点类型(docs / blog,缺省 docs),主题列表会按当前站点的类型过滤。
layout.hbs 与 page.hbs 内可用以下数据:
内置 helper:asset、eq;partials/ 下的 .hbs 按文件名注册为局部模板(如 partials/nav.hbs → {{> nav}}),支持递归调用。
在「主题」页可以:复制内置主题为新主题 → 在制作器里编辑模板/样式并实时预览 → 导出 ZIP 分享;他人导入 ZIP 即可使用。
环境要求:Node 20+、Rust;Windows 需 VS Build Tools(C++ 工作负载),macOS 需 Xcode Command Line Tools(xcode-select --install)。
npm install # 安装前端依赖
npm run dev # 纯浏览器开发(内置 mock 演示站点,无需 Rust)
npm run tauri dev # 完整桌面应用开发
npm run check # vue-tsc 类型检查
npm run build # 前端类型检查 + 生产构建
cargo check # 在 src-tauri/ 下,Rust 编译检查
npm run icons # 由 icon.png 生成全套应用图标
npm run windows:portable # Windows x64 免安装构建 -> release/Plainstruct_版本号_Windows_x64_Portable.zip
npm run tauri -- build # 平台产物(dmg / app)- 前端:Vue 3 + TypeScript + Vite + Pinia + Tailwind CSS 4(自定义素构令牌);编辑器 CodeMirror 6;渲染 markdown-it + highlight.js;模板 Handlebars
- 桌面:Tauri 2(Rust)。文件 IO、ZIP、GitHub API 在 Rust 命令层;
site://自定义协议直读站点文件夹,构建预览与发布产物完全一致 - 无后端:应用状态存于程序根目录的
data/文件夹(便携式,数据随程序走;该目录不可写时自动回退系统应用数据目录),站点数据全部在站点文件夹内
├── public/ # 应用 Logo:logo.svg(单标)/ logo-full.svg(全字标,含 -dark 暗色变体)
├── scripts/ # 图标生成(含 macOS 满铺图标适配)/ 免安装打包脚本
├── src/ # 前端源码
│ ├── ipc/ # Tauri IPC 封装 + 浏览器 mock
│ ├── lib/ # 路径映射 / Markdown / 主题引擎 / 构建管线
│ ├── themes/ # 内置主题(plain-light / plain-dark / ink / terminal / gallery / blog-light / blog-dark)
│ ├── stores/ components/ views/ i18n/
└── src-tauri/ # Rust 桌面层(命令 / 协议 / GitHub 同步)
Plainstruct 素构 by MogroWang Studio。主题模板接口与 ZIP 格式可供第三方自由扩展。