preprocessor: link between a piece of content and an Issue

[jpluscplusm]

trafficstars

It'd be handy to have a way to record that a piece of content is affected by a specific Issue, inside the content itself.

This would be useful in a couple of ways:

1. to emit some text exposing the link to the reader, along with the Issue's implications

   • we currently use hard-coded info-blocks, but we might decide to change that
     • IMHO the info block makes such links /too/ visible, as (again IMHO!) a callout to an Issue probably wants to sit more as a corner-case, requiring some kind of deaccented representation
     • but it probably still needs to sit at an author-decided position in the content, and not be (e.g.) a generic header on all such Issue-affected docs
   • we need to cope with arbitrary prose, explaining the Issue in the context of that piece of content
     • so this probably can't just be a preprocessor task that fetches the linked Issue's title/summary/etc, and injects that into the in-content representation as "sufficient" context

2. to flag content as being in need of review when the state of the linked issue changes.

Edit: here's a fake example, pulled from my recollection of an info block in the docs that I can't locate right now:

{{< info >}}
Be aware that this method doesn't work with integers because of
[Issue 123456](link to cue-lang/cue issue).
If you're working with ints, use the other method on this page.

Once the Issue is resolved both methods will work across all primitive
types and this warning will be removed as it'll be moot.
{{< /info >}}

It would also be useful to be able to mark a page as being suitable for review after an issue changes state, but in a way which doesn't rely on the issue being exposed to the reader via an info box or equivalent (E.g. front matter metadata).

I mention this in this issue as it feels like it'd share a lot of the logic with the above use case, even if they're not identical.

[myitcv]

@jpluscplusm - is this covered off by https://alpha.cuelang.org/examples/shortcodes/issue/?

[jpluscplusm]

Arguably the first point I made is now handled, but this pair of subsequent and related points aren't covered by the Hugo issue shortcode:

to flag content as being in need of review when the state of the linked issue changes.

It would also be useful to be able to mark a page as being suitable for review after an issue changes state, but in a way which doesn't rely on the issue being exposed to the reader via an info box or equivalent (E.g. front matter metadata).

I think handling these cases together would be useful.

We have some documentation pages which (inconsistently) capture a relatedIssues list in their front matter. It would be handy to be able to run the preprocessor in a review-related mode where it:

• aggregates the set of all related issues present in the page corpus
  • from either/both of the relatedIssues list and the uses of the on-page issue shortcode
• fetches each issue's status from GitHub
• lists those pages that are associated with an issue that's not open/etc