Site Customization
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;
}
Custom Logo
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