|
| 1 | +# 🏷️ Branding your help file |
| 2 | + |
| 3 | +To customize the default identity of the application to your own visual identity, **HelpViewer** provides tools that are described in the following subchapters. |
| 4 | + |
| 5 | +For some tools, simply adding files to your help is sufficient. For others, configuration changes or knowledge of CSS or JavaScript is required. |
| 6 | + |
| 7 | +For the changes to be visible to users, you must always recompile the help (release a new version). Otherwise, the new files or CSS/JS changes will not be visible. |
| 8 | + |
| 9 | +## Easy modifications |
| 10 | + |
| 11 | +### 🌅 Welcome screen |
| 12 | + |
| 13 | +- The welcome screen is represented by the **README.md** file located at the root of the language version of the help. |
| 14 | +- This file opens first when the reader launches the help. |
| 15 | + |
| 16 | +### 🌐 Custom application icon in the page header (favicon) |
| 17 | + |
| 18 | +- Place the file in the help repository: |
| 19 | +**helpProject/_base/favicon.png** |
| 20 | + |
| 21 | +### 📖 Topic tree icons |
| 22 | + |
| 23 | +- The option to change icons in the topic tree is described in the chapter [TOC icons][TocIcon]. |
| 24 | + |
| 25 | +## Configuration edits |
| 26 | + |
| 27 | +### 🎨 Replacing or extending cascading styles |
| 28 | + |
| 29 | +- How to replace or extend cascading styles is described in the chapter 🛠️ [Viewer Custom UI][customUI]. |
| 30 | +- Keep in mind that some definitions (e.g., CSS class names or id attribute values) can only be changed with certain restrictions. |
| 31 | +- In the file hvdata/data.zip:**main.css**, there is a pseudo-class **:root** at the beginning, which contains color palette constants. For initial adjustments, changing the values here may be sufficient. |
| 32 | +- Within the pseudo-class **:root**, which you would define in **plus.css**, you can additionally change the font of the entire application interface. |
| 33 | +- CSS3 allows you to define [visual effects and transitions][CSS3Effects]. Another source can be the article [Web Visual Effects with CSS3][CSS3Effects2]. |
| 34 | + |
| 35 | +#### 🖌️ Changing colors and fonts |
| 36 | + |
| 37 | +Below is an example of how to set global variables for colors and fonts. You can then use these variables anywhere in CSS via `var()`. |
| 38 | + |
| 39 | +```css |
| 40 | +:root { |
| 41 | + --color-bg: black; |
| 42 | + --color-fg: white; |
| 43 | + --font: "Segoe UI", Roboto, sans-serif; /* main font */ |
| 44 | +} |
| 45 | + |
| 46 | +body { |
| 47 | + font-family: var(--font); |
| 48 | + background: var(--color-bg); /* use of variable */ |
| 49 | + color: var(--color-fg, silver); /* use of variable with fallback value if missing */ |
| 50 | +} |
| 51 | +``` |
| 52 | + |
| 53 | +If possible, use CSS variables. This makes it easier to change colors, fonts, or other parameters in the future. |
| 54 | + |
| 55 | +#### 🖱️ Defining a custom cursor |
| 56 | + |
| 57 | +- You can define a custom cursor in **plus.css** as follows: |
| 58 | + |
| 59 | +```css |
| 60 | +:root { |
| 61 | + cursor: url('my-cursor.png'), auto; |
| 62 | +} |
| 63 | +``` |
| 64 | + |
| 65 | +The file **my-cursor.png** must be in a relative location to **index.html** and cannot be part of help files or data (it cannot be in a ZIP archive). |
| 66 | + |
| 67 | +### 🧩 Advanced tools, programming |
| 68 | + |
| 69 | +- Some tools in the following chapters may be limited or non-functional depending on the deployment or configuration in your environment. For information on downloading and installing the package, contact your system administrator. |
| 70 | +- The tools require minimal configuration. Some require additional programming of the source code when running the help (helpProjekt/_base/**plus.js**). |
| 71 | +- These advanced options for modifying the application identity are described in 🧩 [Developer Guide][DGuide]. |
| 72 | +- Automatically generated documentation of the running instance is also available and accessible via the 🧩 [Object explorer][oexplorer] plugin in 🐞 debug mode. Debug mode is not enabled by default in production environments. |
| 73 | +- The application can be downloaded as: |
| 74 | + - 🚀 complete package (ZIP) |
| 75 | + - 📥 custom package (ZIP) |
| 76 | + - 🐳 [Docker/Podman container][DCONT] |
| 77 | + |
| 78 | +### 💧 Watermark |
| 79 | + |
| 80 | +- Functionality is provided by the 🖥️ puiWatermark plugin, which must be supplemented with configuration. |
| 81 | + |
| 82 | +### 🖼️ Custom icons for buttons |
| 83 | + |
| 84 | +- Button icons can be changed in the configuration of plugins derived from 🖥️ puiButton. Each plugin has a configuration option ⚙️ CAPTION with a default value. |
| 85 | +- To change the icons, you may need to distribute your own font file within the help file (place it in the **_base** directory). |
| 86 | + |
| 87 | +### 💬 Texts and tooltips |
| 88 | + |
| 89 | +- Application labels and translations are controlled by localization, which is part of the application data. |
| 90 | +- For more information, see the following chapters: |
| 91 | + - 🌐 [New language for Viewer][DGuideLangCentral] - main localization data |
| 92 | + - 🌐 [Plugin localization][DGuideLangPlug] - localization data for individual plugins |
| 93 | +- These changes only require configuration adjustments. Code modifications are usually not necessary. |
| 94 | + |
| 95 | +#### © Copyright, ® registered, and ™ trademark |
| 96 | + |
| 97 | +- Copyright, registered design, trademark, and disclaimer texts must be added to the application according to your needs. |
| 98 | +- No special program-level support for this area is currently implemented. |
| 99 | +- Programming and manual modification or extension of the application package is required here. |
| 100 | +- The application is distributed under an open license [MIT][MIT]. You can modify and distribute the code commercially and non-commercially, but you must retain the **HelpViewer** license and the original copyright in your own packages. |
| 101 | + |
| 102 | +[TocIcon]: tocIcon.md "TOC icons" |
| 103 | +[customUI]: customUI.md "Viewer Custom UI" |
| 104 | +[DGuide]: ?d=hlp-dguide/Help-__.zip "Documentation for developers" |
| 105 | +[DGuideLangCentral]: ?d=hlp-dguide/Help-__.zip&p=newLangViewer.md "New language for Viewer" |
| 106 | +[DGuideLangPlug]: ?d=hlp-dguide/Help-__.zip&p=plugLocStrings.md "Plugin localization" |
| 107 | +[oexplorer]: ?d=hlp-dguide/Help-__.zip&p=oexplorer.md "Object explorer" |
| 108 | +[DCONT]: https://github.com/HelpViewer/HelpViewer/pkgs/container/helpviewer "Container" |
| 109 | +[CSS3Effects]: https://prismic.io/blog/css-image-effects "50 Creative CSS Image Effects for Engaging Websites" |
| 110 | +[CSS3Effects2]: https://leanpub.com/web-visual-effects-with-css3/read "Web Visual Effects with CSS3" |
| 111 | +[MIT]: https://github.com/HelpViewer/HelpViewer/blob/master/LICENSE "MIT license" |
0 commit comments