### Clone Discourse and Start Development Container

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/02-development-environments/03-docker-setup.md

Clones the Discourse repository and starts the development container. The `--init` flag ensures dependencies are installed, the database is migrated, and an admin user is created.

```shell
git clone https://github.com/discourse/discourse.git

```

```shell
cd discourse

```

```shell
d/boot_dev --init

```

--------------------------------

### Start Discourse with Custom Hostname and Listener

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/02-development-environments/05-ubuntu-debian-setup.md

Starts the Discourse development server, allowing for custom hostname and listener port configurations. This is useful when the default settings cause conflicts or when working on a remote server.

```shell
DISCOURSE_HOSTNAME=localhost UNICORN_LISTENER=localhost:3000 bin/ember-cli -u
```

--------------------------------

### Bootstrap Discourse Application

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/02-development-environments/05-ubuntu-debian-setup.md

Installs Ruby gems and JavaScript dependencies for Discourse, and then creates and migrates the development and test databases. Finally, it starts the Rails and Ember servers.

```shell
cd ~/discourse
source ~/.bashrc
bundle install
pnpm install
bin/rails db:create
bin/rails db:migrate
RAILS_ENV=test bin/rails db:create db:migrate
bin/ember-cli -u
```

--------------------------------

### Start Discourse Development Servers

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/02-development-environments/04-macos-setup.md

Starts the Rails and Ember CLI servers for local development. Two options are provided: running them in separate terminal tabs or using a single command to run the Unicorn server in the background.

```shell
# Option 1: Separate terminals
bundle exec rails server
bin/ember-cli

# Option 2: Single terminal
bin/ember-cli -u
```

--------------------------------

### Setup PostgreSQL Role for Discourse

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/02-development-environments/05-ubuntu-debian-setup.md

Creates a PostgreSQL role with the same name as the current Linux system username. This is required for Discourse to access the database.

```shell
cd /tmp && sudo -u postgres createuser -s "$USER"
```

--------------------------------

### Start development server with host forwarding

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/02-development-environments/09-multisite-setup.md

Launch the ember-cli development server with the --forward-host option to allow the browser to resolve multisite hostnames.

```bash
bin/ember-cli -u --forward-host
```

--------------------------------

### Install Docker on MacOS

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/02-development-environments/03-docker-setup.md

Provides options for installing Docker on MacOS. Users can download a packaged .dmg from the Docker store or use the Homebrew package manager to install Docker.

```shell
# Option 1: Download a packaged .dmg from the [Docker store](https://store.docker.com/editions/community/docker-ce-desktop-mac)

```

```shell
# Option 2: brew install docker

```

--------------------------------

### Create New Admin User for Discourse

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/02-development-environments/05-ubuntu-debian-setup.md

Creates a new administrator account for the Discourse installation by running a Rails generator. This command prompts the user for necessary information to set up the admin.

```shell
bin/rails admin:create
```

--------------------------------

### Ember Component Test Setup Method

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/03-code-internals/03-acceptance-tests.md

This JavaScript code demonstrates the 'setup' method within an Ember component test. It's used to define and set up the data context for the component being tested. Here, it initializes 'testSnack' with sample data, which is then passed to the component via the template.

```javascript
setup() {
  this.set('testSnack', {
    name: 'Potato Chips',
    description: 'Now with extra trans fat!'
  });
}
```

--------------------------------

### Install Missing Gems

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/02-development-environments/03-docker-setup.md

Installs any missing Ruby gems required by Discourse. This command is useful if you encounter errors related to missing gem dependencies.

```shell
d/bundle install

```

--------------------------------

### Run MailHog for Email Testing

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/02-development-environments/05-ubuntu-debian-setup.md

Starts the MailHog service, which is a local SMTP server used for testing email functionality in development environments. It captures outgoing emails without actually sending them.

```shell
mailhog
```

--------------------------------

### Install Docker on Ubuntu (alternative)

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/02-development-environments/03-docker-setup.md

