From 66ffd4f64975713b9cdbec4c843399878eb1bc5a Mon Sep 17 00:00:00 2001
From: Dobrunia Kostrigin <48620984+Dobrunia@users.noreply.github.com>
Date: Mon, 30 Mar 2026 19:19:08 +0300
Subject: [PATCH 1/5] PR title: Fix deep page nesting in sidebar, prev/next
 order, and parent dropdown indent

---
 package.json                                  |  2 +-
 src/backend/build-static.ts                   |  3 +-
 src/backend/controllers/pages.ts              | 36 +++++++++++++++
 src/backend/models/pagesFlatArray.ts          |  8 ++--
 src/backend/routes/index.ts                   |  2 +-
 src/backend/routes/middlewares/pages.ts       |  2 +-
 src/backend/routes/pages.ts                   | 10 ++---
 src/backend/utils/menu.ts                     | 45 +++++++++++--------
 .../views/components/sidebar-branch.twig      | 18 ++++++++
 src/backend/views/components/sidebar.twig     | 14 +-----
 src/backend/views/pages/form.twig             |  9 ++--
 src/frontend/js/modules/sidebar.js            | 10 ++++-
 src/frontend/styles/components/sidebar.pcss   |  5 +++
 13 files changed, 111 insertions(+), 53 deletions(-)
 create mode 100644 src/backend/views/components/sidebar-branch.twig

diff --git a/package.json b/package.json
index f0395845..fa3a380f 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "codex.docs",
   "license": "Apache-2.0",
