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 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. Effectively only replaces 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 an example later on this page.

""

VERSIONS
versions

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

""

DOCS_IMPORT_EXAMPLE_RESOURCES
N/A

If "true", load all front-end 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 CONFIG_PATH variable (dspublisher/config by default), and override the properties you need. You don’t need 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 the npm run dspublisher:start or npm run dspublisher:build commands without extra command-line parameters.