Installs the docker.io package and adds the current user to the docker group on Ubuntu systems. This allows running Docker commands without sudo and requires a system reboot to take effect.

```shell
sudo apt-get install docker.io

```

```shell
sudo usermod -a -G docker $USER

```

```shell
sudo reboot

```

--------------------------------

### Install Docker CE on Ubuntu

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/02-development-environments/03-docker-setup.md

Installs Docker Community Edition on Ubuntu systems. This process involves adding the Docker repository, updating package lists, and installing the docker-ce package. It ensures Docker is available for running containers.

```shell
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -

```

```shell
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"

```

```shell
sudo apt-get update

```

```shell
sudo apt-get install -y docker-ce

```

--------------------------------

### Initialize Discourse Markdown extension

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/03-code-internals/09-markdown-extensions.md

Defines the required setup function for a Discourse Markdown extension. This function is automatically called by the engine during initialization if the module is located in the correct directory.

```javascript
export function setup(helper) {
  // ... your code goes here
}
```

--------------------------------

### Run Discourse Development Servers

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/02-development-environments/03-docker-setup.md

Starts the Rails server and the Ember CLI development server for Discourse. These commands should be run in separate terminals from the Discourse source root.

```shell
# In one terminal:
d/rails s

```

```shell
# And in a separate terminal
d/ember-cli

```

--------------------------------

### Initialize Git Repository for Discourse Plugin

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/04-plugins/04-git-setup.md

Commands to create a local directory, initialize a new Git repository, add a README, and push the initial commit to a remote GitHub repository.

```sh
mkdir -p ~/code/discourse-plugin-test
cd ~/code/discourse-plugin-test
echo "# discourse-plugin-test" >> README.md
git init
git add README.md
git commit -m "first commit"
git remote add origin git@github.com:eviltrout/discourse-plugin-test.git
git push -u origin master
```

--------------------------------

### Access Themeable Site Settings

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/05-themes-components/02-quick-reference.md

Configure site-wide settings in about.json and access them via the siteSettings service in JavaScript or templates.

```json
"theme_site_settings": {
  "enable_welcome_banner": false
}
```

```javascript
@service siteSettings;

this.siteSettings.enable_welcome_banner;
```

```handlebars
<template>{{this.siteSettings.enable_welcome_banner}}</template>
```

--------------------------------

### Install and initialize Lefthook for Git hooks

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/03-code-internals/02-lint-and-format.md

This command installs the necessary project dependencies and initializes Lefthook to manage pre-commit hooks. It ensures that code linting and formatting checks are executed automatically before any commit is finalized.

```sh
pnpm install
pnpm run lefthook install
```

--------------------------------

### Manage PostgreSQL and Redis Services

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/02-development-environments/06-windows-10-setup.md

Commands to start PostgreSQL and Redis services to resolve connection errors. These commands ensure the backend services are active and listening on their respective ports.

```sh
sudo service postgresql start
redis-server --daemonize yes --port 6379
```

--------------------------------

### Clone Discourse Repository

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/02-development-environments/05-ubuntu-debian-setup.md

Clones the Discourse source code repository into the user's home directory. This is the first step in setting up a local development environment.

```shell
git clone https://github.com/discourse/discourse.git ~/discourse
```

--------------------------------

### Manage Theme Settings

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/05-themes-components/02-quick-reference.md

Define custom settings in settings.yml and access them across JavaScript, GJS templates, and SCSS files.

```yaml
fruit:
  default: apples|oranges
  type: list
  description:
    en: English Description
    fr: Description Française
```

```javascript
console.log(settings.fruit);
```

```handlebars
<template>{{settings.fruit}}</template>
```

```scss
html {
  font-size: #{$global-font-size}px;
  background: $site-background;
}
```

--------------------------------

### Readable Message Format Example (Good)

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/05-themes-components/27-message-format.md

Presents a well-formatted and readable example of Message Format strings in English, demonstrating proper indentation and structure for plural forms. This improves maintainability and understanding.

