Documentation

Documentation

Design System Publisher Configuration

Various aspects of the documentation website can be configured through environment variables or with a JSON configuration file.

Configuration Options

Environment variables override the JSON property configuration. The website needs to be rebuilt — or restarted in development mode — in order for changes to the configuration variables to take effect.

All path options are relative to the content project folder.

ENV Variable
JSON Property		 Description Default Value

CONFIG_PATH
N/A

Path to configuration JSON files.

"dspublisher/config"

THEME_PATH
themePath

Path to theme customizations. See Site Customization.

"dspublisher/theme"

ARTICLES_PATH
articlesPath

Path to the AsciiDoc articles.

"articles"

EXAMPLES_IMPORT_PATH
examplesImportPath

Path to the dynamically imported custom element examples.

"frontend/demo"

TITLE
title

The site title. Used as the main prefix in the page <title>. Also used in meta tags and sitemap generation. Not visible in the site UI.

"Docs"

SITE_URL
siteUrl

The root URL of the site (i.e., the domain without a path). For example, "https://example.com". A [filename]sitemap.xml is not generated unless this is provided.

""

PATH_PREFIX
pathPrefix

The root path where the website is hosted. For example, if you deploy the site to https://example.com/docs, the path prefix should be "/docs".

"/"

PROXY_VAADIN_HOSTNAME
proxyVaadinHostname

The host name of the Vaadin project. Used for request proxying.

"localhost"

EXAMPLES_INCLUDE_URL_PREFIX
examplesIncludeUrlPrefix

URL prefix from which JavaScript examples are included.

"/vaadin/web-component/"

VAADIN_CONNECT_PREFIX
vaadinConnectPrefix

Prefix used for Vaadin Fusion endpoints. Replaces effectively only global VAADIN_CONNECT_PREFIX variables with the provided value.

"/connect"

VERSIONS_URL
versionsUrl

An absolute URL to a JSON file that defines the available versions of the documentation. See example later on this page.

""

VERSIONS
versions

A JSON object defining the available documentation versions. See example later on this page.

""

DOCS_IMPORT_EXAMPLE_RESOURCES
N/A

If "true", load all frontend resources up front when the first component sample is encountered. See Rendered UI Examples for more information.

undefined

You can prefix the environment variable names with DOCS_ (e.g., DOCS_TITLE) if you need to avoid conflicts with other systems that use the same variable names. The VERSIONS variable is an exception, as it expects a JSON value, and providing that as a string through the command line would be verbose. For example:

[
  {
    "title": "Vaadin 23",
    "shortTitle": "V23",
    "url": "/docs/latest"
  },
  {
    "title": "Vaadin 22",
    "shortTitle": "V22",
    "url": "/docs/v22"
  },
]

The title value is shown in the version drop-down, and the shortTitle value, if provided, is shown as the drop-down button value when that version is selected.

Configuration JSON File

The configuration options with a JSON property can be overridden with a configuration file. The default configuration is the following:

{
  "articlesPath": "articles",
  "themePath": "dspublisher/theme",
  "examplesImportPath": "frontend/demo",
  "examplesIncludeUrlPrefix": "/vaadin/web-component/",
  "vaadinConnectPrefix": "/connect",
  "proxyVaadinHostname": "localhost",
  "pathPrefix": "/",
  "versionsUrl": "",
  "versions": "",
  "siteUrl": "",
  "title": "Docs"
}

Create a default.json file in the content project, in the folder defined by the CONFIG_PATH variable — dspublisher/config, by default — and override the properties you need. You don’t have to repeat the default values.

You can also define a production.json configuration file in the same folder, to use a different configuration for your production build.

With the configuration files in place, you can use execute npm run dspublisher:start, or npm run dspublisher:build without extra command-line parameters.