Frankly I find the doc super pretty and practical!...

# kobweb

[אליהו הדס]

Frankly I find the doc super pretty and practical! Bravo! It might even be worth making a framework like mkdocs, I think all kotlin devs will love it and it would democratize kobweb

[David Herman]

Thank you @אליהו הדס. I suppose the question would be what I could offer that mkdocs doesn't?

Also, not sure if people realize it, but although a Kobweb definitely takes a little bit of initial effort to set it up, the docs pages you are reading are all markdown:

https://github.com/varabyte/kobweb-site/tree/dev/site/src/jsMain/resources/markdown/docs

[David Herman]

(Here is a link to the first "What is Kobweb" article)

[okarm]

I'd really appreciate the content being wider. It is unreasonably narrow. Code snippets don't fit. Most of us have at least 2k monitors, most likely 4k monitors. Why waste the space?

[David Herman]

@okarm We can definitely play with it but it's tricky to write content that looks good on really wide monitors and mobile devices both. If you extend things too much, the formatting doesn't automatically look great -- your paragraphs become thin, one line snakes that are visually unpleasing.

Code running over width is definitely annoying, for sure, but in general I try to format our examples so that it fits within the given bounds. There are always going to be exceptions where doing that makes it look worse than just asking the user to scroll.

I have a 2k wide screen monitor and a 4k monitor BTW so this isn't just a case of me unaware of what's out there (which can often be the case!)

[David Herman]

Another option is we keep the width the same but reduce the font size a little.

[okarm]

Currently I count 71 columns for the monospace content. Seems a bit low.

[David Herman]

Here's a comparison between GitHub's README and our current site design

[David Herman]

You can see we're giving up some space to the sidebars here, and our text is a little bit bigger.

[okarm]

I genuinely wonder how many people consume a technical reference for a programming framework from a mobile device.

[David Herman]

I'm sure it's not an insignificant number

[אליהו הדס]

@David Herman

Thank you @אליהו הדס. I suppose the question would be what I could offer that mkdocs doesn't?

Indeed, while mkdocs excels at generating documentation, its functionality is primarily limited to that purpose. In contrast, by incorporating a dedicated module into Kobweb, we could significantly expand its capabilities: not only enabling the creation of documentation with the same ease as mkdocs but also facilitating the development of complete websites where documentation is seamlessly integrated. This approach would offer a more flexible and enriched experience, allowing for the combination of technical content with modern web design.

[David Herman]

@אליהו הדס Definitely worth thinking about! I won't be able to prioritize something like this for quite a while but I would be happy to support any effort whose design addresses real pain points. A short term solution might be to create a new template that people could instantiate to make it easy for people to create their own docs site from there -- for example, I think people would be happy for things to be set up so they can add new markdown docs pages and automatically get sidebars.

[אליהו הדס]

Yes I think a model would be perfect to start and see what it gives! Maybe you should hide a little all the somewhat complex configuration in libraries so as not to scare new users :)

[אליהו הדס]

Currently, most websites separate their documentation from the main site. Adopting an integrated approach would align with the Kotlin and Kotlin Multiplatform philosophy of delivering a seamless user experience.

[David Herman]

@okarm can you revisit the site? We pushed the width out a little bit.

[okarm]

@David Herman Thank you. A significant improvement in my opinion.

[David Herman]

@okarm Thanks for confirming, and for the feedback!

[David Herman]

If you find any pages that still look weird, feel free to ping here or DM me directly.