```messageformat
There { currentTopics, plural,
    one {is <strong>#</strong> topic}
  other {are <strong>#</strong> topics}
}. Visitors need more to read and reply to – we recommend at least { requiredTopics, plural,
    one {<strong>#</strong> topic}
  other {<strong>#</strong> topics}
}. Only staff can see this message.
```

--------------------------------

### Discourse Theme CLI Commands

Source: https://context7.com/discourse/discourse-developer-docs/llms.txt

Provides essential commands for the Discourse Theme CLI, facilitating local theme development and synchronization with a Discourse instance. Includes installation, creation, downloading, and live-watching functionalities. Requires Ruby and gem installation.

```bash
# Install the theme CLI
gem install discourse_theme

# Create a new theme
discourse_theme new my-awesome-theme

# Download existing theme from Discourse
discourse_theme download existing-theme

# Watch for changes and sync to Discourse (live reload)
discourse_theme watch my-awesome-theme

# Theme directory structure after creation:
# my-awesome-theme/
# # about.json
# # settings.yml
# # common/
# #     common.scss
# #     head_tag.html
# # desktop/
# #     desktop.scss
# # mobile/
# #     mobile.scss
# # javascript/
# #     discourse/
# #         api-initializers/
# #             init-theme.gjs
```

--------------------------------

### Bootstrap Discourse Database and Migrations

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/02-development-environments/04-macos-setup.md

Creates and migrates the local Discourse database for both development and testing environments. This prepares the database schema for the application.

```shell
bundle exec rake db:create
bundle exec rake db:migrate
RAILS_ENV=test bundle exec rake db:create db:migrate
```

--------------------------------

### Implement Theme Translations

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/05-themes-components/02-quick-reference.md

Define localizable strings in locale YAML files and retrieve them using the i18n helper with the themePrefix scope.

```yaml
en:
  my_translation_key: "I love themes"
```

```javascript
import { i18n } from "discourse-i18n";
i18n(themePrefix("my_translation_key"));
```

```handlebars
import { i18n } from "discourse-i18n";

<template>
  {{i18n (themePrefix "my_translation_key")}}
  <DButton @label={{theme-prefix "my_translation_key"}} />
</template>
```

--------------------------------

### Implement a full Markdown-it extension

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/03-code-internals/09-markdown-extensions.md

Demonstrates a complete implementation of a Markdown-it extension in Discourse. It includes configuring options, allowlisting HTML tags, and registering a custom inline rule.

```javascript
function amazingMarkdownItInline(state, silent) {
   // standard markdown it inline extension goes here.
   return false;
}

export function setup(helper) {
   if(!helper.markdownIt) { return; }

   helper.registerOptions((opts,siteSettings)=>{
      opts.features.['my_extension'] = !!siteSettings.my_extension_enabled;
   });

   helper.allowList(['span.amazing', 'div.amazing']);

   helper.registerPlugin(md=>{
      md.inline.push('amazing', amazingMarkdownItInline);
   });
}
```

--------------------------------

### Run Database Migrations

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/02-development-environments/03-docker-setup.md

Applies pending database migrations for the development environment. This command ensures the database schema is up-to-date with the current Discourse code.

```shell
d/rake db:migrate RAILS_ENV=development

```

--------------------------------

### Define Discourse Plugin Metadata

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/04-plugins/04-git-setup.md

A basic plugin.rb file structure required for Discourse to recognize and load the plugin, including name, description, version, and author metadata.

```ruby
# name: discourse-plugin-test
# about: Shows how to set up Git
# version: 0.0.1
# authors: Robin Ward
```

--------------------------------

### Integrating Discourse core components

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/07-theme-developer-tutorial/05-components.md

Shows how to import and use the DButton component from Discourse core. It also illustrates using the @tracked decorator for state management and the @action decorator to bind component methods to template events.

