feat: Add popular content per locale (#14939)

app/controllers/api/v1/accounts/portals_controller.rb

@@ -81,7 +81,8 @@ class Api::V1::Accounts::PortalsController < Api::V1::Accounts::BaseController
       :name, :page_title, :slug, :archived,
       { config: [:default_locale, :layout, { allowed_locales: [] }, { draft_locales: [] },
                  { social_profiles: %i[facebook x instagram linkedin youtube tiktok github whatsapp] },
-                 { locale_translations: locale_translation_keys.index_with { %i[name page_title header_text] } }] }
+                 { locale_translations: locale_translation_keys.index_with { %i[name page_title header_text] } },
+                 { popular_content: popular_content_keys.index_with { { category_ids: [], article_ids: [] } } }] }
     )
   end
 
@@ -89,6 +90,10 @@ class Api::V1::Accounts::PortalsController < Api::V1::Accounts::BaseController
     params.dig(:portal, :config, :locale_translations)&.keys || []
   end
 
+  def popular_content_keys
+    params.dig(:portal, :config, :popular_content)&.keys || []
+  end
+
   def live_chat_widget_params
     permitted_params = params.permit(:inbox_id)
     return {} unless permitted_params.key?(:inbox_id)

app/controllers/concerns/portal_home_data.rb

@@ -4,17 +4,53 @@ module PortalHomeData
   private
 
   def load_home_data
-    base_articles = @portal.articles.published.where(locale: @locale).includes(:author, :category)
+    load_recommended_content
+    # The classic hero only needs the recommendations above; the rest is
+    # documentation-layout home data (also used on custom-domain home pages).
+    return unless @portal.layout == 'documentation'
+
     @visible_categories = @portal.categories
                                  .where(locale: @locale)
                                  .joins(:articles).where(articles: { status: :published })
                                  .order(position: :asc)
                                  .group('categories.id')
-    @popular_topics = @visible_categories.first(3)
+    @popular_topics = @recommended_categories.presence || @visible_categories.first(3)
     @featured = base_articles.order_by_views.limit(6)
     @category_contributors = build_category_contributors(@visible_categories)
   end
 
+  def load_recommended_content
+    @recommended_categories = recommended_categories
+    @recommended_articles = recommended_articles
+  end
+
+  def base_articles
+    @base_articles ||= @portal.articles.published.where(locale: @locale).includes(:author, :category)
+  end
+
+  # Admin-recommended categories for the locale, in the chosen order. Unlike the
+  # position-based fallback, published articles aren't required: the admin's pick wins.
+  def recommended_categories
+    ids = @portal.popular_category_ids(@locale)
+    ordered_by_ids(@portal.categories.where(locale: @locale, id: ids), ids)
+  end
+
+  # Admin-recommended articles for the locale, in the chosen order, limited to
+  # published articles that still exist.
+  def recommended_articles
+    ids = @portal.popular_article_ids(@locale)
+    ordered_by_ids(base_articles.where(id: ids), ids)
+  end
+
+  # Loads the scope and returns its records ordered to match `ids`, dropping any
+  # that no longer exist. Skips the query entirely when `ids` is blank.
+  def ordered_by_ids(scope, ids)
+    return [] if ids.blank?
+
+    by_id = scope.index_by(&:id)
+    ids.filter_map { |id| by_id[id] }
+  end
+
   def build_category_contributors(categories)
     category_ids = categories.map(&:id)
     return {} if category_ids.empty?

app/controllers/dashboard_controller.rb

@@ -64,10 +64,8 @@ class DashboardController < ActionController::Base
     return unless @portal
 
     @locale = @portal.default_locale
-    if @portal.layout == 'documentation'
-      request.variant = :documentation
-      load_home_data
-    end
+    request.variant = :documentation if @portal.layout == 'documentation'
+    load_home_data
     render 'public/api/v1/portals/show', layout: 'portal', portal: @portal and return
   end
 

app/controllers/public/api/v1/portals_controller.rb

@@ -7,7 +7,7 @@ class Public::Api::V1::PortalsController < Public::Api::V1::Portals::BaseControl
   before_action :set_portal_layout
   before_action :set_view_variant
   before_action :ensure_portal_feature_enabled
-  before_action :load_home_data, only: [:show], if: -> { @portal_layout == 'documentation' }
+  before_action :load_home_data, only: [:show], unless: -> { @is_plain_layout_enabled }
   layout 'portal'
 
   def show

app/javascript/dashboard/api/helpCenter/articles.js

@@ -17,6 +17,7 @@ class ArticlesAPI extends PortalsAPI {
     categorySlug,
     sort,
     query,
+    signal,
   }) {
     const url = getArticleSearchURL({
       pageNumber,
@@ -30,7 +31,7 @@ class ArticlesAPI extends PortalsAPI {
       host: this.url,
     });
 
-    return axios.get(url);
+    return axios.get(url, { signal });
   }
 
   searchArticles({ portalSlug, query }) {

app/javascript/dashboard/api/specs/article.spec.js

@@ -37,7 +37,8 @@ describe('#PortalAPI', () => {
         authorId: '1',
       });
       expect(axiosMock.get).toHaveBeenCalledWith(
-        '/api/v1/portals/room-rental/articles?page=1&locale=en-US&status=published&author_id=1'
+        '/api/v1/portals/room-rental/articles?page=1&locale=en-US&status=published&author_id=1',
+        { signal: undefined }
       );
     });
   });

app/javascript/dashboard/components-next/HelpCenter/LocaleCard/LocaleCard.vue

@@ -56,6 +56,9 @@ const localeMenuLabels = computed(() => ({
   'customize-content': t(
     'HELP_CENTER.LOCALES_PAGE.LOCALE_CARD.DROPDOWN_MENU.CUSTOMIZE_CONTENT'
   ),
+  'select-popular-content': t(
+    'HELP_CENTER.LOCALES_PAGE.LOCALE_CARD.DROPDOWN_MENU.SELECT_POPULAR_CONTENT'
+  ),
   delete: t('HELP_CENTER.LOCALES_PAGE.LOCALE_CARD.DROPDOWN_MENU.DELETE'),
 }));
 

app/javascript/dashboard/components-next/HelpCenter/Pages/LocalePage/LocaleList.vue

@@ -2,6 +2,7 @@
 import { ref } from 'vue';
 import LocaleCard from 'dashboard/components-next/HelpCenter/LocaleCard/LocaleCard.vue';
 import LocaleContentDialog from 'dashboard/components-next/HelpCenter/Pages/LocalePage/LocaleContentDialog.vue';
+import PopularContentDialog from 'dashboard/components-next/HelpCenter/Pages/LocalePage/PopularContentDialog.vue';
 import { useStore } from 'dashboard/composables/store';
 import { useAlert, useTrack } from 'dashboard/composables';
 import { useUISettings } from 'dashboard/composables/useUISettings';
@@ -26,6 +27,7 @@ const route = useRoute();
 const { uiSettings, updateUISettings } = useUISettings();
 
 const contentDialogRef = ref(null);
