Files

T

Serendipity edbf78f236 feat: 初始化 Halo 暗色模式插件

- Halo Plugin 后端（Java/Gradle），含 DarkModePlugin 主类和测试
- Vue 3 + TypeScript 前端 UI，包含主题切换组件和设置页面
- 暗色模式 CSS 变量和覆盖样式（布局/编辑器/表单/滚动条等）
- 设计文档和调查文档
- Halo 插件/主题开发 Agent Skills

Co-Authored-By: Claude <noreply@anthropic.com>

2026-08-06 21:03:00 +08:00

4.5 KiB

Raw Blame History

Finder API

Finder APIs query data from any template location regardless of the current route — ideal for sidebars, footers, and other global data needs.

Available Finders

Finder	Purpose
`postFinder`	Post list / detail / prev-next / archives
`categoryFinder`	Category list / tree structure / breadcrumbs
`tagFinder`	Tag list / detail
`menuFinder`	Menus and menu items
`singlePageFinder`	Single page list / detail
`commentFinder`	Comments and replies
`contributorFinder`	Contributors
`siteStatsFinder`	Site statistics
`themeFinder`	Theme information
`pluginFinder`	Plugin information

Key Usage Pattern

Use th:with to bind the result in the current scope:

<div th:with="menu = ${menuFinder.getPrimary()}">
  <a
    th:each="item : ${menu.menuItems}"
    th:href="${item.status.href}"
    th:text="${item.status.displayName}"
  ></a>
</div>

Common Notes

postFinder.list({...}) is the recommended unified query method (all parameters are optional); it supersedes the deprecated list(page, size), listByCategory(...), etc.
Halo 2.25+ adds postFinder.cursorByCategory(postName) for previous/next posts inside the current post's primary category. It only matches the same category and does not include child categories.
Halo 2.24.1+ adds postFinder.random(maxSize) for random published posts.
Halo 2.22+ changed postFinder.cursor(postName): the result no longer has current; previous and next are ListedPostVo.
metadata.name is the unique resource identifier — it is not the display name (displayName/title).
Pair settings.yaml categorySelect/tagSelect inputs with Finder queries so users can configure query parameters in Console instead of hard-coding them in templates.

Image Thumbnails

Halo 2.19+ generates responsive thumbnails for attachment images. Use thumbnail.gen(uri, size) to get a scaled URL:

<img
  th:src="${post.spec.cover}"
  th:srcset="|${thumbnail.gen(post.spec.cover, 's')} 400w,
              ${thumbnail.gen(post.spec.cover, 'm')} 800w,
              ${thumbnail.gen(post.spec.cover, 'l')} 1200w,
              ${thumbnail.gen(post.spec.cover, 'xl')} 1600w|"
  sizes="(max-width: 1600px) 100vw, 1600px"
/>

Size parameter	Width
`s`	400px
`m`	800px
`l`	1200px
`xl`	1600px

Halo 2.22+ automatically adds responsive image attributes to all <img> tags on the page. Only use thumbnail.gen() manually when you need custom control over specific images.

Online Docs

Do not rely on training data for Finder API method signatures — Halo evolves across versions and your training data may be outdated or incomplete. Always fetch the relevant doc before writing code that calls a specific Finder method.

4.5 KiB Raw Blame History