```gjs
import Component from "@glimmer/component";
import { tracked } from "@glimmer/tracking";
import { action } from "@ember/object";
import DButton from "discourse/components/d-button";

export default class CustomWelcomeBanner extends Component {
  @tracked counter = 0;

  @action
  incrementCounter() {
    this.counter++;
  }

  <template>
    <div class="custom-welcome-banner">
      Count:
      {{this.counter}}
      <DButton
        @icon="plus"
        @translatedLabel="Increment"
        @action={{this.incrementCounter}}
      />
    </div>
  </template>
}
```

--------------------------------

### Upload Theme or Component for System Tests

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/05-themes-components/15-e2e-testing.md

Before running your system tests, you must upload the theme or theme component using the provided helper methods. `upload_theme` is used for themes, and `upload_theme_component` is for theme components. These should be called within a `let!` block to ensure they are executed before tests.

```ruby
RSpec.describe "Testing A Theme or Theme Component", system: true do
  let!(:theme) do
    upload_theme
  end

  # or `upload_theme_component` if your theme is a component
  #
  # let!(:theme_component) do
  #   upload_theme_component
  # end

  it "displays the component" do
    # Test logic here
  end
end
```

--------------------------------

### Create Hello World Banner with HTML and CSS

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/07-theme-developer-tutorial/01-introduction.md

A basic example demonstrating how to inject a custom banner into a Discourse theme. The HTML defines the banner structure, while the SCSS provides styling to center the text and apply a background color.

```html
<div class="hello-world-banner">
  <h2 class="hello-world">Hello World!</h2>
</div>
```

```scss
.hello-world-banner {
  height: 300px;
  width: 100%;
  background: red;
  display: flex;
  align-items: center;
  justify-content: center;
  margin-bottom: 1em;
}

.hello-world {
  font-size: 8em;
  color: white;
}
```

--------------------------------

### Sign In Users for System Tests

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/05-themes-components/15-e2e-testing.md

The `sign_in` helper method allows you to test your theme's appearance and behavior under different user roles. You can easily switch between regular users, staff, or other fabricated user types to ensure consistent functionality across your site.

```ruby
RSpec.describe "Testing A Theme", system: true do
  let!(:theme) do
    upload_theme
  end

  it "does not display the theme for a regular user" do
    user = Fabricate(:user)
    sign_in(user)

    # Test logic for regular user
  end

  it "displays the theme for a staff user" do
    admin = Fabricate(:admin)
    sign_in(admin)

    # Test logic for staff user
  end
end
```

--------------------------------

### Reset Discourse Development Database

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/02-development-environments/03-docker-setup.md

Resets the Discourse development database by removing the persisted data. This command is useful for starting with a clean database state.

```shell
sudo rm -fr data

```

--------------------------------

### Render components into Discourse outlets

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/07-theme-developer-tutorial/04-outlets.md

Demonstrates the basic usage of the renderInOutlet API to inject components into specific UI locations. It shows both standard component registration and inline template rendering.

```js
api.renderInOutlet(outletName, component);
```

```gjs
const MyComponent = <template>Hello World</template>;
api.renderInOutlet("some-outlet", MyComponent);

// Or on one line
api.renderInOutlet("some-outlet", <template>Hello World</template>);
```

--------------------------------

### Run MailHog for Email Testing

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/02-development-environments/03-docker-setup.md

Starts MailHog, a tool for testing emails sent by Discourse during development. This command allows developers to inspect outgoing emails without actually sending them.

```shell
d/mailhog

```

--------------------------------

### Initialize Discourse theme repository

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/05-themes-components/23-font-component.md

Commands to create a new directory, initialize a git repository, and prepare the project structure for a Discourse theme component.

```shell
mkdir discourse-roboto-theme
cd discourse-roboto-theme
git init .
vim about.json
```

--------------------------------

### Setup Discourse Development Environment with Dev Containers

Source: https://context7.com/discourse/discourse-developer-docs/llms.txt

Instructions for setting up a Discourse development environment using Dev Containers. This method ensures a consistent workspace by containerizing dependencies. It involves cloning the Discourse repository, opening it in VSCode with the Dev Containers extension, building the container, and accessing the development instance.

