[Dokka 2] Align heading 1 (<h1>) styles

[MGaetan89]

Is your feature request related to a problem? Please describe

When including a module documentation using the following:

dokkaSourceSets.getByName("main") {
    includes.from("Module.md")
}

Where Module.md contains something like:

# Module Content

Lorem ipsum

The title is rendered as:

<h1 class="cover"><span><span>Content</span></span></h1>

However, if I include a top-level documentation using:

tasks.withType<DokkaGenerateTask> {
    generator.includes.from("Module.md")
}

With the same content as before, the title is rendered as:

<h1 class="">Content</h1>

This results in a different layout between the two pages:

Top-level title	Module title

Describe the solution you'd like

Both titles have the same style.

Describe alternatives you've considered

For the moment, I can replace my top-level title with a HTML tag, instead of the Markdown # tag:

<h1 class="cover"><span><span>Content</span></span></h1>

[MGaetan89]

The same happens for a regular paragraph:

Top-level content	Module content

[whyoleg]

Hey, thanks for raising the issue!
First of all, I wanted to ask, why do you need to configure includes for DokkaGenerateTask separately and not via dokka DSL?
generator.includes works only for multi-module projects, and in this case you need to configure it, f.e like this in root project (to be fair in the project where you aggregate documentation):

dokka {
  dokkaPublications.html {
    includes.from("...")
  }
}

@adam-enko correct me if I wrong, as this is missing from migration guide

Anyway, it's a bit strange that the styles are different, have you experienced the same with behavior with Dokka 1.9.x?

[MGaetan89]

First of all, I wanted to ask, why do you need to configure includes for DokkaGenerateTask separately and not via dokka DSL?

I'm using generator.includes from my roor build.gradle.kts file. In each module build.gradle.kts file, I'm using dokkaPublications.html.includes.
I just tried to use the following, but includes() doesn't seem to be available. Maybe the API is missing?

dokka {
    pluginsConfiguration.html {
        includes("Module.md")
    }
}

It's accessible from dokka.dokkaSourceSets.incldues, but the root module does not have any source set.

Anyway, it's a bit strange that the styles are different, have you experienced the same with behavior with Dokka 1.9.x?

We didn't deploy any HTML documentation when we were using Dokka 1.9.20. We decided to set this up with Dokka 2 directly.

[whyoleg]

I just tried to use the following, but includes() doesn't seem to be available. Maybe the API is missing?

My bad, the correct way for the root module is to use the same syntax as in source sets: includes.from("Module.md"). I will fix previous comment.

We didn't deploy any HTML documentation when we were using Dokka 1.9.20

got it, thanks, looks like this is not something that changed in Dokka 2.0, but just a minor styles differences, because those pages are just different (module page vs all-modules page)

[MGaetan89]

My bad, the correct way for the root module is to use the same syntax as in source sets: includes.from("Module.md"). I will fix previous comment.

That doesn't seem to exist either: https://github.com/Kotlin/dokka/blob/master/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/plugins/DokkaHtmlPluginParameters.kt

[whyoleg]

oh, missed that in your comment, you need to use dokkaPublications.html (as written in my example) and not pluginsConfiguration.html

[MGaetan89]

My bad 😅
I switched to dokkaPublications.html and it works too.

The style are still different though

[adam-enko]

I agree that the behaviour is confusing.

The options used to configure Dokka Generator has two includes fields, and I'm not sure why or what the difference is.

• The top-level DokkaConfiguration
  https://github.com/Kotlin/dokka/blob/v2.0.0-Beta/dokka-subprojects/core/src/main/kotlin/org/jetbrains/dokka/configuration.kt#L144

• For each DokkaSourceSet
  https://github.com/Kotlin/dokka/blob/v2.0.0-Beta/dokka-subprojects/core/src/main/kotlin/org/jetbrains/dokka/configuration.kt#L190

(DokkaModuleDescription also has an 'includes' field, but that's the root directory of each partial Dokka Module to be aggregated into a Publication https://github.com/Kotlin/dokka/blob/v2.0.0-Beta/dokka-subprojects/core/src/main/kotlin/org/jetbrains/dokka/configuration.kt#L251, and isn't relevant here.)

DGP provides a way of configuring includes both at the top-level (e.g. dokkaPublications.html { includes(...) } and per source set.