search

Kotlin / api-guidelines

Best practices to consider when writing an API for your library
https://kotl.in/api-guide
Apache License 2.0
145 stars 20 forks source link

Fixing image src paths for markdown files in topics #2

Closed mjovanc closed 1 year ago

IgnatBeresnev commented 1 year ago

Hi! Thanks for taking the time to address it.

Unfortunately, it's not obvious, but it's not a bug, it's actually a feature :)

I've added some more details to our CONTRIBUTING.md document.

Quoting it:

Our documentation is written in Markdown format with some domain specific language (DSL) constructs that are used at JetBrains.

Unfortunately, this means that the document might not be rendered correctly or as expected when viewing it on GitHub or locally, as some tags and constructs work differently or are very specific.

For example, you might see this and think it to be a bug, because, normally, the <img> tag expects the src attribute to have a relative link to the image file:

<img src="debug-person-builder.png"/>

However, in our case, it's not a bug, but a feature - it's enough to specify the file name only, and our documentation engine will link it correctly with the actual image file correctly.

You can find this and other formatting rules in the Kotlin documentation guidelines document.

So I'm closing the issue as nothing needs to be done about this, but thank you for caring!