How to Create a Dark Mode-Ready Publishing Template

How to Create a Dark Mode-Ready Publishing Template From a Default One

By default, two templates supports both light and dark mode: Light and Oxygen. The following example uses the Light template:

Copy the existing Publishing Template (see Creating a Publishing Template Starting from an Existing Template).

Edit the light-theme.css stylesheet with the colors you want to add/modify:

:root {
  --wh-primary-bg: #e3e3e3;
  ...
  --wh-title-color: #333;
}

@media screen {
  :root[data-wh-theme="dark"] {
    color-scheme: dark;
    --wh-primary-bg: #293136;
    ...
    --wh-title-color: #bfbfbf;
  }
}

If you added new color variables, add CSS rules using them (in light.css for example):
```
*[class ~= "topic/title"] {
  color: var(--wh-title-color);
}
```
Duplicate the DITA Map WebHelp Responsive transformation scenario.
Click the Choose Custom Publishing Template link and select your template.
Click OK to save the changes, then run the transformation scenario.

How to Create a Dark Mode-Ready Publishing Template From Scratch

Create a Publishing Template, see Creating a Publishing Template Starting from Scratch.

Create a custom CSS stylesheet (theme.css for example) and add the light colors:

Note:

Built-in CSS rules will automatically use the variables defined here and in the next step.

:root {
  /* General */
  --wh-primary-bg: #fff;
  --wh-primary-color: #000;
  --wh-secondary-bg: #000;
  --wh-secondary-color: #fff;
  --wh-strong-color: #888;
  --wh-soft-color: #ccc;
  --wh-subtle-color: #f2f2f2;

  --wh-top-menu-bg: #e6e6e6;
  --wh-main-page-toc-bg: #f2f8ff;
  --wh-main-page-toc-border: #c0c0c0;
  --wh-main-page-shortdesc-color: #0d1a2b;
  --wh-close-toc-icon-border: #343a40;
  --wh-close-toc-button-shadow: rgba(0,0,0,.16);

  --wh-link-color: #337ab7;
  --wh-label-color: #666;
  --wh-pre-bg: #eee;
  --wh-tooltip-color: #5185cb;
  --wh-code-color: #800000;
  --wh-boolean-color: #008000;
  --wh-state-color: #ff0000;
  --wh-syntaxdiagram-color: #800000;
  --wh-markup-color: #639;
  --wh-fig-border: #c0c0c0;
  --wh-caution-bg: #ffd100;
  --wh-danger-bg: #c8102e;
  --wh-warning-bg: #ff8200;
  --wh-hazardstatement-bg: #0072ce;
  --wh-indexterm-bg: #fdf;
  --wh-go2top-bg: #444;
  --wh-go2top-border: #999;
  --wh-toggle-border: #347bb7;

  /* Search */
  --wh-search-color: #c93416;
  --wh-search-breadcrumb-color: #ccc;
  --wh-search-loader-base-bg: #eaecec;
  --wh-search-loader-glow-bg: #f3f3f3;
  --wh-search-facets-bg: #e3ebf3;
  --wh-search-facets-disabled-color: #b7b6b6;
  --wh-search-facets-border: #ebebeb;
  --wh-search-results-facets-bg: #f5f5f5;
  --wh-search-results-facets-color: #212c37;
  --wh-highlight-bg: #ffff88;
  --wh-scroll-bg: #d6d6d6;

  /* Change Tracking */
  --wh-oxy-delete-color: #ff0000;
  --wh-oxy-insert-color: #0000ff;
  --wh-oxy-change-done-color: #808080;
  --wh-oxy-range-color: #800000;
  --wh-oxy-comment-border: #ffa500;
  --wh-oxy-change-bg: #ffff00;
  --wh-oxy-attributes-footnote-bg: #00ffff;
  --wh-oxy-comment-footnote-bg: #ffffaa;
  --wh-oxy-delete-footnote-bg: #ffaaaa;
  --wh-oxy-insert-footnote-bg: #ddddff;

  /* Syntax Highlight */
  --wh-hl-json_key-color: #7263b9;
  --wh-hl-keyword-color: #7f0055;
  --wh-hl-string-color: #2a00ff;
  --wh-hl-comment-color: #006400;
  --wh-hl-directive-color: #8b26c9;
  --wh-hl-tag-color: #000096;
  --wh-hl-attribute-color: #ff7935;
  --wh-hl-value-color: #993300;
  --wh-hl-html-color: #000080;
  --wh-hl-xsl-color: #0066ff;
  --wh-hl-annotation-color: #808080;
  --wh-hl-tag-doctype-comment-color: #3f5fbf;
  --wh-hl-tag-doctype-color: #0000ff;

  /* OpenAPI */
  --wh-openapi-border: #c5c5c5;
  --wh-openapi-post-bg: #c2f2cb;
  --wh-openapi-get-bg: #ccebff;
  --wh-openapi-delete-bg: #ffceca;
  --wh-openapi-put-bg: #ffe7c7;
  --wh-openapi-head-bg: #f4e6ff;
}

In the same stylesheet, add the dark colors:

Note:

If you are using the same color in both light and dark modes, you only need to define it for the light mode.

