search

typelevel / Laika

Site and E-book Generator and Customizable Text Markup Transformer for sbt, Scala and Scala.js
https://typelevel.org/Laika/
Apache License 2.0
406 stars 44 forks source link

Theme documentation needs attention #576

Open noelwelsh opened 5 months ago

noelwelsh commented 5 months ago

The current documentation for custom themes could do with a rework.

There are two main problems:

  1. The documentation doesn't give an overview of the process.
  2. The documentation is completely backwards

After about 3 hours working on creating my own theme I think I need to create a ThemeProvider that builds a theme using ThemeBuilder. ThemeBuilder is only mentioned at the very end of the documentation, yet this is the type I should start with. The first type documented is Theme, which as best I can tell I will never explicitly define. This is a common problem of explaining all the intricate pieces, which are naturally interesting to the developer who created them, but doesn't address the problems the user has.

Better documentation would start with an overview: to create a custom theme create a ThemeProvider that builds a theme using a ThemeBuilder. Then go on to explain how these types work.

"While Laika offers the full API as for user inputs for maximum flexibility and consistency, it is recommended to avoid any file system resources by using addFile or addDirectory."

I think this sentence is saying I should not using addFile or addDirectory, but as written is it ambiguous. I think it reads better as "While Laika offers the full API as for user inputs for maximum flexibility and consistency, it is recommended to avoid using addFile or addDirectory to add any file system resources."

jenshalm commented 5 months ago

Yes, I agree the structure is somewhat unfortunate. It was several years ago that I wrote this page, so I don't remember my motivation for doing it like this. I had to actually re-read it myself now before I could respond.

It seems to be that if the first section titled "The Theme Trait" is removed and instead replaced by a general overview of what type of functionality you usually assemble for a theme and what APIs you'll be using for this, then the other sections after that could probably remain unchanged.

I won't get to work on this before both 1.0.1 and 1.1.0 are out, so it'll take a bit, which is why I put it into Backlog for now.