Documentation

Documentation

Site Customization

The documentation website styles can be customized to fit the brand and design guidelines of your organization. Custom headers and footers are also possible.

The documentation website styles can be customized to fit the brand and design guidelines of your organization. See Custom Theme for Rendered UI Examples to learn how to apply a theme for the rendered UI examples within the documentation pages.

Website Styles

The website’s styles can be defined in the global.css file, placed in the THEME_PATH folder — dspublisher/theme by default.

The easiest way to customize the website styles is to use CSS custom properties. Here’s an example:

html {
  --docs-header-background-color: green;
  --docs-font-family: 'Times New Roman';
}

During development, changes to the website’s styles are automatically applied after a couple of seconds.

The following sections list the available properties and their default values.

Color

To override colors for dark mode, use the html[theme~="dark"] selector. Use --docs-theme-toggle-display: none to disable theme switching.

html {
  --docs-black-hsl: 210, 18%, 5%;
  --docs-black: hsla(210, 18%, 5%, 1);
  --docs-white: hsla(210, 18%, 100%, 1);

  --docs-gray-0: hsla(210, 18%, 100%, 1);
  --docs-gray-25: hsla(210, 18%, 97%, 1);
  --docs-gray-50: hsla(210, 18%, 92%, 1);
  --docs-gray-75: hsla(210, 18%, 85%, 1);
  --docs-gray-100: hsla(210, 18%, 75%, 1);
  --docs-gray-200: hsla(210, 18%, 64%, 1);
  --docs-gray-300: hsla(210, 18%, 52%, 1);
  --docs-gray-400: hsla(210, 18%, 42%, 1);
  --docs-gray-500: hsla(210, 18%, 33%, 1);
  --docs-gray-600: hsla(210, 18%, 25%, 1);
  --docs-gray-700: hsla(210, 18%, 20%, 1);
  --docs-gray-800: hsla(210, 18%, 17%, 1);
  --docs-gray-900: hsla(210, 18%, 15%, 1);

  --docs-blue-50: hsla(210, 95%, 96%, 1);
  --docs-blue-100: hsla(210, 95%, 88%, 1);
  --docs-blue-200: hsla(210, 95%, 78%, 1);
  --docs-blue-300: hsla(210, 95%, 67%, 1);
  --docs-blue-400: hsla(210, 95%, 56%, 1);
  --docs-blue-500: hsla(210, 95%, 45%, 1);
  --docs-blue-600: hsla(210, 95%, 36%, 1);
  --docs-blue-700: hsla(210, 95%, 27%, 1);
  --docs-blue-800: hsla(210, 95%, 21%, 1);
  --docs-blue-900: hsla(210, 95%, 17%, 1);

  --docs-red-50: hsla(3, 80%, 96%, 1);
  --docs-red-100: hsla(3, 80%, 90%, 1);
  --docs-red-200: hsla(3, 80%, 82%, 1);
  --docs-red-300: hsla(3, 80%, 72%, 1);
  --docs-red-400: hsla(3, 80%, 61%, 1);
  --docs-red-500: hsla(3, 80%, 50%, 1);
  --docs-red-600: hsla(3, 80%, 39%, 1);
  --docs-red-700: hsla(3, 80%, 29%, 1);
  --docs-red-800: hsla(3, 80%, 21%, 1);
  --docs-red-900: hsla(3, 80%, 17%, 1);

  --docs-green-50: hsla(145, 85%, 96%, 1);
  --docs-green-100: hsla(145, 85%, 67%, 1);
  --docs-green-200: hsla(145, 85%, 54%, 1);
  --docs-green-300: hsla(145, 85%, 44%, 1);
  --docs-green-400: hsla(145, 85%, 36%, 1);
  --docs-green-500: hsla(145, 85%, 29%, 1);
  --docs-green-600: hsla(145, 85%, 23%, 1);
  --docs-green-700: hsla(145, 85%, 18%, 1);
  --docs-green-800: hsla(145, 85%, 15%, 1);
  --docs-green-900: hsla(145, 85%, 12%, 1);

  --docs-yellow-50: hsla(44, 85%, 96%, 1);
  --docs-yellow-100: hsla(44, 85%, 69%, 1);
  --docs-yellow-200: hsla(44, 85%, 56%, 1);
  --docs-yellow-300: hsla(44, 85%, 46%, 1);
  --docs-yellow-400: hsla(44, 85%, 38%, 1);
  --docs-yellow-500: hsla(44, 85%, 31%, 1);
  --docs-yellow-600: hsla(44, 85%, 25%, 1);
  --docs-yellow-700: hsla(44, 85%, 21%, 1);
  --docs-yellow-800: hsla(44, 85%, 17%, 1);
  --docs-yellow-900: hsla(44, 85%, 14%, 1);

  --docs-purple-50: hsla(270, 95%, 96%, 1);
  --docs-purple-100: hsla(270, 95%, 88%, 1);
  --docs-purple-200: hsla(270, 95%, 78%, 1);
  --docs-purple-300: hsla(270, 95%, 67%, 1);
  --docs-purple-400: hsla(270, 95%, 56%, 1);
  --docs-purple-500: hsla(270, 95%, 45%, 1);
  --docs-purple-600: hsla(270, 95%, 36%, 1);
  --docs-purple-700: hsla(270, 95%, 27%, 1);
  --docs-purple-800: hsla(270, 95%, 21%, 1);
  --docs-purple-900: hsla(270, 95%, 17%, 1);

  --docs-heading-text-color: var(--docs-gray-900);
  --docs-body-text-color: var(--docs-gray-600);
  --docs-secondary-text-color: var(--docs-gray-400);
  --docs-tertiary-text-color: var(--docs-gray-300);
  --docs-disabled-text-color: var(--docs-gray-200);

  --docs-background-color: var(--docs-gray-0);
  --docs-surface-color-1: var(--docs-gray-50);
  --docs-surface-color-2: var(--docs-gray-25);
  --docs-surface-color-3: var(--docs-gray-0);

  --docs-divider-color-1: var(--docs-gray-75);
  --docs-divider-color-2: var(--docs-gray-100);

  --docs-link-color: var(--docs-blue-500);
  --docs-visited-link-color: var(--docs-blue-700);

  --docs-header-background-color: var(--docs-surface-color-1);

  --docs-admonitionblock-background-color: transparent;
  --docs-admonitionblock-note-border-color: var(--docs-divider-color-2);
  --docs-admonitionblock-note-icon-color: var(--docs-secondary-text-color);
  --docs-admonitionblock-tip-border-color: var(--docs-green-400);
  --docs-admonitionblock-caution-border-color: var(--docs-yellow-300);
  --docs-admonitionblock-warning-border-color: var(--docs-red-500);
  --docs-admonitionblock-important-border-color: var(--docs-blue-500);

  --docs-breadcrumb-color: var(--docs-tertiary-text-color);
  --docs-breadcrumb-separator-color: var(--docs-disabled-text-color);

  --docs-example-render-background-color: var(--docs-white);
  --docs-example-render-color: var(--docs-black);

  --docs-tab-selected-color: var(--docs-blue-500);

  --docs-code-font-size: var(--docs-font-size-s);
  --docs-code-line-height: var(--docs-line-height-m);
  --docs-code-color: var(--docs-body-text-color);
  --docs-code-background-color: var(--docs-surface-color-2);
  --docs-code-comment-color: var(--docs-tertiary-text-color);
  --docs-code-punctuation-color: var(--docs-secondary-text-color);
  --docs-code-operator-color: var(--docs-purple-500);
  --docs-code-property-color: var(--docs-blue-500);
  --docs-code-css-property-color: var(--docs-red-600);
  --docs-code-tag-color: var(--docs-blue-500);
  --docs-code-string-color: var(--docs-green-500);
  --docs-code-number-color: var(--docs-green-600);
  --docs-code-boolean-color: var(--docs-yellow-500);
  --docs-code-keyword-color: var(--docs-purple-600);
  --docs-code-function-color: var(--docs-blue-500);
  --docs-code-selector-color: var(--docs-blue-600);
  --docs-code-annotation-color: var(--docs-yellow-400);
  --docs-code-constant-color: var(--docs-blue-700);
  --docs-code-symbol-color: var(--docs-red-800);
  --docs-code-deleted-color: var(--docs-red-400);
  --docs-code-attr-name-color: var(--docs-red-500);
  --docs-code-attr-value-color: var(--docs-purple-700);
  --docs-code-char-color: var(--docs-green-700);
  --docs-code-builtin-color: var(--docs-yellow-800);
  --docs-code-inserted-color: var(--docs-green-500);
  --docs-code-entity-color: var(--docs-blue-500);
  --docs-code-url-color: var(--docs-link-color);
  --docs-code-css-string-color: var(--docs-code-string-color);
  --docs-code-atrule-color: var(--docs-red-400);
  --docs-code-keyword-color: ;
  --docs-code-regex-color: ;
  --docs-code-important-color: ;
  --docs-code-imports-color: var();
  --docs-code-variable-color: var(--docs-blue-500);
  --docs-code-class-name-color: var(--docs-blue-700);
  --docs-code-parameter-color: var(--docs-yellow-700);
  --docs-code-interpolation-color: var();
  --docs-code-interpolation-punctuation-color: var(--docs-code-punctuation-color);
  --docs-code-property-access-color: var(--docs-red-600);
  --docs-code-tagged-line-background-color: var(--docs-blue-50);
  --docs-code-tagged-line-border-color: var(--docs-blue-400);

  --docs-inline-code-color: inherit;
  --docs-inline-code-background-color: hsla(var(--docs-black-hsl), 0.03);
  --docs-inline-code-border: 1px solid hsla(var(--docs-black-hsl), 0.08);

  --docs-version-badge-upcoming-background-color: var(--docs-green-50);
  --docs-version-badge-upcoming-color: var(--docs-green-700);
  --docs-version-badge-new-background-color: var(--docs-blue-50);
  --docs-version-badge-new-color: var(--docs-blue-700);
  --docs-version-badge-deprecated-background-color: var(--docs-red-50);
  --docs-version-badge-deprecated-color: var(--docs-red-700);
}

