Hi, is anyone available to help me with the above? ^ :slightly_smiling_face:

# dokka

[shelbycohen]

Hi, is anyone available to help me with the above? ^ 🙂

[Kamil Doległo]

Hi there 👋 Sure thing, could for firstly check if your README contains a proper # Module [module-name] header?
I assume it does, if it worked before, then the followup question would be whether you can share your project with me or provide some MRE?

[shelbycohen]

@Kamil Doległo Hi! Thanks for the response. I just got it working and it does have # Module [module-name] header. The problem was that it couldn’t parse the markdown in the readme for some reason. Now it shows up by using includes.from(file("$rootDir/moduleName/README.md")) but it shows up 3 times in the generated index file. Any idea why thats happening?

[Kamil Doległo]

No idea TBH. We had an issue like that some time ago but it kind of fixed itself, so we don’t know what had been wrong and did not investigate it too much: https://github.com/Kotlin/dokka/issues/1323
Could you check some newer version of dokka (preferably one of our dev builds)?

[shelbycohen]

yes which version should I try? 0.11.0-dev-59 ?

[shelbycohen]

also can you have multiple markdown files and use includes like this:

includes.from(files("$rootDir/moduleName/README.md", "$rootDir/moduleName/usage.md")) ? What is the expected behavior when doing this?

[Kamil Doległo]

The repo is located here: maven("<https://maven.pkg.jetbrains.space/kotlin/p/dokka/dev>") with the latest version being 1.4.20-dev-0

[shelbycohen]

Okay great I’ll try that

[Kamil Doległo]

also can you have multiple markdown files and use includes

Yes, I believe each file will be parsed and appended to the relevant modules/packages

[shelbycohen]

If I have multiple markdown files should I have # Module module-name at the top of all of them that are in the same module?

[Kamil Doległo]

Nope, the #Module module-name header just marks the start of documentation for that specific module, if you have several of those markers, then all subsequent lines (until the next header, eg. for package or EOF) will be appended to the module-name module

[shelbycohen]

Got it, thank you for the help!

Okay I just tried with 1.4.20-dev-0 and I am having the same issue with markdown file showing up 3 times in index.md

[shelbycohen]

Also when I have a second markdown file it doesn’t append it like you said. It gives an error saying Unexpected classifier # when I start the doc with a header such as # Usage

[Kamil Doległo]

That’s not good, could you create an MRE for the issue?

I probably misunderstood your question. You have to repeat the # Module module-name header if you have the documentation for the module itself split into several files.
You shouldn’t repeat this header if you have documentation for module’s packages in a several files

[shelbycohen]

Okay got it. Sorry what is MRE?

[Kamil Doległo]

Minimal reproducible example if you can’t share your project. Unfortunately I can’t reproduce the issue myself 😞

[shelbycohen]

Okay yes I’ll do that! Thank you!

[Kamil Doległo]

Great, thank you as well! ☺️

[Andrzej Ratajczak [VL]]

Currently, adding documentation for 2 or more descriptions for module/package will favor first one that gets parsed. It can be fixed easily, but I'd postpone that a little before some greater changes to avoid merging conflicts.

Anyway, I think it's a bad idea to distribute description for single element across different markdown files, because you cannot be sure what order they will keep (ordering of paths is not enough guarantee). Moreover, it would be hard to maintain all files, becuase you'd have to keep in mind that one description is parted in 2 or more files.

The bug with 3 copies of description is very werid. Is this multiplatform (at least multiple sourceSets) project?

[Andrzej Ratajczak [VL]]

Here is PR fixing that. You can subscribe to it to get notification when it will be merged. Note that this is, as I said, unpredictable in what order these descriptions will be appended, so I highly unrecommend doing that

https://github.com/Kotlin/dokka/pull/1480

[shelbycohen]

@Andrzej Ratajczak [VL] Thank you for the info. I can use one markdown to include but I just want an easy way to jump to certain sections and was experimenting with splitting into different markdown files to see how that would look. Any other suggestions if I want to customize how the home page looks?

[Andrzej Ratajczak [VL]]

There are/will be some ways to add for example custom styles or assets, however I don't know how exactly you want to customize home page, so I cannot help much in that matter.

Of course you can make your own plugin, that will extend HtmlRenderer , so you have full control on certain sections/assests/styles etc.