docs(lighthouse,postcard,signpost): compile README Go examples via src= (quick-261118-qsd)

This commit is contained in:
Jakub Zych
2026-11-18 20:13:14 +01:00
parent a2551d83d7
commit 1e56d750ef
7 changed files with 482 additions and 150 deletions

View File

@@ -32,57 +32,60 @@ Use cases:
A content plugin registers its types:
```go
package blog
import (
"context"
"strings"
"git.golem15.com/golem15/summercms/modules/pact"
)
var _ pact.HasMenuItemTypes = (*Plugin)(nil)
type Plugin struct{}
func (p *Plugin) MenuItemTypes() []pact.MenuItemType {
```go src=modules/signpost/example_test.go#BlogPlugin.MenuItemTypes
// MenuItemTypes registers acme-post, which points at one post, and
// acme-all-posts, which lists every post. The list type names acme-post in
// PatternFrom, so a host override of the post URL reaches its items too.
func (p BlogPlugin) MenuItemTypes() []pact.MenuItemType {
return []pact.MenuItemType{{
Key: "acme-post",
Label: "acme.blog::lang.menuitem.post",
DefaultPattern: "/blog/:slug",
Placeholders: []string{":slug"},
References: func(ctx context.Context) ([]pact.MenuItemReference, error) {
return []pact.MenuItemReference{{Value: "hello-world", Label: "Hello world"}}, nil
},
Resolve: func(ctx context.Context, in pact.MenuItemResolve) (*pact.ResolvedMenuItem, error) {
url := strings.ReplaceAll(in.Pattern, ":slug", in.Reference)
return &pact.ResolvedMenuItem{
Title: "Hello world",
URL: url,
Alternates: []pact.MenuItemAlternate{{Locale: "en", URL: url, Title: "Hello world"}},
}, nil
},
References: p.postReferences,
Resolve: p.resolvePost,
}, {
Key: "acme-all-posts",
Label: "acme.blog::lang.menuitem.all_posts",
DefaultPattern: "/blog/:slug",
PatternFrom: "acme-post",
Nesting: true,
Resolve: resolveAllPosts,
DynamicItems: true,
Resolve: p.resolveAllPosts,
}}
}
```
A menu plugin resolves an entry and serves the reference dropdown of its form:
```go
```go src=modules/signpost/example_test.go#ExampleRegistry_Resolve
app := exampleApp()
blog := BlogPlugin{posts: []BlogPost{{Slug: "hello", Title: "Hello"}, {Slug: "again", Title: "Again"}}}
if err := signpost.Activate(app, []BlogPlugin{blog}); err != nil {
fmt.Println(err)
return
}
reg, _ := app.Lookup[*signpost.Registry]()
item, err := reg.Resolve(ctx, entry.Type, entry.Reference, entry.URLPattern, true, "")
item, err := reg.Resolve(context.Background(), "acme-all-posts", "", "", true, "")
if err != nil {
fmt.Println(err)
return
}
for _, child := range item.Items {
fmt.Println(child.Title, child.URL)
}
// Output:
// Hello /news/hello
// Again /news/again
```
func (c entriesController) DependentOptions(ctx context.Context, field string, values map[string]any) (pact.DependentOptionSet, error) {
```go src=modules/signpost/example_test.go#EntriesController.DependentOptions
// DependentOptions serves the reference dropdown: the references of the
// menu item type chosen in the type field, with their depth.
func (c EntriesController) DependentOptions(ctx context.Context, field string, values map[string]any) (pact.DependentOptionSet, error) {
typ, _ := values["type"].(string)
return signpost.ReferenceOptions(ctx, c.registry(), typ)
reg, _ := c.app.Lookup[*signpost.Registry]()
return signpost.ReferenceOptions(ctx, reg, typ)
}
```
@@ -90,38 +93,64 @@ func (c entriesController) DependentOptions(ctx context.Context, field string, v
A record type adds a `pact.ContentDescriptor`: the admin controller that edits the records, their morph type, and a `Describe` that answers each locale's URL (built from the pattern it receives, as `Resolve` builds alternates), title, description, image and word count:
```go
{
Key: "acme-post",
DefaultPattern: "/blog/:slug",
Resolve: resolvePost,
Content: &pact.ContentDescriptor{
Controller: "acme.blog.posts",
Model: "acme_blog_posts",
Describe: func(ctx context.Context, in pact.ContentDescribe) (*pact.ContentRecord, error) {
post, err := loadPost(ctx, in.ID)
if err != nil || post == nil {
return nil, err
}
return &pact.ContentRecord{
ID: in.ID,
Published: post.Published,
Locales: []pact.ContentLocale{{
Locale: "en",
URL: strings.ReplaceAll(in.Pattern, ":slug", post.Slug),
Title: post.Title,
}},
}, nil
```go src=modules/signpost/example_content_test.go#NewsPlugin.MenuItemTypes
// MenuItemTypes registers acme-article with a content descriptor: the
// controller that edits articles, their morph type, what kind of record an
// article is, the MCP tool that edits one, Describe and Match.
func (p NewsPlugin) MenuItemTypes() []pact.MenuItemType {
return []pact.MenuItemType{{
Key: "acme-article",
Label: "acme.news::lang.menuitem.article",
DefaultPattern: "/news/:slug",
Placeholders: []string{":slug", ":id"},
Resolve: p.resolve,
Content: &pact.ContentDescriptor{
Controller: "acme.news.articles",
Model: "acme_news_articles",
Kind: pact.ContentKindArticle,
Tools: map[string]string{pact.ContentToolEdit: "acme_update_article"},
Describe: p.describe,
Match: p.match,
},
},
}}
}
```
The descriptor may also say what kind of record the type holds and which MCP tool edits one (`Kind: pact.ContentKindArticle`, `Tools: map[string]string{pact.ContentToolEdit: "acme_update_post"}`), and `Describe` may report the record's `PublishedAt`, `Parents`, `Authors` and `TopHeading`, and per locale its `Images`, `Videos` and `Headings` (see [Content descriptors](../../docs/plugins/menu-item-types.md#content-descriptors)). Every one of them is optional.
```go src=modules/signpost/example_content_test.go#NewsPlugin.describe
// describe answers one article per locale; the URL is built from the
// layered pattern it receives. Besides the page defaults it reports the
// first publication, the author and the body's heading outline, whose
// headings start at level 2 because the page renders the title as the level-1
// heading.
func (p NewsPlugin) describe(_ context.Context, in pact.ContentDescribe) (*pact.ContentRecord, error) {
for _, a := range p.articles {
if a.ID != in.ID {
continue
}
url := strings.NewReplacer(":slug", a.Slug, ":id", a.ID).Replace(in.Pattern)
headings := []pact.ContentHeading{}
for _, h := range a.Headings {
headings = append(headings, pact.ContentHeading{Level: 2, Text: h})
}
published := a.PublishedAt
return &pact.ContentRecord{
ID: a.ID,
Published: a.Published,
PublishedAt: &published,
Authors: []pact.ContentPerson{{Name: a.Author}},
TopHeading: 2,
Locales: []pact.ContentLocale{{Locale: "en", URL: url, Title: a.Title, Headings: headings}},
}, nil
}
return nil, nil
}
```
The descriptor may also say what kind of record the type holds and which MCP tool edits one (`Kind` and `Tools` above), match a public path back to a record (`Match`), and `Describe` may report the record's `PublishedAt`, `Parents`, `Authors` and `TopHeading`, and per locale its `Images`, `Videos` and `Headings` (see [Content descriptors](../../docs/plugins/menu-item-types.md#content-descriptors)). Every one of them is optional.
A consumer maps a record event to its type and reads the record's new URL:
```go
```go src=modules/signpost/example_content_test.go#listen
app.Events.Listen("acme.audit", func(ctx context.Context, ev *pact.RecordSaved) error {
reg, _ := app.Lookup[*signpost.Registry]()
typ, ok := reg.ContentTypeForModel(ev.Model)
@@ -132,7 +161,7 @@ app.Events.Listen("acme.audit", func(ctx context.Context, ev *pact.RecordSaved)
if err != nil || rec == nil {
return err
}
log.Printf("%s now lives at %s", ev.ID, rec.Locales[0].URL)
logger.Printf("%s now lives at %s", ev.ID, rec.Locales[0].URL)
return nil
})
```