-  "version": "2.2.4",
+  "version": "2.3.0",
   "type": "module",
   "bin": {
     "codex.docs": "dist/backend/app.js"
diff --git a/src/backend/build-static.ts b/src/backend/build-static.ts
index ca0894aa..019c6397 100644
--- a/src/backend/build-static.ts
+++ b/src/backend/build-static.ts
@@ -105,8 +105,7 @@ export default async function buildStatic(): Promise<void> {
     const parentIdOfRootPages = '0' as EntityId;
     const previousPage = await PagesFlatArray.getPageBefore(pageId);
     const nextPage = await PagesFlatArray.getPageAfter(pageId);
-    const menu = createMenuTree(parentIdOfRootPages, allPages, pagesOrder, 2);
-
+    const menu = createMenuTree(parentIdOfRootPages, allPages, pagesOrder);
     const result = await renderTemplate('./views/pages/page.twig', {
       page,
       pageParent,
diff --git a/src/backend/controllers/pages.ts b/src/backend/controllers/pages.ts
index 89f133ba..855c5f64 100644
--- a/src/backend/controllers/pages.ts
+++ b/src/backend/controllers/pages.ts
@@ -86,6 +86,42 @@ class Pages {
     return pagesMap;
   }
 
+  /**
+   * Depth in parent chain: 0 for root pages, +1 per ancestor below root (for select indent).
+   */
+  private static computePageDepth(page: Page, pagesMap: Map<string, Page>): number {
+    let depth = 0;
+    let cur: Page | undefined = page;
+
+    while (cur?._parent && !isEqualIds(cur._parent, '0' as EntityId)) {
+      depth++;
+      cur = pagesMap.get(cur._parent.toString());
+    }
+
+    return depth;
+  }
+
+  /**
+   * Ordered pages for the parent `<select>` with visual nesting (indent = depth).
+   *
+   * @param excludePageId - when editing, exclude this page and its descendants (same as groupByParent)
+   */
+  public static async getParentSelectOptions(
+    excludePageId?: EntityId
+  ): Promise<Array<{ page: Page; depth: number; indent: string }>> {
+    const pages = excludePageId
+      ? await this.groupByParent(excludePageId)
+      : await this.groupByParent();
+    const pagesMap = await this.getPagesMap();
+    const indentUnit = '\u00a0\u00a0';
+
+    return pages.map((page) => {
+      const depth = Pages.computePageDepth(page, pagesMap);
+
+      return { page, depth, indent: indentUnit.repeat(depth) };
+    });
+  }
+
   /**
    * Group all pages by their parents
    * If the pageId is passed, it excludes passed page from result pages
diff --git a/src/backend/models/pagesFlatArray.ts b/src/backend/models/pagesFlatArray.ts
index bfe45f22..088f4403 100644
--- a/src/backend/models/pagesFlatArray.ts
+++ b/src/backend/models/pagesFlatArray.ts
@@ -51,7 +51,8 @@ class PagesFlatArray {
   /**
    * Returns pages flat array
    *
-   * @param nestingLimit - number of flat array nesting, set null to dismiss the restriction, default nesting 2
+   * @param nestingLimit - max `level` to keep (level 0 = root pages, 1 = their children, …).
+   * Pass **null** to return the full tree order (needed for prev/next links past depth 2).
    * @returns {Promise<Array<PagesFlatArrayData>>}
    */
   public static async get(nestingLimit: number | null = 2): Promise<Array<PagesFlatArrayData>> {
@@ -108,7 +109,8 @@ class PagesFlatArray {
    * @returns {Promise<PagesFlatArrayData | undefined>}
    */
   public static async getPageBefore(pageId: EntityId): Promise<PagesFlatArrayData | undefined> {
-    const arr = await this.get();
+    /** `null` = no level cap; default (2) would drop pages at level ≥2 from the chain */
+    const arr = await this.get(null);
 
     const pageIndex = arr.findIndex((item) => isEqualIds(item.id, pageId));
 
@@ -128,7 +130,7 @@ class PagesFlatArray {
    * @returns {Promise<PagesFlatArrayData | undefined>}
    */
   public static async getPageAfter(pageId: EntityId): Promise<PagesFlatArrayData | undefined> {
-    const arr = await this.get();
+    const arr = await this.get(null);
 
     const pageIndex = arr.findIndex( (item) => isEqualIds(item.id, pageId));
 
diff --git a/src/backend/routes/index.ts b/src/backend/routes/index.ts
index 3505e846..3cc6e109 100644
--- a/src/backend/routes/index.ts
+++ b/src/backend/routes/index.ts
@@ -14,6 +14,6 @@ router.use('/', pagesMiddleware, home);
 router.use('/', pagesMiddleware, pages);
 router.use('/', pagesMiddleware, auth);
 router.use('/api', verifyToken, allowEdit, api);
-router.use('/', aliases);
+router.use('/', pagesMiddleware, aliases);
 
 export default router;
diff --git a/src/backend/routes/middlewares/pages.ts b/src/backend/routes/middlewares/pages.ts
index 8fafe4b5..7afae7cb 100644
--- a/src/backend/routes/middlewares/pages.ts
+++ b/src/backend/routes/middlewares/pages.ts
@@ -25,7 +25,7 @@ export default asyncMiddleware(async (req: Request, res: Response, next: NextFun
     const pages = await Pages.getAllPages();
     const pagesOrder = await PagesOrder.getAll();
 
-    res.locals.menu = createMenuTree(parentIdOfRootPages, pages, pagesOrder, 2);
+    res.locals.menu = createMenuTree(parentIdOfRootPages, pages, pagesOrder);
   } catch (error) {
     console.log('Can not load menu:', error);
   }
diff --git a/src/backend/routes/pages.ts b/src/backend/routes/pages.ts
index 1809b4ed..001211da 100644
--- a/src/backend/routes/pages.ts
+++ b/src/backend/routes/pages.ts
@@ -13,12 +13,10 @@ const router = express.Router();
  */
 router.get('/page/new', verifyToken, allowEdit, async (req: Request, res: Response, next: NextFunction) => {
   try {
-    const pagesAvailableGrouped = await Pages.groupByParent();
-
-    console.log(pagesAvailableGrouped);
+    const parentSelectOptions = await Pages.getParentSelectOptions();
 
     res.render('pages/form', {
-      pagesAvailableGrouped,
+      parentSelectOptions,
       page: null,
     });
   } catch (error) {
@@ -36,7 +34,7 @@ router.get('/page/edit/:id', verifyToken, allowEdit, async (req: Request, res: R
   try {
     const page = await Pages.get(pageId);
     const pagesAvailable = await Pages.getAllExceptChildren(pageId);
-    const pagesAvailableGrouped = await Pages.groupByParent(pageId);
+    const parentSelectOptions = await Pages.getParentSelectOptions(pageId);
 
     if (!page._parent) {
       throw new Error('Parent not found');
@@ -47,7 +45,7 @@ router.get('/page/edit/:id', verifyToken, allowEdit, async (req: Request, res: R
     res.render('pages/form', {
       page,
       parentsChildrenOrdered,
-      pagesAvailableGrouped,
+      parentSelectOptions,
     });
   } catch (error) {
     res.status(404);
diff --git a/src/backend/utils/menu.ts b/src/backend/utils/menu.ts
index 1b43417a..6137424c 100644
--- a/src/backend/utils/menu.ts
+++ b/src/backend/utils/menu.ts
@@ -3,17 +3,26 @@ import Page from '../models/page.js';
 import PageOrder from '../models/pageOrder.js';
 import { isEqualIds } from '../database/index.js';
 
+/** Max sidebar nesting depth (root sections count as depth 1). */
+const MENU_MAX_DEPTH = 64;
+
 /**
- * Process one-level pages list to parent-children list
+ * Build parent→children menu tree for the sidebar.
  *
  * @param parentPageId - parent page id
  * @param pages - list of all available pages
  * @param pagesOrder - list of pages order
- * @param level - max level recursion
- * @param currentLevel - current level of element
+ * @param maxDepth - stop recursing deeper than this (default: MENU_MAX_DEPTH)
+ * currentDepth - current depth from the tree root (1 = direct children of parentPageId)
  */
-export function createMenuTree(parentPageId: EntityId, pages: Page[], pagesOrder: PageOrder[], level = 1, currentLevel = 1): Page[] {
-  const childrenOrder = pagesOrder.find(order => isEqualIds(order.data.page, parentPageId));
+export function createMenuTree(
+  parentPageId: EntityId,
+  pages: Page[],
+  pagesOrder: PageOrder[],
+  maxDepth: number = MENU_MAX_DEPTH,
+  currentDepth: number = 1
+): Page[] {
+  const childrenOrder = pagesOrder.find((order) => isEqualIds(order.data.page, parentPageId));
 
   /**
    * branch is a page children in tree
@@ -24,26 +33,26 @@ export function createMenuTree(parentPageId: EntityId, pages: Page[], pagesOrder
 
   if (childrenOrder) {
     ordered = childrenOrder.order.map((pageId: EntityId) => {
-      return pages.find(page => isEqualIds(page._id, pageId));
+      return pages.find((page) => isEqualIds(page._id, pageId));
     });
   }
 
-  const unordered = pages.filter(page => isEqualIds(page._parent, parentPageId));
+  const unordered = pages.filter((page) => isEqualIds(page._parent, parentPageId));
   const branch = Array.from(new Set([...ordered, ...unordered]));
 
-  /**
-   * stop recursion when we got the passed max level
-   */
-  if (currentLevel === level + 1) {
-    return [];
-  }
+  const canRecurse = currentDepth < maxDepth;
 
   /**
    * Each parents children can have subbranches
    */
-  return branch.filter(page => page && page._id).map(page => {
-    return Object.assign({
-      children: createMenuTree(page._id, pages, pagesOrder, level, currentLevel + 1),
-    }, page.data);
-  });
+  return branch
+    .filter((page) => page && page._id)
+    .map((page) => {
+      const subtree = canRecurse
+        ? createMenuTree(page._id!, pages, pagesOrder, maxDepth, currentDepth + 1)
+        : [];
+
+      /** `children` must win over anything stored on the page document */
+      return { ...page.data, children: subtree };
+    });
 }
diff --git a/src/backend/views/components/sidebar-branch.twig b/src/backend/views/components/sidebar-branch.twig
new file mode 100644
index 00000000..79d97000
--- /dev/null
+++ b/src/backend/views/components/sidebar-branch.twig
@@ -0,0 +1,18 @@
+{% if nodes is not empty %}
+  <ul class="docs-sidebar__section-list {{ ulClass }}">
+    {% for node in nodes %}
+      <li>
+        <a
+          class="docs-sidebar__section-list-item-wrapper"
+          href="{{ node.uri ? '/' ~ node.uri : '/page/' ~ node._id }}">
+          <div class="docs-sidebar__section-list-item {{ page is defined and toString(page._id) == toString(node._id) ? 'docs-sidebar__section-list-item--active' : '' }}">
+            <span>{{ node.title | striptags }}</span>
+          </div>
+        </a>
+        {% if node.children is defined and node.children is not empty %}
+          {% include 'components/sidebar-branch.twig' with { nodes: node.children, ulClass: 'docs-sidebar__section-list--nested' } %}
+        {% endif %}
+      </li>
+    {% endfor %}
+  </ul>
+{% endif %}
diff --git a/src/backend/views/components/sidebar.twig b/src/backend/views/components/sidebar.twig
index 46fb7e73..c5b26d29 100644
--- a/src/backend/views/components/sidebar.twig
+++ b/src/backend/views/components/sidebar.twig
@@ -26,19 +26,7 @@
         </div>
         </a>
         {% if firstLevelPage.children is not empty %}
-          <ul class="docs-sidebar__section-list">
-            {% for child in firstLevelPage.children %}
-              <li>
-                <a
-                  class="docs-sidebar__section-list-item-wrapper"
-                  href="{{ child.uri ? '/' ~ child.uri : '/page/' ~ child._id }}">
-                    <div class="docs-sidebar__section-list-item {{page is defined and toString(page._id) == toString(child._id) ? 'docs-sidebar__section-list-item--active' : ''}}">
-                      <span>{{ child.title | striptags }}</span>
-                    </div>
-                </a>
-              </li>
-            {% endfor %}
-          </ul>
+          {% include 'components/sidebar-branch.twig' with { nodes: firstLevelPage.children, ulClass: '' } %}
         {% endif %}
       </section>
     {% endfor %}
diff --git a/src/backend/views/pages/form.twig b/src/backend/views/pages/form.twig
index 643f9530..37263dcc 100644
--- a/src/backend/views/pages/form.twig
+++ b/src/backend/views/pages/form.twig
@@ -26,14 +26,11 @@
           {% endif %}
           <select id="parent" name="parent">
             <option value="0">Root</option>
-            {% for _page in pagesAvailableGrouped %}
+            {% for entry in parentSelectOptions %}
+              {% set _page = entry.page %}
               {% if toString(_page._id) != toString(currentPageId) %}
                 <option value="{{ toString(_page._id) }}" {{ page is not empty and toString(page._parent) == toString(_page._id) ? 'selected' : ''}}>
-                  {% if _page._parent != "0" %}
-                    &nbsp;
-                    &nbsp;
-                  {% endif %}
-                  {{ _page.title }}
+                  {{- entry.indent -}}{{- _page.title -}}
                 </option>
               {% endif %}
             {% endfor %}
diff --git a/src/frontend/js/modules/sidebar.js b/src/frontend/js/modules/sidebar.js
index e6dee56e..482bf3b6 100644
--- a/src/frontend/js/modules/sidebar.js
+++ b/src/frontend/js/modules/sidebar.js
@@ -128,9 +128,15 @@ export default class Sidebar {
       return;
     }
 
-    const itemsCount = sectionList.children.length;
+    /**
+     * Section has overflow:hidden; max-height must fit nested lists or deeper levels get clipped.
+     */
+    requestAnimationFrame(() => {
+      const natural = sectionList.scrollHeight;
+      const fallback = sectionList.querySelectorAll('li').length * ITEM_HEIGHT;
 
-    sectionList.style.maxHeight = `${itemsCount * ITEM_HEIGHT}px`;
+      sectionList.style.maxHeight = `${Math.max(natural, fallback)}px`;
+    });
   }
 
   /**
diff --git a/src/frontend/styles/components/sidebar.pcss b/src/frontend/styles/components/sidebar.pcss
index 04f6f83a..75aaf013 100644
--- a/src/frontend/styles/components/sidebar.pcss
+++ b/src/frontend/styles/components/sidebar.pcss
@@ -249,6 +249,11 @@
     margin: 0;
     z-index: 1;
     position: relative;
+
+    &--nested {
+      padding-left: 12px;
+      margin-top: 2px;
+    }
   }
 
   &__section-toggler {

From 56d8a79b3b832fc20a3a461105d74909ac410c7e Mon Sep 17 00:00:00 2001
From: Dobrunia Kostrigin <48620984+Dobrunia@users.noreply.github.com>
Date: Mon, 30 Mar 2026 20:29:11 +0300
Subject: [PATCH 2/5] Refactor sidebar component structure

---
 .../views/components/sidebar-branch.twig      |  18 ---
 .../views/components/sidebar-section.twig     |  26 ++++
 src/backend/views/components/sidebar.twig     |  20 +--
 src/frontend/js/classes/sidebar-filter.js     | 117 ++++++++++--------
 src/frontend/js/modules/sidebar.js            |  85 +++++++++----
 src/frontend/styles/components/sidebar.pcss   |  79 ++++++------
 6 files changed, 191 insertions(+), 154 deletions(-)
 delete mode 100644 src/backend/views/components/sidebar-branch.twig
 create mode 100644 src/backend/views/components/sidebar-section.twig

diff --git a/src/backend/views/components/sidebar-branch.twig b/src/backend/views/components/sidebar-branch.twig
deleted file mode 100644
index 79d97000..00000000
--- a/src/backend/views/components/sidebar-branch.twig
+++ /dev/null
@@ -1,18 +0,0 @@
-{% if nodes is not empty %}
-  <ul class="docs-sidebar__section-list {{ ulClass }}">
-    {% for node in nodes %}
-      <li>
-        <a
-          class="docs-sidebar__section-list-item-wrapper"
-          href="{{ node.uri ? '/' ~ node.uri : '/page/' ~ node._id }}">
-          <div class="docs-sidebar__section-list-item {{ page is defined and toString(page._id) == toString(node._id) ? 'docs-sidebar__section-list-item--active' : '' }}">
-            <span>{{ node.title | striptags }}</span>
-          </div>
-        </a>
-        {% if node.children is defined and node.children is not empty %}
-          {% include 'components/sidebar-branch.twig' with { nodes: node.children, ulClass: 'docs-sidebar__section-list--nested' } %}
-        {% endif %}
-      </li>
-    {% endfor %}
-  </ul>
-{% endif %}
diff --git a/src/backend/views/components/sidebar-section.twig b/src/backend/views/components/sidebar-section.twig
new file mode 100644
index 00000000..cb60214a
--- /dev/null
+++ b/src/backend/views/components/sidebar-section.twig
@@ -0,0 +1,26 @@
+{% set is_leaf = node.children is not defined or node.children is empty %}
+<section class="docs-sidebar__section{{ nested ? ' docs-sidebar__section--nested' : '' }}{{ is_leaf ? ' docs-sidebar__section--leaf' : '' }}" data-id="{{ node._id }}">
+  <a class="docs-sidebar__section-title-wrapper"
+    href="{{ node.uri ? '/' ~ node.uri : '/page/' ~ node._id }}"
+  >
+    <div class="docs-sidebar__section-title {{ page is defined and toString(page._id) == toString(node._id) ? 'docs-sidebar__section-title--active' : '' }}">
+      <span>
+        {{ node.title | striptags }}
+      </span>
+      {% if node.children is defined and node.children is not empty %}
+        <button type="button" class="docs-sidebar__section-toggler" aria-label="Toggle section">
+          {{ svg('arrow-up') }}
+        </button>
+      {% endif %}
+    </div>
+  </a>
+  {% if node.children is defined and node.children is not empty %}
+    <ul class="docs-sidebar__section-list docs-sidebar__section-list--nested">
+      {% for child in node.children %}
+        <li>
+          {% include 'components/sidebar-section.twig' with { node: child, nested: true } %}
+        </li>
+      {% endfor %}
+    </ul>
+  {% endif %}
+</section>
diff --git a/src/backend/views/components/sidebar.twig b/src/backend/views/components/sidebar.twig
index c5b26d29..21aa2178 100644
--- a/src/backend/views/components/sidebar.twig
+++ b/src/backend/views/components/sidebar.twig
@@ -10,25 +10,7 @@
 	    <input class="docs-sidebar__search" type="text" placeholder="Search" />
 	  </span>
     {% for firstLevelPage in menu %}
-      <section class="docs-sidebar__section" data-id="{{firstLevelPage._id}}">
-        <a class="docs-sidebar__section-title-wrapper"
-          href="{{firstLevelPage.uri ? '/' ~ firstLevelPage.uri : '/page/' ~ firstLevelPage._id }}"
-        >
-        <div class="docs-sidebar__section-title {{page is defined and page._id == firstLevelPage._id ? 'docs-sidebar__section-title--active' : ''}}">
-          <span>
-            {{ firstLevelPage.title | striptags }}
-          </span>
-          {% if firstLevelPage.children is not empty %}
-            <button class="docs-sidebar__section-toggler">
-              {{ svg('arrow-up') }}
-            </button>
-          {% endif %}
-        </div>
-        </a>
-        {% if firstLevelPage.children is not empty %}
-          {% include 'components/sidebar-branch.twig' with { nodes: firstLevelPage.children, ulClass: '' } %}
-        {% endif %}
-      </section>
+      {% include 'components/sidebar-section.twig' with { node: firstLevelPage, nested: false } %}
     {% endfor %}
 
     <div class="docs-sidebar__logo">
diff --git a/src/frontend/js/classes/sidebar-filter.js b/src/frontend/js/classes/sidebar-filter.js
index 7087ccde..339b4aff 100644
--- a/src/frontend/js/classes/sidebar-filter.js
+++ b/src/frontend/js/classes/sidebar-filter.js
@@ -23,14 +23,12 @@ export default class SidebarFilter {
    */
   static get CSS() {
     return {
+      section: 'docs-sidebar__section',
       sectionHidden: 'docs-sidebar__section--hidden',
       sectionTitle: 'docs-sidebar__section-title',
       sectionTitleSelected: 'docs-sidebar__section-title--selected',
       sectionTitleActive: 'docs-sidebar__section-title--active',
       sectionList: 'docs-sidebar__section-list',
-      sectionListItem: 'docs-sidebar__section-list-item',
-      sectionListItemWrapperHidden: 'docs-sidebar__section-list-item-wrapper--hidden',
-      sectionListItemSlelected: 'docs-sidebar__section-list-item--selected',
       sidebarSearchWrapper: 'docs-sidebar__search-wrapper',
     };
   }
@@ -43,7 +41,7 @@ export default class SidebarFilter {
      * Stores refs to HTML elements needed for sidebar filter to work.
      */
     this.sidebar = null;
-    this.sections = [];
+    this.rootSections = [];
     this.sidebarContent = null;
     this.search = null;
     this.searchResults = [];
@@ -53,14 +51,14 @@ export default class SidebarFilter {
   /**
    * Initialize sidebar filter.
    *
-   * @param {HTMLElement[]} sections - Array of sections.
+   * @param {HTMLElement[]} rootSections - Top-level sections (direct children of sidebar content).
    * @param {HTMLElement} sidebarContent - Sidebar content.
    * @param {HTMLElement} search - Search input.
    * @param {Function} setSectionCollapsed - Function to set section collapsed.
    */
-  init(sections, sidebarContent, search, setSectionCollapsed) {
+  init(rootSections, sidebarContent, search, setSectionCollapsed) {
     // Store refs to HTML elements.
-    this.sections = sections;
+    this.rootSections = rootSections;
     this.sidebarContent = sidebarContent;
     this.search = search;
     this.setSectionCollapsed = setSectionCollapsed;
@@ -202,11 +200,8 @@ export default class SidebarFilter {
       return;
     }
 
-    // focus title or item.
     if (type === 'title') {
       element.classList.add(SidebarFilter.CSS.sectionTitleSelected);
-    } else if (type === 'item') {
-      element.classList.add(SidebarFilter.CSS.sectionListItemSlelected);
     }
 
     // scroll to focused title or item.
@@ -230,11 +225,8 @@ export default class SidebarFilter {
       return;
     }
 
-    // blur title or item.
     if (type === 'title') {
       element.classList.remove(SidebarFilter.CSS.sectionTitleSelected);
-    } else if (type === 'item') {
-      element.classList.remove(SidebarFilter.CSS.sectionListItemSlelected);
     }
   }
 
@@ -294,54 +286,76 @@ export default class SidebarFilter {
    * @param {string} searchValue - Search value.
    */
   filterSection(section, searchValue) {
-    // match with section title.
     const sectionTitle = section.querySelector('.' + SidebarFilter.CSS.sectionTitle);
-    const sectionList = section.querySelector('.' + SidebarFilter.CSS.sectionList);
+    const sectionList = section.querySelector(':scope > .' + SidebarFilter.CSS.sectionList);
+
+    if (!sectionTitle) {
+      return false;
+    }
+
+    const empty = !searchValue || !searchValue.trim();
+
+    if (empty) {
+      section.classList.remove(SidebarFilter.CSS.sectionHidden);
+
+      if (sectionList) {
+        Array.from(sectionList.children).forEach((li) => {
+          const nestedSection = li.querySelector(':scope > .' + SidebarFilter.CSS.section);
+
+          if (nestedSection) {
+            this.filterSection(nestedSection, searchValue);
+          }
+        });
+      }
+
+      return true;
+    }
 
-    // check if section title matches.
     const isTitleMatch = this.isValueMatched(sectionTitle.textContent, searchValue);
+    let hasMatch = isTitleMatch;
 
-    const matchResults = [];
-    // match with section items.
-    let isSingleItemMatch = false;
+    if (isTitleMatch) {
+      this.searchResults.push({
+        element: sectionTitle,
+        type: 'title',
+      });
+    }
 
     if (sectionList) {
-      const sectionListItems = sectionList.querySelectorAll('.' + SidebarFilter.CSS.sectionListItem);
-
-      sectionListItems.forEach(item => {
-        if (this.isValueMatched(item.textContent, searchValue)) {
-          // remove hiden class from item.
-          item.parentElement.classList.remove(SidebarFilter.CSS.sectionListItemWrapperHidden);
-          // add item to search results.
-          matchResults.push({
-            element: item,
-            type: 'item',
-          });
-          isSingleItemMatch = true;
-        } else {
-          // hide item if it is not a match.
-          item.parentElement.classList.add(SidebarFilter.CSS.sectionListItemWrapperHidden);
+      for (const li of sectionList.children) {
+        const nestedSection = li.querySelector(':scope > .' + SidebarFilter.CSS.section);
+
+        if (!nestedSection) {
+          continue;
         }
-      });
-    }
-    if (!isTitleMatch && !isSingleItemMatch) {
-      // hide section if it's items are not a match.
-      section.classList.add(SidebarFilter.CSS.sectionHidden);
-    } else {
-      const parentSection = sectionTitle.closest('section');
 
-      // if item is in collapsed section, expand it.
-      if (!parentSection.classList.contains(SidebarFilter.CSS.sectionTitleActive)) {
-        this.setSectionCollapsed(parentSection, false);
+        const childHasMatch = this.filterSection(nestedSection, searchValue);
+
+        hasMatch = hasMatch || childHasMatch;
       }
-      // show section if it's items are a match.
+    }
+
+    if (hasMatch) {
       section.classList.remove(SidebarFilter.CSS.sectionHidden);
-      // add section title to search results.
-      this.searchResults.push({
-        element: sectionTitle,
-        type: 'title',
-      }, ...matchResults);
+      this.setSectionCollapsed(section, false);
+
+      let el = section.parentElement;
+
+      while (el && el !== this.sidebarContent) {
+        const ancSection = el.closest('.' + SidebarFilter.CSS.section);
+
+        if (!ancSection) {
+          break;
+        }
+
+        this.setSectionCollapsed(ancSection, false);
+        el = ancSection.parentElement;
+      }
+    } else {
+      section.classList.add(SidebarFilter.CSS.sectionHidden);
     }
+
+    return hasMatch;
   }
 
   /**
@@ -356,8 +370,7 @@ export default class SidebarFilter {
     this.selectedSearchResultIndex = null;
     // empty search results.
     this.searchResults = [];
-    // match search value with sidebar sections.
-    this.sections.forEach(section => {
+    this.rootSections.forEach(section => {
       this.filterSection(section, searchValue);
     });
   }
diff --git a/src/frontend/js/modules/sidebar.js b/src/frontend/js/modules/sidebar.js
index 482bf3b6..122a8395 100644
--- a/src/frontend/js/modules/sidebar.js
+++ b/src/frontend/js/modules/sidebar.js
@@ -7,11 +7,6 @@ import SidebarFilter from '../classes/sidebar-filter';
 const LOCAL_STORAGE_KEY = 'docs_sidebar_state';
 const SIDEBAR_VISIBILITY_KEY = 'docs_sidebar_visibility';
 
-/**
- * Section list item height in px
- */
-const ITEM_HEIGHT = 31;
-
 /**
  * Sidebar module
  */
@@ -30,7 +25,6 @@ export default class Sidebar {
       sectionTitle: 'docs-sidebar__section-title',
       sectionTitleActive: 'docs-sidebar__section-title--active',
       sectionList: 'docs-sidebar__section-list',
-      sectionListItemActive: 'docs-sidebar__section-list-item--active',
       sidebarToggler: 'docs-sidebar__toggler',
       sidebarSlider: 'docs-sidebar__slider',
       sidebarCollapsed: 'docs-sidebar--collapsed',
@@ -71,6 +65,8 @@ export default class Sidebar {
     this.isVisible = storedVisibility !== 'false';
     // Sidebar filter module
     this.filter = new SidebarFilter();
+    /** @type {number | null} */
+    this._recalcListsRaf = null;
   }
 
   /**
@@ -81,17 +77,25 @@ export default class Sidebar {
    */
   init(settings, moduleEl) {
     this.nodes.sidebar = moduleEl;
-    this.nodes.sections = Array.from(moduleEl.querySelectorAll('.' + Sidebar.CSS.section));
-    this.nodes.sections.forEach(section => this.initSection(section));
     this.nodes.sidebarContent = moduleEl.querySelector('.' + Sidebar.CSS.sidebarContent);
+    this.nodes.sections = Array.from(moduleEl.querySelectorAll('.' + Sidebar.CSS.section));
+    this.nodes.rootSections = Array.from(
+      this.nodes.sidebarContent.querySelectorAll(':scope > .' + Sidebar.CSS.section)
+    );
+    this.nodes.sections.forEach((section) => this.initSection(section));
+    this.scheduleRecalcSectionLists();
     this.nodes.toggler = moduleEl.querySelector('.' + Sidebar.CSS.sidebarToggler);
     this.nodes.toggler.addEventListener('click', () => this.toggleSidebar());
     this.nodes.slider = moduleEl.querySelector('.' + Sidebar.CSS.sidebarSlider);
     this.nodes.slider.addEventListener('click', () => this.handleSliderClick());
 
     this.nodes.search = moduleEl.querySelector('.' + Sidebar.CSS.sidebarSearch);
-    this.filter.init(this.nodes.sections, this.nodes.sidebarContent,
-      this.nodes.search, this.setSectionCollapsed);
+    this.filter.init(
+      this.nodes.rootSections,
+      this.nodes.sidebarContent,
+      this.nodes.search,
+      this.setSectionCollapsed
+    );
 
     this.ready();
   }
@@ -110,7 +114,7 @@ export default class Sidebar {
       return;
     }
 
-    togglerEl.addEventListener('click', e => this.handleSectionTogglerClick(id, section, e));
+    togglerEl.addEventListener('click', (e) => this.handleSectionTogglerClick(id, section, e));
 
     if (typeof this.sectionsState[id] === 'undefined') {
       this.sectionsState[id] = false;
@@ -118,24 +122,49 @@ export default class Sidebar {
     if (this.sectionsState[id]) {
       this.setSectionCollapsed(section, true, false);
     }
+  }
 
-    /**
-     * Calculate and set sections list max height for smooth animation
-     */
-    const sectionList = section.querySelector('.' + Sidebar.CSS.sectionList);
+  /**
+   * Recompute max-height for every expanded section list (nested opens change ancestor scrollHeight).
+   * Uses a two-phase measure so parents see full child height (ITEM_HEIGHT * li was wrong for deep trees).
+   */
+  recalcSectionListsMaxHeight() {
+    this.nodes.sections.forEach((section) => {
+      if (section.classList.contains(Sidebar.CSS.sectionCollapsed)) {
+        return;
+      }
+      const list = section.querySelector(':scope > .' + Sidebar.CSS.sectionList);
 
-    if (!sectionList) {
-      return;
-    }
+      if (list) {
+        list.style.maxHeight = 'none';
+      }
+    });
 
-    /**
-     * Section has overflow:hidden; max-height must fit nested lists or deeper levels get clipped.
-     */
     requestAnimationFrame(() => {
-      const natural = sectionList.scrollHeight;
-      const fallback = sectionList.querySelectorAll('li').length * ITEM_HEIGHT;
+      [...this.nodes.sections].reverse().forEach((section) => {
+        if (section.classList.contains(Sidebar.CSS.sectionCollapsed)) {
+          return;
+        }
+        const list = section.querySelector(':scope > .' + Sidebar.CSS.sectionList);
 
-      sectionList.style.maxHeight = `${Math.max(natural, fallback)}px`;
+        if (!list) {
+          return;
+        }
+        list.style.maxHeight = `${list.scrollHeight + 4}px`;
+      });
+    });
+  }
+
+  /**
+   * Batches recalc after collapse/expand and filter-driven opens.
+   */
+  scheduleRecalcSectionLists() {
+    if (this._recalcListsRaf !== null) {
+      return;
+    }
+    this._recalcListsRaf = requestAnimationFrame(() => {
+      this._recalcListsRaf = null;
+      this.recalcSectionListsMaxHeight();
     });
   }
 
@@ -162,7 +191,7 @@ export default class Sidebar {
    * @param {boolean} [animated] - true if state should change with animation
    */
   setSectionCollapsed(sectionEl, collapsed, animated = true) {
-    const sectionList = sectionEl.querySelector('.' + Sidebar.CSS.sectionList);
+    const sectionList = sectionEl.querySelector(':scope > .' + Sidebar.CSS.sectionList);
 
     if (!sectionList) {
       return;
@@ -170,13 +199,15 @@ export default class Sidebar {
     sectionEl.classList.toggle(Sidebar.CSS.sectionAnimated, animated);
     sectionEl.classList.toggle(Sidebar.CSS.sectionCollapsed, collapsed);
 
+    this.scheduleRecalcSectionLists();
+
     /**
      * Highlight section item as active if active child item is collapsed.
      */
-    const activeSectionListItem = sectionList.querySelector('.' + Sidebar.CSS.sectionListItemActive);
+    const activeInSubtree = sectionList.querySelector('.' + Sidebar.CSS.sectionTitleActive);
     const sectionTitle = sectionEl.querySelector('.' + Sidebar.CSS.sectionTitle);
 
-    if (!activeSectionListItem) {
+    if (!activeInSubtree) {
       return;
     }
     if (collapsed && animated) {
diff --git a/src/frontend/styles/components/sidebar.pcss b/src/frontend/styles/components/sidebar.pcss
index 75aaf013..8eac153f 100644
--- a/src/frontend/styles/components/sidebar.pcss
+++ b/src/frontend/styles/components/sidebar.pcss
@@ -114,10 +114,32 @@
   }
 
   &__section {
-    overflow: hidden;
+    /* overflow only on the list — squircle mask on titles bleeds past the box and was clipped here */
+    overflow: visible;
     flex-shrink: 0;
     margin-top: 20px;
 
+    &--nested {
+      margin-top: 2px;
+    }
+
+    &--leaf {
+      .docs-sidebar__section-title {
+        font-size: 14px;
+        line-height: 21px;
+        height: 29px;
+
+        @media (--mobile) {
+          font-size: 16px;
+          line-height: 21px;
+        }
+      }
+
+      .docs-sidebar__section-title--active {
+        color: white;
+      }
+    }
+
     &--hidden {
       display: none;
     }
@@ -137,6 +159,7 @@
     &--collapsed {
       .docs-sidebar__section-list {
         max-height: 0 !important;
+        padding-bottom: 0;
       }
 
       .docs-sidebar__section-toggler {
@@ -156,25 +179,11 @@
   &__section-title {
     font-size: 16px;
     line-height: 24px;
-    font-weight: 700;
+    font-weight: 400;
+    color: var(--color-text-main);
     z-index: 2;
     position: relative;
     height: 34px;
-  }
-
-  &__section-list-item {
-    font-size: 14px;
-    line-height: 21px;
-    height: 29px;
-
-    @media (--mobile) {
-      font-size: 16px;
-      line-height: 21px;
-    }
-  }
-
-  &__section-title,
-  &__section-list-item {
     display: flex;
     align-items: center;
     justify-content: space-between;
@@ -190,12 +199,16 @@
 
     &--active,
     &:hover {
-      @apply --squircle;
+      /* plain radius: --squircle uses mask-box-image and gets clipped by overflow:hidden on ancestors */
+      border-radius: 8px;
+    }
+
+    &:has(.docs-sidebar__section-toggler) {
+      font-weight: 700;
     }
   }
 
-  &__section-title > span,
-  &__section-list-item > span {
+  &__section-title > span {
     white-space: nowrap;
     overflow: hidden;
     text-overflow: ellipsis;
@@ -208,22 +221,7 @@
     }
   }
 
-  &__section-list-item-wrapper {
-    padding: 1px 0;
-    display: block;
-    &--hidden {
-      display: none !important;
-    }
-  }
-
-  li:last-child {
-    .docs-sidebar__section-list-item-wrapper {
-      padding-bottom: 0;
-    }
-  }
-
-  &__section-title:not(&__section-title--active),
-  &__section-list-item:not(&__section-list-item--active) {
+  &__section-title:not(&__section-title--active) {
     @media (--can-hover) {
       &:hover {
         background: var(--color-link-hover);
@@ -231,8 +229,7 @@
     }
   }
 
-  &__section-title--active,
-  &__section-list-item--active {
+  &__section-title--active {
     background: linear-gradient(270deg, #129bff 0%, #8a53ff 100%);
     color: white;
 
@@ -246,14 +243,20 @@
   &__section-list {
     list-style: none;
     padding: 0;
+    padding-bottom: 6px;
     margin: 0;
     z-index: 1;
     position: relative;
+    overflow: hidden;
 
     &--nested {
       padding-left: 12px;
       margin-top: 2px;
     }
+
+    & > li + li {
+      margin-top: 2px;
+    }
   }
 
   &__section-toggler {

From 9c9de400eb5742fbd0e9e4fc87fbf8b261db7380 Mon Sep 17 00:00:00 2001
From: Dobrunia Kostrigin <48620984+Dobrunia@users.noreply.github.com>
Date: Mon, 30 Mar 2026 20:37:59 +0300
Subject: [PATCH 3/5] Refactor menu tree creation for improved readability

---
 src/backend/utils/menu.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/backend/utils/menu.ts b/src/backend/utils/menu.ts
index 6137424c..3f503469 100644
--- a/src/backend/utils/menu.ts
+++ b/src/backend/utils/menu.ts
@@ -33,11 +33,11 @@ export function createMenuTree(
 
   if (childrenOrder) {
     ordered = childrenOrder.order.map((pageId: EntityId) => {
-      return pages.find((page) => isEqualIds(page._id, pageId));
+      return pages.find(page => isEqualIds(page._id, pageId));
     });
   }
 
-  const unordered = pages.filter((page) => isEqualIds(page._parent, parentPageId));
+  const unordered = pages.filter(page => isEqualIds(page._parent, parentPageId));
   const branch = Array.from(new Set([...ordered, ...unordered]));
 
   const canRecurse = currentDepth < maxDepth;

From da0730183e9d973912b2fe0ddfff38c64ccbffc1 Mon Sep 17 00:00:00 2001
From: Dobrunia Kostrigin <48620984+Dobrunia@users.noreply.github.com>
Date: Thu, 2 Apr 2026 22:32:33 +0300
Subject: [PATCH 4/5] Refactor page grouping logic to combine parent and map
 retrieval, improving efficiency and readability. Update sidebar filter to
 handle navigation more robustly by ensuring the correct element is clicked.

---
 src/backend/controllers/pages.ts          | 41 +++++++++++++++--------
 src/frontend/js/classes/sidebar-filter.js |  6 ++--
 src/frontend/js/modules/sidebar.js        | 14 ++++++--
 3 files changed, 43 insertions(+), 18 deletions(-)

diff --git a/src/backend/controllers/pages.ts b/src/backend/controllers/pages.ts
index 855c5f64..b8c2fb0b 100644
--- a/src/backend/controllers/pages.ts
+++ b/src/backend/controllers/pages.ts
@@ -109,10 +109,9 @@ class Pages {
   public static async getParentSelectOptions(
     excludePageId?: EntityId
   ): Promise<Array<{ page: Page; depth: number; indent: string }>> {
-    const pages = excludePageId
-      ? await this.groupByParent(excludePageId)
-      : await this.groupByParent();
-    const pagesMap = await this.getPagesMap();
+    const { pages, pagesMap } = excludePageId
+      ? await this.groupByParentWithMap(excludePageId)
+      : await this.groupByParentWithMap('' as EntityId);
     const indentUnit = '\u00a0\u00a0';
 
     return pages.map((page) => {
@@ -123,13 +122,12 @@ class Pages {
   }
 
   /**
-   * Group all pages by their parents
-   * If the pageId is passed, it excludes passed page from result pages
-   *
-   * @param {string} pageId - pageId to exclude from result pages
-   * @returns {Page[]}
+   * Same as {@link groupByParent} but returns the pages map from the same load (no second getPagesMap).
    */
-  public static async groupByParent(pageId = '' as EntityId): Promise<Page[]> {
+  private static async groupByParentWithMap(pageId = '' as EntityId): Promise<{
+    pages: Page[];
+    pagesMap: Map<string, Page>;
+  }> {
     const rootPageOrder = await PagesOrder.getRootPageOrder(); // get order of the root pages
     const childPageOrder = await PagesOrder.getChildPageOrder(); // get order of the all other pages
 
@@ -137,7 +135,7 @@ class Pages {
      * If there is no root and child page order, then it returns an empty array
      */
     if (!rootPageOrder || (!rootPageOrder && childPageOrder.length <= 0)) {
-      return [];
+      return { pages: [], pagesMap: new Map() };
     }
 
     const pagesMap = await this.getPagesMap();
@@ -176,16 +174,31 @@ class Pages {
      * Otherwise just returns result itself
      */
     if (pageId) {
-      return this.removeChildren(result, pageId).reduce((prev, curr) => {
+      const pages = this.removeChildren(result, pageId).reduce((prev, curr) => {
         if (curr instanceof Page) {
           prev.push(curr);
         }
 
         return prev;
       }, Array<Page>());
-    } else {
-      return result;
+
+      return { pages, pagesMap };
     }
+
+    return { pages: result, pagesMap };
+  }
+
+  /**
+   * Group all pages by their parents
+   * If the pageId is passed, it excludes passed page from result pages
+   *
+   * @param {string} pageId - pageId to exclude from result pages
+   * @returns {Page[]}
+   */
+  public static async groupByParent(pageId = '' as EntityId): Promise<Page[]> {
+    const { pages } = await this.groupByParentWithMap(pageId);
+
+    return pages;
   }
 
   /**
diff --git a/src/frontend/js/classes/sidebar-filter.js b/src/frontend/js/classes/sidebar-filter.js
index 339b4aff..245d7d37 100644
--- a/src/frontend/js/classes/sidebar-filter.js
+++ b/src/frontend/js/classes/sidebar-filter.js
@@ -96,8 +96,10 @@ export default class SidebarFilter {
 
     // handle enter key when item is focused.
     if (e.code === 'Enter' && this.selectedSearchResultIndex !== null) {
-      // navigate to focused item.
-      this.searchResults[this.selectedSearchResultIndex].element.click();
+      const raw = this.searchResults[this.selectedSearchResultIndex].element;
+      const navigateEl = raw.closest('a') || raw;
+
+      navigateEl.click();
       // prevent default action.
       e.preventDefault();
       e.stopPropagation();
diff --git a/src/frontend/js/modules/sidebar.js b/src/frontend/js/modules/sidebar.js
index 122a8395..5f6bca6a 100644
--- a/src/frontend/js/modules/sidebar.js
+++ b/src/frontend/js/modules/sidebar.js
@@ -7,6 +7,11 @@ import SidebarFilter from '../classes/sidebar-filter';
 const LOCAL_STORAGE_KEY = 'docs_sidebar_state';
 const SIDEBAR_VISIBILITY_KEY = 'docs_sidebar_visibility';
 
+/**
+ * Slack beyond scrollHeight + vertical borders for max-height (subpixels, hover radius).
+ */
+const SIDEBAR_LIST_MAX_HEIGHT_SLACK_PX = 4;
+
 /**
  * Sidebar module
  */
@@ -94,7 +99,7 @@ export default class Sidebar {
       this.nodes.rootSections,
       this.nodes.sidebarContent,
       this.nodes.search,
-      this.setSectionCollapsed
+      this.setSectionCollapsed.bind(this)
     );
 
     this.ready();
@@ -150,7 +155,12 @@ export default class Sidebar {
         if (!list) {
           return;
         }
-        list.style.maxHeight = `${list.scrollHeight + 4}px`;
+        const cs = globalThis.getComputedStyle(list);
+        const borderY =
+          (Number.parseFloat(cs.borderTopWidth) || 0) +
+          (Number.parseFloat(cs.borderBottomWidth) || 0);
+
+        list.style.maxHeight = `${list.scrollHeight + borderY + SIDEBAR_LIST_MAX_HEIGHT_SLACK_PX}px`;
       });
     });
   }

From d1ff3727892f659e643779fc17b334d03188751d Mon Sep 17 00:00:00 2001
From: Dobrunia Kostrigin <48620984+Dobrunia@users.noreply.github.com>
Date: Fri, 3 Apr 2026 11:23:32 +0300
Subject: [PATCH 5/5] Refactor parent select options to remove visual indenting
 and streamline data structure. Update Twig template to handle depth-based
 indentation for improved clarity in dropdowns.

---
 src/backend/controllers/pages.ts  | 14 ++++++--------
 src/backend/views/pages/form.twig |  7 +++++--
 2 files changed, 11 insertions(+), 10 deletions(-)

diff --git a/src/backend/controllers/pages.ts b/src/backend/controllers/pages.ts
index b8c2fb0b..73881d14 100644
--- a/src/backend/controllers/pages.ts
+++ b/src/backend/controllers/pages.ts
@@ -102,23 +102,21 @@ class Pages {
   }
 
   /**
-   * Ordered pages for the parent `<select>` with visual nesting (indent = depth).
+   * Ordered pages for the parent `<select>` with nesting depth (indent in the template).
    *
    * @param excludePageId - when editing, exclude this page and its descendants (same as groupByParent)
    */
   public static async getParentSelectOptions(
     excludePageId?: EntityId
-  ): Promise<Array<{ page: Page; depth: number; indent: string }>> {
+  ): Promise<Array<{ page: Page; depth: number }>> {
     const { pages, pagesMap } = excludePageId
       ? await this.groupByParentWithMap(excludePageId)
       : await this.groupByParentWithMap('' as EntityId);
-    const indentUnit = '\u00a0\u00a0';
 
-    return pages.map((page) => {
-      const depth = Pages.computePageDepth(page, pagesMap);
-
-      return { page, depth, indent: indentUnit.repeat(depth) };
-    });
+    return pages.map((page) => ({
+      page,
+      depth: Pages.computePageDepth(page, pagesMap),
+    }));
   }
 
   /**
diff --git a/src/backend/views/pages/form.twig b/src/backend/views/pages/form.twig
index 37263dcc..10bffdef 100644
--- a/src/backend/views/pages/form.twig
+++ b/src/backend/views/pages/form.twig
@@ -30,7 +30,10 @@
               {% set _page = entry.page %}
               {% if toString(_page._id) != toString(currentPageId) %}
                 <option value="{{ toString(_page._id) }}" {{ page is not empty and toString(page._parent) == toString(_page._id) ? 'selected' : ''}}>
-                  {{- entry.indent -}}{{- _page.title -}}
+                  {%- if entry.depth > 0 -%}
+                    {%- for _ in 1..entry.depth %}&nbsp;&nbsp;{% endfor -%}
+                  {%- endif -%}
+                  {{- _page.title|striptags -}}
                 </option>
               {% endif %}
             {% endfor %}
@@ -42,7 +45,7 @@
             <select id="above" name="above">
               <option value="0">—</option>
               {% for _page in parentsChildrenOrdered %}
-                <option value="{{ toString(_page._id) }}">{{ _page.title }}</option>
+                <option value="{{ toString(_page._id) }}">{{ _page.title|striptags }}</option>
               {% endfor %}
             </select>
           </div>