+const popularContentDialogRef = ref(null);
 
 const isLocaleDefault = code => {
   return props.portal?.meta?.default_locale === code;
@@ -154,6 +156,8 @@ const handleAction = ({ action }, localeCode) => {
     publishLocale({ localeCode: localeCode });
   } else if (action === 'customize-content') {
     contentDialogRef.value.openForLocale(localeCode);
+  } else if (action === 'select-popular-content') {
+    popularContentDialogRef.value.openForLocale(localeCode);
   } else if (action === 'delete') {
     deletePortalLocale({ localeCode: localeCode });
   }
@@ -174,5 +178,6 @@ const handleAction = ({ action }, localeCode) => {
       @action="handleAction($event, locale.code)"
     />
     <LocaleContentDialog ref="contentDialogRef" :portal="portal" />
+    <PopularContentDialog ref="popularContentDialogRef" :portal="portal" />
   </ul>
 </template>

app/javascript/dashboard/components-next/HelpCenter/Pages/LocalePage/PopularContentDialog.vue

@@ -0,0 +1,235 @@
+<script setup>
+import { ref, computed } from 'vue';
+import { useI18n } from 'vue-i18n';
+import { useDebounceFn } from '@vueuse/core';
+import { useStore } from 'dashboard/composables/store';
+import { useAlert } from 'dashboard/composables';
+import { useAbortableRequest } from 'dashboard/composables/useAbortableRequest';
+import categoriesAPI from 'dashboard/api/helpCenter/categories';
+import articlesAPI from 'dashboard/api/helpCenter/articles';
+import Dialog from 'dashboard/components-next/dialog/Dialog.vue';
+import ReorderableMultiSelect from 'dashboard/components-next/combobox/ReorderableMultiSelect.vue';
+
+const props = defineProps({
+  portal: {
+    type: Object,
+    default: () => ({}),
+  },
+});
+
+const MAX_CATEGORIES = 3;
+const MAX_ARTICLES = 6;
+const KEY = 'HELP_CENTER.LOCALES_PAGE.POPULAR_CONTENT_DIALOG';
+
+const { t } = useI18n();
+const store = useStore();
+
+const dialogRef = ref(null);
+const activeLocale = ref('');
+// One flag per picker so each shows its skeleton until its own data loads.
+const categoriesLoading = ref(false);
+const { run: runArticleRequest, isPending: articlesLoading } =
+  useAbortableRequest();
+
+const categoryOptions = ref([]);
+const selectedCategoryIds = ref([]);
+
+// Articles are searched server-side, so cache options for selected items that
+// fall outside the current results.
+const articleResults = ref([]);
+const articleOptionById = ref({});
+const selectedArticleIds = ref([]);
+
+const popularContent = computed(
+  () => props.portal?.config?.popular_content || {}
+);
+
+const articleOptions = computed(() => {
+  const options = new Map();
+  selectedArticleIds.value.forEach(id => {
+    if (articleOptionById.value[id])
+      options.set(id, articleOptionById.value[id]);
+  });
+  articleResults.value.forEach(option => options.set(option.value, option));
+  return [...options.values()];
+});
+
+const toArticleOption = article => ({
+  value: article.id,
+  label: article.title,
+  subtitle: t(`${KEY}.ARTICLES.IN_CATEGORY`, {
+    category: article.category?.name || t(`${KEY}.ARTICLES.UNCATEGORIZED`),
+  }),
+});
+
+const fetchCategories = async localeCode => {
+  const {
+    data: { payload },
+  } = await categoriesAPI.get({
+    portalSlug: props.portal?.slug,
+    locale: localeCode,
+  });
+  return payload.map(category => ({
+    value: category.id,
+    label: category.name,
+    subtitle: t(`${KEY}.CATEGORIES.ARTICLES_COUNT`, {
+      count: category.meta?.articles_count || 0,
+    }),
+    icon: category.icon,
+    iconColor: category.icon_color,
+  }));
+};
+
+const requestArticles = async (query, signal) => {
+  const { data } = await articlesAPI.getArticles({
+    pageNumber: 1,
+    portalSlug: props.portal?.slug,
+    locale: activeLocale.value,
+    status: 'published',
+    query,
+    signal,
+  });
+  articleResults.value = data.payload.map(article => {
+    const option = toArticleOption(article);
+    articleOptionById.value[article.id] = option;
+    return option;
+  });
+};
+
+const searchArticles = (query = '') =>
+  runArticleRequest(signal => requestArticles(query, signal));
+
+const onArticleSearch = useDebounceFn(searchArticles, 300);
+
+// Resolve options for pre-selected articles that aren't in the current results.
+const cacheSelectedArticleOptions = async () => {
+  const unknownIds = selectedArticleIds.value.filter(
+    id => !articleOptionById.value[id]
+  );
+  await Promise.all(
+    unknownIds.map(async id => {
+      try {
+        const { data } = await articlesAPI.getArticle({
+          id,
+          portalSlug: props.portal?.slug,
+        });
+        articleOptionById.value[id] = toArticleOption(data.payload);
+      } catch {
+        // Deleted since it was picked; leave it for the id fallback.
+      }
+    })
+  );
+};
+
+const loadCategories = async localeCode => {
+  categoriesLoading.value = true;
+  try {
+    const options = await fetchCategories(localeCode);
+    // Reopened for another locale mid-flight; drop the stale response.
+    if (localeCode !== activeLocale.value) return;
+    categoryOptions.value = options;
+  } catch (error) {
+    useAlert(error?.message || t(`${KEY}.API.ERROR_MESSAGE`));
+  } finally {
+    if (localeCode === activeLocale.value) categoriesLoading.value = false;
+  }
+};
+
+const loadArticles = async () => {
+  try {
+    await runArticleRequest(signal =>
+      Promise.all([cacheSelectedArticleOptions(), requestArticles('', signal)])
+    );
+  } catch (error) {
+    useAlert(error?.message || t(`${KEY}.API.ERROR_MESSAGE`));
+  }
+};
+
+const openForLocale = localeCode => {
+  const existing = popularContent.value[localeCode] || {};
+  activeLocale.value = localeCode;
+  selectedCategoryIds.value = [...(existing.category_ids || [])];
+  selectedArticleIds.value = [...(existing.article_ids || [])];
+  categoryOptions.value = [];
+  articleResults.value = [];
+  articleOptionById.value = {};
+  dialogRef.value?.open();
+
+  loadCategories(localeCode);
+  loadArticles();
+};
+
+const onConfirm = async () => {
+  const updated = { ...popularContent.value };
+  const entry = {
+    category_ids: selectedCategoryIds.value,
+    article_ids: selectedArticleIds.value,
+  };
+
+  if (entry.category_ids.length || entry.article_ids.length) {
+    updated[activeLocale.value] = entry;
+  } else {
+    delete updated[activeLocale.value];
+  }
+
+  try {
+    await store.dispatch('portals/update', {
+      portalSlug: props.portal?.slug,
+      config: { popular_content: updated },
+    });
+    dialogRef.value?.close();
+    useAlert(t(`${KEY}.API.SUCCESS_MESSAGE`));
+  } catch (error) {
+    useAlert(error?.message || t(`${KEY}.API.ERROR_MESSAGE`));
+  }
+};
+
+defineExpose({ openForLocale });
+</script>
+
+<template>
+  <Dialog
+    ref="dialogRef"
+    type="edit"
+    :title="t(`${KEY}.TITLE`)"
+    :description="t(`${KEY}.DESCRIPTION`)"
+    :confirm-button-label="t(`${KEY}.CONFIRM`)"
+    @confirm="onConfirm"
+  >
+    <div class="flex flex-col gap-5">
+      <ReorderableMultiSelect
+        v-model="selectedCategoryIds"
+        :options="categoryOptions"
+        :max="MAX_CATEGORIES"
+        :label="t(`${KEY}.CATEGORIES.LABEL`)"
+        :add-label="t(`${KEY}.ADD_ANOTHER`)"
+        :search-placeholder="t(`${KEY}.SEARCH`)"
+        :empty-state="t(`${KEY}.EMPTY`)"
+        fallback-icon="i-lucide-folder"
+        :loading="categoriesLoading"
+      >
+        <template #counter="{ remaining }">
+          {{ t(`${KEY}.SLOTS_LEFT`, { count: remaining }) }}
+        </template>
+        <template #note>{{ t(`${KEY}.OVERRIDING_DEFAULTS`) }}</template>
+      </ReorderableMultiSelect>
+      <ReorderableMultiSelect
+        v-model="selectedArticleIds"
+        server-search
+        :options="articleOptions"
+        :max="MAX_ARTICLES"
+        :label="t(`${KEY}.ARTICLES.LABEL`)"
+        :add-label="t(`${KEY}.ADD_ANOTHER`)"
+        :search-placeholder="t(`${KEY}.SEARCH`)"
+        :empty-state="t(`${KEY}.EMPTY`)"
+        :loading="articlesLoading"
+        @search="onArticleSearch"
+      >
+        <template #counter="{ remaining }">
+          {{ t(`${KEY}.SLOTS_LEFT`, { count: remaining }) }}
+        </template>
+        <template #note>{{ t(`${KEY}.OVERRIDING_DEFAULTS`) }}</template>
+      </ReorderableMultiSelect>
+    </div>
+  </Dialog>
+</template>

app/javascript/dashboard/components-next/combobox/ComboBoxDropdown.vue

@@ -1,6 +1,8 @@
 <script setup>
 import { ref } from 'vue';
 import { useI18n } from 'vue-i18n';
+import Spinner from 'dashboard/components-next/spinner/Spinner.vue';
+import Icon from 'dashboard/components-next/icon/Icon.vue';
 
 const props = defineProps({
   open: {
@@ -27,6 +29,10 @@ const props = defineProps({
     type: [String, Number, Array],
     default: () => [],
   },
+  loading: {
+    type: Boolean,
+    default: false,
+  },
 });
 
 const emit = defineEmits(['select', 'search']);
@@ -63,13 +69,22 @@ defineExpose({
     class="absolute z-50 w-full mt-1 transition-opacity duration-200 border rounded-md shadow-lg bg-n-solid-1 border-n-strong"
   >
     <div class="relative border-b border-n-strong">
-      <span class="absolute i-lucide-search top-2.5 size-4 left-3" />
+      <Spinner
+        v-if="loading"
+        :size="16"
+        class="absolute top-2.5 start-3 text-n-slate-11"
+      />
+      <Icon
+        v-else
+        icon="i-lucide-search"
+        class="absolute top-2.5 size-4 start-3"
+      />
       <input
         ref="searchInput"
         :value="searchValue"
         type="search"
         :placeholder="searchPlaceholder || t('COMBOBOX.SEARCH_PLACEHOLDER')"
-        class="reset-base w-full py-2 pl-10 pr-2 text-sm focus:outline-none border-none rounded-t-md bg-n-solid-1 text-n-slate-12"
+        class="reset-base w-full py-2 !ps-10 !pe-2 text-sm focus:outline-none border-none rounded-t-md bg-n-solid-1 text-n-slate-12"
         @input="onInputSearch"
       />
     </div>

app/javascript/dashboard/components-next/combobox/ReorderableMultiSelect.vue

@@ -0,0 +1,297 @@
+<script setup>
+import { ref, computed, nextTick } from 'vue';
+import { OnClickOutside } from '@vueuse/components';
+import Button from 'dashboard/components-next/button/Button.vue';
+import ComboBoxDropdown from 'dashboard/components-next/combobox/ComboBoxDropdown.vue';
+import EmojiIcon from 'dashboard/components-next/emoji-icon-picker/EmojiIcon.vue';
+import Spinner from 'dashboard/components-next/spinner/Spinner.vue';
+import Icon from 'dashboard/components-next/icon/Icon.vue';
+
+// Drag-reorderable multi-select capped at `max`. The model is the ordered list
+// of selected values.
+const props = defineProps({
+  // { value, label, subtitle?, icon?, iconColor? } — icon is an emoji or an
+  // icon-picker value, and falls back to `fallbackIcon`.
+  options: {
+    type: Array,
+    default: () => [],
+  },
+  max: {
+    type: Number,
+    default: 3,
+  },
+  label: {
+    type: String,
+    default: '',
+  },
+  addLabel: {
+    type: String,
+    default: '',
+  },
+  searchPlaceholder: {
+    type: String,
+    default: '',
+  },
+  emptyState: {
+    type: String,
+    default: '',
+  },
+  fallbackIcon: {
+    type: String,
+    default: 'i-lucide-file-text',
+  },
+  // Show skeleton rows while options load, so the row height stays stable.
+  loading: {
+    type: Boolean,
+    default: false,
+  },
+  disabled: {
+    type: Boolean,
+    default: false,
+  },
+  // Let the parent filter `options` (via the `search` event) instead of locally.
+  serverSearch: {
+    type: Boolean,
+    default: false,
+  },
+});
+
+const emit = defineEmits(['search']);
+
+const selectedIds = defineModel({ type: Array, default: () => [] });
+
+const isOpen = ref(false);
+const searchQuery = ref('');
+const dragIndex = ref(null);
+const dropdownRef = ref(null);
+
+const optionsByValue = computed(
+  () => new Map(props.options.map(option => [option.value, option]))
+);
+
+const selectedRows = computed(() =>
+  selectedIds.value.map(
+    id => optionsByValue.value.get(id) || { value: id, label: String(id) }
+  )
+);
+
+const remaining = computed(() => props.max - selectedIds.value.length);
+
+const canAddMore = computed(() => selectedIds.value.length < props.max);
+
+const dropdownOptions = computed(() => {
+  const available = props.options.filter(
+    option => !selectedIds.value.includes(option.value)
+  );
+  if (props.serverSearch) return available;
+
+  const query = searchQuery.value.toLowerCase();
+  return available.filter(option =>
+    option.label?.toLowerCase().includes(query)
+  );
+});
+
+const onSearch = value => {
+  searchQuery.value = value;
+  emit('search', value);
+};
+
+const toggleDropdown = () => {
+  isOpen.value = !isOpen.value;
+  if (isOpen.value) {
+    onSearch('');
+    nextTick(() => dropdownRef.value?.focus());
+  }
+};
+
+const onSelect = option => {
+  if (!canAddMore.value) return;
+  selectedIds.value = [...selectedIds.value, option.value];
+  if (!canAddMore.value) isOpen.value = false;
+};
+
+const removeItem = id => {
+  selectedIds.value = selectedIds.value.filter(value => value !== id);
+};
+
+const onDragStart = index => {
+  dragIndex.value = index;
+};
+
+const onDragOver = index => {
+  if (dragIndex.value === null || dragIndex.value === index) return;
+  const ids = [...selectedIds.value];
+  const [moved] = ids.splice(dragIndex.value, 1);
+  ids.splice(index, 0, moved);
+  dragIndex.value = index;
+  selectedIds.value = ids;
+};
+
+const onDragEnd = () => {
+  dragIndex.value = null;
+};
+</script>
+
+<template>
+  <div>
+    <div
+      v-if="label || $slots.counter"
+      class="flex items-center justify-between mb-1.5"
+    >
+      <label class="text-sm font-medium text-n-slate-12">{{ label }}</label>
+      <div class="flex items-center gap-2">
+        <span class="text-xs text-n-slate-10">
+          <slot name="counter" :remaining="remaining" :max="max" />
+        </span>
+        <div class="flex items-center gap-1">
+          <span
+            v-for="slot in max"
+            :key="slot"
+            class="w-4 h-1 rounded-full"
+            :class="slot <= selectedIds.length ? 'bg-n-brand' : 'bg-n-slate-4'"
+          />
+        </div>
+      </div>
+    </div>
+
+    <OnClickOutside @trigger="isOpen = false">
+      <div
+        class="flex flex-col gap-1 p-1 border rounded-xl border-n-weak bg-n-background"
+        :class="{ 'opacity-50 pointer-events-none': disabled }"
+      >
+        <div
+          v-if="loading && selectedIds.length && !isOpen"
+          class="flex flex-col gap-1 overflow-y-auto max-h-[216px]"
+          aria-busy="true"
+        >
+          <div
+            v-for="n in selectedIds.length"
+            :key="n"
+            class="flex items-center gap-2 px-2 py-1.5 rounded-lg bg-n-alpha-2"
+          >
+            <span
+              class="flex-shrink-0 opacity-40 i-lucide-grip-vertical size-4 text-n-slate-9"
+            />
+            <div class="flex-shrink-0 rounded-md size-6 bg-n-alpha-3" />
+            <div class="flex-grow min-w-0">
+              <p class="mb-0 text-sm">
+                <span
+                  class="inline-block w-32 h-2.5 align-middle rounded bg-n-alpha-3 animate-pulse"
+                />
+              </p>
+              <p class="mb-0 text-xs">
+                <span
+                  class="inline-block w-20 h-2 align-middle rounded bg-n-alpha-3 animate-pulse"
+                />
+              </p>
+            </div>
+            <span class="flex-shrink-0 size-6" />
+          </div>
+        </div>
+
+        <div
+          v-else-if="selectedRows.length"
+          class="flex flex-col gap-1 overflow-y-auto max-h-[216px]"
+        >
+          <div
+            v-for="(row, index) in selectedRows"
+            :key="row.value"
+            draggable="true"
+            class="flex items-center gap-2 px-2 py-1.5 transition-colors rounded-lg cursor-grab group/row"
+            :class="
+              index === dragIndex
+                ? 'opacity-40 bg-n-alpha-3 ring-1 ring-inset ring-n-brand'
+                : 'bg-n-alpha-2 hover:bg-n-alpha-3'
+            "
+            @dragstart="onDragStart(index)"
+            @dragover.prevent="onDragOver(index)"
+            @dragend="onDragEnd"
+          >
+            <span
+              class="flex-shrink-0 transition-colors i-lucide-grip-vertical size-4 text-n-slate-9 group-hover/row:text-n-slate-11"
+            />
+            <div
+              class="flex items-center justify-center flex-shrink-0 text-sm rounded-md size-6 bg-n-alpha-3 text-n-slate-11"
+            >
+              <EmojiIcon
+                v-if="row.icon"
+                :value="row.icon"
+                :color="row.iconColor"
+                class="shrink-0 size-4"
+              />
+              <span v-else class="size-4" :class="fallbackIcon" />
+            </div>
+            <div class="flex-grow min-w-0">
+              <p class="mb-0 text-sm truncate text-n-slate-12">
+                {{ row.label }}
+              </p>
+              <p
+                v-if="row.subtitle"
+                class="mb-0 text-xs truncate text-n-slate-10"
+              >
+                {{ row.subtitle }}
+              </p>
+            </div>
+            <Button
+              type="button"
+              ghost
+              slate
+              xs
+              no-animation
+              icon="i-lucide-x"
+              class="flex-shrink-0"
+              @click="removeItem(row.value)"
+            />
+          </div>
+        </div>
+
+        <div v-if="canAddMore" class="relative">
+          <Button
+            type="button"
+            ghost
+            slate
+            sm
+            no-animation
+            justify="start"
+            :label="addLabel"
+            :disabled="loading && !isOpen"
+            class="w-full"
+            @click="toggleDropdown"
+          >
+            <template #icon>
+              <Spinner
+                v-if="loading && !isOpen"
+                :size="16"
+                class="text-n-slate-11"
+              />
+              <Icon
+                v-else
+                icon="i-lucide-search"
+                class="flex-shrink-0 size-4"
+              />
+            </template>
+          </Button>
+          <ComboBoxDropdown
+            ref="dropdownRef"
+            :open="isOpen"
+            :options="dropdownOptions"
+            :search-value="searchQuery"
+            :search-placeholder="searchPlaceholder"
+            :empty-state="emptyState"
+            :loading="loading"
+            @update:search-value="onSearch"
+            @select="onSelect"
+          />
+        </div>
+      </div>
+    </OnClickOutside>
+
+    <p
+      v-if="selectedIds.length && $slots.note"
+      class="flex items-center gap-1.5 mt-1.5 mb-0 text-xs text-n-slate-11"
+    >
+      <span class="rounded-full size-1.5 bg-n-teal-9" />
+      <slot name="note" />
+    </p>
+  </div>
+</template>

app/javascript/dashboard/components-next/combobox/specs/ReorderableMultiSelect.spec.js

@@ -0,0 +1,224 @@
+import { mount } from '@vue/test-utils';
+import { h } from 'vue';
+import ReorderableMultiSelect from '../ReorderableMultiSelect.vue';
+
+const OPTIONS = [
+  { value: 1, label: 'Getting started', subtitle: 'Guides' },
+  { value: 2, label: 'Billing', subtitle: 'Payments' },
+  { value: 3, label: 'Security' },
+  { value: 4, label: 'API', icon: '🔌', iconColor: '#000' },
+];
+
+// A findable dropdown stub that exposes the `focus()` the component calls on open.
+const ComboBoxDropdownStub = {
+  name: 'ComboBoxDropdown',
+  props: [
+    'open',
+    'options',
+    'searchValue',
+    'searchPlaceholder',
+    'emptyState',
+    'loading',
+  ],
+  emits: ['select', 'update:searchValue'],
+  methods: { focus() {} },
+  template: '<div class="combo-dropdown" />',
+};
+
+// Renders a real <button> so clicks reach the parent handlers; `data-icon`
+// lets specs tell the remove buttons (icon="i-lucide-x") from the add trigger.
+const ButtonStub = {
+  name: 'Button',
+  props: ['label', 'icon', 'disabled'],
+  emits: ['click'],
+  template:
+    '<button :data-icon="icon" :disabled="disabled" @click="$emit(\'click\')"><slot name="icon" />{{ label }}</button>',
+};
+
+const mountSelect = (props = {}, slots = {}) =>
+  mount(ReorderableMultiSelect, {
+    props: { options: OPTIONS, max: 3, ...props },
+    slots,
+    global: {
+      stubs: {
+        Button: ButtonStub,
+        ComboBoxDropdown: ComboBoxDropdownStub,
+        Spinner: true,
+        Icon: true,
+        EmojiIcon: true,
+        OnClickOutside: { template: '<div><slot /></div>' },
+      },
+    },
+  });
+
+const dropdown = wrapper => wrapper.findComponent(ComboBoxDropdownStub);
+const addTrigger = wrapper =>
+  wrapper.findAll('button').find(button => !button.attributes('data-icon'));
+const removeButtons = wrapper =>
+  wrapper.findAll('button[data-icon="i-lucide-x"]');
+const rows = wrapper => wrapper.findAll('[draggable="true"]');
+const lastModel = wrapper => wrapper.emitted('update:modelValue')?.at(-1)?.[0];
+
+describe('ReorderableMultiSelect', () => {
+  describe('rendering selected rows', () => {
+    it('renders rows in model order with labels resolved from options', () => {
+      const wrapper = mountSelect({ modelValue: [2, 1] });
+
+      const labels = rows(wrapper).map(row => row.find('p').text());
+      expect(labels).toEqual(['Billing', 'Getting started']);
+    });
+
+    it('falls back to the stringified id when an option is unknown', () => {
+      const wrapper = mountSelect({ modelValue: [99] });
+
+      expect(rows(wrapper)[0].find('p').text()).toBe('99');
+    });
+
+    it('renders the progress dots filled up to the selection count', () => {
+      const wrapper = mountSelect({
+        modelValue: [1, 2],
+        max: 3,
+        label: 'Tags',
+      });
+
+      const filled = wrapper.findAll('.bg-n-brand').length;
+      expect(filled).toBe(2);
+    });
+
+    it('exposes remaining and max to the counter slot', () => {
+      const wrapper = mountSelect(
+        { modelValue: [1], max: 3 },
+        { counter: ({ remaining, max }) => h('span', `${remaining}/${max}`) }
+      );
+
+      expect(wrapper.text()).toContain('2/3');
+    });
+  });
+
+  describe('adding options', () => {
+    it('appends the chosen option to the model', () => {
+      const wrapper = mountSelect({ modelValue: [1] });
+
+      dropdown(wrapper).vm.$emit('select', OPTIONS[1]);
+
+      expect(lastModel(wrapper)).toEqual([1, 2]);
+    });
+
+    it('hides the add trigger once the model reaches max', () => {
+      const wrapper = mountSelect({ modelValue: [1, 2], max: 2 });
+
+      expect(addTrigger(wrapper)).toBeUndefined();
+      expect(dropdown(wrapper).exists()).toBe(false);
+    });
+
+    it('closes the dropdown when the last slot is filled', async () => {
+      const wrapper = mountSelect({ modelValue: [1], max: 2 });
+      await addTrigger(wrapper).trigger('click');
+      expect(dropdown(wrapper).props('open')).toBe(true);
+
+      dropdown(wrapper).vm.$emit('select', OPTIONS[1]);
+      await wrapper.vm.$nextTick();
+
+      // Reaching max removes the trigger (and its dropdown) entirely.
+      expect(dropdown(wrapper).exists()).toBe(false);
+    });
+
+    it('excludes already-selected options from the dropdown', () => {
+      const wrapper = mountSelect({ modelValue: [1] });
+
+      const values = dropdown(wrapper)
+        .props('options')
+        .map(option => option.value);
+      expect(values).toEqual([2, 3, 4]);
+    });
+  });
+
+  describe('removing options', () => {
+    it('removes the clicked item from the model', async () => {
+      const wrapper = mountSelect({ modelValue: [1, 2, 3] });
+
+      await removeButtons(wrapper)[1].trigger('click');
+
+      expect(lastModel(wrapper)).toEqual([1, 3]);
+    });
+  });
+
+  describe('searching', () => {
+    it('filters options locally by label', async () => {
+      const wrapper = mountSelect({ modelValue: [] });
+
+      dropdown(wrapper).vm.$emit('update:searchValue', 'bill');
+      await wrapper.vm.$nextTick();
+
+      const values = dropdown(wrapper)
+        .props('options')
+        .map(option => option.value);
+      expect(values).toEqual([2]);
+    });
+
+    it('emits search and skips local filtering when serverSearch is set', async () => {
+      const wrapper = mountSelect({ modelValue: [], serverSearch: true });
+
+      dropdown(wrapper).vm.$emit('update:searchValue', 'bill');
+      await wrapper.vm.$nextTick();
+
+      expect(wrapper.emitted('search').at(-1)).toEqual(['bill']);
+      // All unselected options remain; the parent owns filtering.
+      expect(dropdown(wrapper).props('options')).toHaveLength(4);
+    });
+
+    it('emits an empty search when the trigger opens', async () => {
+      const wrapper = mountSelect({ modelValue: [1] });
+
+      await addTrigger(wrapper).trigger('click');
+
+      expect(wrapper.emitted('search').at(-1)).toEqual(['']);
+      expect(dropdown(wrapper).props('open')).toBe(true);
+    });
+  });
+
+  describe('reordering', () => {
+    it('moves a row to the dropped position within the model', async () => {
+      const wrapper = mountSelect({ modelValue: [1, 2, 3] });
+
+      await rows(wrapper)[0].trigger('dragstart');
+      await rows(wrapper)[2].trigger('dragover');
+
+      expect(lastModel(wrapper)).toEqual([2, 3, 1]);
+    });
+  });
+
+  describe('loading state', () => {
+    it('shows skeleton rows when loading a non-empty, closed selection', () => {
+      const wrapper = mountSelect({ modelValue: [1, 2], loading: true });
+
+      const skeleton = wrapper.find('[aria-busy="true"]');
+      expect(skeleton.exists()).toBe(true);
+      expect(skeleton.findAll('.animate-pulse').length).toBeGreaterThan(0);
+    });
+
+    it('does not show skeletons when the selection is empty', () => {
+      const wrapper = mountSelect({ modelValue: [], loading: true });
+
+      expect(wrapper.find('[aria-busy="true"]').exists()).toBe(false);
+    });
+
+    it('shows the real rows, not skeletons, while searching in an open dropdown', async () => {
+      // Open first (trigger is enabled), then a live search turns loading on.
+      const wrapper = mountSelect({ modelValue: [1, 2] });
+      await addTrigger(wrapper).trigger('click');
+
+      await wrapper.setProps({ loading: true });
+
+      expect(wrapper.find('[aria-busy="true"]').exists()).toBe(false);
+      expect(rows(wrapper)).toHaveLength(2);
+    });
+
+    it('forwards loading to the dropdown and disables the closed trigger', () => {
+      const wrapper = mountSelect({ modelValue: [1], loading: true });
+
+      expect(dropdown(wrapper).props('loading')).toBe(true);
+      expect(addTrigger(wrapper).attributes('disabled')).toBeDefined();
+    });
+  });
+});

app/javascript/dashboard/composables/spec/useAbortableRequest.spec.js

@@ -0,0 +1,120 @@
+import { effectScope } from 'vue';
+import { useAbortableRequest } from '../useAbortableRequest';
+
+// Resolves when the request "completes", rejects like axios does when the
+// signal is aborted mid-flight.
+const abortableRunner =
+  (value, { fail = false } = {}) =>
+  signal =>
+    new Promise((resolve, reject) => {
+      signal.addEventListener('abort', () => {
+        const error = new Error('canceled');
+        error.name = 'CanceledError';
+        reject(error);
+      });
+      // Defer so a follow-up `run`/`abort` can supersede this one first.
+      Promise.resolve().then(() => {
+        if (signal.aborted) return;
+        if (fail) {
+          reject(new Error('boom'));
+          return;
+        }
+        resolve(value);
+      });
+    });
+
+describe('useAbortableRequest', () => {
+  it('passes a fresh signal to the runner and returns its result', async () => {
+    const { run } = useAbortableRequest();
+    let received = null;
+
+    const result = await run(signal => {
+      received = signal;
+      return Promise.resolve('ok');
+    });
+
+    expect(received).toBeInstanceOf(AbortSignal);
+    expect(received.aborted).toBe(false);
+    expect(result).toBe('ok');
+  });
+
+  it('toggles isPending around the request', async () => {
+    const { run, isPending } = useAbortableRequest();
+    expect(isPending.value).toBe(false);
+
+    const pending = run(() => Promise.resolve('done'));
+    expect(isPending.value).toBe(true);
+
+    await pending;
+    expect(isPending.value).toBe(false);
+  });
+
+  it('aborts the previous request when a new one starts', async () => {
+    const { run } = useAbortableRequest();
+
+    const first = run(abortableRunner('first'));
+    const second = run(abortableRunner('second'));
+
+    await expect(first).resolves.toBeUndefined();
+    await expect(second).resolves.toBe('second');
+  });
+
+  it('returns the onAbort value when a request is superseded', async () => {
+    const { run } = useAbortableRequest();
+
+    const first = run(abortableRunner('first'), { onAbort: null });
+    const second = run(abortableRunner('second'));
+
+    await expect(first).resolves.toBeNull();
+    await expect(second).resolves.toBe('second');
+  });
+
+  it('abort cancels the in-flight request and clears isPending', async () => {
+    const { run, abort, isPending } = useAbortableRequest();
+
+    const pending = run(abortableRunner('value'));
+    expect(isPending.value).toBe(true);
+
+    abort();
+
+    await expect(pending).resolves.toBeUndefined();
+    expect(isPending.value).toBe(false);
+  });
+
+  it('rethrows non-abort errors and clears isPending', async () => {
+    const { run, isPending } = useAbortableRequest();
+
+    await expect(run(abortableRunner(null, { fail: true }))).rejects.toThrow(
+      'boom'
+    );
+    expect(isPending.value).toBe(false);
+  });
+
+  it('aborts the in-flight request when its scope is disposed', async () => {
+    const scope = effectScope();
+    let request;
+    scope.run(() => {
+      request = useAbortableRequest();
+    });
+
+    const pending = request.run(abortableRunner('value'));
+    expect(request.isPending.value).toBe(true);
+
+    scope.stop();
+
+    await expect(pending).resolves.toBeUndefined();
+    expect(request.isPending.value).toBe(false);
+  });
+
+  it('keeps separate controllers per instance', async () => {
+    const a = useAbortableRequest();
+    const b = useAbortableRequest();
+
+    const first = a.run(abortableRunner('a'));
+    // Starting b's request must not abort a's.
+    const second = b.run(abortableRunner('b'));
+
+    await expect(first).resolves.toBe('a');
+    await expect(second).resolves.toBe('b');
+  });
+});

app/javascript/dashboard/composables/useAbortableRequest.js

@@ -0,0 +1,62 @@
+import { getCurrentScope, onScopeDispose, ref } from 'vue';
+
+export const isAbortError = error =>
+  error?.name === 'AbortError' ||
+  error?.name === 'CanceledError' ||
+  error?.code === 'ERR_CANCELED';
+
+/**
+ * Keeps only the latest request alive. Starting a new `run` (or calling
+ * `abort`) cancels the previous request through its `AbortSignal`, so
+ * out-of-order responses can never overwrite fresher data.
+ *
+ * @example
+ * const { run, abort, isPending } = useAbortableRequest();
+ * const results = await run(signal => api.search(query, { signal }));
+ *
+ * @returns {{
+ *   run: (runner: (signal: AbortSignal) => Promise<any>, options?: { onAbort?: any }) => Promise<any>,
+ *   abort: () => void,
+ *   isPending: import('vue').Ref<boolean>,
+ * }}
+ * `run` resolves with the runner's value, or `options.onAbort` (default
+ * `undefined`) when the request was superseded. Non-abort errors are rethrown.
+ */
+export function useAbortableRequest() {
+  const isPending = ref(false);
+  let controller = null;
+
+  const abort = () => {
+    controller?.abort();
+    controller = null;
+    isPending.value = false;
+  };
+
+  const run = async (runner, { onAbort } = {}) => {
+    controller?.abort();
+    const currentController = new AbortController();
+    controller = currentController;
+    isPending.value = true;
+
+    try {
+      return await runner(currentController.signal);
+    } catch (error) {
+      if (currentController.signal.aborted || isAbortError(error))
+        return onAbort;
+      throw error;
+    } finally {
+      // Only the latest run owns the shared state; a superseded run leaves it
+      // for the run that replaced it.
+      if (controller === currentController) {
+        controller = null;
+        isPending.value = false;
+      }
+    }
+  };
+
+  // Cancel any in-flight request when the owning scope is disposed.
+  // Guarded so the composable can also be used outside an effect scope.
+  if (getCurrentScope()) onScopeDispose(abort);
+
+  return { run, abort, isPending };
+}

app/javascript/dashboard/helper/portalHelper.js

@@ -166,6 +166,13 @@ export const LOCALE_MENU_ITEMS = {
     value: 'customize-content',
     icon: 'i-lucide-pencil',
   },
+  selectPopularContent: {
+    label:
+      'HELP_CENTER.LOCALES_PAGE.LOCALE_CARD.DROPDOWN_MENU.SELECT_POPULAR_CONTENT',
+    action: 'select-popular-content',
+    value: 'select-popular-content',
+    icon: 'i-lucide-sparkles',
+  },
   delete: {
     label: 'HELP_CENTER.LOCALES_PAGE.LOCALE_CARD.DROPDOWN_MENU.DELETE',
     action: 'delete',
@@ -185,6 +192,7 @@ export const buildLocaleMenuItems = ({ isDefault, isDraft }) => {
         LOCALE_MENU_ITEMS.moveToDraft,
       ]),
       LOCALE_MENU_ITEMS.customizeContent,
+      LOCALE_MENU_ITEMS.selectPopularContent,
       ...disableLocaleMenuItems([LOCALE_MENU_ITEMS.delete]),
     ];
   }
@@ -193,6 +201,7 @@ export const buildLocaleMenuItems = ({ isDefault, isDraft }) => {
     return [
       LOCALE_MENU_ITEMS.publishLocale,
       LOCALE_MENU_ITEMS.customizeContent,
+      LOCALE_MENU_ITEMS.selectPopularContent,
       LOCALE_MENU_ITEMS.delete,
     ];
   }
@@ -201,6 +210,7 @@ export const buildLocaleMenuItems = ({ isDefault, isDraft }) => {
     LOCALE_MENU_ITEMS.makeDefault,
     LOCALE_MENU_ITEMS.moveToDraft,
     LOCALE_MENU_ITEMS.customizeContent,
+    LOCALE_MENU_ITEMS.selectPopularContent,
     LOCALE_MENU_ITEMS.delete,
   ];
 };

app/javascript/dashboard/helper/specs/portalHelper.spec.js

@@ -74,26 +74,34 @@ describe('PortalHelper', () => {
   });
 
   describe('buildLocaleMenuItems', () => {
-    it('disables other actions but keeps customize enabled for the default locale', () => {
+    it('disables other actions but keeps content actions enabled for the default locale', () => {
       const items = buildLocaleMenuItems({ isDefault: true, isDraft: false });
-      const customize = items.find(item => item.action === 'customize-content');
+      const enabledActions = ['customize-content', 'select-popular-content'];
 
-      expect(customize).toBeTruthy();
-      expect(customize.disabled).toBeFalsy();
+      enabledActions.forEach(action => {
+        expect(
+          items.find(item => item.action === action)?.disabled
+        ).toBeFalsy();
+      });
       expect(
         items
-          .filter(item => item.action !== 'customize-content')
+          .filter(item => !enabledActions.includes(item.action))
           .every(item => item.disabled)
       ).toBe(true);
     });
 
-    it('returns publish, customize, and delete actions for draft locales', () => {
+    it('returns publish, customize, popular content, and delete actions for draft locales', () => {
       expect(
         buildLocaleMenuItems({
           isDefault: false,
           isDraft: true,
         }).map(({ action }) => action)
-      ).toEqual(['publish-locale', 'customize-content', 'delete']);
+      ).toEqual([
+        'publish-locale',
+        'customize-content',
+        'select-popular-content',
+        'delete',
+      ]);
     });
 
     it('returns default, draft, customize, and delete actions for live locales', () => {
@@ -106,6 +114,7 @@ describe('PortalHelper', () => {
         'change-default',
         'move-to-draft',
         'customize-content',
+        'select-popular-content',
         'delete',
       ]);
     });

app/javascript/dashboard/i18n/locale/en/helpCenter.json

@@ -720,9 +720,33 @@
           "MOVE_TO_DRAFT": "Move to draft",
           "PUBLISH_LOCALE": "Publish locale",
           "CUSTOMIZE_CONTENT": "Localize content",
+          "SELECT_POPULAR_CONTENT": "Select recommended content",
           "DELETE": "Delete"
         }
       },
+      "POPULAR_CONTENT_DIALOG": {
+        "TITLE": "Recommended content",
+        "DESCRIPTION": "Pick up to 3 categories and 6 articles to feature on this locale's help center home page. Drag them into the order you want visitors to see.",
+        "SEARCH": "Search...",
+        "EMPTY": "No matching results",
+        "ADD_ANOTHER": "Add another...",
+        "SLOTS_LEFT": "{count} slots left",
+        "OVERRIDING_DEFAULTS": "Overriding defaults for this locale",
+        "CONFIRM": "Save recommendations",
+        "CATEGORIES": {
+          "LABEL": "Recommended categories",
+          "ARTICLES_COUNT": "No articles | {count} article | {count} articles"
+        },
+        "ARTICLES": {
+          "LABEL": "Recommended articles",
+          "IN_CATEGORY": "in {category}",
+          "UNCATEGORIZED": "Uncategorized"
+        },
+        "API": {
+          "SUCCESS_MESSAGE": "Recommended content updated successfully",
+          "ERROR_MESSAGE": "Unable to update recommended content. Try again."
+        }
+      },
       "CONTENT_DIALOG": {
         "TITLE": "Localize content",
         "DESCRIPTION": "Set values specific to this locale. Anything left blank falls back to the default locale.",

app/models/concerns/portal_config_schema.rb

@@ -14,6 +14,18 @@ module PortalConfigSchema
     'additionalProperties' => false
   }.freeze
 
+  # Per-locale recommended content for the portal home page: an ordered list of
+  # `category_ids` (the hero's "Recommended topics" pills) and `article_ids` (the
+  # "Recommended" articles section). When empty, the portal uses its defaults.
+  POPULAR_CONTENT_SCHEMA = {
+    'type' => 'object',
+    'properties' => {
+      'category_ids' => { 'type' => %w[array null], 'items' => { 'type' => 'integer' } },
+      'article_ids' => { 'type' => %w[array null], 'items' => { 'type' => 'integer' } }
+    },
+    'additionalProperties' => false
+  }.freeze
+
   CONFIG_PARAMS_SCHEMA = {
     'type' => 'object',
     'properties' => {
@@ -27,6 +39,10 @@ module PortalConfigSchema
       'locale_translations' => {
         'type' => %w[object null],
         'additionalProperties' => LOCALE_TRANSLATION_SCHEMA
+      },
+      'popular_content' => {
+        'type' => %w[object null],
+        'additionalProperties' => POPULAR_CONTENT_SCHEMA
       }
     },
     'required' => [],

app/models/portal.rb

@@ -53,7 +53,12 @@ class Portal < ApplicationRecord
   scope :active, -> { where(archived: false) }
 
   # TODO: 'website_token' is an unused reserved key; remove with a migration that scrubs it from existing portals' config
-  CONFIG_JSON_KEYS = %w[allowed_locales default_locale draft_locales website_token social_profiles layout locale_translations].freeze
+  CONFIG_JSON_KEYS = %w[allowed_locales default_locale draft_locales website_token social_profiles layout locale_translations
+                        popular_content].freeze
+
+  # Max number of recommended categories/articles shown per locale.
+  POPULAR_CATEGORY_LIMIT = 3
+  POPULAR_ARTICLE_LIMIT = 6
 
   def file_base_data
     {
@@ -115,6 +120,14 @@ class Portal < ApplicationRecord
     config_value('layout').presence || 'classic'
   end
 
+  def popular_category_ids(locale = default_locale)
+    Array(config.dig('popular_content', locale.to_s, 'category_ids')).first(POPULAR_CATEGORY_LIMIT)
+  end
+
+  def popular_article_ids(locale = default_locale)
+    Array(config.dig('popular_content', locale.to_s, 'article_ids')).first(POPULAR_ARTICLE_LIMIT)
+  end
+
   def social_profiles
     config_value('social_profiles') || {}
   end

app/views/api/v1/accounts/portals/_portal.json.jbuilder

@@ -19,6 +19,7 @@ json.config do
   json.layout portal.layout
   json.social_profiles portal.social_profiles
   json.locale_translations portal.config['locale_translations'] || {}
+  json.popular_content portal.config['popular_content'] || {}
 end
 
 if portal.channel_web_widget

app/views/layouts/_portal_scripts.html.erb

@@ -67,6 +67,11 @@ html.light {
 #category-block:hover #category-name  {
   color: var(--dynamic-hover-color);
 }
+/* Recommended topic pills in the classic hero */
+.recommended-pill:hover {
+  border-color: var(--dynamic-hover-color);
+  color: var(--dynamic-hover-color);
+}
 </style>
 
 <script>

app/views/public/api/v1/portals/_featured_articles.html.erb

@@ -1,12 +1,13 @@
-<% featured_articles = articles.where(category_id: categories).search_by_status(:published).order_by_views.limit(6) %>
-<% if featured_articles.count >= 6 %>
+<% recommended = local_assigns[:recommended].presence %>
+<% featured_articles = recommended || articles.where(category_id: categories).search_by_status(:published).order_by_views.select(:id, :title, :slug).limit(6) %>
+<% if recommended || featured_articles.length >= 6 %>
 <section class="flex flex-col w-full h-full lg:container">
    <div class="flex flex-col gap-5 px-3 py-5 border border-solid rounded-lg border-slate-100 dark:border-slate-800">
-      <div class="flex items-center justify-between w-full"> 
+      <div class="flex items-center justify-between w-full">
          <div class="flex flex-col items-start gap-1">
             <div class="flex flex-row items-center gap-2 px-2">
                <h3 class="text-xl font-semibold leading-relaxed text-slate-800 dark:text-slate-50">
-                  <%= I18n.t('public_portal.header.featured_articles') %>
+                  <%= recommended ? I18n.t('public_portal.header.recommended') : I18n.t('public_portal.header.featured_articles') %>
                </h3>
             </div>
          </div>

app/views/public/api/v1/portals/_hero.html.erb

@@ -18,6 +18,18 @@
       </h1>
       <p class="text-slate-600 dark:text-slate-200 text-start text-lg leading-normal pt-2 pb-4"><%= I18n.t('public_portal.hero.sub_title') %></p>
       <div id="search-wrap" class="w-full relative z-30"></div>
+      <% if @recommended_categories.present? %>
+        <div class="mt-5 flex items-center gap-2 flex-wrap text-sm">
+          <span class="text-slate-500 dark:text-slate-400"><%= I18n.t('public_portal.sidebar.recommended_label') %></span>
+          <% @recommended_categories.each do |category| %>
+            <a href="<%= public_portal_category_path(@portal.slug, category.locale, category.slug) %>"
+               class="recommended-pill inline-flex items-center gap-1 px-2.5 py-1 rounded-full bg-white dark:bg-slate-800 border border-solid border-slate-200 dark:border-slate-700 text-slate-700 dark:text-slate-100 transition">
+              <% if category.icon.present? %><span class="inline-flex items-center text-xs leading-none"><%= render_emoji_or_icon(category.icon, category.icon_color) %></span><% end %>
+              <%= category.name %>
+            </a>
+          <% end %>
+        </div>
+      <% end %>
     </div>
   </div>
 </section>

app/views/public/api/v1/portals/documentation_layout/_hero.html.erb

@@ -1,4 +1,4 @@
-<%# locals: (portal:, popular_topics: []) %>
+<%# locals: (portal:, popular_topics: [], recommended: false) %>
 <section class="relative border-b border-solid border-n-weak bg-n-slate-1 dark:bg-n-slate-2 min-h-[50vh] flex items-center">
   <div class="absolute inset-0 pointer-events-none text-n-portal-faint [background-image:linear-gradient(to_right,currentColor_1px,transparent_1px),linear-gradient(to_bottom,currentColor_1px,transparent_1px)] [background-size:56px_56px] [mask-image:radial-gradient(ellipse_at_50%_30%,black_35%,transparent_80%)] [-webkit-mask-image:radial-gradient(ellipse_at_50%_30%,black_35%,transparent_80%)]" aria-hidden="true"></div>
 
@@ -17,7 +17,7 @@
 
       <% if popular_topics.any? %>
         <div class="mt-5 flex items-center gap-2 flex-wrap text-sm">
-          <span class="text-n-slate-10"><%= I18n.t('public_portal.sidebar.popular_label') %></span>
+          <span class="text-n-slate-10"><%= I18n.t("public_portal.sidebar.#{recommended ? 'recommended_label' : 'popular_label'}") %></span>
           <% popular_topics.each do |category| %>
             <a href="<%= public_portal_category_path(portal.slug, category.locale, category.slug) %>"
                class="inline-flex items-center gap-1 px-2.5 py-1 rounded-full bg-white/60 dark:bg-n-slate-1/60 backdrop-blur border border-solid border-n-weak text-n-slate-11 hover:text-n-portal hover:border-n-portal transition">

app/views/public/api/v1/portals/show.html+documentation.erb

@@ -1,4 +1,4 @@
-<%= render 'public/api/v1/portals/documentation_layout/hero', portal: @portal, popular_topics: @popular_topics %>
+<%= render 'public/api/v1/portals/documentation_layout/hero', portal: @portal, popular_topics: @popular_topics, recommended: @recommended_categories.present? %>
 
 <section class="px-6 md:px-10 py-8 md:py-10">
   <%= render 'public/api/v1/portals/documentation_layout/section_header',
@@ -19,14 +19,15 @@
   <% end %>
 </section>
 
-<% if @featured.any? %>
+<% home_articles = @recommended_articles.presence || @featured %>
+<% if home_articles.any? %>
   <section class="px-6 md:px-10 py-8 md:py-10 border-t border-n-weak">
     <%= render 'public/api/v1/portals/documentation_layout/section_header',
-               title: I18n.t('public_portal.sidebar.popular_articles'),
-               subtitle: I18n.t('public_portal.sidebar.popular_articles_subtitle'),
+               title: @recommended_articles.present? ? I18n.t('public_portal.sidebar.recommended') : I18n.t('public_portal.sidebar.popular_articles'),
+               subtitle: @recommended_articles.present? ? I18n.t('public_portal.sidebar.recommended_subtitle') : I18n.t('public_portal.sidebar.popular_articles_subtitle'),
                subtitle_class: 'mt-1.5 text-base text-n-slate-11' %>
     <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
-      <% @featured.each do |article| %>
+      <% home_articles.each do |article| %>
         <%= render 'public/api/v1/portals/documentation_layout/article_card', portal: @portal, article: article %>
       <% end %>
     </div>

app/views/public/api/v1/portals/show.html.erb

@@ -1,5 +1,5 @@
 <%= render "public/api/v1/portals/hero", portal: @portal %>
 <div class="max-w-5xl w-full flex flex-col flex-grow mx-auto py-8 px-4 md:px-8 gap-6">
-  <div><%= render "public/api/v1/portals/featured_articles", articles: @portal.articles, categories: @portal.categories.where(locale: @locale), portal: @portal %></div>
+  <div><%= render "public/api/v1/portals/featured_articles", articles: @portal.articles, categories: @portal.categories.where(locale: @locale), portal: @portal, recommended: @recommended_articles %></div>
   <%= render "public/api/v1/portals/home_categories", portal: @portal, locale: @locale %>
 </div>

config/locales/en.yml

@@ -493,7 +493,10 @@ en:
       browse_by_topic_subtitle: Find guides, tutorials, and answers organised by category.
       popular_articles: Popular articles
       popular_articles_subtitle: What other people are reading right now.
+      recommended: Recommended articles
+      recommended_subtitle: Hand-picked articles to get you started.
       popular_label: 'Popular topics:'
+      recommended_label: 'Recommended topics:'
       authors_others: "%{names} and %{count} others"
       primary_nav: Primary
     hero:
@@ -529,6 +532,7 @@ en:
         light: Light
         dark: Dark
       featured_articles: Featured Articles
+      recommended: Recommended articles
       uncategorized: Uncategorized
     404:
       title: Page not found

spec/controllers/api/v1/accounts/portals_controller_spec.rb

@@ -174,7 +174,8 @@ RSpec.describe 'Api::V1::Accounts::Portals', type: :request do
             'default_locale' => 'en',
             'layout' => 'classic',
             'social_profiles' => {},
-            'locale_translations' => {}
+            'locale_translations' => {},
+            'popular_content' => {}
           }
         )
       end

spec/controllers/public/api/v1/portals_controller_spec.rb

@@ -106,6 +106,82 @@ RSpec.describe Public::Api::V1::PortalsController, type: :request do
     end
   end
 
+  describe 'GET /public/api/v1/portals/{portal_slug}/{locale} recommended content' do
+    let(:category_a) { create(:category, portal: portal, account: account, name: 'Getting Started', locale: 'en') }
+    let(:category_b) { create(:category, portal: portal, account: account, name: 'Billing', locale: 'en') }
+    let(:alpha) { create(:article, account: account, author: agent, portal: portal, locale: 'en', status: :published, title: 'Alpha Guide') }
+    let(:beta) { create(:article, account: account, author: agent, portal: portal, locale: 'en', status: :published, title: 'Beta Guide') }
+    let(:gamma) { create(:article, account: account, author: agent, portal: portal, locale: 'en', status: :published, title: 'Gamma Guide') }
+
+    it 'renders recommended articles in the configured order' do
+      portal.update!(config: { allowed_locales: %w[en], default_locale: 'en',
+                               popular_content: { 'en' => { 'article_ids' => [gamma.id, alpha.id] } } })
+
+      get "/hc/#{portal.slug}/en"
+
+      expect(response).to have_http_status(:success)
+      expect(response.body).to include('Recommended articles')
+      expect(response.body.index('Gamma Guide')).to be < response.body.index('Alpha Guide')
+    end
+
+    it 'drops draft and other-locale ids from the recommended articles' do
+      draft = create(:article, account: account, author: agent, portal: portal, locale: 'en', status: :draft, title: 'Draft Secret')
+      spanish = create(:article, account: account, author: agent, portal: portal, locale: 'es', status: :published, title: 'Spanish Only')
+      portal.update!(config: { allowed_locales: %w[en es], default_locale: 'en',
+                               popular_content: { 'en' => { 'article_ids' => [alpha.id, draft.id, spanish.id] } } })
+
+      get "/hc/#{portal.slug}/en"
+
+      expect(response).to have_http_status(:success)
+      expect(response.body).to include('Alpha Guide')
+      expect(response.body).not_to include('Draft Secret')
+      expect(response.body).not_to include('Spanish Only')
+    end
+
+    it 'does not leak one locale\'s recommendations into another' do
+      portal.update!(config: { allowed_locales: %w[en es], default_locale: 'en',
+                               popular_content: { 'es' => { 'article_ids' => [alpha.id] } } })
+
+      get "/hc/#{portal.slug}/en"
+
+      expect(response).to have_http_status(:success)
+      expect(response.body).not_to include('Recommended articles')
+    end
+
+    it 'renders recommended categories as hero pills in the configured order' do
+      portal.update!(config: { allowed_locales: %w[en], default_locale: 'en',
+                               popular_content: { 'en' => { 'category_ids' => [category_b.id, category_a.id] } } })
+
+      get "/hc/#{portal.slug}/en"
+
+      expect(response).to have_http_status(:success)
+      expect(response.body).to include('recommended-pill')
+      expect(response.body).to include('Getting Started', 'Billing')
+      expect(response.body.index('Billing')).to be < response.body.index('Getting Started')
+    end
+
+    it 'falls back to featured articles when no recommendations are configured' do
+      create_list(:article, 6, account: account, author: agent, portal: portal, locale: 'en', status: :published, category: category_a)
+
+      get "/hc/#{portal.slug}/en"
+
+      expect(response).to have_http_status(:success)
+      expect(response.body).to include('Featured Articles')
+      expect(response.body).not_to include('Recommended articles')
+    end
+
+    it 'renders recommended articles in the documentation layout' do
+      portal.update!(config: { allowed_locales: %w[en], default_locale: 'en', layout: 'documentation',
+                               popular_content: { 'en' => { 'article_ids' => [alpha.id, beta.id] } } })
+
+      get "/hc/#{portal.slug}/en"
+
+      expect(response).to have_http_status(:success)
+      expect(response.body).to include('Recommended articles')
+      expect(response.body).to include('Alpha Guide', 'Beta Guide')
+    end
+  end
+
   describe 'GET /public/api/v1/portals/{portal_slug}/sitemap' do
     context 'when custom_domain is present' do
       it 'returns a valid urlset sitemap with the correct namespace' do