README file from
GithubPoster Wall
Poster Wall 是一个 Local First 的 Obsidian 插件。它把包含指定标签的 Markdown 笔记展示为响应式海报墙，不需要 Dataview、Bases 或独立媒体数据库。
当前版本：1.1.0
当前版本只在 macOS 和 Obsidian 1.12.7+ 上进行支持性测试。插件被标记为桌面端专用；它可能在 Windows 或 Linux 上运行，但暂不承诺支持。
功能
- 按一个或多个标签展示笔记，父标签自动包含层级子标签。
- 按标题或 Vault 路径搜索，支持最近修改和名称排序。
- 点击海报打开原始笔记，
Command点击在新标签页打开。 - 在卡片上直接设置或清除 0.5–5 星评分；点击星星左右半区可选择半星，评分保存在插件数据库中。
- 鼠标悬停或键盘聚焦卡片时翻面，背面显示标题、评分和分享文字。
- 封面优先级：Property → 插件数据库 → 正文第一张 Markdown 图片 → 占位图。
- 支持 Vault 图片、
[[wikilink]]、HTTPS 图片和从 Finder 导入图片。 - 监听笔记、附件与文件夹的创建、删除和重命名；编辑标签、Property 或正文图片后自动刷新。
- 默认不修改 Markdown 正文或 Properties。
使用
- 在 Obsidian 中启用 Poster Wall。
- 打开 设置 → 社区插件 → Poster Wall。
- 添加要展示的标签，例如
#读书、#电影。 - 点击左侧 ribbon 的网格图标，或在命令面板执行“打开海报墙”。
卡片翻面与分享文字
卡片正面展示封面。鼠标移入或键盘聚焦卡片后，卡片会翻到背面，显示标题、评分和短评。点击卡片仍然可以打开原始笔记。卡片上的图片按钮用于添加或修改插件数据库封面；如果笔记已有有效的封面 Property，Property 保持权威，插件会提示你在笔记中修改它。
分享文字默认读取笔记 Properties 中的 summary 字段：
summary: "这是一句适合展示在卡片背面的短评。"
如果没有该字段，插件会使用正文中的第一段可读文字作为兜底。可以在设置中把“分享文字字段”改成其他 Property 名称。当前版本只负责在卡片背面展示文字，不包含分享按钮、图片导出或网页生成。
默认设置
- 封面字段：
cover - 分享文字字段：
summary - Finder 图片导入目录：
PosterWall/Covers - 支持的导入格式：PNG、JPEG、WebP、GIF、AVIF、SVG
数据与隐私
插件通过 Obsidian 的 loadData()/saveData() 将自身设置、封面覆盖和评分保存在插件目录的 data.json 中。它不建立内容数据库，不写入 Markdown，也不包含遥测、广告、账号系统或在线元数据搜索。
如果笔记或插件数据库引用 HTTPS 封面，Obsidian 会直接连接该图片所属服务器以显示图片，因此服务器可能看到你的 IP 地址和常规网络请求信息。插件不会预先探测、下载或代理这些图片，并设置 no-referrer。本地导入只会读取用户在系统文件选择器中明确选择的图片。
替换或移除数据库封面不会删除已导入的图片文件，以避免误删用户数据。
开发
npm install
npm run dev
完整验证：
npm run check
生产构建生成根目录下的 main.js。手动安装时，将 main.js、manifest.json 和 styles.css 复制到测试 Vault 的插件目录。不要在主 Vault 中开发或验证插件。
发布新版本
main.js 是构建产物，因此不提交到源码仓库；推送与 manifest.json 版本号一致的 Git tag 后，GitHub Actions 会构建它，并将 main.js、manifest.json 和 styles.css 作为 Release Assets 上传。
发布 1.1.0 时执行：
npm version 1.1.0 --no-git-tag-version
npm run version
npm run check
git add package.json package-lock.json manifest.json versions.json
git commit -m "chore: prepare 1.1.0 release"
git tag 1.1.0
git push origin main
git push origin 1.1.0
Release 页面中的附件必须直接显示为 main.js、manifest.json 和 styles.css，不能只依赖 GitHub 自动生成的源码压缩包。
正式发布前需要把 manifest.json 和 package.json 中的作者信息替换为维护者公开身份，并确认 Release 仓库地址。
English
Poster Wall is a local-first Obsidian desktop plugin that displays tagged Markdown notes as a responsive poster wall. It requires no Dataview, Bases, separate media database, account, or online metadata service.
Current version: 1.1.0
This release is tested and supported on macOS with Obsidian 1.12.7 or newer. The plugin is marked as desktop-only; it may run on Windows or Linux, but those platforms are not currently supported.
Features
- Display notes matching one or more tags, including child tags under configured parent tags.
- Search by note title or Vault path, with modified-time and name sorting.
- Automatically flip cards on mouse hover or keyboard focus.
- Show the title, rating, and share text on the back of each card while keeping the card clickable to open the note.
- Set or clear 0.5–5 star ratings directly on the card, including half-star selection.
- Resolve covers in this order: Property → plugin database → first Markdown image in the note → placeholder.
- Support Vault images,
[[wikilink]]references, HTTPS images, and Finder imports. - Refresh automatically when notes, attachments, folders, tags, Properties, or body images change.
- Do not modify Markdown bodies or Properties by default.
Card flip and share text
The front of a card displays the cover. Hovering over or focusing the card flips it to the back, which displays the title, rating, and short review text. The share text is read from the configurable summary Property by default:
summary: "A short review to display on the back of the card."
If the Property is missing, Poster Wall falls back to the first readable paragraph in the note. The Property name can be changed in the plugin settings. Version 1.1.0 displays the text on the card but does not include sharing buttons, image export, or webpage generation yet.
Default settings
- Cover Property:
cover - Share text Property:
summary - Finder import folder:
PosterWall/Covers - Supported import formats: PNG, JPEG, WebP, GIF, AVIF, SVG
Usage
- Enable Poster Wall in Obsidian.
- Open Settings → Community plugins → Poster Wall.
- Add tags to display, such as
#booksor#movies. - Click the grid icon in the ribbon or run “Open Poster Wall” from the command palette.
Data and privacy
Poster Wall stores its settings, cover overrides, and ratings in the plugin data.json file through Obsidian's loadData()/saveData(). It does not build a content database, modify Markdown, collect telemetry, display ads, require an account, or search online metadata.
When a note or plugin database references an HTTPS cover, Obsidian connects directly to that image server to display it. The server may therefore see your IP address and normal image request information. Poster Wall does not probe, download, or proxy those images and sets no-referrer. Local imports only read images explicitly selected through the system file picker.
Replacing or removing a database cover does not delete an imported image file.
Development
npm install
npm run dev
Run the complete validation suite with:
npm run check
The production build generates main.js in the repository root. For manual installation, copy main.js, manifest.json, and styles.css into the test Vault's plugin directory. Do not develop or test in your primary Vault.
Releasing
main.js is a build artifact and is not committed to the source repository. After pushing a Git tag that matches the version in manifest.json, GitHub Actions builds it and uploads main.js, manifest.json, and styles.css as Release Assets.
To release 1.1.0:
npm version 1.1.0 --no-git-tag-version
npm run version
npm run check
git add package.json package-lock.json manifest.json versions.json
git commit -m "chore: prepare 1.1.0 release"
git tag 1.1.0
git push origin main
git push origin 1.1.0
Release assets must appear directly as main.js, manifest.json, and styles.css; do not rely only on GitHub's automatically generated source archives. Before publishing, replace the placeholder author identity in manifest.json and package.json and verify the release repository address.