```bash
# Clone Discourse repository
git clone https://github.com/discourse/discourse

# Open in VSCode with Dev Containers extension installed
# Use: File -> Open Folder -> select discourse directory
# Then: Cmd/Ctrl + Shift + P -> "Open folder in container..."

# Run default build task (Ctrl/Cmd + Shift + B)
# Wait for "Build successful" message

# Access development instance at http://localhost:4200
```

--------------------------------

### Accessing contextual data in outlets

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/07-theme-developer-tutorial/04-outlets.md

Shows how to use Handlebars syntax within <template> blocks to render dynamic content based on user state or outlet arguments. It highlights the use of @outletArgs to access contextual information like categories.

```gjs
const currentUser = api.getCurrentUser();

api.renderInOutlet(
  "discovery-list-container-top",
  <template>
    <div class="custom-welcome-banner">
      {{#if currentUser}}
        Welcome back @{{currentUser.username}}
      {{else}}
        Welcome to our community
      {{/if}}
    </div>
  </template>
);
```

```gjs
api.renderInOutlet(
  "discovery-list-container-top",
  <template>
    <div class="custom-welcome-banner">
      {{#if currentUser}}
        Welcome back @{{currentUser.username}}.
      {{else}}
        Welcome to our community.
      {{/if}}
      You're viewing
      {{#if @outletArgs.category}}
        "{{@outletArgs.category.name}}" topics.
      {{else}}
        all topics.
      {{/if}}
    </div>
  </template>
);
```

--------------------------------

### Initialize Git Repository for Color Scheme

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/05-themes-components/31-color-scheme.md

Sets up a new Git repository to manage the color scheme files. It initializes the repository and opens the 'about.json' file for editing.

```shell
mkdir my-awesome-scheme
cd my-awesome-scheme
git init .
vim about.json
```

--------------------------------

### Run Theme System Tests with discourse_theme CLI

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/05-themes-components/15-e2e-testing.md

Execute theme system tests using the `discourse_theme` CLI. This tool simplifies the process, offering options to run tests within a local Discourse development environment or a Docker container. Docker is recommended for ease of setup.

```bash
discourse_theme rspec .

# Run tests in a specific directory
discourse_theme rspec /path/to/theme/spec/system

# Run a specific test file
discourse_theme rspec /path/to/theme/spec/system/my_system_spec.rb

# Run a specific test case by line number
discourse_theme rspec /path/to/theme/spec/system/my_system_spec.rb:12
```

--------------------------------

### Install Discourse Dependencies (Gems and JS)

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/02-development-environments/04-macos-setup.md

Installs the necessary Ruby gems and JavaScript dependencies for Discourse. This step ensures that all required libraries and packages are available for the application to run.

```shell
bundle install
pnpm install
```

--------------------------------

### Configure multisite database settings

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/02-development-environments/09-multisite-setup.md

Define the multisite configuration in a YAML file. This maps hostnames to specific database adapters and names for the development environment.

```yaml
---
alternate:
  adapter: postgresql
  database: discourse_alternate
  host_names:
    - alternate.localhost
```

--------------------------------

### Less Readable Message Format Example (Bad)

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/05-themes-components/27-message-format.md

Shows a less readable example of Message Format strings, where the formatting is condensed, making it harder to parse and understand the structure. This is contrasted with the 'Good' example for clarity.

```messageformat
There {currentTopics, plural, one {is <strong>#</strong> topic} other {are <strong>#</strong> topics}}. Visitors need more to read and reply to – we recommend at least { requiredTopics, plural, one {<strong>#</strong> topic} other {<strong>#</strong> topics}}. Only staff can see this message.
```

--------------------------------

### Execute Tachometer benchmark

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/03-code-internals/07-js-performance.md

Command to run the Tachometer benchmarking tool using the specified configuration file.

```bash
npx tachometer@latest --config ./bench.json
```

--------------------------------

### Example Single Custom Icon Spritesheet

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/05-themes-components/19-custom-icons.md

