Support custom theme

[piever]

I could not find in the docs whether it's possible to pass a custom CSS theme?

For example, I've noted that the size of card-cover in the grid theme is hard-coded here, which is a bit problematic when the thumbnail image is wide and short (leaving lots of vertical space empty). I was wondering if it would be possible to support loading some extra custom css where the user could override some of the theme's choices?

[johnnychen94]

This is also a pain to me because I don't have too much HTML/CSS/js web knowledge I can't think of a good solution here, and the template is coupled with the generation process.

Basically, DemoCards will pass some values to the Mustache.jl template. Currently, there are only four items passed:

• coverpath: path to cover image
• title: card title (usually short)
• description: one line description. Less than 500 characters.
• id: passed to Documenter's [title](@id <id>) to assist cross-references

To support a custom theme, two things are required:

1. prepare a set of mustache templates for sections and cards.
2. prepare some css files as assets
3. pass the mustach templates to makedemos via templates keywords.
4. pass your own css assets to Documenter.

For 1 and 2 you can maybe start from the results of cardtheme("grid") and find some idea.

custom_templates, custom_assets = gen_custom_theme()
gallery, postprocess_cb, _ = makedemos("gallery"; templates=custom_templates)
format = Documenter.HTML(assets = [custom_assets])

makedocs(...)
postprocess_cb()

You need to remove "theme" option from the top-level config.json. Currently, there will be a deprecation because I prefer to have all these declared in the config files but haven't figure out a clean solution. If you have more ideas, I think we can maybe solidify this usage and make it a part of API.

[johnnychen94]

I've noted that the size of card-cover in the grid theme is hard-coded here, which is a bit problematic when the thumbnail image is wide and short

I hard-coded it because it has the best visual look that I can tweak from my very limited web knowledge. If you know more about this, it's doable to pass more information to cardtheme and make it generate something different. For example:

{
    "theme":{
        "name" : "grid",
        "style":{
            "card-cover.height" : "200px"
        }
    }
}

Again, I didn't expose these because the current grid/list themes are quite experimental and I really hope there are someone who can contribute a wonderful gallery template :)

[piever]

Normally, when javascript packages offer some component with themability (like the card grid here) they do so via css classes. Basically, you would "promise stability" in terms of what class names are used in the grid theme (card-section, card-text, etcetera) and you would allow users to pass a css other than your style.css (see for example https://refreshless.com/nouislider/more/#section-styling).

I imagine a custom style to use instead of your style could be given via

{
    "theme":{
        "name" : "grid",
        "style": "path/to/custom/style.css"
    }
}

I think this is much easier than passing css settings via json. Once users fine tune this, it's also straightforward to contribute that css file to this repo.

Another option would be to use a premade component. For example, Documenter uses Bulma.io as css stylesheet, so it should already be available in the built document. You can just replace your custom card component with the card component from Bulma (see here). This may actually be the best way forward, so whatever customization is applied to Documenter (such as the dark theme) automatically applies to the demo cards. I imagine all you have to do for that is to replace your custom html for the card with the Bulma template linked above.