KT-50452 Make flexible html for customization (#2374)

1 files changed, 36 insertions, 5 deletions

diff --git a/docs/src/doc/docs/user_guide/base-specific/frontend.md b/docs/src/doc/docs/user_guide/base-specific/frontend.md
index e6802639..ecbd6964 100644
--- a/docs/src/doc/docs/user_guide/base-specific/frontend.md
+++ b/docs/src/doc/docs/user_guide/base-specific/frontend.md
@@ -2,12 +2,12 @@
 
 ## Prerequisites
 
-Dokka's Html format requires a web server to view documentation correctly.
+Dokka's HTML format requires a web server to view documentation correctly.
 This can be achieved by using the one that is build in IntelliJ or providing your own.
 If this requisite is not fulfilled Dokka with fail to load navigation pane and search bars.
 
 !!! important
-    Concepts specified below apply only to configuration of the Base Plugin (that contains Html format) 
+    Concepts specified below apply only to configuration of the Base Plugin (that contains HTML format) 
     and needs to be applied via pluginsConfiguration and not on the root one.
 
 ## Modifying assets
@@ -20,19 +20,21 @@ Currently, user can modify:
  
 Every file provided in those values will be applied to **every** page.
 
-Dokka uses 3 stylesheets:
+Dokka uses 4 stylesheets:
 
 * `style.css` - main css file responsible for styling the page
 * `jetbrains-mono.css` - fonts used across dokka
 * `logo-styles.css` - logo styling
+* [`prism.css`](https://github.com/Kotlin/dokka/blob/master/plugins/base/src/main/resources/dokka/styles/prism.css) - code highlighting
 
-User can choose to add or override those files. 
+Also, it uses js scripts. The actual ones are [here](https://github.com/Kotlin/dokka/tree/master/plugins/base/src/main/resources/dokka/scripts).
+User can choose to add or override those files - stylesheets and js scripts. 
 Resources will be overridden when in `pluginConfiguration` block there is a resource with the same name.
 
 ## Modifying footer
 
 Dokka supports custom messages in the footer via `footerMessage` string property on base plugin configuration. 
-Keep in mind that this value will be passed exactly to the output html, so it has to be valid and escaped correctly.
+Keep in mind that this value will be passed exactly to the output HTML, so it has to be valid and escaped correctly.
 
 ## Separating inherited members
 
@@ -69,3 +71,32 @@ In order to override a logo and style it accordingly a css file named `logo-styl
 
 
 For build system specific instructions please visit dedicated pages: [gradle](../gradle/usage.md#applying-plugins), [maven](../maven/usage.md#applying-plugins) and [cli](../cli/usage.md#configuration-options)
+
+## Custom HTML pages
+
+Templates are taken from the folder that is defined by the `templatesDir` property.
+To customize HTML output, you can use the [default template](https://github.com/Kotlin/dokka/blob/master/plugins/base/src/main/resources/dokka/templates) as a starting point.
+
+!!! note
+    To change page assets, you can set properties `customAssets` and `customStyleSheets`.
+    Assets are handled by Dokka itself, not FreeMaker.
+
+Currently, there is only one template file with predefined name `base.ftl`. It defines general design of all pages to render.  
+If `templatesDir` is defined, Dokka will find the `base.ftl` file there.
+
+Variables given below are available to the template:
+  - `${pageName}` - the page name
+  - `${footerMessage}` - text that is set by the `footerMessage` property
+  - `${sourceSets}` - a nullable list of source sets, only for multi-platform pages. Each source set has `name`, `platfrom` and `filter` properties.
+
+Also, Dokka-defined [directives](https://freemarker.apache.org/docs/ref_directive_userDefined.html) can be used:
+  - `<@content/>` - main content
+  - `<@resources/>` - scripts, stylesheets 
+  - `<@version/>` - version ([versioning-plugin](https://kotlin.github.io/dokka/1.6.10/user_guide/versioning/versioning/) will replace this with a version navigator)
+  - `<@template_cmd name="...""> ...</@template_cmd>` - is used for variables that depend on the root project (such `pathToRoot`, `projectName`). They are available only inside the directive. This is processed by a multi-module task that assembles partial outputs from modules. 
+     Example:
+    ```
+    <@template_cmd name="projectName">
+       <span>${projectName}</span>
+    </@template_cmd>
+    ```
\ No newline at end of file