Site Customization
The documentation website styles can be customized to fit the brand and design guidelines of your organization. A custom application theme can also be applied, which affects the theme of rendered UI examples within the documentation pages.
Website Styles
The website’s styles can be defined in the global.css style sheet in the dspublisher/docs-theme folder.
Most styles can be customized using custom properties.
The following are the most commonly used style properties:
| Font family |
| Font family for headings |
| Font size for H1…H6 level headings |
| Color of body text |
| Color of headings |
| Color of unvisited links |
| Color of visited links |
| Header background color |
| Selected tab color (for code sample tabs, etc) |
| Max width of the website’s content |
| Width of the page sidebar / table of contents |
| Max width of the page’s body (excluding sidebar/table of contents) |
The following properties are set in an HTML selector block:
html {
--docs-header-background-color: green;
--docs-font-family: 'Times New Roman';
}Changes to the website’s styles are automatically applied after a couple of seconds.
Header
The “full name” given to the initialization script sets the website’s title. See Settings for changing it after initialization.
The title text size is determined by the --docs-font-size-h3 property, but its styling can be fully customized as follows:
header h3 {
--docs-heading-text-color: red;
--docs-font-family-heading: Helvetica;
}A logo image can be inserted into website’s header by copying the image into the docs-theme folder and replacing the background-image value in the header style block.
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 {
background-image: url("logo.png");
background-size: contain;
background-repeat: no-repeat;
}|
Note
|
Application theme
This section is about styling the documentation website itself.
See Applying a Custom Application Theme for instructions on how to apply a theme which is used in UI examples.
|
Custom Top Header
You can use the empty top-level header element (<dspublisher-header>) on the documentation site, above the application header, to add custom content inside it using the "[filename]dspublisher/docs-theme/header.ts`" file.
If it exports a custom element class, Design System Publisher uses it to register a new custom element with the tag name `dspublisher-header, which gets rendered as the top header.
import { html, LitElement } from 'lit-element';
export default class extends LitElement {
render() {
return html`
<div>This is my custom header</div>
`;
}
}Since the top-level header is a custom element which gets dynamically defined, it may cause a layout shift when this happens.
If you know the height of the custom header in advance, you can avoid the layout shift by assigning a static height for the <dspublisher-header> element in the global.css styles.
dspublisher-header {
height: 100px;
}Settings
Various aspects of the website can be configured through environment variables in the dspublisher/.env file:
| The website’s page title, which appears in the browser’s chrome. This title is also used in web search results (Google, etc) and in social share previews. Doesn’t appear anywhere in the documentation website UI. |
| Path to the site theme folder |
| Path to the root folder for articles. Relative path to the project root folder. |
| Boolean that determines whether to load the custom top header content in development mode |
| Boolean that determines whether all frontend resources are loaded up-front when the first component sample is encountered. See details below. |
| Required, if the application isn’t deployed on the root path “/”. Only effective when building for production. |
If you only intend to provide TypeScript component examples, you can optimize the loading of frontend resources by setting DOCS_IMPORT_EXAMPLE_RESOURCES to false.
It disables the automatic loading of any frontend resources needed for Java samples.
The website needs to be rebuilt, or restarted in development mode, in order for changes to these environment variables to take effect.
362C3515-84BB-4D13-B1F2-E8C58374B7AE