Possibility of using custom templates

[thatlittleboy]

Is there a possibility of using custom Jinja templates when rendering the digest? Right now, it is always using the template bundled in with the project (digest.html.j2).
Preferably the ability to customize different templates for different digests within the same dinghy.yaml.

I imagine an API like

  - digest: digests/nvim-1day.html
    title: Nvim-related news
    since: 1 day
    template: templates/my-nvim-tpl.html.j2  # <--------------
    items:
      - https://github.com/nvim-treesitter/nvim-treesitter/
      - https://github.com/nvim-tree/nvim-tree.lua

[nedbat]

Interesting idea. I'd have to look carefully at the data provided to the template, since that would be a public supported API if people can write their own templates...

[nedbat]

Right now, the data passed to Jinja is an ad-hoc mixture of the JSON returned by GitHub, with some extra information thrown in, and re-organized into the hierarchy to display.

Define DINGHY_SAVE_RESULT=1 in your environment, and run dinghy. It will write .json files alongside the .html files. You can get a sense of the data, and we can talk about approaches.

[nedbat]

I've just made a change on main to prefix all of the dinghy keys in the data to make it easier to distinguish between the data direct from GraphQL and the data computed or rearranged by dinghy: f9feac9.

[nedbat]

There's also the matter of the reverse-engineered --label-r (etc) CSS attributes:

<span class="label" style="--label-r:0;--label-g:82;--label-b:204;--label-h:215;--label-s:100;--label-l:40;">T: design</span>

These are computed by a Python-provided function in the Jinja template, and rely on CSS copied from GitHub:

  .label {
    padding: .2em .5em .1em .5em;
    border-radius: 2em;
    font-size: 75%;
    opacity: .85;
    vertical-align: middle;
    white-space: nowrap;
    /* GitHub label style computations, lifted from github.com */
    border: 1px solid transparent;
    --perceived-lightness: calc( ((var(--label-r) * 0.2126) + (var(--label-g) * 0.7152) + (var(--label-b) * 0.0722)) / 255 );
    --lightness-switch: max(0, min(calc((var(--perceived-lightness) - var(--lightness-threshold)) * -1000), 1));
    --lightness-threshold: 0.453;
    --border-threshold: 0.96;
    --border-alpha: max(0, min(calc((var(--perceived-lightness) - var(--border-threshold)) * 100), 1));
    background: rgb(var(--label-r), var(--label-g), var(--label-b));
    color: hsl(0, 0%, calc(var(--lightness-switch) * 100%));
    border-color: hsla(var(--label-h), calc(var(--label-s) * 1%), calc((var(--label-l) - 25) * 1%), var(--border-alpha));
  }

Would you copy all of that into a custom template, or should it be provided somehow by dinghy?

[nedbat]

@thatlittleboy Another way to approach this: what would you like to change about the template? How would your custom template differ from mine?

[thatlittleboy]

Thanks @nedbat , let me take some time to digest this information and get back to you over the weekend. Before looking through all these, my initial thoughts / idea with a custom template was to:

• inject some of my own (simple!) css and boilerplate html (e.g. change section headings, preamble, things of that nature) to change the "look" of the digest.
• have greater flexibility over how the data is presented, e.g. using a different length for truncation, or changing how the data is sorted before presentation. E.g. if I wanted to sort by time desc instead of asc, or if I wanted to always show Releases first before Issues / PRs.
• which is also the reason why I also specifically asked for digest-specific template. I might want to present different digests differently.

Obviously, some of these "options" could be baked into dinghy itself as CLI args/dinghy config, but for maximum flexibility, I thought a custom template was the easiest to achieve these. Then dinghy is just more of a tool to collect the github activity into a structured list, then how this information is displayed can be controlled by templates --- either personalized using an entirely new user-provided template, or extended from a base template provided by dinghy.

---

So this was just what I wanted to achieve with custom templates, I'll see if I can form more thoughts on how to practically achieve this, after I take a closer look at what you've written above! <3

[thatlittleboy]

There's also the matter of the reverse-engineered --label-r (etc) CSS attributes:
...
Would you copy all of that into a custom template, or should it be provided somehow by dinghy?

For my personal use-case, I'm not intending to modify these in my templates. So ideally, it would be provided by dinghy. (But I'm also fine just copying it into my custom template if it comes down to that.)

As for how this option can be realized: it would probably entail refactoring the css styles out into its own file (suppose base.css) first and foremost, and allowing overwriting of the default styles where necessary:

<head>
...
<link rel="stylesheet" type="text/css" href="templates/css/base.css">
<link rel="stylesheet" type="text/css" href="templates/css/my-custom-css.css">
</head>
...

(To be clear: So your default-provided template would just have base.css, whereas my custom templates can inherit your base.css + add my own css file on top of that)

Do you think this could work?

[nedbat]

I haven't done anything yet to help with the CSS, but in commit b4e750a, you can specify a template setting to choose your own Jinja2 template. I haven't made a new release yet; let me know if you try it.

[thatlittleboy]

Yep, I just copied dinghy.html.j2 and made some simple adjustments to test-drive it, and works great, thanks! @nedbat

I tested two changes with the template thus far:

• changed background colour of entire html via css
• resorted the entries to always show Releases first, before the other kinds (Issues/PRs).

https://github.com/thatlittleboy/github-digest/pull/2/files

and result

https://thatlittleboy.github.io/github-digest/

---

The handling/inheritance of CSS can be more ergonomic (as discussed above), but I'm satisfied with this solution for now. 😄

[nedbat]

This is now released as part of dinghy 1.1.0.