검색 배너 테마 구성 요소 비활성화

뉴스 및 이벤트 공지사항
1

Over the past few months, we have been working on a welcome banner feature that is part of Discourse’s core product. This core welcome banner feature greets new and returning visitors to your community and makes it easy for them to search for content that’s relevant to their needs and interests. With this new core banner in place, we are now deprecating the Search Banner theme component to reduce the complexity of our product offerings and ensure all Discourse users benefit from continued improvements to the core feature.

In this topic, we’ll cover what deprecation means for current users of the Search Banner theme component.

If you are a hosted customer…

We will begin migrating hosted customers from the Search Banner component to the welcome banner feature on 20 November 2025. If you’re currently using this component, you’ll receive a message with the exact timing details for your plan tier.

This migration will copy over any site texts that you’ve updated for the theme component (i.e. search_banner.headline, search_banner.subhead, search_banner.search_button_text) and the values for the show on, plugin outlet, and background image theme component settings into the core feature settings.

Our goal is to minimize the visible impact of this move, so that the banner created by the core feature looks the same as the banner created by the theme component. Communities with an image on their banner may notice a slight shift in its positioning which can be addressed by cropping the image to center the content you want to appear in the banner.

After this migration, the theme component will be disabled and can be safely deleted from the Themes & components page (/admin/config/customize/components).

If you are a self-hosted user…

You should plan to migrate yourself from the theme component to the core feature by 15 December 2025. You can do this manually or using our provided script.

Manual migration

Here’s a map of how the Search Banner theme component’s site texts and settings relate to the same features for the core welcome banner:

Setting description Search Banner theme component Welcome Banner core feature
The heading text shown on the welcome banner. search_banner.headline site text js.welcome_banner.header.anonymous_members and js.welcome_banner.header.logged_in_members site texts
The subheading text shown on the welcome banner. search_banner.subhead site text js.welcome_banner.subheader.anonymous_members and js.welcome_banner.subheader.logged_in_members site texts
The text used for the search button on the banner. * search_banner.search_button_text site text js.welcome_banner.search_placeholder site text
Setting to determine which pages display the welcome banner. show on theme component setting Welcome banner page visibility site setting
Setting to determine where on the page the welcome banner appears. plugin outlet theme component setting Welcome banner location site setting
Background image used on the welcome banner. background image light theme component setting Welcome banner image site setting

* Note that the core welcome banner feature doesn’t support an explicit search button, so we recommend mapping this text to the customizable search field placeholder text for a similar result.

Script migration

Migration consists of three rake tasks that must be run in the following order:

  1. Migrate component settings:
    themes:advanced_search_banner:1_migrate_settings_to_welcome_banner
  2. Migrate component translations:
    themes:advanced_search_banner:2_migrate_translations_to_welcome_banner
  3. Enable core banner, exclude component from themes where it is used, and disable component:
    themes:advanced_search_banner:3_exclude_and_disable

Files <random_name>.sh to be run in container:

  1. task_1.sh:
#!/bin/bash

cd /var/www/discourse && rake themes:advanced_search_banner:1_migrate_settings_to_welcome_banner
  1. task_2.sh:
#!/bin/bash

cd /var/www/discourse && rake themes:advanced_search_banner:2_migrate_translations_to_welcome_banner
  1. task_3.sh
#!/bin/bash

cd /var/www/discourse && rake themes:advanced_search_banner:3_exclude_and_disable

It is recommended to run each rake task individually for better control over the migration process.

A convenience task themes:advanced_search_banner:migrate_all is also available to run all three sequentially, but use it at your own discretion.

9개의 좋아요
Can I use Discourse Algolia Search in the Search Banner?
Making Search Banner TL/group enabled
How to make the Search Banner text use primary instead of sceondary color?
How can I add this style of background to the Search Banner?
Search-banner: welcome text for unregistered users
Search Banner image cuts off on smaller screens
Anything wrong with this component?
Forum search bar not showing up
Current Projects - November 2025
Changing translation text in Search Banner
2

Do you mean something like this?

#!/bin/bash
cd /var/www/discourse && rake themes:advanced_search_banner:migrate_settings_to_welcome_banner  && rake themes:advanced_search_banner:migrate_translations_to_welcome_banner &&  rake themes:advanced_search_banner:exclude_and_disable

I don’t think many self-hosters will infer that from <task_1_2_or_3>

Are these rake tasks likely to fail? Can we just run them all at once? If that’s the case, why not have just one rake task that does them all?

Maybe people want something like this:

docker exec -t app bash -c `cd /var/www/discourse && rake themes:advanced_search_banner:migrate_settings_to_welcome_banner  && rake themes:advanced_search_banner:migrate_translations_to_welcome_banner &&  rake themes:advanced_search_banner:exclude_and_disable`

So for people who don’t understand how to do this, they just lose all of their old settings and customized text, right?

What about the people who don’t upgrade again until March? They can still run those rake tasks then? I’m not clear what the importance of 15 December is.

3개의 좋아요
5

I’ll let my colleague who created the script help with the first part of your question, but for the last two questions:

No.

The script is one option; manual migration is another option. That is why we provided very clear descriptions of how the theme component’s settings / strings map to the welcome banner’s settings / strings.

December 15 is when we are completing our migration of hosted customers and when we will officially stop supporting / maintaining the Search Banner component. We are recommending that other users of this component migrate before then so they’re not caught off guard when the theme component becomes incompatible with Discourse core in the future.

If folks choose to wait until later, they should still be able to run these tasks or perform the migration manually, but in the meantime they will be running an unsupported theme component.

5개의 좋아요
6

