Add an optional introduction above the Knowledge Base index

README.md

@@ -38,6 +38,8 @@ The Knowledge Base follows each member's board style. It starts as a flat articl
 index (one list of every article, with a category dropdown); hierarchical category
 browsing and an optional colour stylesheet (a bundled one, or your own CSS file) are
 set on the same ACP page; see the [styling guide](docs/TODO/archive/styling/README.md).
+The same page can switch on a short introduction above the article index, written in
+BBCode or Markdown; it is off until you switch it on.
 
 A search of the board also shows the matching articles in a **Knowledge Base** block above
 the forum results, with an **Also search the Knowledge Base** option in the advanced search.

adm/style/acp_knowledgebase_config.html

@@ -75,6 +75,35 @@ <h1>{{ lang('ACP_KNOWLEDGE_BASE_CONFIGURE') }}</h1>
 				<input name="hierarchical_index" id="hierarchical_index" type="checkbox" value="1" {{ HIERARCHICAL_INDEX_ON }}/>
 			</dd>
 		</dl>
+		<dl>
+			<dt>
+				<label for="intro_enabled">{{ lang('KB_INTRO_ENABLE') }}{{ lang('COLON') }}</label><br>
+				<span>{{ lang('KB_INTRO_ENABLE_EXPLAIN') }}</span>
+			</dt>
+			<dd>
+				<input name="intro_enabled" id="intro_enabled" type="checkbox" value="1"
+					onClick="document.getElementById('intro_options').style.display = this.checked ? '' : 'none';"
+					{{ INTRO_ON }}/>
+			</dd>
+		</dl>
+		<div id="intro_options" style="display: {{ INTRO_DISPLAY }};">
+			<dl>
+				<dt>
+					<label for="intro_text">{{ lang('KB_INTRO_TEXT') }}{{ lang('COLON') }}</label><br>
+					<span>{{ lang('KB_INTRO_TEXT_EXPLAIN') }}</span>
+				</dt>
+				<dd><textarea name="intro_text" id="intro_text" rows="6" cols="60">{{ INTRO_TEXT }}</textarea></dd>
+			</dl>
+			<dl>
+				<dt>
+					<label for="intro_markdown">{{ lang('KB_INTRO_MARKDOWN') }}{{ lang('COLON') }}</label><br>
+					<span>{{ lang('KB_INTRO_MARKDOWN_EXPLAIN') }}</span>
+				</dt>
+				<dd>
+					<input name="intro_markdown" id="intro_markdown" type="checkbox" value="1" {{ INTRO_MARKDOWN_ON }}/>
+				</dd>
+			</dl>
+		</div>
 		<dl>
 			<dt>
 				<label for="alt_style_enabled">{{ lang('KB_ALT_STYLE_ENABLE') }}{{ lang('COLON') }}</label><br>

config/services.yml

@@ -18,6 +18,7 @@ services:
             - '@phpbbmodders.knowledgebase.inc'
             - '%tables.articles_table%'
             - '%tables.categories_table%'
+            - '@phpbbmodders.knowledgebase.intro'
 
     phpbbmodders.knowledgebase.controller.category:
         class: phpbbmodders\knowledgebase\controller\category
@@ -34,6 +35,7 @@ services:
             - '@phpbbmodders.knowledgebase.inc'
             - '%tables.articles_table%'
             - '%tables.categories_table%'
+            - '@phpbbmodders.knowledgebase.intro'
 
     phpbbmodders.knowledgebase.controller.recent_changes:
         class: phpbbmodders\knowledgebase\controller\recent_changes
@@ -262,6 +264,14 @@ services:
             # Argument order differs between 3.3.x and 4.0; the renderer class copes with either.
             - [configure_user, ['@user', '@config', '@auth']]
 
+    phpbbmodders.knowledgebase.intro:
+        class: phpbbmodders\knowledgebase\inc\intro
+        arguments:
+            - '@config'
+            - '@config_text'
+            - '@phpbbmodders.knowledgebase.article_text'
+            - '@template'
+
     phpbbmodders.knowledgebase.article_text:
         class: phpbbmodders\knowledgebase\textformatter\article_text
         arguments:
@@ -346,6 +356,7 @@ services:
             - '%tables.kb_users_table%'
             - '%tables.kb_groups_table%'
             - '@phpbbmodders.knowledgebase.alternative_styles'
+            - '@phpbbmodders.knowledgebase.intro'
 
     phpbbmodders.knowledgebase.controller.set_order:
         class: phpbbmodders\knowledgebase\controller\set_order

