Developer Guides Index

[Discourse]

Documentation about extending Discourse with plugins, themes, and theme components, working with the core code, and using the Discourse API.

Introduction

• Introduction: Introduction to Discourse Development

Development Environments

• Dev Container: Developing Discourse using a Dev Container
• GitHub Codespaces: Developing Discourse on GitHub Codespaces
• Docker setup: Install Discourse for development using Docker
• macOS setup: Install Discourse on macOS for development
• Ubuntu/Debian setup: Install Discourse on Ubuntu or Debian for Development
• Windows setup: Install Discourse on Windows for development
• Non-Docker plugins: Install plugins in your non-Docker development environment
• Local setup: Set up a local Discourse Development Environment?
• Multisite setup: Set up a multisite development environment
• Fedora setup: Set up Discourse for development on Fedora Linux

Code & Internals

• Ember components: Add Ember Components to Discourse
• Lint and format: Automatically lint and format code before commits
• Acceptance tests: Write acceptance tests and component tests for Ember code in Discourse
• Run test suites: How to run Discourse core, plugin and theme QUnit test suites
• Version compatibility: Pinning plugin and theme versions for older Discourse installs (.discourse-compatibility)
• Ember object ownership: Ember object ownership (getOwner, service injections, etc.)
• JS performance: Using Google’s ‘tachometer’ to measure JS performance changes in Discourse
• CI with GitHub Actions: Setup Continuous Integration using GitHub Actions
• Markdown extensions: Developer’s guide to Markdown extensions
• Converting modals: Converting modals from legacy controllers to new DModal component API
• DModal API: Using the DModal API to render Modal windows (aka popups/dialogs) in Discourse
• JS API: Using the JS API
• Plugin outlet connectors: Using Plugin Outlet Connectors from a Theme or Plugin
• modifyClass: Using modifyClass to change core behavior
• Creating routes: Creating Routes in Discourse and Showing Data
• Authentication method: Adding a new ‘managed’ authentication method to Discourse
• Accidental serialization of ActiveRecord models: Preventing accidental serialization of ActiveRecord models
• Overriding templates: (not recommended) Overriding Discourse templates from a Theme or Plugin
• Service objects: Using service objects in Discourse
• System specs: Write end-to-end system specs for the Discourse user interface
• FormKit: Discourse toolkit to render forms.
• AppEvents Triggers: AppEvents Triggers Reference
• Transformers: Using Transformers to customize client-side values and behavior
• Topic List Customization: Customizing the topic list
• CSS guidelines: Guidelines for CSS classes using BEM
• Designing for Devices: Designing for Different Devices (Viewport Size, Touch/Hover, etc.)

Plugins

• Basic plugin: Developing Discourse Plugins - Part 1 - Create a basic plugin
• Plugin outlet: Developing Discourse Plugins - Part 2 - Connect to a plugin outlet
• Site settings: Developing Discourse Plugins - Part 3 - Add custom site settings
• Git setup: Developing Discourse Plugins - Part 4 - Setup git
• Admin interface: Developing Discourse Plugins - Part 5 - Add an admin interface
• Acceptance tests: Developing Discourse Plugins - Part 6 - Add acceptance tests
• Publish your plugin: Developing Discourse Plugins - Part 7 - Publish your plugin
• New locales: Add a new locale from plugin
• Chat integration: Add a new provider to discourse-chat-integration
• markdown-it extension: Repackaging a markdown-it extension as a Discourse plugin
• Rails autoloading: Structuring a plugin for Rails autoloading

Themes & Components

• Developing Themes: Developing Discourse Themes & Theme Components
• Quick reference: Theme Developer Quick Reference Guide
• Designers guide: Designer’s Guide to getting started with themes in Discourse
• Theme Creator: Get started with Theme Creator and the Theme CLI
• Theme CLI: Install the Discourse Theme CLI console app to help you build themes
• Theme structure: Structure of themes and theme components
• Multiple JS files: Split up theme Javascript into multiple files
• Multiple SCSS files: Split up theme SCSS into multiple files
• Theme settings: Add settings to your Discourse theme
• Objects for theme settings: Objects type for theme setting
• Migrate settings: Migrate Discourse theme settings
• Theme metadata: Adding metadata and screenshots to a Theme
• Core variables: Use Discourse Core Variables in your Theme
• Localizable strings: Add localizable strings to themes and theme components
• E2E testing: End-to-end system testing for themes and theme components
• Minimizing maintenance: Minimizing Maintenance on Theme Customizations
• Font sizes: Change font sizes in your themes
• Include assets: Include assets (e.g. images, fonts) in themes and components
• Custom icons: Replace Discourse’s default SVG icons with custom icons in a theme
• Dark mode: Update themes and plugins to support automatic dark mode
• Theme modifiers: Theme modifiers: A brief introduction
• Pseudo-elements: Insert text or images anywhere on your site using CSS pseudo-elements
• Font component: Create and share a font theme component
• Highlight.JS language: Install a new language for Highlight.JS via a theme component
• Homepage content: Add custom content that only appears on your homepage
• Message format: Message Format support for localization
• Global icon changes: Change icons globally
• Alternative icons: Alternative icons
• Wiki post style: Change the style of a wiki post
• Color scheme: Create and share a color scheme
• Navigation menu: Use the navigation_menu query parameter to preview the sidebar or other options
• Post content styles: Customize posts’ contents with your own styles
• Theme screenshots: Adding preview screenshots to Discourse themes
• Themeable site settings: Controlling site settings with themes

General Guides

• White-labelling mobile apps: Things to consider before deciding to white-label the Discourse Mobile apps
• Custom automations: Create custom Automations
• Public data dump: Discourse Public Data Dump
• AI evals: Run Discourse AI evals

Theme Dev Tutorial

• 1 - Introduction: Theme Developer Tutorial: 1. Introduction
• 2 - Remote Theme: Theme Developer Tutorial: 2. Creating a remote theme
• 3 - CSS: Theme Developer Tutorial: 3. CSS in Themes
• 4 - Outlets: Theme Developer Tutorial: 4. Using Outlets to insert and replace content
• 5 - Components: Theme Developer Tutorial: 5. Building and using components
• 6 - JS API: Theme Developer Tutorial: 6. Using the JS API
• 7 - Conclusion: Theme Developer Tutorial: 7. Wrapping up