buildprofiles.xml
Last modified: 31 January 2025buildprofiles.xml is used to configure the build process and output, such as the header and footer, search settings, shortcut and version switcher.
By default, the buildprofiles.xml file should be located under the cfg directory in the help module, unless you specify a different directory using the <build-config> element in writerside.cfg.
tip
To create the buildprofiles.xml file, you can right-click the build configuration directory (cfg by default) in the Project tool window, select New, and then click buildprofiles.xml.
Here is a sample build config file:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE buildprofiles SYSTEM "https://resources.jetbrains.com/writerside/1.0/build-profiles.dtd">
<buildprofiles xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/build-profiles.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<variables>
<web-root>https://www.jetbrains.com/help</web-root>
<download-page>https://www.jetbrains.com/writerside/download/</download-page>
<download-title>Get Writerside</download-title>
<showDownloadButton>true</showDownloadButton>
<primary-color>strawberry</primary-color>
<header-logo>writerside.svg</header-logo>
<custom-favicons>https://www.jetbrains.com/icon-512.png</custom-favicons>
</variables>
<shortcuts>
<src>keymap.xml</src>
<layout name="Windows" display-name="Windows"/>
<layout name="macOS" display-name="macOS"/>
<layout name="GNOME" display-name="Linux"/>
</shortcuts>
<footer>
<social type="blog" href="https://blog.jetbrains.com/writerside/">Writerside Blog</social>
<social type="twitter" href="https://twitter.com/onwriterside">Writerside on Twitter</social>
<link href="https://youtrack.jetbrains.com/issues/WRS">Issue tracker</link>
<link href="https://youtrack.jetbrains.com/form/9cf3cf67-8bc0-4cbc-824c-7ade4c563338">Submit support request</link>
<link href="mailto:writerside@jetbrains.com">Contact us</link>
<copyright>2000 JetBrains s.r.o.</copyright>
</footer>
<build-profile instance="wrs">
<sitemap priority="0.35" change-frequency="monthly"/>
<variables>
<noindex-content>false</noindex-content>
<product-web-url>https://www.jetbrains.com/help/writerside/</product-web-url>
<og-twitter>@onwriterside</og-twitter>
<og-image>https://resources.jetbrains.com/storage/products/writerside/img/meta/preview.png</og-image>
<images-prefix-override>https://my.company.com/images/</images-prefix-override>
</variables>
</build-profile>
</buildprofiles>
buildprofiles.xml can contain the following elements and attributes:
<algolia-api-key>
Specify the Algolia Search API key.
Example:
<algolia-api-key>123456789</algolia-api-key>
<algolia-id>
Specify the Algolia Application ID.
Example:
<algolia-id>ABC123DEF4</algolia-id>
<algolia-index>
Specify the Algolia Index name.
Example:
<algolia-index>prod_INDEX_NAME</algolia-index>
<algolia-show-logo>
Specify "true" to display the Algolia logo in the search results, as required by certain plans.
<analytics-body-html-file>
Specify the name of the file that contains a Google analytics <noscript>
to install the Google tag into a help website. The script file must be placed in the cfg/
folder. This code will be inserted after the <body>
tag opening.
<analytics-head-script-file>
Specify the name of the file that contains a Google analytics <script>
to install the Google tag into a help website. The script file must be placed in the cfg/
folder. This code will be inserted after the <head>
tag opening.
<build-profile>
This is the root element for settings related to specific instances.
Attributes:
<buildprofiles>
This is the root element with settings applicable to all instances.
- Child elements
<build-profile> <footer> <icons> <property-bundles> <shortcuts> <sitemap> <variables>
<color-preset>
Specify the intensity of the primary accent color:
soft
: Minimal contrasting touch of the primary accent color.contrast
(default): Default look with moderate contrast and intensity.vivid
: Most contrasting usage of the primary accent color.
Example:
<color-preset>vivid</color-preset>
<content-max-width>
Specify the maximum width (in pixels) for article content.
Example:
<content-max-width>500</content-max-width>
<contribute-url>
Specify the link to the documentation source where users can contribute, for example, a public GitHub repository. It must point to the documentation folder where the 'topics' folder is located.
If the link points to GitHub, the corresponding icon will be displayed.
Example:
<contribute-url>https://github.com/JetBrains/intellij-sdk-docs/edit/main/</contribute-url>
<copyright>
Specify the copyright information. For example:
<copyright>2000 JetBrains s.r.o.</copyright>
<custom-css>
Specify a file with custom css configuration to add into the head
element on every page. File is expected to be in "static" folder under a folder for build configuration files ("cfg" by default)
<custom-favicons>
Specify a list of custom favicons ordered by size (16x16, 32x32, 96x96, 300x300, 500x500).
Example:
<custom-favicons>icon16.svg,icon32.svg,icon96.svg,icon300.svg,icon500.svg</custom-favicons>
You need to specify at least one icon with the smallest size. You can also reference it via a URL.
<custom-video-cover>
Specify the name of an image from the designated images folder to be displayed as the video cover for embedded videos.
To show different covers depending on the selected help theme (light or dark), add the image for the dark theme with the same file name and the _dark.png
suffix.
<custom-video-cover>video_preview_image.png</custom-video-cover>
<download-page>
Specify the URL where the header button should link to, such as the product download page on your website.
<download-title>
Specify the title of the button in the header. By default, the title is Get %instance%
, where %instance%
is the name of the current instance.
<enable-contribution>
Set to true
to enable the Edit page option that points to the documentation source where users can contribute.
<footer>
Specify the info you want to display in the webhelp footer, such as links to social media, a contact email address, links to other resources, and ICP information.
<footer>
<social type="facebook" href="https://example.com">Product page on Facebook</social>
<social type="rss" href="https://example.com">Product RSS feed</social>
<social type="email" href="mail@example.com">Send us an email</social>
<link href="https://example.com">Custom link 1</link>
<link href="https://example.com">Custom link 2</link>
<link href="https://example.com">Custom link 3</link>
</footer>
<generate-canonicals>
Add the canonical element to the head
section of every HTML page. It will point to the configured web root of your help website. For example, if the web root is specified as https://my.product.site/help
, Writerside will generate the following: <link rel="canonical" href="https://my.product.site/help"/>
<generate-sitemap-url-prefix>
Specify the prefix for the URL added to the <loc>
element in the generated sitemap.
<header-logo>
Specify the name of a file from the designated images folder to be displayed in the website header.
Logo image requirements:
SVG or PNG format. We recommend using SVG for better quality on Retina and 4K displays.
Height-to-width aspect ratio between 1.2 and 0.24. We recommend using square images.
Image height more than 48px.
<icons>
Specify the locations of directories with icons.
Attributes:
<icp>
Specify the information about the Internet Content Provider license. This is a legal requirement if your website is hosted on a server in mainland China or is available to visitors from China.
<ignore-problems>
Specify errors and warnings to ignore in build and preview.
<images-prefix-override>
Override the web path for images if you produce a separate artifact with images and store them elsewhere, not publish them with your main help website.
<include-after-body>
Specify a file with HTML code to add after the body
element on every page.
<include-before-body>
Specify a file with HTML code to add before the body
element on every page.
<include-in-head>
Specify a file with HTML code to add into the head
element on every page.
<index-page-url-prefix>
Specify the URL prefix to use for redirects. By default, redirects point to other HTML files in the same directory, but if you want redirects to some other location, specify it in this variable.
<layout>
Specify the set of keymap layouts used in your help website. For example:
<layout name="Windows" display-name="Windows"/>
<layout name="macOS" display-name="macOS"/>
<layout name="GNOME" display-name="Linux"/>
Attributes:
<link>
Specify links to other resources, such as the support portal or issue tracker. Use href
attribute to specify the resource URL. For example:
<link href="https://youtrack.jetbrains.com/issues/WRS">Issue tracker</link>
<link href="mailto:writerside@jetbrains.com">Contact us</link>
Attributes:
<link-color>
Specify the link color.
Use hex codes (e.g. #307FFF) or color names from the list:
frozen (default)
strawberry
dracula
iris
aqua
halloween
ruby
blueberry
emerald
metallic
purple
forest
deep-ocean
Example:
<link-color>#307FFF</link-color>
<local-src>
Specify the location of per-instance icons.
Attributes:
<locale-code>
Specify the locale to use for capitalization transformation in titles and for lowercasing topic file names to produce the resulting HTML file names. By default, Writerside uses the root locale whose language, country, and variant are empty strings.
<max-search-hits-to-display>
Specify the maximum number of search results to return.
<max-search-results>
Specify the maximum number of search results to return.
<noindex-content>
Set to false
to enable indexing of content by external search engines. By default, Writerside produces content that is not indexed by search engines.
Example:
<noindex-content>false</noindex-content>
Attributes:
<offline-docs>
Produce a self-contained help website that can be used in an isolated environment with no internet access. Setting <offline-docs>true</offline-docs>
bundles resources such as the frontend application, styles, fonts, and favicons into the produced output.
<og-image>
Specify the URL to an image displayed in the link snippet when sharing links to help pages.
<og-image>https://example.com/sample.jpg</og-image>
<og-twitter>
Specify a Twitter handle displayed in the link snippet when sharing links to help pages.
<og-twitter>@onwriterside</og-twitter>
<primary-color>
Specify the accent color for various UI components, such as the focused item in the table of contents, the active tab, or a button.
Use hex codes (e.g. #307FFF) or color names from the list:
frozen (default)
strawberry
dracula
iris
aqua
halloween
ruby
blueberry
emerald
metallic
purple
forest
deep-ocean
Example:
<primary-color>#307FFF</primary-color>
<product-web-url>
Specify the URL for clicks on the logo in the header. Usually, it should link to the main page of your help website or to your main product page.
<product-web-url>https://example.com/help/</product-web-url>
<property-bundles>
Specify the settings for property bundles.
<property-cleanup>
Specify a regular expression for symbols to remove from property values. For example, to remove an ellipsis at the end: <property-cleanup>\.{3}$</property-cleanup>
.
<property-file>
Specify the location of the file with property declarations.
Attributes:
<property-folder>
Specify the location of the directory with property files.
Attributes:
<resizable-sidebar>
Set to true
to enable manual resizing for the Table of Content panel.
Example:
<resizable-sidebar>true</resizable-sidebar>
<search-endpoint>
Specify the URL for a custom search endpoint.
<search-scope>
Specify the search scope.
<search-scopes-provider>
Specify the URL for the Algolia search endpoint.
<shared-src>
Specify the location of shared icons.
<shortcuts>
Specify the settings for shortcuts.
Attributes:
<showDownloadButton>
Specify whether you want to show a button in the header with a link.
<sidebar-width>
Specify the default width (in pixels) for the Table of Content panel.
Example:
<sidebar-width>200</sidebar-width>
<sitemap>
Specify the settings for the generated sitemap. For example:
<sitemap priority="0.35" change-frequency="monthly"/>
Attributes:
<social>
Specify links to social media accounts, an RSS feed, a blog, or a contact email address. They will be displayed with the corresponding icons.
Use the type
attribute to specify the resource type, and the href
attribute to specify the link.
For example:
<social type="blog" href="https://blog.jetbrains.com/writerside/">Writerside Blog</social>
<social type="twitter" href="https://twitter.com/onwriterside">Writerside on Twitter</social>
Attributes:
<src>
Specify the path to the file with keymaps declarations relative to the module root.
Attributes:
<variables>
Specify various variables that control the output.
- Child elements
<algolia-api-key> <algolia-id> <algolia-index> <algolia-show-logo> <analytics-body-html-file> <analytics-head-script-file> <color-preset> <content-max-width> <contribute-url> <custom-css> <custom-favicons> <custom-video-cover> <download-page> <download-title> <enable-contribution> <generate-canonicals> <generate-sitemap-url-prefix> <header-logo> <ignore-problems> <images-prefix-override> <include-after-body> <include-before-body> <include-in-head> <index-page-url-prefix> <link-color> <locale-code> <max-search-hits-to-display> <max-search-results> <noindex-content> <offline-docs> <og-image> <og-twitter> <primary-color> <product-web-url> <property-cleanup> <resizable-sidebar> <search-endpoint> <search-scope> <search-scopes-provider> <showDownloadButton> <sidebar-width> <versions-comparison> <versions-switcher> <web-root> <webmaster> <write-help-state-file>
<versions-comparison>
Specify a URL to the version comparison matrix. This URL opens when the reader clicks the <available-only-for>
label.
<versions-switcher>
Specify the link to the help-versions.json
file that lists all published versions of your documentation. The help website uses this file to render the version switcher component.
<versions-switcher>https://my.documentation.com/help-versions.json</versions-switcher>
<web-root>
Specify the URL of your documentation website. For example, set https://mycompany.com/help
if you are going to publish the produced help website at this URL. This will ensure that the builder produces correct metadata for HTML pages (such as canonical and OG URLs) and correct URLs for pages in the search index.
<webmaster>
Specify the main support email that will be used for the "Contact us" link in the footer.
<write-help-state-file>
Produce the current.help.state
file that contains the status configured for the produced instance, such as release
, eap
, or deprecated
.