About the Layouts Plugin

This plugin is a framework for custom Discourse layouts. It’s main use case is adding sidebars to Discourse. You can see it in action on this site! Our left hand sidebar is managed by this plugin.

When you should use the Layouts Plugin

In some cases, using a theme component to add a sidebar to Discourse will work fine. If any of the sidebar theme components (particularly those developed by the Disocurse team) work for your use case, you sould use that.

However, if you want to have sidebars as a key part of your UX, or if you have a use case that doesn’t match an existing sidebar theme component, you should considering using this plugin.

The advantages of the Layouts Plugin

There are a number of unique advantages of this plugin, compared with other sidebar plugins or theme components. We’ve listed them here to give you a sense when evaluating it.

  • Mobile sidebars.

  • Widget ordering. Specify the order widgets appear in the sidebar

  • Context-specific widgets. Target your widgets to topic lists, topics and user profiles.

  • Group-specific widgets. Show different sidebar content to different users.

  • Granular layout settings including:

    • Sidebar width (no fiddling with css that breaks everything else)

    • Setting the “breakpoint” at which responsive sidebars are applied

    • Allowing the user to hide/show sidebars, even in the topic.

  • Maintainability. Many sidebar themes or plugins override key Discourse templates or styles. These will become out of date as Discourse changes. This plugin does not override any templates or styles. It’s baked into Discourse’s structure.

  • Extensibility. Any developer can easily add their own widgets. Use the layouts plugin widget hooks to easily access any data, including categories, users and topics inside your widget. Don’t mess around with container lookups or unnecessary ajax calls. There’s even custom plugin-outlets in the sidebars to display additional content. See our Widget Development Guide for more details.

How to use the Layouts Plugin

Think of this plugin as a “Framework” that lets you manage your Discourse layout. The actual widgets that you show in your sidebars are provided by theme components or other plugins. When you use this plugin you always use it alongside another plugin or theme component.

Please read the Installation and Setup Guide to learn more.