A practical example of a spritesheet containing a single 'bat-icon'. It demonstrates the use of the viewBox attribute for scaling and fill="currentColor" for theme-aware coloring.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
  <symbol id="bat-icon" viewBox="6 6 36 36">
    <path
      fill="currentColor"
      d="M24,18.2c0.7,0,0.9,0.2,0.9,0.2l0.4-1.7c0,0,0.4,1.5,0.4,2.8c0.2,1.1,2.2,0.4,3.9,0C31.4,19.1,32,16,32,16h16c0,0-9.4,3.5-7,10c0,0-14.8-2-17,7l0,0c-2.2-9-17-7-17-7c2.4-6.5-7-10-7-10h16c0,0,0.6,3.1,2.3,3.5c1.7,0.4,3.9,1.1,3.9,0c0.2-1.1,0.4-2.8,0.4-2.8l0.4,1.7C23.1,18.4,23.4,18.2,24,18.2L24,18.2L24,18.2z"
    />
  </symbol>
</svg>
```

--------------------------------

### Register Component in Discourse Initializer

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/07-theme-developer-tutorial/04-outlets.md

Demonstrates how to import a custom component and register it to a specific Discourse outlet using the apiInitializer function.

```gjs
import { apiInitializer } from "discourse/lib/api";
import CustomWelcomeBanner from "../components/custom-welcome-banner";

export default apiInitializer((api) => {
  api.renderInOutlet("discovery-list-container-top", CustomWelcomeBanner);
});
```

--------------------------------

### Render Specialized Form Controls

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/03-code-internals/21-form-kit.md

Examples of rendering specific input types including Checkbox, Code editor, and Calendar components.

```handlebars
<Form as |form|>
  <form.Field @name="approved" @title="Approved" as |field|>
    <field.Checkbox />
  </form.Field>
</Form>

<Form as |form|>
  <form.Field @name="query" @title="Query" as |field|>
    <field.Code @lang="sql" @height={{400}} />
  </form.Field>
</Form>

<Form as |form|>
  <form.Field @name="start" @title="Start" as |field|>
    <field.Calendar @includeTime={{false}} />
  </form.Field>
</Form>
```

--------------------------------

### Implementing JS logic in Glimmer components

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/07-theme-developer-tutorial/05-components.md

Demonstrates using a JavaScript getter to process user group data within a Glimmer component. It filters out trust-level groups and formats the remaining names into a comma-separated string for template rendering.

```gjs
export default class CustomWelcomeBanner extends Component {
  @service currentUser;

  get commaSeparatedGroups() {
    return this.currentUser?.groups
      .reject((group) => group.name.startsWith("trust_level_"))
      .map((group) => group.name)
      .join(", ");
  }

