Shuoshuo Feature#

Shuoshuo (说说) is a short-status/microblog page type added in Butterfly v5.0. It renders items from a YAML/JSON data source — not from regular Hexo posts — through a custom build-time processing pipeline that makes them behave like posts (Markdown, tag plugin support, timezone correction) without actually being Hexo posts.

Data Sources#

Shuoshuo items come from one of two mutually exclusive sources 1:

The local path is the only one that goes through Hexo's content rendering pipeline. Remote data is displayed as-is (no server-side Markdown rendering).

Item Schema#

Each item supports the following fields 1:

Rendering Pipeline (shuoshuoFN helper)#

The core logic lives in the shuoshuoFN helper in scripts/helpers/page.js. For each local item, it runs four steps in order:

1. Timezone Correction#

Hexo treats all times as UTC. The helper uses moment-timezone to convert each item.date to the site's configured timezone before any rendering 2.

2. Mock Post Object + before_post_render#

To enable Hexo tag plugins and markdown preprocessors (e.g., syntax highlighters, code fence wrappers), the helper constructs a minimal mock post object — { content: item.content } — and passes it synchronously through all registered before_post_render filters 3:

const mockPost = { content: item.content }
hexo.execFilterSync('before_post_render', mockPost, { context: hexo })
item.content = mockPost.content

This is the key compatibility shim: plugins that transform post content (e.g., wrapping code blocks in <hexoPostRenderCodeBlock> elements) operate on this mock object just as they would on a real post.

3. Code Block Protection + Tag Plugin Rendering#

Before running tag plugins, the helper extracts any <hexoPostRenderCodeBlock> segments into a side-array and replaces them with <!--CODEBLOCK_N--> placeholders. This prevents the Nunjucks tag renderer from mangling pre-processed code 4. Tag plugins are then rendered via hexo.extend.tag.env.renderString(); errors are silently swallowed to allow graceful fallback.

4. Markdown Rendering + Placeholder Restoration#

The content is passed through hexo.render.renderSync({ engine: 'markdown' }), then code block placeholders are restored from the side-array 5.

Pipeline Diagram#

Template & Client-Side Rendering#

The Pug template layout/includes/page/shuoshuo.pug calls shuoshuoFN at build time and embeds the result as JSON 6:

- const localDate = page.shuoshuo_url ? [] : shuoshuoFN(site.data.shuoshuo, page)
script(type='application/json' id='shuoshuo-data')!= safeJSON(localDate)

Client-side JavaScript (loadShuoshuo) then reads this JSON (or fetches from shuoshuo_url), sorts by date, applies the limit filter, and renders items with pagination — 8 items per page by default .

Lazyload support for images is applied client-side when theme.lazyload.field === 'site' 8. A shuoshuo:rendered DOM event fires after each page render 9, useful for third-party integrations.

Known Limitations & Notes#

• Official docs state tag plugins and math formulas are not supported 1. The code does call execFilterSync('before_post_render') and tag.env.renderString(), but errors are silently ignored — so tag plugins may partially work, with no guarantee.
• Remote shuoshuo_url bypasses all server-side rendering; content must be pre-rendered HTML or plain Markdown displayed verbatim.
• Comments require a unique key field per item. Per-item comment sections are injected dynamically via addCommentToShuoshuo() 10; each click destroys the previous comment widget and mounts a new one.
• PJAX cleanup: The template registers a pjax:send listener to remove the .shuoshuo-navigation element on navigation, preventing DOM leaks 11.

Key Files#