html[theme~="dark"] {
  --docs-black-hsl: 210, 50%, 1%;
  --docs-heading-text-color: var(--docs-gray-0);
  --docs-body-text-color: var(--docs-gray-75);
  --docs-secondary-text-color: var(--docs-gray-100);
  --docs-tertiary-text-color: var(--docs-gray-200);
  --docs-disabled-text-color: var(--docs-gray-300);

  --docs-background-color: var(--docs-gray-900);
  --docs-surface-color-1: var(--docs-gray-800);
  --docs-surface-color-2: var(--docs-gray-700);
  --docs-surface-color-3: var(--docs-gray-600);

  --docs-divider-color-1: var(--docs-gray-500);
  --docs-divider-color-2: var(--docs-gray-400);

  --docs-link-color: var(--docs-blue-300);
  --docs-visited-link-color: var(--docs-blue-500);

  --docs-header-background-color: var(--docs-surface-color-3);

  --docs-tab-selected-color: var(--docs-blue-300);

  --docs-text-selection-background-color: var(--docs-gray-500);

  --docs-admonitionblock-tip-border-color: var(--docs-green-300);
  --docs-admonitionblock-caution-border-color: var(--docs-yellow-300);
  --docs-admonitionblock-warning-border-color: var(--docs-red-500);
  --docs-admonitionblock-important-border-color: var(--docs-blue-400);

  --docs-code-operator-color: var(--docs-purple-300);
  --docs-code-property-color: var(--docs-blue-300);
  --docs-code-css-property-color: var(--docs-red-200);
  --docs-code-tag-color: var(--docs-blue-300);
  --docs-code-string-color: var(--docs-green-300);
  --docs-code-number-color: var(--docs-green-200);
  --docs-code-boolean-color: var(--docs-yellow-300);
  --docs-code-keyword-color: var(--docs-purple-200);
  --docs-code-function-color: var(--docs-blue-300);
  --docs-code-selector-color: var(--docs-blue-200);
  --docs-code-annotation-color: var(--docs-yellow-400);
  --docs-code-constant-color: var(--docs-blue-100);
  --docs-code-symbol-color: var(--docs-red-100);
  --docs-code-deleted-color: var(--docs-red-400);
  --docs-code-attr-name-color: var(--docs-red-300);
  --docs-code-attr-value-color: var(--docs-purple-200);
  --docs-code-char-color: var(--docs-green-200);
  --docs-code-builtin-color: var(--docs-yellow-100);
  --docs-code-inserted-color: var(--docs-green-300);
  --docs-code-entity-color: var(--docs-blue-300);
  --docs-code-variable-color: var(--docs-blue-300);
  --docs-code-class-name-color: var(--docs-blue-200);
  --docs-code-parameter-color: var(--docs-yellow-200);
  --docs-code-property-access-color: var(--docs-red-300);
  --docs-code-tagged-line-background-color: var(--docs-gray-600);
  --docs-code-tagged-line-border-color: var(--docs-blue-600);

  --docs-inline-code-color: inherit;
  --docs-inline-code-background-color: hsla(0deg, 0%, 100%, 0.05);
  --docs-inline-code-border: 1px solid hsla(0deg, 0%, 100%, 0.1);

  --docs-version-badge-upcoming-background-color: var(--docs-green-800);
  --docs-version-badge-upcoming-color: var(--docs-green-100);
  --docs-version-badge-new-background-color: var(--docs-blue-800);
  --docs-version-badge-new-color: var(--docs-blue-100);
  --docs-version-badge-deprecated-background-color: var(--docs-red-900);
  --docs-version-badge-deprecated-color: var(--docs-red-100);
}
Typography 
html {
  --docs-font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto,
    Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji',
    'Segoe UI Symbol';
  --docs-font-family-heading: var(--docs-font-family);
  --docs-font-family-monospace: ui-monospace, 'SF Mono', 'Source Code Pro',
    Consolas, 'Liberation Mono', Menlo, Monaco, 'Ubuntu Mono', monospace;
  --docs-font-family-ui: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto,
    Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji',
    'Segoe UI Symbol';

  --docs-font-size-2xs: 0.75rem;
  --docs-font-size-xs: 0.8125rem;
  --docs-font-size-s: 0.875rem;
  --docs-font-size-m: 1rem;

  --docs-font-size-h1: 2.5rem;
  --docs-font-size-h2: 1.75rem;
  --docs-font-size-h3: 1.5rem;
  --docs-font-size-h4: 1.25rem;
  --docs-font-size-h5: 1rem;
  --docs-font-size-h6: 0.875rem;

  --docs-line-height-s: 1.25;
  --docs-line-height-m: 1.6;
  --docs-line-height-l: 1.8;

  --docs-font-weight-normal: 400;
  --docs-font-weight-emphasis: 500;
  --docs-font-weight-strong: 600;
  --docs-font-weight-heading: 500;

  --docs-admonitionblock-font-size: inherit;
}
Spacing 
html {
  --docs-space-2xs: 0.125rem;
  --docs-space-xs: 0.25rem;
  --docs-space-s: 0.5rem;
  --docs-space-m: 1rem;
  --docs-space-l: 1.5rem;
  --docs-space-xl: 2rem;
  --docs-space-2xl: 4rem;
  --docs-space-3xl: 8rem;

  --docs-layout-max-width: 85rem;
  --docs-layout-gutter-width: calc(var(--docs-space-l) + var(--docs-space-xs));
  --docs-article-sidebar-width: 12rem;
  --docs-article-max-width: 55rem;

  --docs-paragraph-margin: 0 0 1.125em;
}
Other 
html {
  --docs-border-radius-s: 0.125rem;
  --docs-border-radius-m: 0.25rem;
  --docs-border-radius-l: 0.375rem;
  --docs-border-radius-full: 50em;

  --docs-admonitionblock-border-radius: var(--docs-border-radius-l);
  --docs-admonitionblock-border-width: 1px 1px 1px 0.25rem;

  --docs-box-shadow-m: 0 4px 12px -4px hsla(var(--docs-black-hsl), 0.3);
  --docs-box-shadow-l: 0 0 10px hsla(var(--docs-black-hsl), 0.2);

  --docs-theme-toggle-display: inline-block;

  --docs-breadcrumb-separator-character: '/';
  --docs-breacrumb-separator-font-size: 1em;
}

