search

Kotlin / dokka

API documentation engine for Kotlin
https://kotl.in/dokka
Apache License 2.0
3.45k stars 411 forks source link

OGP Support for `dokkaHtml` #3761

Open gmitch215 opened 3 months ago

gmitch215 commented 3 months ago

Is your feature request related to a problem? Please describe I love Dokka's style, and I think it could easily implement the Open Graph Protocol for better use in social media sites.

Describe the solution you'd like Add some <meta> tags that implement OGP.

Describe alternatives you've considered No current alternatives exist within Dokka

Additional context If you are unfamiliar with that the Open Graph Protocol is, it allows sites to be embedded on various social media websites, which can be useful for sharing dokka-related documentation.

adam-enko commented 3 months ago

Hi, thanks for the request.

I'm not familiar with Open Graph Protocol, but from looking at the page you linked it seems like it requires simply adding <meta> tags to the <head> of the HTML page.

It is possible to modify Dokka's default HTML template to add these tags. See the docs here: https://kotlinlang.org/docs/dokka-html.html#templates. The base template is here.

So that I understand it better, could you provide an example of the meta tags that should be added to a Dokka site? Are there any other code sites (e.g. Javadoc, Doxygen) that also add the OGP tags? This would help understand better whether Dokka should always add some tags, or the tags should be dynamic per page, or constant for a single project.

gmitch215 commented 3 months ago

As a basic example, this is what I think should happen across all pages:

<head>
  <meta property="og:title" content="[value of 'title' tag]" />
  <meta property="og:description" content="[page description]" />
  <meta property="og:type" content="website" />
  <meta property="og:url" content="[the current URL]" />
  <meta property="og:image" content="[the icon set in the dokka documentation]" />

Some JavaDoc providers and Doxygen plugins do this as well, or use alternative tags like <meta name="description">.

[page description] can be either:

This one isn't necessarily related to OGP, but serve the same purpose of embedding onto social media websites:

    <meta name="theme-color" content="#bc1be6"> <!-- the purple from the kotlin logo -->
gmitch215 commented 1 month ago

Hello, any progress on this issue?

adam-enko commented 1 month ago

Hi, no, there's no update.

I know the kotlin-wrappers added some OGP tags to the Dokka template, so you could use that as inspiration for your own projects. However, the tags aren't dynamic.

Possibly OGP tags could be added dynamically by implementing a custom Dokka plugin. There's a guide on how to implement a custom Dokka plugin here.