  <template>
    <div class="custom-welcome-banner">
      {{#if this.username}}
        Welcome back @{{this.username}}. You're a member of
        {{this.commaSeparatedGroups}}.
      {{else}}
        Welcome to our community.
      {{/if}}
    </div>
  </template>
}
```

--------------------------------

### Render Modal using Old showModal API (JavaScript)

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/03-code-internals/10-converting-modals.md

Demonstrates how to render a modal using the older `showModal` API in Discourse. This method takes a controller name and options, returning a controller instance.

```javascript
import showModal from "discourse/lib/show-modal";

export default class extends Component {
  showMyModal() {
    const controller = showModal("my-modal", {
      title: "My Modal Title",
      modalClass: "my-modal-class",
      model: { topic: this.topic },
    });

    controller.set("updateTopic", this.updateTopic);
  });
}
```

--------------------------------

### Execute Rake tasks for multisite environments

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/02-development-environments/09-multisite-setup.md

Run database tasks for specific sites using the RAILS_DB environment variable, or run them across all sites by omitting the variable.

```bash
RAILS_DB=alternate rake db:create
RAILS_DB=alternate rake db:migrate
```

```bash
rake db:create
rake db:migrate
```

--------------------------------

### Define theme settings and modifier mapping

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/05-themes-components/21-theme-modifiers.md

Example showing a boolean setting defined in settings.yml and its corresponding mapping to a theme modifier in about.json.

```yaml
show_excerpts:
  default: false
```

```json
{
  "modifiers": {
    "serialize_topic_excerpts": {
      "type": "setting",
      "value": "show_excerpts"
    }
  }
}
```

--------------------------------

### Create Symbolic Link for Plugin Development

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/04-plugins/04-git-setup.md

Commands to create a symbolic link from the local plugin directory into the Discourse plugins folder, allowing the development server to detect the plugin without moving files.

```sh
cd ~/code/discourse/plugins
ln -s ~/code/discourse-plugin-test .
```

--------------------------------

### Render dynamic content into a Plugin Outlet using GJS

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/07-theme-developer-tutorial/01-introduction.md

Uses the Discourse API to inject an Ember template into the 'discovery-list-container-top' outlet. It checks the current user status to conditionally render a personalized welcome message.

```gjs
const currentUser = api.getCurrentUser();

api.renderInOutlet(
  "discovery-list-container-top",
  <template>
    <div class="custom-welcome-banner">
      {{#if currentUser}}
        Welcome back @{{currentUser.username}}
      {{else}}
        Welcome to our community
      {{/if}}
    </div>
  </template>
);
```

--------------------------------

### Implement Text Post-Processing

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/03-code-internals/09-markdown-extensions.md

Utilizes the core text post-process ruler to apply regex-based transformations to text content before final rendering.

```javascript
md.core.textPostProcess.ruler.push("onlyfastcars", {
  matcher: /(car)|(bus)/,
  onMatch: function (buffer, matches, state) {
    let token = new state.Token("text", "", 0);
    token.content = "fast " + matches[0];
    buffer.push(token);
  },
});
```

--------------------------------

### Version control and deployment commands

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/05-themes-components/23-font-component.md

Standard git commands to stage, commit, and push the theme component changes to a remote GitHub repository.

```shell
git add LICENSE
git add about.json
git add assets/roboto.woff2
git add common/common.scss
git commit -am "first commit"
git push
```

--------------------------------

### Shutdown Discourse Development Container

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/02-development-environments/03-docker-setup.md

Shuts down the running Discourse development Docker container. This command is used to stop the development environment when you are finished.

```shell
d/shutdown_dev

```

--------------------------------

### Discourse Acceptance Testing with QUnit

Source: https://context7.com/discourse/discourse-developer-docs/llms.txt

Shows how to write acceptance tests for Discourse applications using QUnit. This example demonstrates setting up user states, mocking API responses with Pretender, and asserting DOM elements and interactions within a specific route. Requires Discourse testing helpers.

```javascript
// test/javascripts/acceptance/my-feature-test.js
import { acceptance } from "helpers/qunit-helpers";
import { visit, click, fillIn } from "@ember/test-helpers";

acceptance("My Feature", function (needs) {
  needs.user(); // Logged-in user
  needs.settings({ my_plugin_enabled: true });

  needs.pretender((server, helper) => {
    server.get("/my-api/data.json", () => {
      return helper.response({
        items: [
          { id: 1, name: "Item 1" },
          { id: 2, name: "Item 2" },
        ],
      });
    });
  });

  test("displays feature when enabled", async function (assert) {
    await visit("/my-feature");

    assert.dom(".my-feature-container").exists("feature container is present");
    assert.dom(".item").exists({ count: 2 }, "displays all items");
  });

  test("handles user interaction", async function (assert) {
    await visit("/my-feature");
    await fillIn(".search-input", "test");
    await click(".search-button");

    assert.dom(".results").exists("shows search results");
  });
});
```

--------------------------------

### Create a plugin connector template

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/03-code-internals/13-plugin-outlet-connectors.md

An example of a basic Handlebars template for a plugin connector, which is rendered as an Ember component within the specified outlet.

```handlebars
<div class="alert alert-info">
  This topic was created by a member of the
  <a href="https://discourse.org/team">Discourse Team</a>
</div>
```

--------------------------------

### Run Discourse Specs

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/02-development-environments/04-macos-setup.md

Executes the automated tests for the Discourse application. This command helps ensure the application's integrity and that recent changes have not introduced regressions.

```shell
bundle exec rake autospec
```

--------------------------------

### Run All Discourse Tests

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/02-development-environments/03-docker-setup.md

Executes all automated tests for Discourse using the `autospec` rake task. This is a convenient way to ensure the codebase is functioning correctly.

```shell
d/rake autospec

```

--------------------------------

### Start secondary Ember-CLI instance for benchmarking

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/03-code-internals/07-js-performance.md

Launches a secondary Ember-CLI instance in production mode, proxied to the Rails server, to allow side-by-side performance comparison of different code versions.

```bash
EMBER_ENV=production pnpm ember serve --port 4201 --proxy http://localhost:3000
```

--------------------------------

### Initialize Discourse API with Custom JavaScript

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/07-theme-developer-tutorial/02-remote-theme.md

This code snippet initializes the Discourse API to render a custom welcome banner. It checks if a user is logged in and displays a personalized greeting or a general welcome message. This requires the 'discourse/lib/api' module.

```gjs
import { apiInitializer } from "discourse/lib/api";

export default apiInitializer("1.8.0", (api) => {
  const currentUser = api.getCurrentUser();

  api.renderInOutlet(
    "discovery-list-container-top",
    <template>
      <div class="custom-welcome-banner">
        {{#if currentUser}}
          Welcome back @{{currentUser.username}}
        {{else}}
          Welcome to our community
        {{/if}}
      </div>
    </template>
  );
});
```

--------------------------------

### Expose Container Ports Globally

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/02-development-environments/03-docker-setup.md

Configures the Discourse development container to globally expose its ports. By default, ports are not exposed externally, but this flag enables it.

```shell
d/boot_dev -p

```

--------------------------------

### Implementing Page Objects

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/03-code-internals/20-system-specs.md

Example of a Page Object class structure in Ruby, used to encapsulate page navigation, element selection, and user interactions for consistent testing.

```ruby
# frozen_string_literal: true

module PageObjects
  module Pages
    class Tag < PageObjects::Pages::Base
      def visit_tag(tag)
        page.visit "/tag/#{tag.name}"
        self
      end

      def tag_info_btn
        find("#show-tag-info")
      end

      def add_synonyms_dropdown
        PageObjects::Components::SelectKit.new("#add-synonyms")
      end

      def search_tags(query)
        add_synonyms_dropdown.search(query)
      end

      def tag_box(tag)
        find(".tag-box div[data-tag-name='#{tag}']")
      end
    end
  end
end
```

--------------------------------

### Search for Plugin Outlets via CLI

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/04-plugins/02-plugin-outlet.md

A shell command to search the local codebase for all existing PluginOutlet declarations in Handlebars files.

```bash
git grep "<PluginOutlet" -- "*.hbs"
```

--------------------------------

### Create New Discourse Admin Account

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/02-development-environments/04-macos-setup.md

Creates a new administrator account for the local Discourse instance. This command prompts the user to enter details for the admin user.

```shell
RAILS_ENV=development bundle exec rake admin:create
```

--------------------------------

### Initialize and manipulate forms with FormKit

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/03-code-internals/21-form-kit.md

Demonstrates how to initialize the FormKit helper and perform common form actions like submitting, resetting, filling inputs, and toggling controls.

```javascript
import formKit from "discourse/tests/helpers/form-kit";

const myForm = formKit(".my-form");
formKit().submit();
formKit().reset();
await formKit().field("foo").fillIn("bar");
await formKit().field("foo").toggle();
```

--------------------------------

### Run Specific Plugin Tests

Source: https://github.com/discourse/discourse-developer-docs/blob/main/docs/02-development-environments/03-docker-setup.md

Runs tests for a specific Discourse plugin. This command allows developers to focus on testing changes within a particular plugin.

```shell
d/rake plugin:spec["discourse-follow"]

```