Markdown default theming

[charlee-dev]

Hi. I markdown support in Kobweb is already great! I may introduce it to my team soon, so we can use it to build great-looking and easy-to-update internal documentation.

As a site creator, I want to be able to create a theme that is applied automatically to every markdown file. So when other team members create their documentation markdown page, they don't need to apply the theme manually.

[bitspittle]

Thanks so much for the report! This has been fixed and will go out in 0.10.6 and after.

A 0.10.6-SNAPSHOT version has been published if you'd like to verify for yourself early that this is working.

Normally, it's probably still best practice to set the YAML root field. Still, moving forward, if you don't specify a root at all, a better default will occur, which looks something like this:

Column {
   ... markdown content ...
 }

You can control the fallback root used (above, Column) by changing the kobwebx.markdown.defaultRoot property. Like so:

kobwebx {
   markdown {
      defaultRoot.set("com.charlee.components.layouts.MarkdownLayout")
   }
}

Note: kobwebx.markdown will move to kobweb.markdown in 0.11.0, sorry for the future compile error. This will hopefully be relatively soon.

Another option: You can also tag a composable with @App to make it the global root (and honestly it's totally embarrassing I haven't documented this in the README yet! But code looks like this.)

So, you can change your @App definition to use a Column, like

@App
@Composable
fun MyApp(content: @Composable () -> Unit) {
   SilkApp {
      Surface {
         Column {
            content()
         }
      }
   }
}

If you do that, then you can just clear the markdown.defaultRoot property (since you don't need it anymore) by setting it to the empty string: kobwebx.markdown.defaultRoot.set("")

You should only override the @App like this if you are certain that all your pages will be simple markdown pages forever in the future (but note that if that decision ever changes, it will be really annoying to fix it!)

In summary

Recommendations in priority order

1. Set your root in every markdown file
2. Change the markdown.defaultRoot property if you want to point it to something besides a column (e.g. a layout you defined in your code)
3. Do nothing and your output will be wrapped in a Column. This looks better than before but there won't be any padding so it doesn't look amazing.
4. Create an @App composable which is markdown friendly.