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 f2dd31b05b..d2d45ceee7 100644 --- a/docs/src/doc/docs/user_guide/base-specific/frontend.md +++ b/docs/src/doc/docs/user_guide/base-specific/frontend.md @@ -81,22 +81,24 @@ To customize HTML output, you can use the [default template](https://github.com/ 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. +There is a template file with predefined name `base.ftl`. It defines general design of all pages to render. +`base.ftl` can import another templates that can be set by user as well. +If `templatesDir` is defined, Dokka will find a template file there. +If the file is not found, a default one will be used. 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. +* `${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="...""> ...` - 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"> - ${projectName} - - ``` \ No newline at end of file +* `<@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="...""> ...` - 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"> + ${projectName} + + ``` \ No newline at end of file diff --git a/plugins/base/src/main/resources/dokka/templates/base.ftl b/plugins/base/src/main/resources/dokka/templates/base.ftl index fb8fabd90b..36df0d3d20 100644 --- a/plugins/base/src/main/resources/dokka/templates/base.ftl +++ b/plugins/base/src/main/resources/dokka/templates/base.ftl @@ -1,10 +1,13 @@ +<#import "includes/page_heads.ftl" as page_heads> +<#import "includes/header.ftl" as header> +<#import "includes/footer.ftl" as footer> +<#import "includes/article.ftl" as article> - ${pageName} + <@page_heads.display/> <@template_cmd name="pathToRoot"> - <#-- This script doesn't need to be there but it is nice to have @@ -19,43 +22,14 @@ if(savedDarkMode === true){ <@resources/> - + <@header.display/>
- <@content/> -
${footerMessage}Generated by dokka -
+ <@article.display/> + <@footer.display/>
diff --git a/plugins/base/src/main/resources/dokka/templates/includes/article.ftl b/plugins/base/src/main/resources/dokka/templates/includes/article.ftl new file mode 100644 index 0000000000..7f300881e4 --- /dev/null +++ b/plugins/base/src/main/resources/dokka/templates/includes/article.ftl @@ -0,0 +1,3 @@ +<#macro display> + <@content/> + \ No newline at end of file diff --git a/plugins/base/src/main/resources/dokka/templates/includes/footer.ftl b/plugins/base/src/main/resources/dokka/templates/includes/footer.ftl new file mode 100644 index 0000000000..461a8162d4 --- /dev/null +++ b/plugins/base/src/main/resources/dokka/templates/includes/footer.ftl @@ -0,0 +1,7 @@ +<#macro display> +
+ ${footerMessage}Generated by dokka +
+ \ No newline at end of file diff --git a/plugins/base/src/main/resources/dokka/templates/includes/header.ftl b/plugins/base/src/main/resources/dokka/templates/includes/header.ftl new file mode 100644 index 0000000000..495974f582 --- /dev/null +++ b/plugins/base/src/main/resources/dokka/templates/includes/header.ftl @@ -0,0 +1,29 @@ +<#macro display> + + \ No newline at end of file diff --git a/plugins/base/src/main/resources/dokka/templates/includes/page_heads.ftl b/plugins/base/src/main/resources/dokka/templates/includes/page_heads.ftl new file mode 100644 index 0000000000..f897c104dc --- /dev/null +++ b/plugins/base/src/main/resources/dokka/templates/includes/page_heads.ftl @@ -0,0 +1,6 @@ +<#macro display> + ${pageName} + <@template_cmd name="pathToRoot"> + + + \ No newline at end of file