controller/acp_controller.php

@@ -34,6 +34,7 @@
 use phpbbmodders\knowledgebase\inc\field\kb_field_type_factory;
 use phpbbmodders\knowledgebase\inc\icon;
 use phpbbmodders\knowledgebase\inc\functions_kb;
+use phpbbmodders\knowledgebase\inc\intro;
 use phpbbmodders\knowledgebase\inc\upload_directory;
 use phpbbmodders\knowledgebase\search\kb_search_backend_factory;
 
@@ -165,6 +166,9 @@ protected functions_kb $kb;
 	 * @param string                    $kb_groups_table
 	 * @param alternative_styles        $alt_styles
 	 */
+	/** @var intro|null The index introduction text; optional so older callers still build */
+	protected intro|null $intro;
+
 	public function __construct(
 		driver_interface $db, config $config, db_text $config_text, helper $helper, manager $ext_manager,
 		language $language, auth $auth, request_interface $request, template $template, user $user,
@@ -173,9 +177,10 @@ public function __construct(
 		kb_field_type_factory $field_factory,
 		string $phpbb_root_path, string $php_ext, string $articles_table, string $categories_table,
 		string $logs_table, string $attachments_table, string $options_table, string $kb_users_table,
-		string $kb_groups_table, alternative_styles $alt_styles
+		string $kb_groups_table, alternative_styles $alt_styles, intro|null $intro = null
 	)
 	{
+		$this->intro = $intro;
 		$this->db = $db;
 		$this->config = $config;
 		$this->config_text = $config_text;
@@ -282,6 +287,10 @@ public function settings(): void
 			'EXTGROUP_FILESIZE'        => $max_filesize,
 			'ADVANCED_FORM'            => $announce_forum_id ? '' : 'none',
 			'HIERARCHICAL_INDEX_ON'    => $this->config['kb_hierarchical_index'] ? 'checked="checked"' : '',
+			'INTRO_ON'                 => $this->intro && $this->intro->is_enabled() ? 'checked="checked"' : '',
+			'INTRO_DISPLAY'            => $this->intro && $this->intro->is_enabled() ? '' : 'none',
+			'INTRO_TEXT'               => $this->intro ? $this->intro->for_edit() : '',
+			'INTRO_MARKDOWN_ON'        => $this->intro && $this->intro->is_markdown() ? 'checked="checked"' : '',
 			'ALT_STYLE_ON'             => $this->config['kb_alt_style_enabled'] ? 'checked="checked"' : '',
 			'ALT_STYLE_DISPLAY'        => $this->config['kb_alt_style_enabled'] ? '' : 'none',
 			'S_ALT_STYLE_OPTIONS'      => $this->alternative_style_options((string) $this->config['kb_alt_style']),
@@ -360,6 +369,14 @@ protected function set_settings(): void
 		$this->config->set('kb_font_icon', $kb_font_icon);
 
 		$this->config->set('kb_hierarchical_index', $this->request->variable('hierarchical_index', 0) ? 1 : 0);
+		if ($this->intro)
+		{
+			$this->intro->save(
+				(bool) $this->request->variable('intro_enabled', 0),
+				utf8_normalize_nfc($this->request->variable('intro_text', '', true)),
+				(bool) $this->request->variable('intro_markdown', 0)
+			);
+		}
 		$this->config->set('kb_feed_format', $feed_format);
 		$this->save_alternative_style();
 		$this->save_announcement_forum();

controller/category.php

@@ -22,6 +22,7 @@
 use phpbb\template\template;
 use phpbb\user;
 use phpbbmodders\knowledgebase\inc\functions_kb;
+use phpbbmodders\knowledgebase\inc\intro;
 
 class category
 {
@@ -77,12 +78,16 @@ protected functions_kb $kb;
 	 * @param string            $articles_table
 	 * @param string            $categories_table
 	 */
+	/** @var intro|null The index introduction text */
+	protected intro|null $intro;
+
 	public function __construct(
 		driver_interface $db, config $config, helper $helper, language $language, auth $auth,
 		request_interface $request, template $template, user $user, pagination $pagination, functions_kb $kb,
-		string $articles_table, string $categories_table
+		string $articles_table, string $categories_table, intro|null $intro = null
 	)
 	{
+		$this->intro = $intro;
 		$this->db = $db;
 		$this->config = $config;
 		$this->helper = $helper;
@@ -473,6 +478,11 @@ public function cat(): \Symfony\Component\HttpFoundation\Response
 		}
 
 		$this->kb->assign_nav_tabs_vars('index', $cat_id);
+		// The flat index (all categories) is the Knowledge Base index in its default layout
+		if ($flat_all)
+		{
+			$this->intro?->assign();
+		}
 
 		return $this->helper->render('@phpbbmodders_knowledgebase/kb_cat_body.html', ($this->language->lang('LIBRARY') . ' » ' . $this->language->lang('CATEGORY')));
 	}

controller/index.php

@@ -22,6 +22,7 @@
 use phpbb\template\template;
 use phpbb\user;
 use phpbbmodders\knowledgebase\inc\functions_kb;
+use phpbbmodders\knowledgebase\inc\intro;
 
 class index
 {
@@ -77,12 +78,16 @@ protected functions_kb $kb;
 	 * @param string             $articles_table
 	 * @param string             $categories_table
 	 */
+	/** @var intro|null The index introduction text */
+	protected intro|null $intro;
+
 	public function __construct(
 		driver_interface $db, config $config, helper $helper, language $language, auth $auth,
 		request_interface $request, template $template, user $user, pagination $pagination, functions_kb $kb,
-		string $articles_table, string $categories_table
+		string $articles_table, string $categories_table, intro|null $intro = null
 	)
 	{
+		$this->intro = $intro;
 		$this->db = $db;
 		$this->config = $config;
 		$this->helper = $helper;
@@ -178,6 +183,7 @@ public function main(): \Symfony\Component\HttpFoundation\Response
 		]);
 
 		$this->kb->assign_nav_tabs_vars('index');
+		$this->intro?->assign();
 
 		return $this->helper->render('@phpbbmodders_knowledgebase/kb_index_body.html', $this->language->lang('LIBRARY'));
 	}

docs/testing.md

@@ -1487,3 +1487,23 @@ is a separate piece of work, not part of this change.
 **Not covered.** Boards upgraded from phpBB 3.3 to 4.0 with kinerity data (the sequence case is
 covered by PHPUnit only); a custom style; kinerity versions before 1.2.1 on a board (1.0.x's missing
 column is covered by PHPUnit only); MariaDB.
+
+## Introduction text on the index - 11/12/2026
+
+`inc/intro.php` shows an administrator's introduction under the Knowledge Base title, on the
+hierarchical index and on the flat index (all categories). It is set on the ACP configuration page:
+a switch, the text, and whether it is Markdown; BBCode, smilies and links work as in an article,
+through the same `article_text` service. Migration `version_2_0_33` adds it switched off, holding
+the text kinerity/knowledgebase showed, and switches it on on a board imported from kinerity.
+
+`tests/kb_intro_test.php` covers the stored default text, nothing shown while switched off or empty,
+saving BBCode and Markdown, emptying it, and the migration's steps and its kinerity check.
+
+Claude ran the migration on the phpBB 3.3 PostgreSQL board imported from kinerity: it came up
+switched on with kinerity's text, in the same place as on the kinerity board beside it. In the ACP,
+the text was saved as BBCode (bold, a link, a smiley, `&` and quotes) and came back unchanged in the
+editor, then as Markdown (bold, a link, inline code); both displayed formatted on the flat index. It
+also showed on the hierarchical index, and nothing showed once it was switched off.
+
+Not covered: a board that never ran kinerity in a browser (the migration's off-by-default path is
+covered by PHPUnit), and other languages (the default text is English, as kinerity's was).

docs/upgrading-from-kinerity.md

@@ -85,6 +85,11 @@ tables are kept, unchanged.
   A group or user that already has a setting for `u_kb_view` or `a_manage_kb`
   keeps it.
 
+- **The introduction text** kinerity showed above its index. This extension's
+  own introduction (Extensions → Knowledge Base → Configuration) starts out
+  with kinerity's text and is switched on after an import, so visitors still
+  see it. Edit it or switch it off there.
+
 ## What is removed
 
 After the import, kinerity's permissions (with their settings in roles,

inc/default_content.php

@@ -33,11 +33,8 @@ public static function lang(string $language, string $key): string
 				continue;
 			}
 
+			// The language file checks IN_PHPBB, which phpBB always defines
 			$lang = [];
-			if (!defined('IN_PHPBB'))
-			{
-				define('IN_PHPBB', true);
-			}
 			include $file;
 			if (isset($lang[$key]))
 			{