golem15/sm-journal-plugin
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: opt-in scored related posts and category neighbours

Browse Source 
- golem15.journal.related_mode (category | scored, default category) and
  golem15.journal.related_count (3 to 6, default 3, clamped) in
  config/config.yaml; classes.ReadRelatedSettings reads them
- the default mode answers GET /posts/{slug} exactly as before
- scored: related posts ranked by 2 points per shared tag plus 1 per
  shared category, ties by newest, in one scoring query
  (classes.ScoredRelatedPosts), published only for visitors; the answer
  adds previous_in_category and next_in_category, the neighbours by
  publish time within the post's first category by name
  (classes.CategoryNeighbour), in the direction of previous_post and
  next_post
- TestRelatedDefaultUnchanged, TestRelatedScored (a draft and a future
  post sharing every tag never shown) and TestRelatedScoredCountClamped
This commit is contained in:
Jakub Zych
2026-11-04 14:14:09 +01:00
parent 0edf6e1b67
commit ee3cb263dc
5 changed files with 461 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
README.md
View File

@@ -185,6 +185,15 @@ Journal decides per site whether its rich text may hold an H1 (2026-10-28, D-50)
- **Settings API.** `GET` and `PUT /_journal/api/v1/settings` read and write every settings column for `golem15.journal.manage_settings` (`403` without it); `PUT` checks the submitted columns against `models.Settings.Rules` and ignores other keys.
- **Image alt.** `POST /_journal/api/v1/images/alt` `{dry_run, changes: [{post_id, locale, src, alt}]}` sets the alt of the image whose `src` equals `src` in the post's `content_html` (and in `content` when that holds the same image), in the default locale or in `locale`; `alt: ""` marks it decorative. It needs `golem15.journal.access_posts` and edit rights on each post, refuses the whole batch with `422` when one image is not in its post, answers `{changes: [{post_id, locale, src, old_alt, alt, changed}], dry_run}` and fires a `RecordSaved` per changed post. Alt text is post content, so the bulk alt tool is Journal's (`journal_set_image_alt`), not the SEO plugin's.
### Related posts
`GET /_journal/api/v1/posts/{slug}` answers `related_posts` with the post's related posts and `previous_post` and `next_post` with its site-wide neighbours by publish time. The ranking is opt-in (D-82; `classes.ReadRelatedSettings`):
- **`golem15.journal.related_mode: category`** (the default): as before, up to three posts sharing a category with the post, newest first; none for a post without a category. The answer is unchanged.
- **`scored`**: posts sharing a tag or a category, ranked by 2 points per shared tag plus 1 point per shared category, ties by the newest publish time, `golem15.journal.related_count` of them (3 to 6, clamped; 3 when unset). A post that shares nothing is never related. One query computes the scores (`classes.ScoredRelatedPosts`). The answer adds `previous_in_category` and `next_in_category` (`{id, title, slug}` or `null`): the neighbours by publish time within the post's first category by name (`classes.PrimaryCategoryID`, `classes.CategoryNeighbour`), in the direction of `previous_post` and `next_post` (previous is the nearest post published after it, next the nearest one published before it).
Visitors only ever see published posts with a past publish time; an editor who may see drafts also gets drafts among the scored related posts, as the default mode does. The neighbours are published posts only.
### Personal API tokens
The plugin registers two scopes through `journal.Plugin.TokenScopes` (`pact.HasTokenScopes`):
@@ -377,6 +386,13 @@ The request is a `POST` to the URL with `Authorization: Bearer <token>`, `Conten
|-----|----------------------|-------|
| `golem15.journal.content_h1_to_h2` | `SUMMER_GOLEM15__JOURNAL__CONTENT_H1_TO_H2` | The H1 setting used only when the Journal settings row does not exist, default `true` (`config/config.yaml`). The row's `content_h1_to_h2` (Settings › Journal, Headings and links) decides otherwise; `classes.EffectiveH1ToH2` is the one reader. |
### Related posts
| Key | Environment variable | Value |
|-----|----------------------|-------|
| `golem15.journal.related_mode` | `SUMMER_GOLEM15__JOURNAL__RELATED_MODE` | `category` (default, `config/config.yaml`): related posts as before. `scored`: ranked by shared tags and categories, plus `previous_in_category` and `next_in_category` on the post answer. See [related posts](#related-posts). |
| `golem15.journal.related_count` | `SUMMER_GOLEM15__JOURNAL__RELATED_COUNT` | The number of scored related posts, default `3`, clamped to 3 to 6. Read in `scored` mode only. |
### Author pages
| Key | Environment variable | Value |
@@ -396,7 +412,7 @@ The request is a `POST` to the URL with `Authorization: Bearer <token>`, `Conten
| `journal.Plugin` | Compiled plugin; `ID` is `golem15.journal`. |
| `journal.Plugin.Requires` | Returns `golem15.translate` only. |
| `journal.Plugin.LangFS` | Embedded English and Polish UI phrasebooks. |
| `journal.Plugin.ConfigFS` | Ships `config/config.yaml` (`golem15.journal.content_h1_to_h2`). |
| `journal.Plugin.ConfigFS` | Ships `config/config.yaml` (`golem15.journal.content_h1_to_h2`, `golem15.journal.related_mode`, `golem15.journal.related_count`). |
| `journal.Plugin.Migrations` | gormigrate steps registered by this plugin. |
| `journal.Plugin.Models` | Models registered by this plugin. |
| `journal.Plugin.Commands` | Registers `journal:export-posts`, `journal:import-posts`, `journal:reindex` and `journal:fix-headings`. |
@@ -431,6 +447,11 @@ The request is a `POST` to the URL with `Authorization: Bearer <token>`, `Conten
| `classes.EditorH1Converted`, `classes.EditorH1ConvertedCategory` | The phrase keys of the H1 conversion notice for a post and for a category. |
| `classes.H1ToH2Key` | `golem15.journal.content_h1_to_h2`, the config key of the H1 setting when no settings row exists. |
| `classes.EffectiveH1ToH2` | The one reader of the H1 setting: the settings row, else the config key, else true. |
| `classes.RelatedModeKey`, `classes.RelatedCountKey` | `golem15.journal.related_mode` and `golem15.journal.related_count`. |
| `classes.RelatedModeCategory`, `classes.RelatedModeScored`, `classes.RelatedCountDefault`, `classes.RelatedCountMin`, `classes.RelatedCountMax` | The related-posts modes and the count's default and bounds. |
| `classes.RelatedSettings`, `classes.ReadRelatedSettings` | The related-posts mode and count read from the config (`Scored` reports the scored mode). |
| `classes.ScoredRelatedPosts` | The scored mode's related posts: 2 points per shared tag plus 1 per shared category, ties by newest, at most the count, published only unless drafts are allowed. |
| `classes.PrimaryCategoryID`, `classes.CategoryNeighbour` | The post's first category by name, and its previous or next published post by publish time within that category. |
| `classes.GenericAnchors`, `classes.DefaultGenericAnchors` | The generic link texts: the settings row's list, one per line, lowercased, else the default English and Polish lists. |
| `classes.ConvertH1` | Turns every h1 of HTML into an h2 on the tokenizer, keeping every other byte; returns the converted count. |
| `classes.CountH1` | The number of h1 start tags `ConvertH1` would convert. |
@@ -508,6 +529,8 @@ Headings, links and media (Phase 33): `TestHeadingConversionTracer`, `TestHeadin
`TestJournalMCPSmoke` (root package, Docker-free) pins the eleven tools and the prompt (guard, permission, destructive delete, the prompt's arguments and text) and checks that each tool's method and path is a route the plugin registers; `TestOptionalBackendPrincipalDispatch` (`controllers/api`) checks that the list and show handlers see a dispatched backend principal and stay anonymous without one. `TestJournalPromptWrites` (root package, Docker-free) checks that `draft_post` declares `Writes` and, through a served pier endpoint, that a read-only grant's `prompts/list` omits `journal_draft_post` while a read and write grant lists it.
Related posts: `TestRelatedDefaultUnchanged` (the default and the explicit category mode answer as before, without the scored keys), `TestRelatedScored` (ranking, ties, a draft and a future post sharing every tag and category never shown, the category neighbours) and `TestRelatedScoredCountClamped` (`related_media_test.go`) run on Postgres.
`TestMenuItemTypesSmoke` (root package, Postgres) checks the five registered types and resolves each through the registry with host and item pattern overrides, ordered alternates, nesting, the published filter and the `x-default` rule.
The site cache purge has unit tests of the deprecated keys in `classes` (`TestSiteCachePurgeConfig`, `TestSiteCachePurgeRequest`; the request rules are tested in the framework's cooler) and Postgres tests through the admin API (`TestCategoriesAdminPurgesSiteCache`, `TestPostsAdminPurgesSiteCache` on the deprecated keys, `TestSiteCacheFrameworkKeysWin` with both sets) that point the plugin at a local receiver and check one authorized request after each commit.