generateSite

About This Task

When your documentation grows beyond a single document, a microsite bundles everything into a navigable website with landing page, blog, and search. The generateSite task renders a static site from your AsciiDoc sources using docToolchain’s built-in site generator. (Up to v3 this was jBake; v4 replaced it with a self-contained generator while keeping the same jbake--prefixed page metadata.)

./dtcw4 local generateSite

Output is written to build/microsite/output/.

Pages

The microsite is page-oriented: each AsciiDoc file becomes a page. Add page metadata to include a page in the site (the jbake- prefix is kept for backwards compatibility):

page metadata
:jbake-menu: arc42
:jbake-title: Solution Strategy
:jbake-order: 4
:jbake-type: page_toc
:jbake-status: published

:toc:

== Solution Strategy
jbake-menu

The top-level menu code. Defaults to the top-level folder name (without order prefix).

jbake-title

Title shown in the navigation. Defaults to the first headline.

jbake-order

Sort order in the sidebar. Defaults to the numeric prefix of the filename or folder.

jbake-type

Controls the template. Use page_toc for a page with sidebar table of contents, or page for full-width.

jbake-status

Either draft or published. Files prefixed with _ default to draft.

Note
 Start pages with a == level headline.

Configuration

Configuration follows a convention-over-configuration approach. Defaults work out of the box — configure only what you want to change.

Menu

Navigation Structure

  • A top-level menu with entries across the top of the page.

  • A section sidebar for each top-level menu entry.

The structure is derived from your folder layout:

src/docs/
├── 10_foo
│   ├── 10_first.adoc
│   └── 20_second.adoc
└── 20_bar
    ├── 10_lorem.adoc
    └── 20_ipsum
        ├── 10_topic-A.adoc
        └── 20_topic-B.adoc

Top-level folders determine menu codes (foo, bar). Sub-folders create navigation tree nodes. Numeric prefixes control sort order.

Configuring the Top-Level Menu

Map menu codes to display titles in your docToolchainConfig.groovy:

menu = [code1: 'Some Title 1', code2: 'Other Title 2', code3: '-']

Use '-' to hide a menu entry. When no mapping is defined, the code itself is used as the title. The order in the map determines the display order.

Links

In the right column, links are controlled by values in docToolchainConfig.groovy:

  • "Improve this doc": shown when gitRepoUrl is set.

  • "Create an issue": shown when issueUrl is set.

Templates and Style

The bundled templates use Bootstrap 5 as their CSS framework. Templates and styles are bundled with docToolchain.

Branding (Fonts, Colors, Logo)

You can re-brand the microsite without copying the whole theme. Set any of these keys in the microsite block of docToolchainConfig.groovy. Every value is optional — leave it empty to keep the theme default.

microsite.with {
    // your logo, relative to the site's asset root (assets/images)
    logo = 'images/my-logo.png'

    // colors — any CSS color value
    colorPrimary     = '#1f8a5b'   // accent / brand color
    colorPrimaryDark = '#155138'   // darker shade used in gradients
    colorLink        = '#176c49'   // body link color
    colorInk         = '#17181c'   // main text color
    colorBackground  = '#f4f3ee'   // page background
    colorCard        = '#fbfaf6'   // card / panel background

    // fonts — a CSS font-family value
    fontHeading = "'Roboto', sans-serif"
    fontBody    = "'Open Sans', sans-serif"
    fontMono    = "'JetBrains Mono', monospace"
    // optional: load custom web fonts (e.g. a Google Fonts stylesheet)
    fontCssUrl  = 'https://fonts.googleapis.com/css2?family=Roboto&family=Open+Sans&display=swap'
}

The colors override the theme’s CSS custom properties and apply to both the pages and the landing page. For deeper changes, copy the full theme with copyThemes jBakeTheme and edit the CSS directly.

Landing Page

The microsite needs a landing page as its start page. Run copyLandingPage to scaffold an editable copy into your project, then configure it in docToolchainConfig.groovy:

microsite.with {
    landingPage = 'landingpage.gsp'   // file in your theme's doc/ folder
}

The landing page is plain HTML5 styled with Bootstrap — the header and footer are added automatically. If microsite.landingPage is not set, the site is generated without an index.html landing page.

Note
 index.gsp in src/site/templates is the internal master template, not your landing page. Put your landing-page content in src/site/doc/<landingPage> instead.

Blog

The microsite includes a blog. Create posts in src/docs/blog/<year>/<post-name>.adoc:

blog post template
:jbake-title: My Post Title
:jbake-date: 2025-01-15
:jbake-type: post
:jbake-tags: blog, asciidoc
:jbake-status: published

= {jbake-title}
{jbake-date}

Your content here.

Search

The microsite includes a search input field that can be linked to an external search engine.

CI/CD

Set DTC_HEADLESS=true in automated builds to skip interactive prompts (e.g., theme installation).

Source

View the source of this task: scripts/generateSite.groovy on GitHub