A logo image can be inserted into the website’s header by copying the image into the THEME_PATH folder and defining a background-image for the site title element.

Depending on the size and proportions of the image, you may also need to set the background-size and background-repeat properties as follows:

header h3 a::before {
  content: "";
  width: 1em;
  height: 1em;
  background-image: url("logo.svg");
  background-size: contain;
  background-repeat: no-repeat;
}
Note
Application Theme
This section is about styling the documentation website itself. See Custom Theme for Rendered UI Examples for instructions on how to apply a theme which is used for rendered UI examples.

Content Extension Points

Content extension points allow you to insert extra content dynamically in the form of custom HTML elements. These extension points are useful for adding analytics, inserting global navigation items in the header or footer of the page, placing legal information at the end of the page, or including discussions on each documentation page.

<dspublisher-header>

Inserted before the entire page. Spans the entire width of the browser viewport (i.e., not restricted by --docs-layout-max-width).

<dspublisher-footer>

Inserted after the entire page. Spans the entire width of the browser viewport (i.e., not restricted by --docs-layout-max-width).

<dspublisher-article-footer>

Inserted at the end of a page or article content. Spans the width of the content column.

You can define these custom elements using the init-browser.js file, placed in the THEME_PATH folder. You can use Lit for defining these custom elements, or use vanilla JavaScript.

import { html, LitElement } from 'lit';

customElements.define('dspublisher-header', class extends LitElement {
  render() {
    return html`
      <div>This is my custom header</div>
    `;
  }
});

Since these custom elements are dynamically defined, they can cause a layout shifts whey they are rendered. If you know the height or size of the elements in advance, you can avoid the layout shift by assigning a static height for them in the global.css styles:

dspublisher-header {
  height: 100px;
}

362C3515-84BB-4D13-B1F2-E8C58374B7AE