mdFlow · Local Raw Site

FolderMark 本地 Raw 站点

文件一保存，站点自动更新

在 Windows 或 Ubuntu 上，让 FolderMark Local 长期监听 Raw Markdown；内容变化后自动调用 FolderMark 重新生成内容，再由 Local 自带的 HTTP Server 提供访问。个人设备已经通过 ZeroTier 组网时，不需要 Cloudflare Tunnel，也不需要额外安装 nginx、Caddy 或 Everything HTTP Server。

按默认目录开始安装 Local 配置模板 FolderMark 配置模板

Windows / Ubuntu默认端口 8080推荐仅绑定 ZeroTier IP

THREE RESPONSIBILITIES

Raw Markdown、FolderMark 与 Local 各做一件事

三者彼此独立。内容不需要复制进程序目录，FolderMark Local 也不再实现一套 Markdown 解析逻辑。

CONTENT

Raw Markdown

D:/markdown/inbox 是内容源。WebMark 或你使用的编辑器只需要在这里新增、修改、移动或删除 Markdown 与附件。

RUNTIME

FolderMark Local

监听文件系统、合并短时间内的变化、调用 FolderMark、维护成功内容快照，并提供 HTTP Server。它不解析 Front Matter。

RENDERER

FolderMark

唯一的 Markdown 解析与页面实现。它决定 id、cleanup、目录索引、文档路由、正文渲染与本地附件规则。

实际访问链路：浏览器 → FolderMark Local HTTP Server → FolderMark 静态前端 + Local 当前内容快照。Local 启动时完整构建一次前端；以后只有内容变化时，不会重复执行 Vite 前端构建。

DEFAULT LAYOUT

默认目录把程序与内容彻底分开

Windows 示例统一使用 D:。JSON 中推荐用正斜杠 /，这样不需要处理反斜杠转义。

D:/
├── markdown/
│   └── inbox/                 Raw Markdown
└── wwwroot/
    ├── FolderMark/
    │   └── config/
    │       └── foldermark.env
    └── FolderMark-Local/
        └── foldermark-local.json

默认约定

FolderMark：D:/wwwroot/FolderMark

FolderMark Local：D:/wwwroot/FolderMark-Local

Raw Markdown：D:/markdown/inbox

程序更新与内容备份可以因此采用完全不同的策略。

TWO CONFIGS

两份配置分开：运行环境归 Local，FolderMark 保留自己的接口

这是刻意的职责分离。主机地址、端口与监听目录不应该成为 FolderMark 静态站点的一部分；同样，Local 也不应该拥有 FolderMark 的解析规则。

FolderMark Local · JSON

`foldermark-local.json`

保存到 D:/wwwroot/FolderMark-Local/。Local 会直接读取它；所有相对路径都以这个 JSON 所在目录为基准。

{
  "server": {
    "host": "127.0.0.1",
    "port": 8080,
    "domain": ""
  },
  "foldermark": {
    "path": "../FolderMark"
  },
  "content": {
    "mode": "directory",
    "path": "../../markdown/inbox"
  }
}

下载完整 JSON 模板

FolderMark · ENV

`config/foldermark.env`

