Writerside Help

buildprofiles.xml

buildprofiles.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.

Here is a sample build config file:

<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://resources.jetbrains.com/help/img/writerside/</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>
Parent elements

<variables>

<algolia-id>

Specify the Algolia Application ID.

Example:

<algolia-id>ABC123DEF4</algolia-id>
Parent elements

<variables>

<algolia-index>

Specify the Algolia Index name.

Example:

<algolia-index>prod_INDEX_NAME</algolia-index>
Parent elements

<variables>

<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.

Parent elements

<variables>

<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.

Parent elements

<variables>

<browser-edits-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:

<browser-edits-url>https://github.com/JetBrains/intellij-sdk-docs/edit/main/topics</browser-edits-url>
Parent elements

<variables>

<build-profile>

This is the root element for settings related to specific instances.

Parent elements

<buildprofiles>

Child elements

<footer> <sitemap> <variables>

Attributes:

instance

Specify different build settings for different instances.

<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>
Parent elements

<variables>

Specify the copyright information. For example:

<copyright>2000 JetBrains s.r.o.</copyright>

<footer>

<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.

Parent elements

<variables>

<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>
Parent elements

<variables>

<download-page>

Specify the URL where the header button should link to, such as the product download page on your website.

Parent elements

<variables>

<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.

Parent elements

<variables>

<enable-browser-edits>

Set to true to enable the Edit page option that points to the documentation source where users can contribute.

Parent elements

<variables>

<feedback-support>

Specify the main support link for the feedback widget.

Parent elements

<variables>

<feedback-url>

Specify the URL where the feedback form should lead to.

Parent elements

<variables>

<feedback-widget>

Specify whether you want to have the feedback widget on your documentation website.

Parent elements

<variables>

<feedbackRequireEmail>

Specify whether the feedback form should require an email.

Parent elements

<variables>

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>

<build-profile> <buildprofiles>

<copyright> <icp> <link> <social>

<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"/>

Parent elements

<variables>

<generate-sitemap-url-prefix>

Specify the prefix for the URL added to the <loc> element in the generated sitemap.

Parent elements

<variables>

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.

Parent elements

<variables>

<icons>

Specify the locations of directories with icons.

Parent elements

<buildprofiles>

Child elements

<local-src> <shared-src>

Attributes:

instance

Specify different icon settings for different instances.

<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.

Parent elements

<footer>

<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.

Parent elements

<variables>

<include-after-body>

Specify a file with HTML code to add after the body element on every page.

Parent elements

<variables>

<include-before-body>

Specify a file with HTML code to add before the body element on every page.

Parent elements

<variables>

<include-in-head>

Specify a file with HTML code to add into the head element on every page.

Parent elements

<variables>

<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.

Parent elements

<variables>

<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"/>
Parent elements

<shortcuts>

Attributes:

display-name

Specify the name of the layout as it should be displayed in the shortcuts switcher.

instance

Specify different keymap layouts for different instances.

name

Specify the name of the layout used in the keymap declaration file.

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>

<footer>

Specify the URL of an external resource.

<local-src>

Specify the location of per-instance icons.

Parent elements

<icons>

Attributes:

instance

Specify different locations of icons for different instances.

<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.

Parent elements

<variables>

<max-search-hits-to-display>

Specify the maximum number of search results to return.

Parent elements

<variables>

<max-search-results>

Specify the maximum number of search results to return.

Parent elements

<variables>

<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>
Parent elements

<variables>

Attributes:

status

Specify the status of the instance for which you want to enable indexing.

For example, if you want to enable indexing only for release docs:

<noindex-content status="release">false</noindex-content>

<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.

Parent elements

<variables>

<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>
Parent elements

<variables>

<og-twitter>

Specify a Twitter handle displayed in the link snippet when sharing links to help pages.

<og-twitter>@onwriterside</og-twitter>
Parent elements

<variables>

<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.

Possible values:

  • frozen (default)

  • strawberry

  • dracula

  • iris

  • aqua

  • halloween

  • ruby

  • blueberry

  • emerald

  • metallic

  • purple

  • forest

  • deep-ocean

Example:

<primary-color>purple</primary-color>
Parent elements

<variables>

<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>
Parent elements

<variables>

<property-bundles>

Specify the settings for property bundles.

Parent elements

<buildprofiles>

Child elements

<property-file> <property-folder>

<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>.

Parent elements

<variables>

<property-file>

Specify the location of the file with property declarations.

Parent elements

<property-bundles>

Attributes:

instance

Specify different property files for different instances.

<property-folder>

Specify the location of the directory with property files.

Parent elements

<property-bundles>

Attributes:

instance

Specify different property directories for different instances.

<search-endpoint>

Specify the URL for a custom search endpoint.

Parent elements

<variables>

<search-scope>

Specify the search scope.

Parent elements

<variables>

<search-scopes-provider>

Specify the URL for the Algolia search endpoint.

Parent elements

<variables>

<shared-src>

Specify the location of shared icons.

Parent elements

<icons>

<shortcuts>

Specify the settings for shortcuts.

Parent elements

<buildprofiles>

Child elements

<layout> <src>

Attributes:

instance

Specify different shortcut settings for different instances.

<showDownloadButton>

Specify whether you want to show a button in the header with a link.

Parent elements

<variables>

<sitemap>

Specify the settings for the generated sitemap. For example:

<sitemap priority="0.35" change-frequency="monthly"/>
Parent elements

<build-profile> <buildprofiles>

Attributes:

change-frequency

Specify the expected frequency of changes to help search engines with crawling prioritization: daily, weekly, monthly, or yearly.

priority

Specify the importance of pages for search engines as a decimal value from 0 to 1, where 0.5 is a medium priority setting, 0 is least important, and 1 is most important.

<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>
Parent elements

<footer>

Attributes:

href

Specify the social media link URL.

type

Supported type attribute values:

  • facebook

  • twitter

  • linkedin

  • youtube

  • instagram

  • weibo

  • blog

  • rss

  • bilibili

  • email

<src>

Specify the path to the file with keymaps declarations relative to the module root.

Parent elements

<shortcuts>

Attributes:

instance

Specify different keymap files for different instances.

<variables>

Specify various variables that control the output.

Parent elements

<build-profile> <buildprofiles>

Child elements

<algolia-api-key> <algolia-id> <algolia-index> <analytics-body-html-file> <analytics-head-script-file> <browser-edits-url> <color-preset> <custom-favicons> <custom-video-cover> <download-page> <download-title> <enable-browser-edits> <feedback-support> <feedback-url> <feedback-widget> <feedbackRequireEmail> <generate-canonicals> <generate-sitemap-url-prefix> <header-logo> <images-prefix-override> <include-after-body> <include-before-body> <include-in-head> <index-page-url-prefix> <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> <search-endpoint> <search-scope> <search-scopes-provider> <showDownloadButton> <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.

Parent elements

<variables>

<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>
Parent elements

<variables>

<web-root>

Specify the domain name of you documentation. If you do no have one, specify any fake URL, such as https://some.domain/.

Parent elements

<variables>

<webmaster>

Specify the main support email that will be used for the "Contact us" link in the footer.

Parent elements

<variables>

<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.

Parent elements

<variables>

Last modified: 21 June 2024
writerside.cfgTopics