YAF.NET v4 themes are based on Bootstrap 5 and Bootswatch. A theme is written in Sass (SCSS) and compiled to one CSS file, plus two HTML email templates that are styled the same way.

There are two ways to build a theme:

• With the theme kit (recommended, YAF.NET 4.0.11 and newer): the npm package @yafnet/theme-kit contains everything needed. You only need Node.js, not the source code of YAF.NET.
• In the YAF.NET source code: for older versions, or if you build the forum from the source anyway.

At runtime a theme is a folder in the web root of the forum:

wwwroot/css/themes/[theme]/
├── bootstrap-forum.min.css     the compiled theme (Bootstrap + forum styles)
├── EmailTemplate.html          template for all emails
└── DigestTopicTemplate.html    template for one topic in the digest email

• Every folder in wwwroot/css/themes/ is listed as a theme. The folder name is the theme name.
• The board theme is selected in Admin > Board Settings > Theme (default: yaf).
• If Admin > Host Settings > Allow users to change theme is enabled, each user can select a theme in My Settings.
• The light/dark mode selector in the forum header uses the Bootstrap color modes, so a theme should look good in both modes.

A theme is a folder with these source files:

bootstrap-forum.scss of the yaf theme:

@import "_variables.scss";

@import "bootstrap/scss/bootstrap";

@import "forum/chat.scss";

@import "choices/bs-theme.scss";
@import "netStack.scss";

The Bootswatch themes also import _bootswatch.scss right after Bootstrap. Keep the imports of chat.scss, bs-theme.scss and netStack.scss: they contain the styles of the chat, the select boxes and the forum controls.

• Change the variables in _variables.scss, e.g. the primary color, the font and the border radius:

  $blue:    #3761b5 !default;
  $primary: $blue !default;
  
  $font-family-sans-serif: "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif !default;
  $border-radius:          .5rem !default;

  All variables with their default values are in Bootstrap's _variables.scss (node_modules/bootstrap/scss/_variables.scss after npm install). The dark mode colors are in _variables-dark.scss (the variables ending in -dark, e.g. $body-bg-dark).

• Add your own CSS rules at the end of bootstrap-forum.scss (or in _bootswatch.scss), after the Bootstrap import, so you can use the Bootstrap variables and mixins:

  .card-header {
      background-color: tint-color($primary, 80%);
  }

• For the emails, change the colors in _variables-email.scss (yaf theme) or _variables.scss (Bootswatch themes).

The npm package @yafnet/theme-kit contains the sources of all themes included in YAF.NET, the forum styles the themes need, and the command line tool yafnet-theme.

• Node.js 20 or newer

• Optional, for the email templates in the colors of your theme: the .NET SDK and the bootstrap-email tool:

  dotnet tool install --global BootstrapEmail.Net.Cli

  Without bootstrap-email the kit uses the prebuilt email templates of the theme you started from (with its colors).

1. Create a folder for your theme project and install the kit:

   mkdir my-forum-theme
   cd my-forum-theme
   npm init -y
   npm install --save-dev @yafnet/theme-kit@4.0.11

2. Create the theme, here mytheme as a copy of the Bootswatch theme cosmo (without --from the yaf theme is used):

   npx yafnet-theme new mytheme --from cosmo

   npx yafnet-theme list shows all themes you can start from. The theme is created in the folder themes/mytheme.

3. Change the style in themes/mytheme/.

4. Build the theme:

   npx yafnet-theme build

   The theme is written to dist/mytheme/ (bootstrap-forum.min.css, EmailTemplate.html, DigestTopicTemplate.html).

5. Deploy the theme and select it in Admin > Board Settings > Theme.

npx yafnet-theme watch mytheme --out C:\inetpub\yaf\wwwroot\css\themes

Install the kit of the new version and build your theme again, so it gets the styles of new forum features and Bootstrap updates:

npm install --save-dev @yafnet/theme-kit@<new version>
npx yafnet-theme build

• The YAF.NET source code of the same version as your forum, e.g. from the releases (Source code (zip)) or with git:

  git clone --branch v4.0.11 https://github.com/YAFNET/YAFNET.git

• Node.js (LTS version) to compile the CSS.

• Only for the email templates: the .NET SDK and the bootstrap-email tool:

  dotnet tool install --global BootstrapEmail.Net.Cli

Run all commands below in the yafsrc/YetAnotherForum.NET folder. Install the Node.js packages once:

npm install

You don't need to build the forum itself (no Visual Studio, no dotnet build) to build a theme.

1. Change the style in wwwroot/lib/themes/[theme]/.

2. Compile the CSS:

   npm run css

   This compiles the CSS of all themes in wwwroot/lib/themes/ to wwwroot/css/themes/[theme]/bootstrap-forum.min.css.

3. If you changed the email colors, build the email templates:

   npm run emailTemplates

   This builds the templates of all themes and takes a while. To build the templates of one theme only, run bootstrap-email yourself:

   bootstrap-email -f wwwroot/resources/EmailTemplate.html -d wwwroot/css/themes/[theme]/EmailTemplate.html -c wwwroot/lib/themes/[theme]/bootstrap_email.json
   bootstrap-email -f wwwroot/resources/DigestTopicTemplate.html -d wwwroot/css/themes/[theme]/DigestTopicTemplate.html -c wwwroot/lib/themes/[theme]/bootstrap_email-digest.json

4. Deploy the theme.

The example creates the theme mytheme from the yaf theme (plain Bootstrap). To start from a Bootswatch theme, copy that folder instead, e.g. cosmo.

1. Copy the folder wwwroot/lib/themes/yaf to wwwroot/lib/themes/mytheme. Use a folder name without spaces.

2. Replace the old theme name with the new one:

   • bootstrap_email.json and bootstrap_email-digest.json, the setting sass_email_location:

     "sass_email_location": "wwwroot/lib/themes/mytheme/",

   • bootstrap-email.scss, the import of the email variables:

     @import '../themes/mytheme/variables-email';

     ('../themes/mytheme/variables' if you copied a Bootswatch theme)

3. Change the style.

4. Build the CSS and the email templates:

   npm run css
   bootstrap-email -f wwwroot/resources/EmailTemplate.html -d wwwroot/css/themes/mytheme/EmailTemplate.html -c wwwroot/lib/themes/mytheme/bootstrap_email.json
   bootstrap-email -f wwwroot/resources/DigestTopicTemplate.html -d wwwroot/css/themes/mytheme/DigestTopicTemplate.html -c wwwroot/lib/themes/mytheme/bootstrap_email-digest.json

   The build finds new theme folders by itself, no build file needs to be changed.

5. Check that wwwroot/css/themes/mytheme/ contains bootstrap-forum.min.css, EmailTemplate.html and DigestTopicTemplate.html.

6. Deploy the theme and select it in Admin > Board Settings > Theme.

Copy the theme folder (dist/[theme]/ of the theme kit, or wwwroot/css/themes/[theme]/ of the source) into the folder wwwroot/css/themes/ of your forum. The forum doesn't need a restart, the theme is listed in the theme selection right away.

• IIS / Linux: copy the folder into the wwwroot/css/themes folder of the published forum.

• Docker: the themes are part of the image. Mount your theme folder into the container, e.g. in docker-compose.yml:

  volumes:
    - ./mytheme:/app/wwwroot/css/themes/mytheme:ro