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

[lindsey (Lindsey Fogle)]

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

2. task_2.sh:

#!/bin/bash

cd /var/www/discourse && rake themes:advanced_search_banner:2_migrate_translations_to_welcome_banner

3. 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.

[pfaffman (Jay Pfaffman)]

@lindsey

File .sh to be run in container:

#!/bin/bash

cd /var/www/discourse && rake themes:advanced_search_banner:<task_1_2_or_3>

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`

@lindsey

You can do this manually or using our provided script.

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.

[lindsey (Lindsey Fogle)]

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

@pfaffman

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

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.

@lindsey

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

@pfaffman

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.

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.

[yuriy (Yuriy Kurant)]

@pfaffman

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

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.

@pfaffman

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

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

@pfaffman

Are these rake tasks likely to fail?

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

@pfaffman

Can we just run them all at once?

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

[pfaffman (Jay Pfaffman)]

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!

[Moin]

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?

[Thomas_Rother (Thommie Rother)]

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)

[yuriy (Yuriy Kurant)]

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

• Air Theme
• Inky Theme
• Mint Theme
• Sublime Theme

[Moin]

@lindsey

이 마이그레이션은 테마 컴포넌트(예: search_banner.headline, search_banner.subhead, search_banner.search_button_text)에 대해 업데이트한 사이트 텍스트와 show on, plugin outlet, background image 테마 컴포넌트 설정의 값을 핵심 기능 설정으로 복사합니다.

이와 관련하여 질문을 해도 될까요? 오늘 안전 모드(safe mode)를 사용했는데, 마이그레이션 이후 배너를 처음 본 것이 오늘이었기 때문입니다(현재 제 테마에서는 비활성화되어 있습니다. 해당 컴포넌트는 현재 비활성화된 Air 테마에 설치되어 있었습니다).
그래서 배너의 텍스트가 이제 검색 배너의 텍스트와 일치하는 것을 알게 되었습니다.

그런 다음, 인터페이스 언어를 포럼의 기본 언어(독일어)로 전환했는데, 해당 텍스트는 변경되지 않은 것 같습니다.

이것이 마이그레이션의 예상된 결과인가요? 제가 텍스트를 편집했다는 것을 나타내는 로그를 찾을 수 없어서 이것이 마이그레이션의 결과라고 가정하고 있습니다. 하지만 왜 하나의 언어만 변경되고 다른 언어들은 변경되지 않는지 이해가 되지 않습니다. 특히 기본 로케일이 마이그레이션되지 않는 이유에 대해서는 더욱 그렇습니다.

[yuriy (Yuriy Kurant)]

@Moin

배너의 텍스트가 이제 검색 배너의 텍스트와 일치하는 것을 알게 되었습니다.

@Moin

텍스트를 제가 편집했다는 것을 나타내는 로그를 찾을 수 없습니다. 그래서 이것이 마이그레이션의 결과라고 추정합니다.

네, 마이그레이션 스크립트는 기본 검색 배너 텍스트를 핵심 환영 배너 텍스트로 마이그레이션하도록 설계되었습니다.

왜 텍스트가 마이그레이션되었나요?

검색 배너가 Air 테마와 함께 설치되었기 때문에 마이그레이션이 실행되었습니다. 스크립트는 부모 테마(귀하의 경우 Air 테마)가 비활성화되어 있는지 확인하지 않으며, 이는 스크립트 로직의 누락입니다.

---

@Moin

인터페이스 언어를 포럼의 기본 언어(독일어)로 변경했는데, 해당 텍스트가 변경되지 않은 것 같습니다.

@Moin

하지만 왜 다른 언어는 변경되지 않고 한 언어만 변경되는지 정확히 이해하지 못하겠습니다. 특히 기본 로케일이 마이그레이션되지 않는 이유를요.

마이그레이션 스크립트는 로케일이 설정된 경우 여러 로케일을 지원합니다: 소스 코드 링크.

즉, 검색 배너에 독일어 텍스트가 설정되어 있지 않았으므로 마이그레이션할 것이 없었습니다.

마이그레이션 스크립트 작성자로서, 원활한 마이그레이션을 보장하지 못한 이 oversight에 대해 사과드립니다. 귀하의 게시물에서 제가 놓친 부분이 있다면, 더 이상 핵심 팀의 일원이 아니므로 더 나은 도움을 드릴 수 없을 것 같습니다. 이 문제에 대해 여전히 도움이 필요하시다면, 2025-12-15에 마이그레이션을 수행한 사람이 도움을 줄 수 있을 것입니다.

[Moin]

@yuriy

즉, 검색 배너에 독일어 텍스트가 설정되어 있지 않아 이관할 것이 없었다는 뜻입니다.

그런데 왜 테마 컴포넌트에서 독일어 텍스트가 보이나요? 그것들은 1년 이상 전에 추가된 기본 번역입니다.

@Moin

그래서 여전히 영어와 독일어 사이의 차이가 정확히 무엇인지 이해가 되지 않습니다. 사이트 텍스트가 오버라이드된 것으로 보이는 언어는 영어뿐입니다. 스페인어도 아니고, 프랑스어도, 중국어도 아니지만, 검색 배너 컴포넌트는 이 모든 언어로 번역되어 있습니다.

[Moin]

그동안 저는 이 동작을 더 깊이 이해하려고 노력했으며, ChatGPT에게 마이그레이션 로직을 단계별로 설명해 달라고 요청했습니다. 제가 파악한 바로는, 번역 오버라이드가 존재하지 않으면 마이그레이션이 로케일을 결정하지 못하고 영어로 폴백됩니다. 그래서 영어 텍스트가 변경된 것입니다.

아직 이해가 안 되는 부분은 포럼의 기본 로케일이 폴백으로 사용되지 않은 이유, 혹은 마이그레이션이 모든 로케일 또는 어떤 것도 아닌 일관된 방식으로 마이그레이션하지 않은 이유입니다. 사용자 경험 측면에서 보면, 인터페이스 언어와 관계없이 모든 사용자에게 새 웰컴 배너 텍스트 또는 구형 검색 배너 텍스트 중 하나가 일관되게 표시되는 것이 더 합리적일 것입니다.

현재 상태에서는, 독일어 사용자에게는 기본 웰컴 배너 텍스트가, 영어 사용자에게는 기본 검색 배너 텍스트가 표시됩니다. 이는 검색 배너가 웰컴 배너로 마이그레이션되었기 때문입니다. 상당한 시간을 들여 조사해 보았음에도 불구하고, 이 결과는 여전히 제게는 이해가 되지 않습니다.

[lindsey (Lindsey Fogle)]

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

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

@Moin

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

[Moin]

@lindsey

Search 배너 → Welcome 배너로 이주하는 스크립트는 관리자 tarafından 명시적으로 설정된 사용자 정의 사이트 텍스트인 번역 오버라이드만 이주하며, 테마 컴포넌트의 내장 번역은 이주하지 않습니다.

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

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

[yuriy (Yuriy Kurant)]

@Moin

그렇다면 제가 수정하지 않은 영어 텍스트는 왜 마이그레이션되었나요?

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

lib/tasks/migrate_advanced_search_banner_to_welcome_banner.rake