Correct, the provided command will run all three tasks one after the other. Please note we prefixed each task with a number to indicate the intended execution order.

Thanks, we have updated the Script migration section to make it clearer.

We cannot guarantee 100% success, but we have ensured failures are highly unlikely.

Yes, we have added a convenience task: themes:advanced_search_banner:migrate_all.

3개의 좋아요
7

Awesome! I think that’ll help a lot. People like us don’t mind running a handful of take tasks inside a container, but most self-hosters, not so much.

If it were possible to update the theme component to have a depreciation link on the admin panel that pointed here, then that would help them know this topic exists.

What I’d like to do is find a way to find out if the theme component is installed, preferably from the api. I guess that’ll be to pull the theme component json, run it through jq and filter on the component name. I think that should work, and my dashboard has an api key. Then I can have ansible run the rake task inside the container!

3개의 좋아요
8

Are the official themes that automatically install the component changed beforehand so that no one installs the component without realizing they need to manually configure the welcome banner in core for the theme to work in the future?

3개의 좋아요
11

Just for info, I performed the rake tasks as described and it looks as if it worked as planned.

rake.txt.md (3.1 KB)

2개의 좋아요
12

All the official themes which were using Search Banner were updated and transitioned to use Welcome Banner:

4개의 좋아요
13

May I ask a question regarding this? I have used safe mode today, and that’s because today was the first time I saw the banner after the migration (it’s disabled in my current theme; the component was installed with the Air Theme, which is currently disabled).
So, I noticed that the texts in the banner now match the texts from the search banner

image
image708×160 6 KB

image
image620×317 5.54 KB

image
image775×592 23.8 KB

Then, I switched my interface language to the default language of my forum (German), and it seems those texts were not changed.

image
image634×120 3.21 KB

image
image595×339 6.72 KB

image
image776×356 11.5 KB

Is that the expected result of the migration? I cannot find any logs that indicate that it was me who edited the texts; that’s why I assume this is the result of the migration. But I don’t really understand why that would change only one language but not the others. Especially not that it wouldn’t migrate the default locale.

14

Yes, the migration script was designed to migrate the default search banner texts into the core welcome banner texts.

Why were texts migrated?

The migration was executed because the search banner was installed with the Air Theme - the script doesn’t check if the parent theme (in your case, Air Theme) is disabled, which is a miss in the script’s logic.

The migration script does support multiple locales, if they are set: link to source code.

It means that the search banner had no German texts set, so there was nothing to migrate.

As a migration script author, I apologize for this oversight to ensure a smooth migration. If I overlooked anything in your post, I am afraid I won’t be able to provide any better help, as I am no longer a part of the core team. If you still need any assistance with the matter, the person who performed the migration on 2025-12-15 should be able to help.

1개의 좋아요
15

:thinking: But why do I see German texts in the theme component? Those are the default translations which were added more than a year ago.

So I still don’t really understand the difference between English and German. The only language in which the site texts seem overridden is English. No Spanish, no French, no Chinese, but the search banner component was translated into all these languages.

1개의 좋아요
17

In the meantime, I tried to understand the behavior more deeply and asked ChatGPT to walk through the migration logic. As far as I can tell, when no translation overrides exist, the migration doesn’t determine a locale and therefore falls back to English. That explains why the English texts were changed.

What I still don’t understand is why the forum’s default locale wasn’t used as a fallback, or why the migration didn’t consistently migrate either all locales or none. From a user-experience perspective, it would seem more consistent if all users saw either the new welcome banner text or the old search banner text, regardless of their interface language.

As it stands, German-speaking users see the default welcome banner text, while English-speaking users see the default search banner text, because that was migrated to the welcome banner. That result still doesn’t make sense to me, even after spending some time digging into it.

2개의 좋아요
22

Hi @Moin, 이번 건을 조사하는 동안 답변이 늦어 죄송합니다.

Search Banner 컴포넌트는 로케일 파일에 독일어, 스페인어, 프랑스어, 중국어 등 여러 언어에 대한 내장 번역이 포함되어 있었습니다. 이러한 번역은 데이터베이스의 TranslationOverrides로 저장되지 않았으며, 컴포넌트 자체의 일부였습니다. Search Banner → Welcome Banner로의 마이그레이션 스크립트는 관리자만 명시적으로 설정한 커스텀 사이트 텍스트인 번역 오버라이드만 마이그레이션하며, 테마 컴포넌트의 내장 번역은 마이그레이션하지 않습니다. 이는 아래에서 확인하실 수 있는 내용입니다:

이러한 누락으로 인해 마이그레이션 과정이 원활하지 못했던 점, 저희의 실수였음을 사과드립니다!

2개의 좋아요
23

그 부분은 이해합니다. 독일어 텍스트가 이주되지 않은 이유를 설명해 주니까요.

하지만 제가 변경하지 않은 영어 텍스트는 왜 이주되었을까요? 오버라이드된 텍스트만 이주했다면, 그것들도 이주되지 않았어야 하고, 결과는 모든 사용자가 새 텍스트를 보는 일관된 Welcome 배너가 되어야 합니다. 그런데 실제로는 영어 사용자는 Search 배너의 기본 텍스트를 보는 것을 제외하고는 거의 모든 사용자가 새 텍스트를 보는 Welcome 배너가 되었습니다.

24

마이그레이션 스크립트에는 영어 로케일의 기본 텍스트만 하드코딩되어 있습니다. 다른 기본 로케일을 추가하는 것을 간과했습니다. 이것이 자동 마이그레이션 과정에서 독일어 기본 복사본이 누락된 이유를 설명합니다.

1개의 좋아요