[Jekyll Plugin] Links with .md extension instead of .html

[rachelcarmena]

Describe the bug

We're using Dokka 0.10.0 and outputFormat = 'jekyll' and the links are properly generated with .html extensions.

For instance:

[arrow-core](../index.html) / [arrow.typeclasses](./index.html)

However, dokkaJelyll task from Dokka 1.4.32 generates links with .md extensions.

For instance, the corresponding text for the same example as before:

//[arrow-core](../../index.md)/[arrow.typeclasses](index.md)

Expected behaviour

We'd expect the same behavior as before with Dokka 0.10.0:

[arrow-core](../index.html) / [arrow.typeclasses](./index.html)

to be able to browse the generated content.

To Reproduce

Repository: https://github.com/arrow-kt/arrow

Steps:

1. Generate the documentation with Dokka 0.10.0
2. Generate the documentation with Dokka 1.4.32
3. Compare both results

To Reproduce: Step 1 - Generate the documentation with Dokka 0.10.0

cd arrow-libs
./gradlew dokka

To Reproduce: Step 2 - Generate the documentation with Dokka 1.4.32

1. Remove dokka configuration in arrow-libs/gradle/apidoc-creation.gradle
2. Update arrow-libs/gradle.properties:

-DOKKA_VERSION=0.10.0
+DOKKA_VERSION=1.4.32

3. Run dokkaJekyll:

cd arrow-libs
./gradlew dokkaJekyll

To Reproduce: Step 3 - Compare both results

For instance, compare:

./arrow-site/docs/apidocs/arrow-core/arrow.typeclasses/index.md  --- Dokka 0.10.0
./arrow-libs/core/arrow-core/build/dokka/jekyll/arrow-core/arrow.typeclasses/index.md --- Dokka 1.4.32

Dokka configuration

Using the default options at the beginning.

Installation

• Operating system: macOS/Linux
• Build tool: Gradle v6.6.1
• Dokka version: 1.4.32

Additional context

We're trying to move from Dokka 0.10.0 to Dokka 1.4.32

Are you willing to provide a PR?

I'm willing to contribute if some guideline is provided. I just found the way to fix this thing #1968 so far.

[MarcinAman]

Why is having .md files a problem? According to the documentation it is supported: https://jekyllrb.com/docs/pages/

If you would like to have html as an output format i highly recommend checking out our default format (dokkaHtml)

[rachelcarmena]

Hi @MarcinAman thanks for your reply!

Why is having .md files a problem?

The issue isn't related with .md files but the links that appear inside the .md files.

Those links are properly generated with Dokka 0.10.0 inside the .md files like this file content:

[arrow-core](../index.html) / [arrow.typeclasses](./index.html)

However, they are really different with Dokka 1.4.32. The same case as before shows this file content:

//[arrow-core](../../index.md)/[arrow.typeclasses](index.md)

Jekyll build doesn't fix those links. After processing the Dokka output with Jelyll, they will be a HTML element a with a link in the href that points to .md file. So it won't be possible to navigate through the documentation because those referenced .md files are transformed to .html files by the Jekyll build process.

If you would like to have html as an output format i highly recommend checking out our default format (dokkaHtml)

Right, I know it and tried it. That format works like a charm ✨ . However, we would like to continue using Jekyll format to transform the pages with our own elements and styles.

Please, let me know if I explained myself now.

Thanks again for your help!

[rachelcarmena]

Hi @MarcinAman here again to provide .md files:

• index.md generated by Dokka 0.10.0 (task dokka and outputFormat = 'jekyll')
• index.md generated by Dokka 1.4.32 (task dokkaJekyll)

There are more issues with links there:

• Dokka 0.10.0 (task dokka and outputFormat = 'jekyll')

[Monoid](-monoid/index.html)

• Dokka 1.4.32 (task dokkaJekyll)

<a name="arrow.typeclasses/Monoid///PointingToDeclaration/"></a>[Monoid](-monoid/index.md)

Please, reach me out if more details are needed. And I'd very grateful if clues about this behavior are provided to be able to help with the fix.

Thanks!!

[adesentenac]

Dokka 1.4.32 doesn't seem to be ready to generate Jekyll documentation, maybe that should be indicated in the README. I'm also having the same issues which prevent upgrading to the latest dokka version.