@media screen {
  :root[data-wh-theme="dark"] {
    color-scheme: dark;
    /* General */
    --wh-primary-bg: #212529;
    --wh-primary-color: #e3e3e3;
    --wh-secondary-bg: #212529;
    --wh-secondary-color: #e3e3e3;
    --wh-strong-color: #e0e0e0;
    --wh-subtle-color: #3a3b3c;
  
    --wh-top-menu-bg: #2b3035;
    --wh-main-page-toc-bg: #22303c;
    --wh-main-page-shortdesc-color: #d5d5d5;
    --wh-close-toc-icon-border: var(--wh-primary-color);
    --wh-close-toc-button-shadow: rgba(255,255,255,.16);
  
    --wh-link-color: #76a5e0;
    --wh-label-color: #bbb;
    --wh-pre-bg: #444;
    --wh-code-color: #ffa500;
    --wh-boolean-color: #66ff66;
    --wh-state-color: #ff6666;
    --wh-syntaxdiagram-color: #ff4d4d;
    --wh-markup-color: #d1b3ff;
    --wh-caution-bg: #7f6000;
    --wh-danger-bg: #62002b;
    --wh-warning-bg: #993500;
    --wh-hazardstatement-bg: #0025cb;
  
    /* Search */
    --wh-search-color: #a2311a;
    --wh-search-breadcrumb-color: #555555;
    --wh-search-loader-base-bg: #3a3f44;
    --wh-search-loader-glow-bg: #4b525a;
    --wh-search-facets-bg: #2d333b;
    --wh-search-facets-disabled-color: var(--wh-label-color);
    --wh-search-facets-border: #444;
    --wh-search-results-facets-bg: #2c2f35;
    --wh-search-results-facets-color: #d8dee9;
    --wh-highlight-bg: #777700;
    --wh-scroll-bg: #444;
  
    /* Change Tracking */
    --wh-oxy-delete-color: #ff6b6b;
    --wh-oxy-insert-color: #66aaff;
    --wh-oxy-change-done-color: #ccc;
    --wh-oxy-range-color: #ff4d4d;
    --wh-oxy-comment-border: #995f00;
    --wh-oxy-change-bg: #666600;
    --wh-oxy-attributes-footnote-bg: #006666;
    --wh-oxy-comment-footnote-bg: #363600;
    --wh-oxy-delete-footnote-bg: #994d4d;
    --wh-oxy-insert-footnote-bg: #666699;
  
    /* Syntax Highlight */
    --wh-hl-json_key-color: #b5adda;
    --wh-hl-keyword-color: #ff89d8;
    --wh-hl-string-color: #b7a8ff;
    --wh-hl-comment-color: #00cf00;
    --wh-hl-directive-color: #d0a0ed;
    --wh-hl-tag-color: #aaaaff;
    --wh-hl-attribute-color: #ff9763;
    --wh-hl-value-color: #ff9661;
    --wh-hl-html-color: #a9a9ff;
    --wh-hl-xsl-color: #80b2ff;
    --wh-hl-annotation-color: #b0b0b0;
    --wh-hl-tag-doctype-comment-color: #a2b2e0;
    --wh-hl-tag-doctype-color: #a8a8ff;
  
    /* OpenAPI */
    --wh-openapi-border: #8a8a8a;
    --wh-openapi-post-bg: #7eae7a;
    --wh-openapi-get-bg: #7a9fcf;
    --wh-openapi-delete-bg: #b2746e;
    --wh-openapi-put-bg: #bfae86;
    --wh-openapi-head-bg: #7a70b2;
  }
}

Add custom variables for elements that require two color or image variants, such as:

:root {
  ...
  --wh-breadcrumb-color: #878787;
  --wh-related-links-color: #5185cb;
  --wh-publication-toc-color: #7b7a7a;

  --wh-search-image: url("resources/images/custom.png");
}

@media screen {
  :root[data-wh-theme="dark"] {
    color-scheme: dark;
    ...
    --wh-breadcrumb-color: #6ab1e3;
    --wh-related-links-color: #0d6efd;
    --wh-publication-toc-color: var(--wh-breadcrumb-color);
  
    --wh-search-image: url("resources/images/custom_dark.png");
  }
}

If you added new color variables, add CSS rules using them (in custom.css for example):

.wh_breadcrumb ol{
  color: var(--wh-breadcrumb-color);
}
.related-links a,
.related-links a:visited {
  color: var(--wh-related-links-color);
  padding-bottom: .3em;
}
.wh_publication_toc a,
.wh_publication_toc a:visited,
.wh_publication_toc a:hover {
  color: var(--wh-publication-toc-color);
}
.wh_search_input{
  padding: 115px 0;
  background: var(--wh-search-image) right no-repeat var(--wh-search-input-bg);
}

Open the template descriptor file associated with your publishing template, add your custom CSS stylesheets in the <resources> section and declare the parameter in the <parameters> section:

<publishing-template>
  ...
  <webhelp>
    ...
    <resources>
      <css file="theme.css"/>
      <css file="custom.css"/>
    </resources>
    <parameters>
      ...
      <parameter name="webhelp.enable.dark.mode" value="yes"/>
    </parameters>
    ...

Duplicate the DITA Map WebHelp Responsive transformation scenario.
Click the Choose Custom Publishing Template link and select your template.
Click OK to save the changes, then run the transformation scenario.

Restriction:

If you open the output locally in Firefox, the theme settings may not persist between pages. This happens because Firefox treats each local page as a separate origin, preventing shared storage of theme preferences. If you deploy the output on an HTTP server or use another browser, theme settings will persist.