Discourse Home Categories Plugin

Display categories on your Discourse homepage with configurable styles (pills, cards, badges) and horizontal scroll layout.

Table of Contents

• Features
• Quick Start
• Screenshots
• Installation
• Configuration
• Display Styles
• Frontend Components
• File Structure
• Roadmap
• Development
• Localization
• Troubleshooting
• Contributing
• License

---

Features

• Three Display Styles: Pills, Cards, or Badges
• Responsive Settings: Different styles for desktop and mobile
• Configurable Sorting: By position, name, or topic count
• Category Filtering: Exclude specific categories by ID
• Subcategory Control: Include or exclude subcategories
• Topic Count Display: Optional topic count per category
• Category Icons: Show category logos/icons
• Mobile Optimized: Horizontal scroll layout
• Home-Only Option: Show only on homepage, hide on category pages
• Localization: Supports multiple languages (English, Spanish included)

---

Quick Start

# 1. Clone into your Discourse plugins directory
cd /var/discourse/plugins
git clone https://github.com/JoaquinSantarcangelo/discourse-home-categories.git

# 2. Rebuild the container
cd /var/discourse && ./launcher rebuild app

# 3. Configure in Admin > Settings > search "home_categories"

For detailed installation options, see Installation.

---

Screenshots

Pills Style

Compact pill/chip style with category color accent.

Cards Style

Card layout with description and topic count.

Badges Style

Minimal badge style with color indicator.

Mobile View

Responsive horizontal scroll on mobile devices.

Admin Settings

Plugin configuration in the admin panel.

---

Installation

Production (Docker-based Discourse)

1. Add the plugin to your container configuration

   Edit your app.yml file (usually at /var/discourse/containers/app.yml):

   hooks:
     after_code:
       - exec:
           cd: $home/plugins
           cmd:
             - git clone https://github.com/JoaquinSantarcangelo/discourse-home-categories.git

2. Rebuild the container

   cd /var/discourse
   ./launcher rebuild app

3. Configure the plugin

   Go to Admin > Settings and search for home_categories to configure.

Development (Local Setup)

1. Clone the plugin into your plugins directory

   cd /path/to/discourse/plugins
   git clone https://github.com/JoaquinSantarcangelo/discourse-home-categories.git

2. Restart your Discourse server

   bin/rails server

---

Configuration

Navigate to Admin > Settings and search for home_categories:

Setting	Default	Type	Description
home_categories_enabled	true	boolean	Enable/disable the categories display
home_categories_style_desktop	pills	enum	Display style for desktop (pills, cards, badges)
home_categories_style_mobile	badges	enum	Display style for mobile (pills, cards, badges)
home_categories_sort_by	position	enum	Sort by: position, name, or topics_count
home_categories_max_items	10	integer (1-50)	Maximum categories to display
home_categories_show_count	true	boolean	Show topic count per category
home_categories_show_icon	true	boolean	Show category icon/logo
home_categories_exclude_ids	""	category_list	Categories to exclude (select from list)
home_categories_include_subcategories	false	boolean	Include subcategories in display
home_categories_only_on_home	true	boolean	Only show on home, not category pages

---

Display Styles

Pills

Compact horizontal pills with:

• Category color as left border
• Category name
• Optional icon
• Optional topic count badge

Best for: Minimal space usage, quick navigation

Cards

Larger cards with:

• Category color as top border
• Category icon and name
• Truncated description
• Topic count in footer

Best for: More visual appeal, showing category descriptions

Badges

Minimal badges with:

• Small color square indicator
• Category name
• Topic count in parentheses

Best for: Maximum compactness, text-focused design

---

Frontend Components

Component	Description
home-categories.gjs	Main connector component injected into discovery page
category-pill.gjs	Pill/chip style category display
category-card.gjs	Card style with description
category-badge.gjs	Minimal badge style

Injection Point

The plugin injects into the discovery-list-controls-above outlet, placing categories above the navigation filters.

---

File Structure

discourse-home-categories/
├── plugin.rb                    # Main plugin file
├── README.md                    # Documentation
├── LICENSE                      # MIT License
├── assets/
│   ├── javascripts/discourse/
│   │   ├── components/
│   │   │   ├── category-pill.gjs
│   │   │   ├── category-card.gjs
│   │   │   └── category-badge.gjs
│   │   └── connectors/
│   │       └── discovery-list-controls-above/
│   │           └── home-categories.gjs
│   └── stylesheets/
│       └── home-categories.scss
└── config/
    ├── settings.yml             # Plugin settings
    └── locales/
        ├── client.en.yml
        ├── client.es.yml
        ├── server.en.yml
        └── server.es.yml

---

Roadmap

Planned features for future releases:

• Grid Layout - Display categories in a responsive grid
• Wrap Layout - Flexbox layout with wrapping to multiple rows
• Custom CSS Classes - Add custom classes for advanced styling
• Category Whitelist - Option to show only specific categories
• Drag & Drop Reordering - Manual category order in admin

Have a feature request? Open an issue!

---

Development

Local Testing

1. Clone the plugin to your local Discourse plugins directory
2. Restart the Rails server
3. Access Admin > Settings to configure

Linting

bin/lint plugins/discourse-home-categories

Customizing Styles

The plugin uses Discourse CSS variables for theming:

• --primary, --primary-rgb
• --primary-low, --primary-medium, --primary-very-low
• --secondary
• --font-down-1, --font-down-2, --font-0

Category colors are passed via --category-color CSS custom property.

---

Localization

Translation files in config/locales/:

• client.{locale}.yml - Frontend strings
• server.{locale}.yml - Admin settings descriptions

Included languages: English (en), Spanish (es)

To add a new language, create the corresponding locale files following the existing structure.

---

Troubleshooting

Categories not showing

1. Verify the plugin is enabled: Admin > Settings > search home_categories_enabled
2. Check if you're on a supported page (home by default)
3. Ensure categories exist and aren't all excluded

Wrong categories displayed

1. Check home_categories_exclude_ids setting
2. Verify home_categories_include_subcategories setting
3. Adjust home_categories_max_items if needed

Layout issues on mobile

The plugin uses horizontal scroll on all screen sizes. You can configure different styles (pills, cards, badges) for desktop and mobile independently.

Styles not applying

1. Clear browser cache
2. Rebuild Discourse container (production)
3. Restart Rails server (development)

---

Contributing

Contributions are welcome! Here's how you can help:

Reporting Issues

• Search existing issues before creating a new one
• Include Discourse version, plugin version, and steps to reproduce

Submitting Changes

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Follow existing code style and conventions
4. Test your changes locally
5. Submit a pull request with a clear description

Adding Translations

1. Copy config/locales/client.en.yml to client.{locale}.yml
2. Copy config/locales/server.en.yml to server.{locale}.yml
3. Translate all strings
4. Submit a pull request

---

License

This project is licensed under the MIT License - see the LICENSE file for details.