feat: use Notion page title for announcements (#4456)

* feat: use Notion page title for announcements

Use the Notice page title as the announcement title across supported themes, while preserving the existing localized title as a fallback.

Resolves #3159

* docs: document announcement title behavior

Author: ZZHow1024

__tests__/themes/announcementTitle.test.js

@@ -0,0 +1,57 @@
+import { render, screen } from '@testing-library/react'
+import CommerceAnnouncement from '@/themes/commerce/components/Announcement'
+import ExampleAnnouncement from '@/themes/example/components/Announcement'
+import FukasawaAnnouncement from '@/themes/fukasawa/components/Announcement'
+import FuwariAnnouncement from '@/themes/fuwari/components/Announcement'
+import HexoAnnouncement from '@/themes/hexo/components/Announcement'
+import MateryAnnouncement from '@/themes/matery/components/Announcement'
+import MovieAnnouncement from '@/themes/movie/components/Announcement'
+import NextAnnouncement from '@/themes/next/components/Announcement'
+import ThoughtliteAnnouncement from '@/themes/thoughtlite/components/Announcement'
+import XuhomeAnnouncement from '@/themes/xuhome/components/Announcement'
+
+jest.mock('@/lib/global', () => ({
+  useGlobal: () => ({
+    locale: {
+      COMMON: {
+        ANNOUNCEMENT: 'Announcement fallback'
+      }
+    }
+  })
+}))
+
+const notice = {
+  title: 'Custom notice title',
+  blockMap: { block: {} }
+}
+
+describe('announcement titles', () => {
+  test.each([
+    ['commerce', CommerceAnnouncement, 'post'],
+    ['example', ExampleAnnouncement, 'post'],
+    ['fukasawa', FukasawaAnnouncement, 'post'],
+    ['hexo', HexoAnnouncement, 'post'],
+    ['matery', MateryAnnouncement, 'notice'],
+    ['movie', MovieAnnouncement, 'post'],
+    ['next', NextAnnouncement, 'post'],
+    ['thoughtlite', ThoughtliteAnnouncement, 'post'],
+    ['xuhome', XuhomeAnnouncement, 'post']
+  ])('%s uses the Notion Notice page title', (_name, Component, propName) => {
+    render(<Component {...{ [propName]: notice }} />)
+
+    expect(screen.getByText(/Custom notice title/)).toBeInTheDocument()
+  })
+
+  it('fuwari prefers the Notion Notice page title over its fallback title prop', () => {
+    render(<FuwariAnnouncement post={notice} title='Announcement fallback' />)
+
+    expect(screen.getByText(/Custom notice title/)).toBeInTheDocument()
+    expect(screen.queryByText('Announcement fallback')).not.toBeInTheDocument()
+  })
+
+  it('keeps the localized fallback when the Notice page has no title', () => {
+    render(<HexoAnnouncement post={{ blockMap: { block: {} } }} />)
+
+    expect(screen.getByText('Announcement fallback')).toBeInTheDocument()
+  })
+})

docs/developer/THEME_MIGRATION_GUIDE.md

@@ -57,6 +57,7 @@ When migrating a new theme, verify all of these:
 
 2. **Notice/announcement block**
    - Render Notion content using `NotionPage`.
+   - If a separate announcement title is rendered, prefer the Notice page `title` and preserve the theme's existing title as a fallback.
    - Switchable in theme config.
 
 3. **Notion cover as Hero**

docs/developer/THEME_MIGRATION_GUIDE.zh-CN.md

@@ -57,6 +57,7 @@
 
 2. **公告模块**
    - 使用 `NotionPage` 渲染公告内容
+   - 如展示独立公告标题，应优先使用 Notice 页面的 `title`，并保留主题原有标题作为 fallback
    - 可通过主题配置开关启停
 
 3. **Notion 封面作为 Hero**

docs/user-guide/config/notionnext-notice.md

@@ -37,6 +37,8 @@ NotionNext 3.10以后的版本开始支持网站公告，欢迎更新体验。
 
 添加一个Type（类型）为Notice的页面即可，此页面是唯一的，网站只能有一个公告。
 
+对于展示独立公告标题的主题，Notice 页面的标题会优先作为公告标题显示；如果没有可用标题，则继续使用主题原有的「公告 / Announcement」等默认或本地化标题。
+
 ![Untitled](/legacy/56d8cd9cf2c6ec48.png)
 
 
@@ -59,7 +61,7 @@ NotionNext 3.10以后的版本开始支持网站公告，欢迎更新体验。
 ```HTML
 <div className={className}>
     <section id='announcement-wrapper' className="dark:text-gray-300 border dark:border-black rounded-xl lg:p-6 p-4 bg-white dark:bg-hexo-black-gray">
-        <div><i className='mr-2 fas fa-bullhorn' />{locale.COMMON.ANNOUNCEMENT}</div>
+        <div><i className='mr-2 fas fa-bullhorn' />{post?.title || locale.COMMON.ANNOUNCEMENT}</div>
         {post && (<div id="announcement-content">
         <NotionPage post={post} className='text-center' />
     </div>)}

themes/commerce/components/Announcement.js

@@ -8,7 +8,7 @@ const Announcement = ({ post, className }) => {
   if (post?.blockMap) {
     return <div className={className}>
         <section id='announcement-wrapper' className="dark:text-gray-300 border dark:border-black rounded-xl lg:p-6 p-4 bg-white dark:bg-hexo-black-gray">
-            <div><i className='mr-2 fas fa-bullhorn' />{locale.COMMON.ANNOUNCEMENT}</div>
+            <div><i className='mr-2 fas fa-bullhorn' />{post?.title || locale.COMMON.ANNOUNCEMENT}</div>
             {post && (<div id="announcement-content">
             <NotionPage post={post} className='text-center' />
         </div>)}

themes/example/components/Announcement.js

@@ -18,7 +18,7 @@ const Announcement = ({ post, className }) => {
     <aside className='rounded shadow overflow-hidden mb-6'>
       <h3 className='text-sm bg-gray-100 text-gray-700 dark:bg-hexo-black-gray dark:text-gray-200 py-3 px-4 dark:border-hexo-black-gray border-b'>
         <i className='mr-2 fas fa-bullhorn' />
-        {locale.COMMON.ANNOUNCEMENT}
+        {post?.title || locale.COMMON.ANNOUNCEMENT}
       </h3>
 
       {post && (

themes/fukasawa/components/Announcement.js

@@ -8,7 +8,7 @@ const Announcement = ({ post, className }) => {
   if (post?.blockMap) {
     return <div className={className}>
         <section id='announcement-wrapper' className="dark:text-gray-300 rounded-xl px-2 py-4">
-            <div><i className='mr-2 fas fa-bullhorn' />{locale.COMMON.ANNOUNCEMENT}</div>
+            <div><i className='mr-2 fas fa-bullhorn' />{post?.title || locale.COMMON.ANNOUNCEMENT}</div>
             {post && (<div id="announcement-content">
             <NotionPage post={post} className='text-center ' />
         </div>)}

themes/fuwari/components/Announcement.js

@@ -8,7 +8,7 @@ const Announcement = ({ post, className = '', title = 'Announcement' }) => {
   return (
     <section className={`fuwari-card ${className}`}>
       <h2 className='text-sm font-semibold mb-2 tracking-wide uppercase text-[var(--fuwari-muted)]'>
-        {title}
+        {post?.title || title}
       </h2>
       <div id='announcement-content' className='text-sm'>
         <NotionPage post={post} />

themes/hexo/components/Announcement.js

@@ -8,7 +8,7 @@ const Announcement = ({ post, className }) => {
   if (post?.blockMap) {
     return <div className={className}>
         <section id='announcement-wrapper' className="dark:text-gray-300 border dark:border-black rounded-xl lg:p-6 p-4 bg-white dark:bg-hexo-black-gray">
-            <div><i className='mr-2 fas fa-bullhorn' />{locale.COMMON.ANNOUNCEMENT}</div>
+            <div><i className='mr-2 fas fa-bullhorn' />{post?.title || locale.COMMON.ANNOUNCEMENT}</div>
             {post && (<div id="announcement-content">
             <NotionPage post={post} className='text-center' />
         </div>)}

themes/matery/components/Announcement.js

@@ -17,7 +17,7 @@ const Announcement = ({ notice }) => {
             className="mb-4 p-2 overflow-auto shadow-md border dark:border-black rounded-xl bg-white dark:bg-hexo-black-gray">
             <div className="text-sm flex flex-nowrap justify-between">
                 <div className="font-light text-gray-600  dark:text-gray-200">
-                    <i className="mx-2 fas fa-bullhorn" />{locale.COMMON.ANNOUNCEMENT}
+                    <i className="mx-2 fas fa-bullhorn" />{notice?.title || locale.COMMON.ANNOUNCEMENT}
                 </div>
             </div>
             {notice && (<div id="announcement-content">