Page Shell, Navigation, and Routes

Use this reference when adding or changing a core admin page, page header, breadcrumbs, tabs, or sidebar entry.

Admin page shape

Most admin config pages sit in this hierarchy:

Admin interface
Config page in sidebar
Optional third-level tabs
New/edit/show routes for records

Every sidebar-visible config page needs a stable navigation entry, browser title, page title, and page description. This supports consistency now and admin search/navigation enhancements later.

Sidebar entries

Add config pages to ADMIN_NAV_MAP in frontend/discourse/app/lib/sidebar/admin-nav-map.js.

Required or expected keys:

• name: unique snake_case identifier.
• route: Ember route name. Prefer this over href.
• label: I18n key, usually admin.config.page_name.title.
• description: I18n key, usually admin.config.page_name.header_description.
• icon: FontAwesome icon name used in the sidebar.

Use optional keys when relevant:

• routeModels: route params in route order.
• moderator: true if moderators can access the page.
• keywords: I18n key containing |-separated search synonyms.
• links: third-level child routes for admin search; these are not sidebar rows.
• settings_area or settings_category: for pages backed by filtered site settings.
• multi_tabbed: true when a page has settings plus other tabs.

Example to inspect: frontend/discourse/app/lib/sidebar/admin-nav-map.js, especially admin_localization, admin_login, and admin_permalinks.

Translations

Core config page title and description keys should be shaped like this:

en:
  js:
    admin:
      config:
        page_name:
          title: "Page title"
          header_description: "What admins can manage here."
          keywords: "optional|search|terms"

Keep UI text sentence-cased unless the string is a table header or a proper name. Do not split translated sentences around links or interpolated values; use placeholders.

DPageHeader

Use DPageHeader from discourse/ui-kit/d-page-header for the top of admin pages.

Include:

• @titleLabel: translated page title.
• @descriptionLabel: translated page description.
• @learnMoreUrl: optional docs URL.
• @hideTabs={{true}}: when the page has no third-level tabs.
• :breadcrumbs: one DBreadcrumbsItem for /admin, plus the current page and any parent context.
• :actions: page-level actions. Use yielded actions.Primary, actions.Default, actions.Danger, or actions.Wrapped.
• :tabs: third-level DNavItem entries.

The component automatically hides itself on admin new and edit route segments. Override with @shouldDisplay only when the route intentionally needs a header.

Current examples:

• Simple page header: frontend/discourse/admin/templates/admin-config/about.gjs
• Header around filtered settings: frontend/discourse/admin/templates/admin-config/localization/settings.gjs
• Header with actions and tabs: frontend/discourse/admin/templates/admin/backups.gjs
• Plugin wrapper header: frontend/discourse/admin/components/admin-plugin-config-page.gjs

Minimal shape:

import DBreadcrumbsItem from "discourse/ui-kit/d-breadcrumbs-item";
import DPageHeader from "discourse/ui-kit/d-page-header";
import { i18n } from "discourse-i18n";

export default <template>
  <DPageHeader
    @titleLabel={{i18n "admin.config.example.title"}}
    @descriptionLabel={{i18n "admin.config.example.header_description"}}
    @hideTabs={{true}}
  >
    <:breadcrumbs>
      <DBreadcrumbsItem @path="/admin" @label={{i18n "admin_title"}} />
      <DBreadcrumbsItem
        @path="/admin/config/example"
        @label={{i18n "admin.config.example.title"}}
      />
    </:breadcrumbs>
  </DPageHeader>

  <div class="admin-config-page__main-area">
    {{outlet}}
  </div>
</template>

Tabs

Use tabs only for related views inside the same admin context. Do not use them as primary admin navigation; the sidebar owns that.

Tabs are rendered in the DPageHeader :tabs block with DNavItem from discourse/ui-kit/d-nav-item.

<:tabs>
  <DNavItem
    @route="admin.example.settings"
    @label="settings"
    class="admin-example-tabs__settings"
  />
  <DNavItem
    @route="admin.example.records"
    @label="admin.example.records"
    class="admin-example-tabs__records"
  />
</:tabs>

If plugins should extend the tab list, include the established PluginOutlet for that area rather than hardcoding plugin links.

Browser titles

Admin routes should extend Discourse route classes and implement titleToken() when they own a browser title:

import { i18n } from "discourse-i18n";
import DiscourseRoute from "discourse/routes/discourse";

export default class AdminExampleRoute extends DiscourseRoute {
  titleToken() {
    return i18n("admin.config.example.title");
  }
}

For filtered settings pages, use the specialized route class described in filtered-settings-pages.md.

Breadcrumbs

Breadcrumbs appear above the page header content on normal admin pages. Use a /admin crumb first, then page hierarchy crumbs, and mark the current page by using the current path and title. Do not add the normal header/breadcrumb area to third-level new/edit pages; use a back link there instead.

The implementation is via DBreadcrumbsItem yielded into the DPageHeader; DPageHeader provides the container.