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.xml can contain the following elements and attributes:
<algolia-api-key>
Specify the Algolia Search API key.
Example:
- Parent elements
<algolia-id>
Specify the Algolia Application ID.
Example:
- Parent elements
<algolia-index>
Specify the Algolia Index name.
Example:
- Parent elements
<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
<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
<build-profile>
This is the root element for settings related to specific instances.
- Parent elements
- Child elements
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:
- Parent elements
<content-max-width>
Specify the maximum width (in pixels) for article content.
Example:
- Parent elements
<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:
- Parent elements
<copyright>
Specify the copyright information. For example:
- Parent elements
<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)
- Parent elements
<custom-favicons>
Specify a list of custom favicons ordered by size (16x16, 32x32, 96x96, 300x300, 500x500).
Example:
You need to specify at least one icon with the smallest size. You can also reference it via a URL.
- Parent elements
<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.
- Parent elements
<download-page>
Specify the URL where the header button should link to, such as the product download page on your website.
- Parent elements
<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
<enable-contribution>
Set to true
to enable the Edit page option that points to the documentation source where users can contribute.
- Parent elements
<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.
<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
<generate-sitemap-url-prefix>
Specify the prefix for the URL added to the <loc>
element in the generated sitemap.
- Parent elements
<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.
- Parent elements
<icons>
Specify the locations of directories with icons.
- Parent elements
- Child elements
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
<ignore-problems>
Specify errors and warnings to ignore in build and preview.
- Parent elements
<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
<include-after-body>
Specify a file with HTML code to add after the body
element on every page.
- Parent elements
<include-before-body>
Specify a file with HTML code to add before the body
element on every page.
- Parent elements
<include-in-head>
Specify a file with HTML code to add into the head
element on every page.
- Parent elements
<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
<layout>
Specify the set of keymap layouts used in your help website. For example:
- Parent elements
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.
<link>
Specify links to other resources, such as the support portal or issue tracker. Use href
attribute to specify the resource URL. For example:
- Parent elements
Attributes:
- href
Specify the URL of an external resource.
<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:
- Parent elements
<local-src>
Specify the location of per-instance icons.
- Parent elements
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
<max-search-hits-to-display>
Specify the maximum number of search results to return.
- Parent elements
<max-search-results>
Specify the maximum number of search results to return.
- Parent elements
<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:
- Parent elements
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
<og-image>
Specify the URL to an image displayed in the link snippet when sharing links to help pages.
- Parent elements
<og-twitter>
Specify a Twitter handle displayed in the link snippet when sharing links to help pages.
- Parent elements
<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:
- Parent elements
<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.
- Parent elements
<property-bundles>
Specify the settings for property bundles.
- Parent elements
- Child elements
<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
<property-file>
Specify the location of the file with property declarations.
- Parent elements
Attributes:
- instance
Specify different property files for different instances.
<property-folder>
Specify the location of the directory with property files.
- Parent elements
Attributes:
- instance
Specify different property directories for different instances.
<resizable-sidebar>
Set to true
to enable manual resizing for the Table of Content panel.
Example:
<search-endpoint>
Specify the URL for a custom search endpoint.
- Parent elements
<search-scope>
Specify the search scope.
- Parent elements
<search-scopes-provider>
Specify the URL for the Algolia search endpoint.
- Parent elements
<shared-src>
Specify the location of shared icons.
<shortcuts>
Specify the settings for shortcuts.
- Parent elements
- Child elements
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
<sidebar-width>
Specify the default width (in pixels) for the Table of Content panel.
Example:
<sitemap>
Specify the settings for the generated sitemap. For example:
- Parent elements
Attributes:
- change-frequency
Specify the expected frequency of changes to help search engines with crawling prioritization:
daily
,weekly
,monthly
, oryearly
.- 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:
Specify the social media link URL.
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
Attributes:
- instance
Specify different keymap files for different instances.
<variables>
Specify various variables that control the output.
- Parent elements
- Child elements
<algolia-api-key> <algolia-id> <algolia-index> <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.
- Parent elements
<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.
- Parent elements
<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
<webmaster>
Specify the main support email that will be used for the "Contact us" link in the footer.
- Parent elements
<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