<commit_before>:filename: 015_tasks/03_task_generateSite.adoc
include::_config.adoc[]

[[task_generatesite]]
= generateSite

include::../_feedback.adoc[]

== About This Task

When you have only one document, the output of `generateHTML` might meet your requirements.
But as your documentation grows, and you have multiple documents, you will need a microsite which bundles all of the information.
The `generateSite` task uses https://jbake.org[jBake] to create a static site with a landing page, a blog and search.

== Pages

The microsite is page-oriented, not document-oriented.
If you have already organized your documents by chapter, use them as pages to create a great user experience.
The arc42-template sources are a good example.

To include a page in the microsite, add a metadata header to it.

.page metadata
[source, asciidoc]
----
:jbake-menu: arc42
:jbake-title: Solution Strategy
:jbake-order: 4
:jbake-type: page_toc
:jbake-status: published
:filename: 015_tasks/03_task_generateSite.adoc
ifndef::imagesdir[:imagesdir: ../../images]

:toc:

[[section-solution-strategy]]
== Solution Strategy
----

Here is an overview of each element:

*jbake-menu*

The top-level menu for this page.
Defaults to the top-level folder name of the .adoc file within the `docDir`.

*jbake-title*

The title to be displayed in the drop-down top-level menu.
Defaults to the first headline of the file.

*jbake-order*

Applies a sort order to drop-down entries.
Defaults to a prefixed file number, such as `**04**_filename.adoc` or to the prefixed number of the second-level folder name.

*jbake-type*

The page type.
Controls which template is used to render the page.
You will mostly use `page` for a full-width page or `page_toc` for a page with a table of contents (toc) rendered on the left.
Defaults to `page_toc`.

*jbake-status*

Either `draft` or `published`.
Only `published` pages will be rendered.
Defaults to `published` for files with a `jbake-order` and `draft` for files without `jbake-order` or files prefixed with `_`.

*filename*

Required for edit and feedback links (coming soon).
Defaults to the filename :-).

*ifndef*

Fixes the imagesdir according to the nesting level of your docs folder.
Defaults to the main `docDir/images`.

*toc*

For `:jbake-type: page_toc`, you need this line to generate the toc.

NOTE: Start your pages with a `==` level headline.
You can fix the level offset when you include the page in a larger document with `include::chapter.adoc[leveloffset=+1]`.

== Configuration

The configuration follows the __convention over configuration__ approach. 
If you follow the conventions, you don't have to configure anything.
But if you want to, you can override the convention behaviour with a configuration.

=== Menu

The `:jbake-menu:` is only the code for the menu entry to be created.
You can map these codes to menu entries through the configuration ( `microsite`-Section ) in the following way:

[source, groovy]
----
menu = [code1: 'title1', code2: 'title2', code3: '-']
----

if you have four files 

```
src/docs/code1/demo1.adoc
src/docs/code1/demo2.adoc
src/docs/code3/demo3.adoc
src/docs/code3/_demo4.adoc<commit_msg>Update 03_task_generateSite.adoc<commit_after>:filename: 015_tasks/03_task_generateSite.adoc
include::_config.adoc[]

[[task_generatesite]]
= generateSite

include::../_feedback.adoc[]

== About This Task

When you have only one document, the output of `generateHTML` might meet your requirements.
But as your documentation grows, and you have multiple documents, you will need a microsite which bundles all of the information.
The `generateSite` task uses https://jbake.org[jBake] to create a static site with a landing page, a blog and search.

== Pages

The microsite is page-oriented, not document-oriented.
If you have already organized your documents by chapter, use them as pages to create a great user experience.
The arc42-template sources are a good example.

To include a page in the microsite, add a metadata header to it.

.page metadata
[source, asciidoc]
----
:jbake-menu: arc42
:jbake-title: Solution Strategy
:jbake-order: 4
:jbake-type: page_toc
:jbake-status: published
:filename: 015_tasks/03_task_generateSite.adoc
ifndef::imagesdir[:imagesdir: ../../images]

:toc:

[[section-solution-strategy]]
== Solution Strategy
----

Here is an overview of each element:

*jbake-menu*

The top-level menu for this page.
Defaults to the top-level folder name of the .adoc file within the `docDir`.

*jbake-title*

The title to be displayed in the drop-down top-level menu.
Defaults to the first headline of the file.

*jbake-order*

Applies a sort order to drop-down entries.
Defaults to a prefixed file number, such as `**04**_filename.adoc` or to the prefixed number of the second-level folder name.

*jbake-type*

The page type.
Controls which template is used to render the page.
You will mostly use `page` for a full-width page or `page_toc` for a page with a table of contents (toc) rendered on the left.
Defaults to `page_toc`.

*jbake-status*

Either `draft` or `published`.
Only `published` pages will be rendered.
Defaults to `published` for files with a `jbake-order` and `draft` for files without `jbake-order` or files prefixed with `_`.

*filename*

Required for edit and feedback links (coming soon).
Defaults to the filename :-).

*ifndef*

Fixes the imagesdir according to the nesting level of your docs folder.
Defaults to the main `docDir/images`.

*toc*

For `:jbake-type: page_toc`, you need this line to generate the toc.

NOTE: Start your pages with a `==` level headline.
You can fix the level offset when you include the page in a larger document with `include::chapter.adoc[leveloffset=+1]`.

[[config]]
== Configuration

The configuration follows the __convention over configuration__ approach. 
If you follow the conventions, you don't have to configure anything.
But if you want to, you can override the convention behaviour with a configuration.

=== Menu

The `:jbake-menu:` is only the code for the menu entry to be created.
You can map these codes to menu entries through the configuration ( `microsite`-Section ) in the following way:

[source, groovy]
----
menu = [code1: 'title1', code2: 'title2', code3: '-']
----

if you have four files 

```
src/docs/code1/demo1.adoc
src/docs/code1/demo2.adoc
src/docs/code3/demo3.adoc
src/docs/code3/_demo4.adoc
{'fraction_non_alphanumeric': 0.09229559748427672, 'fraction_numerical': 0.010062893081761006, 'mean_word_length': 4.363406408094435, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '665073', 'n_tokens_mistral': 2006, 'n_tokens_neox': 1854, 'n_words': 845}