FolderMark 当前原生配置接口是三个 FOLDERMARK_* 环境变量，并不读取 config/*.json。所以这里用真正能被程序消费的 .env，不提供无效 JSON。

FOLDERMARK_MARKDOWN_ROOT=../../markdown/inbox
FOLDERMARK_PUBLIC_ROOT=public
FOLDERMARK_ORDER_LEDGER_PATH=data/content-order.json

这些相对路径由 FolderMark 进程的工作目录解析。按本页命令从 D:/wwwroot/FolderMark 运行即可。

下载 ENV 模板

谁优先？ 日常 Local 模式以 foldermark-local.json 为准。Local 在调用 FolderMark 时主动传入 Markdown 目录和本次内容快照目录，所以不需要 Local 与 FolderMark 共用一份配置。foldermark.env 主要用于单独运行 FolderMark 内容生成器、调试或脱离 Local 的直接构建。

`content.mode`	实际监听目录	适用场景
`directory`	`content.path`	推荐。直接监听任意外部目录，例如默认的 `D:/markdown/inbox`。
`foldermark`	`<foldermark.path>/markdown`	兼容把 Markdown 与 FolderMark 安装目录放在一起的传统方式；此时不需要填写 `content.path`。

需要独立验证 FolderMark 时，从 D:/wwwroot/FolderMark 执行：

node --env-file=config/foldermark.env scripts/build-content.mjs

WINDOWS INSTALL

Windows：按默认目录从零安装

需要 Node.js 22.12 或更高版本、npm 与 Git。下面只做第一次安装；正常使用不需要每天重新执行。

建立 Raw Markdown 目录

WebMark 或其他 Markdown 工具以后直接写入这里。

New-Item -ItemType Directory -Force D:/markdown/inbox
New-Item -ItemType Directory -Force D:/wwwroot

安装 FolderMark 与 FolderMark Local

cd D:/wwwroot
git clone https://github.com/zkzchb/FolderMark.git
git clone https://github.com/zkzchb/FolderMark-Local.git

cd D:/wwwroot/FolderMark
npm ci

cd D:/wwwroot/FolderMark-Local
npm ci

下载两份模板到各自位置

New-Item -ItemType Directory -Force D:/wwwroot/FolderMark/config

Invoke-WebRequest `
  https://my-work-flow.pages.dev/mdFlow/local/foldermark-local.example.json `
  -OutFile D:/wwwroot/FolderMark-Local/foldermark-local.json

Invoke-WebRequest `
  https://my-work-flow.pages.dev/mdFlow/local/foldermark.env.example `
  -OutFile D:/wwwroot/FolderMark/config/foldermark.env

如果只使用 Local，第二份 ENV 不是启动依赖；保留它便于独立验证 FolderMark。

填写 ZeroTier 监听地址
打开 foldermark-local.json，把默认 127.0.0.1 改成这台主机自己的 ZeroTier IP，例如 10.147.20.5。端口默认 8080；没有内部 DNS 时把 domain 保持为空。
检查配置，再启动
```
cd D:/wwwroot/FolderMark-Local
npm run check
npm start
```
第一次启动会执行一次完整 FolderMark 前端构建。看到启动地址和监听目录后，用本机浏览器先验证。

DAILY OPERATION

以后保存 Markdown 即可，不再手工 `npm run build`

Local 把本地文件监听变成了类似 CI/CD 的自动触发机制，只是触发源从 Git push 变成文件系统变化，而且整个过程都发生在自己的电脑上。

启动时

完整前端构建一次

FolderMark Local 执行一次 FolderMark 完整构建，确保 HTML / JS / CSS 与当前代码一致，然后启动 HTTP Server。

内容变化时

只重新生成内容快照

Markdown 或同目录附件变化 → 等待写入稳定 → debounce 合并事件 → 调用 scripts/build-content.mjs → 成功后原子切换快照。

生成失败时

旧站点继续工作

新快照只有成功完成才生效。一次 Markdown 解析失败不会让 HTTP Server 退出，上一个成功版本继续提供访问。

更新程序时

更新 FolderMark 后重启 Local

git pull 与 npm ci 后重启 FolderMark Local，让它重新进行一次完整前端构建。单纯更新 Markdown 不需要重启。

Windows 开机以后要不要手工运行？

不需要。第一次前台验证正常后，把 FolderMark Local 注册为当前用户登录时自动启动的计划任务：

cd D:/wwwroot/FolderMark-Local
powershell -ExecutionPolicy Bypass -File .\service\windows\install-task.ps1

FolderMark Local 由操作系统常驻；Everything 可以继续承担文件检索职责，但无需再让 Everything HTTP Server 负责 FolderMark 站点。

ZEROTIER NETWORK

只在 ZeroTier 上提供 HTTP，是这个私有站点最简单的边界

FolderMark Local 当前只提供 HTTP，没有用户认证与 TLS。你的场景中所有访问设备已经通过 ZeroTier 建立受控虚拟网络，因此建议直接绑定 ZeroTier IP，而不是开放到所有网卡。

配置	建议	原因
`server.host`	主机 ZeroTier IP	只在 ZeroTier 虚拟网卡监听。
`server.port`	`8080`	默认即可；冲突时换一个空闲端口。
`server.domain`	留空或内部名称	它只影响显示地址，不负责 DNS 解析。
`0.0.0.0`	不推荐	会同时监听其他 IPv4 网卡，扩大暴露面。
Cloudflare Tunnel	不需要	个人设备已能通过 ZeroTier 直接互访。

如果 Windows Defender Firewall 阻止来自 ZeroTier 的连接，只为该程序/端口和 ZeroTier 网络范围增加必要的入站规则；不要为了省事整体关闭防火墙。

UBUNTU / VPS

Ubuntu 使用同一架构，只替换路径与常驻方式

FolderMark Local 的配置结构完全相同。可以把程序放在 /opt、内容放在 /srv，然后用项目提供的 systemd unit 模板长期运行。

示例路径

/opt/FolderMark
/opt/FolderMark-Local
/srv/markdown/inbox

在 Local JSON 中可以直接使用绝对路径，也可以继续使用相对路径。

systemd

service/ubuntu/
foldermark-local.service.example

按项目文档填写用户与安装目录后，使用 systemctl enable --now foldermark-local 设置开机常驻。

FolderMark Local 模板 FolderMark Local FolderMark