E-mail
Introduction
From release 6.0-rc3 we can describe a complete site's layout using an yaml file. Through site schema you can set root page (called home) its children's tree, add attachments and labels.
Use it is pretty straightforward, put your site.yaml in ${basedir}/src/site/confluence folder and describe your preferred layout following the site schema.
Site template
To simplify understanding, below there is a simple site descriptor
home:
uri: encoding.confluence
children:
- name: "page 1"
uri: page1.md
- name: "page 2"
uri: page2.md
attachments:
- name: "attach1.png"
uri: attach1.png
comment: attach1_comment
contentType: "image/png"
version: 1
attachments:
- name: "home.png"
uri: home.png
comment: home_comment
contentType: "image/png"
version: 1
labels:
- encoding
- test
Tags description
site
| Attribute | Description | mandatory |
|---|---|---|
| space-key | space key (if set overrides the equivalent pom configuration) | no |
home
| Attribute | Description | mandatory |
|---|---|---|
| uri | Content's source | no |
| name | Title of page | no (if uri is defined) |
| parentPageId | parent page id (if set overrides the equivalent pom configuration) | no |
| parentPage | parent page name (if set overrides the equivalent pom configuration) | no |
| ignoreVariables | if it is true the variables $ are not injected during page processing | no |
attachment
| Attribute | Description | mandatory |
|---|---|---|
| uri | Content's source or a directory | no |
| name | Name of attachment or a glob pattern | no (if uri is defined) |
| comment | no | |
| contentType | yes | |
| version | no |
Directory support
from version 5.0-rc4 the tag attachment supports also the file inclusion from directory
Example
# include all png files from myfolder attachments: - name: "*.png" uri: myfolder comment: file from myfolder contentType: "image/png" version: 1 # include all files from myfolder attachments: - uri: myfolder comment: "file from myfolder" version: 1
label
The content of label's tag is the label's value
generated
This tag has been added from version 5.0-rc3 and allows to choose where put the built-in generated pages
Currently only plugin.goals is supported therefore such tag is useful when we are dealing with Maven Plugin Documentation
| Attribute | Description | mandatory |
|---|---|---|
| ref | built-in generated pages Id. Currently only plugin.goals is supported | yes |
Usage example
home:
uri: index.confluence
children:
- name: Summary
uri: summary.confluence
- name: Goals
uri: goals.confluence
generated:
ref: plugin.goals
- name: PluginsSummary
uri: plugins-summary.confluence
Note:
The URI format
The uri attribute could refer to
- File resource
We can refer to file in absolute way using file scheme (e.g. file:///Documents/page.confluence) or in relative way not using any scheme. In that case the path will be resolved starting from site home
- Classpath resource
We can refer to resource using classpath schema. (e.g. classpath:page.confluence)
- Network resource
We can refer to resource using http scheme. (e.g. http://www.thesite.com/page.confluence)
Using Freemarker in the Site Definition
Since version 6.5 you can use Freemarker markup inside the Site Definition.
Following static Java classes are available in the model:
- Paths (java.nio.Paths)
- Files (java.nio.Files)
Ex. Files.exists(Paths.get('src/docs/anyfile.txt'))
Following built-in Freemarker models are available:
- statics (ex. ${statics["java.lang.System"].currentTimeMillis()})
- enums (ex. ${enums["java.math.RoundingMode"].UP})
Model of the Maven project is included as project variable. Ex. <#assign tag = project.groupId + '' + project.artifactId + '' + project.version>.
<#assign tag = project.groupId + '-' + project.artifactId + '-' + project.version>
home:
uri: release-version.wiki
children:
- name: "Dependencies"
uri: dependencies.wiki
attachments:
- name: "documentation-confluence-reporting-maven-plugin-7.0-SNAPSHOT.pdf"
uri: ../generated-docs/documentation.pdf
contentType: "application/pdf"
version: 1
comment: Documentation generated to PDF
- name: "documentation-confluence-reporting-maven-plugin-7.0-SNAPSHOT.html"
uri: ../generated-docs/documentation.html
contentType: "text/html"
version: 1
comment: Single page HTML documentation<#if Files.exists(Paths.get('target/generated-docs/openapi.json')) == true>
- name: "openapi-confluence-reporting-maven-plugin-7.0-SNAPSHOT.json"
uri: ../generated-docs/openapi.json
contentType: "application/json"
version: 1
comment: OpenAPIv3 JSON Documentation</#if><#if Files.exists(Paths.get('target/generated-docs/openapi.yaml')) == true>
- name: "openapi-confluence-reporting-maven-plugin-7.0-SNAPSHOT.yaml"
uri: ../generated-docs/openapi.yaml
contentType: "text/yaml"
version: 1
comment: OpenAPIv3 YAML Documentation</#if><#if Files.exists(Paths.get('target/generated-docs/generated-class-diagram.svg')) == true>
- name: "generated-class-diagram-confluence-reporting-maven-plugin-7.0-SNAPSHOT.svg"
uri: ../generated-docs/generated-class-diagram.svg
contentType: "image/svg+xml"
version: 1
comment: Generated UML class diagram</#if>