From 3ba6f1d432d2ad8c81975ddede03c9d1bc7544bf Mon Sep 17 00:00:00 2001 From: Jason Ernst Date: Sun, 20 Sep 2026 16:59:41 -0700 Subject: [PATCH 1/3] Revert the move of the docs out of the binary (#591 rev 2) The per-release content sync into goblog-plugin-docs was judged a non-starter; the docs are a compiled-in plugin, off by default, like the directory. This restores plugins/docs as merged at 076ad07. Co-Authored-By: Claude Opus 5 (1M context) --- README.md | 3 +- docs/PLUGIN_CONTRACT.md | 2 +- docs/THEME_CONTRACT.md | 2 +- docs/guide/doc.go | 30 -- docs/guide/guide_test.go | 344 ------------------ .../plans/2026-09-20-docs-plugin-rev2.md | 6 +- .../plans/2026-09-20-docs-plugin.md | 2 - .../specs/2026-09-20-docs-plugin-design.md | 35 -- go.mod | 1 + go.sum | 2 + goblog.go | 2 + .../docs/content}/directory-formats.md | 0 .../docs/content}/overview.md | 0 .../docs/content}/plugin-api.md | 2 +- .../docs/content}/publishing-a-plugin.md | 0 .../docs/content}/publishing-a-theme.md | 0 .../docs/content}/writing-a-plugin.md | 0 .../docs/content}/writing-a-theme.md | 0 plugins/docs/content_test.go | 176 +++++++++ plugins/docs/docs.go | 174 +++++++++ plugins/docs/docs_test.go | 183 ++++++++++ plugins/docs/pages.go | 18 + plugins/docs/render.go | 76 ++++ plugins/docs/render_test.go | 36 ++ plugins/docs/templates/page.html | 25 ++ 25 files changed, 701 insertions(+), 418 deletions(-) delete mode 100644 docs/guide/doc.go delete mode 100644 docs/guide/guide_test.go rename {docs/guide => plugins/docs/content}/directory-formats.md (100%) rename {docs/guide => plugins/docs/content}/overview.md (100%) rename {docs/guide => plugins/docs/content}/plugin-api.md (99%) rename {docs/guide => plugins/docs/content}/publishing-a-plugin.md (100%) rename {docs/guide => plugins/docs/content}/publishing-a-theme.md (100%) rename {docs/guide => plugins/docs/content}/writing-a-plugin.md (100%) rename {docs/guide => plugins/docs/content}/writing-a-theme.md (100%) create mode 100644 plugins/docs/content_test.go create mode 100644 plugins/docs/docs.go create mode 100644 plugins/docs/docs_test.go create mode 100644 plugins/docs/pages.go create mode 100644 plugins/docs/render.go create mode 100644 plugins/docs/render_test.go create mode 100644 plugins/docs/templates/page.html diff --git a/README.md b/README.md index d68f4813..e469cda3 100644 --- a/README.md +++ b/README.md @@ -45,6 +45,7 @@ A self-hosted blogging platform built with Go. Running at https://www.jasonernst - Dynamic plugins: drop a `.go` file in `plugins/dynamic/` — no rebuild (see [Plugins](#plugins)) - WebAssembly plugins (sandboxed, any language/dependencies) installable from the directory - Install plugins from the [directory](https://www.goblog.live/plugins) with one click under **Admin → Plugins** +- Built-in documentation plugin (`docs`): the plugin/theme builder docs served at `/docs`; what goblog.live/docs runs ### Infrastructure - SQLite (file-based, zero config), MySQL, or PostgreSQL @@ -173,7 +174,7 @@ The plugin directory installs sandboxed WebAssembly modules built with [Extism]( Every export takes and returns JSON through Extism's input/output. Only `identity` is mandatory; a missing export behaves like `BasePlugin`'s no-op. -The full contract — every export's input and output, `ctx`, host functions, store limits, timeouts — is documented at [goblog.live/docs/plugin-api](https://www.goblog.live/docs/plugin-api) (or `/docs/plugin-api` on any goblog running the [docs plugin](https://github.com/goblogplatform/goblog-plugin-docs)); the source of those pages is `docs/guide/`. +The full contract — every export's input and output, `ctx`, host functions, store limits, timeouts — is documented at [goblog.live/docs/plugin-api](https://www.goblog.live/docs/plugin-api) (or `/docs/plugin-api` on any goblog with the `docs` plugin enabled); the source of those pages is `plugins/docs/content/`. Build one with the standard Go toolchain and [`github.com/extism/go-pdk`](https://github.com/extism/go-pdk): ```bash diff --git a/docs/PLUGIN_CONTRACT.md b/docs/PLUGIN_CONTRACT.md index 49a3390b..e038b3c7 100644 --- a/docs/PLUGIN_CONTRACT.md +++ b/docs/PLUGIN_CONTRACT.md @@ -1,3 +1,3 @@ # Publishing a goblog plugin -Moved: this page is now maintained in goblog's builder guide — read it at [goblog.live/docs/publishing-a-plugin](https://www.goblog.live/docs/publishing-a-plugin), or in the source at [`guide/publishing-a-plugin.md`](guide/publishing-a-plugin.md). +Moved: this page is now maintained as goblog's built-in documentation — read it at [goblog.live/docs/publishing-a-plugin](https://www.goblog.live/docs/publishing-a-plugin), or in the source at [`plugins/docs/content/publishing-a-plugin.md`](../plugins/docs/content/publishing-a-plugin.md). diff --git a/docs/THEME_CONTRACT.md b/docs/THEME_CONTRACT.md index 49674626..377a789b 100644 --- a/docs/THEME_CONTRACT.md +++ b/docs/THEME_CONTRACT.md @@ -1,3 +1,3 @@ # Publishing a goblog theme -Moved: this page is now maintained in goblog's builder guide — read it at [goblog.live/docs/publishing-a-theme](https://www.goblog.live/docs/publishing-a-theme), or in the source at [`guide/publishing-a-theme.md`](guide/publishing-a-theme.md). +Moved: this page is now maintained as goblog's built-in documentation — read it at [goblog.live/docs/publishing-a-theme](https://www.goblog.live/docs/publishing-a-theme), or in the source at [`plugins/docs/content/publishing-a-theme.md`](../plugins/docs/content/publishing-a-theme.md). diff --git a/docs/guide/doc.go b/docs/guide/doc.go deleted file mode 100644 index 9333edd3..00000000 --- a/docs/guide/doc.go +++ /dev/null @@ -1,30 +0,0 @@ -// Package guide holds goblog's builder documentation — how to write and -// publish plugins and themes — as markdown. It is not served by goblog: -// goblogplatform/goblog-plugin-docs vendors these files and renders them at -// /docs on goblog.live. The tests here keep the pages honest against the -// code (links resolve, every identifier they name exists). -package guide - -import "embed" - -// Content is every page, by file name. -// -//go:embed *.md -var Content embed.FS - -// Page is one documentation page: its URL segment under /docs, the title -// (also its H1), and its file. -type Page struct { - Slug, Title, File string -} - -// Pages is the sidebar order. Slug "" is the index. -var Pages = []Page{ - {"", "Overview", "overview.md"}, - {"writing-a-plugin", "Writing a plugin", "writing-a-plugin.md"}, - {"plugin-api", "Plugin API reference", "plugin-api.md"}, - {"publishing-a-plugin", "Publishing a plugin", "publishing-a-plugin.md"}, - {"writing-a-theme", "Writing a theme", "writing-a-theme.md"}, - {"publishing-a-theme", "Publishing a theme", "publishing-a-theme.md"}, - {"directory-formats", "Directory formats", "directory-formats.md"}, -} diff --git a/docs/guide/guide_test.go b/docs/guide/guide_test.go deleted file mode 100644 index 7a540b8c..00000000 --- a/docs/guide/guide_test.go +++ /dev/null @@ -1,344 +0,0 @@ -package guide - -import ( - "bufio" - "bytes" - "reflect" - "regexp" - "strconv" - "strings" - "testing" - - "goblog/plugin/wasm" - "goblog/plugins/directory/registry" -) - -func read(t *testing.T, file string) []byte { - t.Helper() - b, err := Content.ReadFile(file) - if err != nil { - t.Fatal(err) - } - return b -} - -// isFence reports whether a line opens or closes a fenced code block. A -// fence may be indented (inside a list item) and may use ``` or ~~~. -func isFence(line string) bool { - line = strings.TrimLeft(line, " \t") - return strings.HasPrefix(line, "```") || strings.HasPrefix(line, "~~~") -} - -// prose returns the page with every fenced code block blanked out, so the -// link and code-span lints see only what goldmark would render as prose. -// Lines are kept (blank) so nothing else shifts. -func prose(src []byte) []byte { - var out bytes.Buffer - inFence := false - sc := bufio.NewScanner(bytes.NewReader(src)) - for sc.Scan() { - line := sc.Text() - if isFence(line) { - inFence = !inFence - out.WriteByte('\n') - continue - } - if !inFence { - out.WriteString(line) - } - out.WriteByte('\n') - } - return out.Bytes() -} - -// headingIDs mirrors goldmark's parser.WithAutoHeadingID() (its -// autoHeadingIDs.Generate): ASCII letters and digits are kept, lowercased; -// spaces, '-' and '_' each become '-'; every other byte — punctuation, -// backticks, multibyte runes — is dropped; an empty result is "heading"; -// a repeated ID gets -1, -2, … appended until it is unique. The ID is -// generated from the heading's raw source line, so inline code -// contributes its text without the backticks. Only ATX headings at -// column 0 are recognised (no setext, no headings inside blockquotes or -// lists), which is all these pages use. The plugin's own tests check -// the same anchors with real goldmark, so a divergence here fails on -// that side, never silently. -func headingIDs(src []byte) map[string]bool { - ids := map[string]bool{} - inFence := false - sc := bufio.NewScanner(bytes.NewReader(src)) - for sc.Scan() { - line := sc.Text() - if isFence(line) { - inFence = !inFence - continue - } - if inFence || !strings.HasPrefix(line, "#") { - continue - } - text := strings.TrimLeft(line, "#") - if !strings.HasPrefix(text, " ") { - continue // "#hashtag" is not a heading - } - text = strings.TrimSpace(text) - // An optional closing sequence of #s is not part of the text. - if i := strings.LastIndex(text, " #"); i >= 0 && strings.Trim(text[i+1:], "#") == "" { - text = strings.TrimSpace(text[:i]) - } - var b strings.Builder - for i := 0; i < len(text); i++ { - c := text[i] - switch { - case c >= 'a' && c <= 'z', c >= '0' && c <= '9': - b.WriteByte(c) - case c >= 'A' && c <= 'Z': - b.WriteByte(c + 'a' - 'A') - case c == ' ', c == '\t', c == '-', c == '_': - b.WriteByte('-') - } - } - id := b.String() - if id == "" { - id = "heading" - } - if ids[id] { - for n := 1; ; n++ { - if candidate := id + "-" + strconv.Itoa(n); !ids[candidate] { - id = candidate - break - } - } - } - ids[id] = true - } - return ids -} - -// TestHeadingIDs pins the goldmark rules the port relies on, with the -// cases the real pages exercise: inline code, punctuation, underscores, -// a fenced "# comment", and a repeated heading. -func TestHeadingIDs(t *testing.T) { - src := []byte("# Plugin API reference\n\n## `.json`\n\n### template_head and template_footer\n\n```sh\n# not a heading\n```\n\n## Next\n\n## Next\n\n## Limits & lifecycle\n\n#notaheading\n") - got := headingIDs(src) - want := []string{"plugin-api-reference", "namejson", "template-head-and-template-footer", "next", "next-1", "limits--lifecycle"} - for _, id := range want { - if !got[id] { - t.Errorf("missing id %q in %v", id, got) - } - } - if len(got) != len(want) { - t.Errorf("got %d ids %v, want %d", len(got), got, len(want)) - } -} - -// TestPagesHaveTitleH1: every manifest entry exists in Content and opens -// with an H1 equal to its title, and nothing is embedded that the -// manifest does not list. -func TestPagesHaveTitleH1(t *testing.T) { - want := []Page{ - {"", "Overview", "overview.md"}, - {"writing-a-plugin", "Writing a plugin", "writing-a-plugin.md"}, - {"plugin-api", "Plugin API reference", "plugin-api.md"}, - {"publishing-a-plugin", "Publishing a plugin", "publishing-a-plugin.md"}, - {"writing-a-theme", "Writing a theme", "writing-a-theme.md"}, - {"publishing-a-theme", "Publishing a theme", "publishing-a-theme.md"}, - {"directory-formats", "Directory formats", "directory-formats.md"}, - } - if !reflect.DeepEqual(Pages, want) { - t.Errorf("Pages = %+v, want %+v", Pages, want) - } - listed := map[string]bool{} - for _, pg := range Pages { - listed[pg.File] = true - src := read(t, pg.File) - first := "" - for _, line := range strings.Split(string(src), "\n") { - if strings.TrimSpace(line) != "" { - first = line - break - } - } - if first != "# "+pg.Title { - t.Errorf("%s must start with %q, got %q", pg.File, "# "+pg.Title, first) - } - } - entries, err := Content.ReadDir(".") - if err != nil { - t.Fatal(err) - } - for _, e := range entries { - if !listed[e.Name()] { - t.Errorf("%s is embedded but not in Pages", e.Name()) - } - } -} - -// internalLink matches [text](/docs/[#anchor]) links in markdown. -var internalLink = regexp.MustCompile(`\]\((/docs(?:/([a-z0-9-]+))?(?:#([A-Za-z0-9_-]+))?)\)`) - -// samePageLink matches [text](#anchor) links in markdown. -var samePageLink = regexp.MustCompile(`\]\(#([A-Za-z0-9_-]+)\)`) - -// TestInternalLinksResolve fails when a page links to a slug that is not -// in the manifest or to an anchor that is not a heading on that page, or -// to a same-page anchor that is not one of its own headings. Fenced code -// is not linted (it is never rendered as a link) — and no page links -// from inside a fence anyway, which the count check asserts. -func TestInternalLinksResolve(t *testing.T) { - bySlug := map[string]Page{} - ids := map[string]map[string]bool{} - for _, pg := range Pages { - bySlug[pg.Slug] = pg - ids[pg.Slug] = headingIDs(read(t, pg.File)) - } - for _, pg := range Pages { - raw := read(t, pg.File) - src := prose(raw) - if a, b := len(internalLink.FindAll(raw, -1)), len(internalLink.FindAll(src, -1)); a != b { - t.Errorf("%s has %d /docs links inside fenced code", pg.File, a-b) - } - for _, m := range internalLink.FindAllSubmatch(src, -1) { - slug, anchor := string(m[2]), string(m[3]) - target, ok := bySlug[slug] - if !ok { - t.Errorf("%s links to unknown page /docs/%s", pg.File, slug) - continue - } - if anchor == "" { - continue - } - if !ids[slug][anchor] { - t.Errorf("%s links to /docs/%s#%s but %s has no such heading", pg.File, slug, anchor, target.File) - } - } - for _, m := range samePageLink.FindAllSubmatch(src, -1) { - if !ids[pg.Slug][string(m[1])] { - t.Errorf("%s links to #%s but has no such heading", pg.File, m[1]) - } - } - } -} - -// TestLicenseListsMatchRegistry: the pages that spell out the accepted -// licenses name every one the directory accepts. -func TestLicenseListsMatchRegistry(t *testing.T) { - for _, file := range []string{"publishing-a-plugin.md", "publishing-a-theme.md", "writing-a-plugin.md"} { - src := string(read(t, file)) - for _, l := range registry.KnownLicenses() { - if !strings.Contains(src, "`"+l+"`") { - t.Errorf("%s does not list the %s license", file, l) - } - } - } -} - -// TestNoAbsoluteSelfLinks keeps a self-hosted copy self-contained. -func TestNoAbsoluteSelfLinks(t *testing.T) { - for _, pg := range Pages { - if bytes.Contains(read(t, pg.File), []byte("goblog.live/docs")) { - t.Errorf("%s links to goblog.live/docs; use /docs/", pg.File) - } - } -} - -// jsonTags collects the json field names of a struct type (embedded structs -// included), so the docs' field tables are checked against the real shapes. -func jsonTags(t reflect.Type, into map[string]bool) { - for i := 0; i < t.NumField(); i++ { - f := t.Field(i) - if f.Anonymous { - jsonTags(f.Type, into) - continue - } - if tag, _, _ := strings.Cut(f.Tag.Get("json"), ","); tag != "" && tag != "-" { - into[tag] = true - } - } -} - -// knownIdentifiers is every snake_case name the docs may put in a code span: -// wasm exports and host functions, the JSON fields of the wire types, and -// an explicit allowlist for setting keys, env vars and file names. A rename -// in code without a docs change fails TestSnakeCaseIdentifiersExist; a new -// term in the docs that is not in code fails it too, which is the point. -func knownIdentifiers() map[string]bool { - known := map[string]bool{} - for _, e := range wasm.Exports { - known[e] = true - } - for _, h := range wasm.HostFunctions { - known[h] = true - } - for _, t := range []reflect.Type{reflect.TypeOf(registry.IndexEntry{}), reflect.TypeOf(registry.DetailDoc{}), reflect.TypeOf(registry.ReleaseDoc{}), reflect.TypeOf(registry.ThemeManifest{}), reflect.TypeOf(registry.Manifest{})} { - jsonTags(t, known) - } - for _, w := range wasm.ContractFieldNames() { - known[w] = true - } - for _, s := range []string{ - // Extism's own built-in host function, distinct from goblog's - // store_* functions in wasm.HostFunctions (plugin-api.md "http"). - "http_request", - - // Template data keys goblog's own templates render, added by - // blog/blog.go and admin/*.go render calls. - "nav_pages", "is_admin", "logged_in", "admin_page", "recent_posts", - "post_type", "post_types", "comment_error", "comment_token", "comment_user", - "outbound_links", "external_backlinks", "client_id", "email_login_enabled", - "plugin_settings", - - // Template data keys added by plugin/registry.go and plugin/wasm/wasm.go - // for plugin-owned pages (plugin-api.md "render_page"). - "has_plugin_content", "plugin_content", "plugin_head_html", "plugin_footer_html", - - // Reserved page slugs a plugin/theme may not claim (plugin/registry.go). - "test_db", "wizard_db", - - // json tag on plugin/installer.Status and theme/installer.Status - // (IndexFetchedAt): when the in-memory index copy was last fetched. - "index_fetched_at", - - // Setting keys seeded in tools/migrate.go and read via - // blog.SettingValue / ctx.Settings elsewhere. - "plugin_directory_url", "theme_directory_url", "refresh_minutes", "github_token", - "site_url", "custom_header_code", "custom_footer_code", - - // comments_require_login is both a template data key (blog/blog.go - // post.html render calls) and the setting blog.CommentsRequireLogin - // reads (blog/blog.go, blog/comment.go). - "comments_require_login", - - // semantic_scholar_id and cache_hours are setting keys of the worked - // example plugin itself (github.com/goblogplatform/goblog-plugin-scholar, - // main.go), not part of goblog's own contract. - "semantic_scholar_id", "cache_hours", - } { - known[s] = true - } - return known -} - -// snakeCase matches a `snake_case` code span, with or without a dotted -// prefix (request.sub_path): the last segment is what is linted. -var snakeCase = regexp.MustCompile("`(?:[a-z][a-z0-9_]*\\.)*([a-z][a-z0-9]*(?:_[a-z0-9]+)+)`") - -// TestSnakeCaseIdentifiersExist lints every `snake_case` span in the pages -// (outside fenced code) against the real identifiers in the code, so a -// rename in code without a matching docs change fails CI instead of -// shipping stale documentation. -func TestSnakeCaseIdentifiersExist(t *testing.T) { - known := knownIdentifiers() - for _, pg := range Pages { - for _, m := range snakeCase.FindAllSubmatch(prose(read(t, pg.File)), -1) { - if !known[string(m[1])] { - t.Errorf("%s names `%s`, which is not an export, host function, wire field or allowlisted name — renamed in code, or a typo?", pg.File, m[1]) - } - } - } - // And the reference page must mention every export and host function. - api := string(prose(read(t, "plugin-api.md"))) - for _, name := range append(append([]string{}, wasm.Exports...), wasm.HostFunctions...) { - if !strings.Contains(api, "`"+name+"`") { - t.Errorf("plugin-api.md does not document %s", name) - } - } -} diff --git a/docs/superpowers/plans/2026-09-20-docs-plugin-rev2.md b/docs/superpowers/plans/2026-09-20-docs-plugin-rev2.md index 967dd9d4..5ad9d021 100644 --- a/docs/superpowers/plans/2026-09-20-docs-plugin-rev2.md +++ b/docs/superpowers/plans/2026-09-20-docs-plugin-rev2.md @@ -127,7 +127,7 @@ func read(t *testing.T, file string) []byte { } // headingID mirrors goldmark's parser.WithAutoHeadingID(): lowercase, -// alphanumerics and '-' kept, '_' and spaces become '-', everything else +// alphanumerics, '-' and '_' kept, spaces become '-', everything else // dropped; a repeated ID gets -1, -2, … appended. The plugin's own tests // check the same anchors with real goldmark, so a divergence here fails // on that side, never silently. @@ -153,9 +153,9 @@ func headingIDs(src []byte) map[string]bool { var b strings.Builder for _, r := range strings.ToLower(text) { switch { - case r >= 'a' && r <= 'z', r >= '0' && r <= '9', r == '-': + case r >= 'a' && r <= 'z', r >= '0' && r <= '9', r == '-', r == '_': b.WriteRune(r) - case r == ' ', r == '_': + case r == ' ': b.WriteByte('-') } } diff --git a/docs/superpowers/plans/2026-09-20-docs-plugin.md b/docs/superpowers/plans/2026-09-20-docs-plugin.md index c3ab6e6c..9cb90ed4 100644 --- a/docs/superpowers/plans/2026-09-20-docs-plugin.md +++ b/docs/superpowers/plans/2026-09-20-docs-plugin.md @@ -1,7 +1,5 @@ # Documentation on goblog.live — Implementation Plan -> Superseded for Tasks 1–2, 7–8 by `2026-09-20-docs-plugin-rev2.md`; the content tasks (3–6) stand. - > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** goblog.live/docs documents how to build and publish plugins and themes, with the API references a builder needs, from markdown that ships inside the goblog binary. diff --git a/docs/superpowers/specs/2026-09-20-docs-plugin-design.md b/docs/superpowers/specs/2026-09-20-docs-plugin-design.md index a9da7d0d..0ac9c75d 100644 --- a/docs/superpowers/specs/2026-09-20-docs-plugin-design.md +++ b/docs/superpowers/specs/2026-09-20-docs-plugin-design.md @@ -84,38 +84,3 @@ goblog.live URL, so a self-hosted copy stays self-contained. - Versioned docs for older releases (the page documents the running version; older versions have their README). - Search. - -## Revision 2 (2026-09-20): served by a WASM plugin - -The compiled-in `plugins/docs` package put goblog.live-specific serving -code — a markdown renderer, a sidebar layout, a `docs` page type and a new -goldmark dependency — into every goblog install, where almost nobody would -enable it. The documentation is a feature of the project site, not of the -engine, and the WASM plugin system exists for exactly this kind of -optional page. So the serving side leaves the binary. - -What stays in goblog is the content and its guard rails: the seven pages -move from `plugins/docs/content/` to `docs/guide/` as a small `guide` -package (`embed.FS` of the markdown plus the `Pages` manifest), and the -tests move with them, rewritten to check the markdown source instead of -rendered HTML — every page opens with an H1 equal to its title, every -`/docs/[#anchor]` and `#anchor` link resolves against goldmark's -auto-heading-ID rules, no page links to goblog.live/docs, every -`snake_case` code span names a real export, host function, wire field or -allowlisted key, and the license lists match `registry.KnownLicenses()`. -goblog itself has no renderer and no goldmark. Rendering lives in -`goblogplatform/goblog-plugin-docs`: it vendors the pages from a goblog -tag (`scripts/sync-content.sh `, recording the ref in -`content/GOBLOG_REF`), renders them with goldmark inside the WASM -sandbox, and answers `render_page` with the `html` result form so goblog -wraps the sidebar and article in the theme's `page_content.html` — the -layout is the one the compiled-in plugin had. - -Rollout: this branch (PR #591) is reworked in place so goblog ships the -`docs/guide` package and the registry `ensurePages` fix, with the README -trims and contract pointers; the plugin repo is created, synced from the -goblog tag, and released as `docs` 1.0.0; it is submitted to the -directory and installed on goblog.live from **Admin → Plugins**, then -enabled, at which point the Docs nav entry appears and the directory -footer links to it resolve. A documentation change is a goblog PR (the lint runs -there) followed by a plugin release that re-syncs the content. diff --git a/go.mod b/go.mod index a0acc146..ee9356e0 100644 --- a/go.mod +++ b/go.mod @@ -22,6 +22,7 @@ require ( github.com/gobwas/glob v0.2.3 github.com/tetratelabs/wazero v1.9.0 github.com/traefik/yaegi v0.16.1 + github.com/yuin/goldmark v1.8.6 gorm.io/driver/postgres v1.6.3 ) diff --git a/go.sum b/go.sum index e42cc36a..b2923732 100644 --- a/go.sum +++ b/go.sum @@ -126,6 +126,8 @@ github.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS github.com/twitchyliquid64/golang-asm v0.15.1/go.mod h1:a1lVb/DtPvCB8fslRZhAngC2+aY1QWCk3Cedj/Gdt08= github.com/ugorji/go/codec v1.3.1 h1:waO7eEiFDwidsBN6agj1vJQ4AG7lh2yqXyOXqhgQuyY= github.com/ugorji/go/codec v1.3.1/go.mod h1:pRBVtBSKl77K30Bv8R2P+cLSGaTtex6fsA2Wjqmfxj4= +github.com/yuin/goldmark v1.8.6 h1:d0VcaP1sx9GkFVkoW+KtggpGi2KZ965i14b0+bDQST4= +github.com/yuin/goldmark v1.8.6/go.mod h1:ip/1k0VRfGynBgxOz0yCqHrbZXhcjxyuS66Brc7iBKg= go.mongodb.org/mongo-driver/v2 v2.8.0 h1:CxWDGQYY8QQwNjAl/aq2sfWakdnWZynnqJ9F4DhHbP8= go.mongodb.org/mongo-driver/v2 v2.8.0/go.mod h1:yOI9kBsufol30iFsl1slpdq1I0eHPzybRWdyYUs8K/0= go.opentelemetry.io/proto/otlp v1.3.1 h1:TrMUixzpM0yuc/znrFTP9MMRh8trP93mkCiDVeXrui0= diff --git a/goblog.go b/goblog.go index 4fcc1a4f..684167a0 100644 --- a/goblog.go +++ b/goblog.go @@ -13,6 +13,7 @@ import ( "goblog/plugin/wasm" "goblog/plugins/analytics" "goblog/plugins/directory" + "goblog/plugins/docs" "goblog/plugins/socialicons" "goblog/theme" tinstaller "goblog/theme/installer" @@ -307,6 +308,7 @@ func main() { dir := directory.New() dir.SetUserAgent("goblog-directory/" + Version) registry.Register(dir) + registry.Register(docs.New()) dynamicEnabled := os.Getenv("ENABLE_DYNAMIC_PLUGINS") == "true" if dynamicEnabled { gplugin.LoadDynamicPlugins(registry, "plugins/dynamic") diff --git a/docs/guide/directory-formats.md b/plugins/docs/content/directory-formats.md similarity index 100% rename from docs/guide/directory-formats.md rename to plugins/docs/content/directory-formats.md diff --git a/docs/guide/overview.md b/plugins/docs/content/overview.md similarity index 100% rename from docs/guide/overview.md rename to plugins/docs/content/overview.md diff --git a/docs/guide/plugin-api.md b/plugins/docs/content/plugin-api.md similarity index 99% rename from docs/guide/plugin-api.md rename to plugins/docs/content/plugin-api.md index 31d14b1e..7ded5783 100644 --- a/docs/guide/plugin-api.md +++ b/plugins/docs/content/plugin-api.md @@ -81,7 +81,7 @@ func settings() int32 { | `nav_order` | Its position there (ascending). | | `description` | Help text; not shown anywhere today. | -**What goblog does:** at startup and after an install or update, it creates a page row for each `page_type` that has none yet, from `title`, `slug`, `show_in_nav` and `nav_order`, enabled. The row is the admin's from then on — title, hero, nav placement and even the slug can be edited under **Admin → Pages** without touching the plugin, because requests are routed by `page_type`. A slug that is invalid, reserved, or already used by a page of another type or by a post type is logged and no page is created. Uninstalling the plugin deletes the rows it created. +**What goblog does:** at startup and after an install or update, it creates a page row for each `page_type` that has none yet, from `title`, `slug`, `show_in_nav` and `nav_order`, enabled. The row is the admin's from then on — title, hero, nav placement and even the slug can be edited under **Admin → Pages** without touching the plugin, because requests are routed by `page_type`. A slug that is invalid, reserved, or already used by a page of another type is logged and no page is created. Uninstalling the plugin deletes the rows it created. ```go //go:wasmexport pages diff --git a/docs/guide/publishing-a-plugin.md b/plugins/docs/content/publishing-a-plugin.md similarity index 100% rename from docs/guide/publishing-a-plugin.md rename to plugins/docs/content/publishing-a-plugin.md diff --git a/docs/guide/publishing-a-theme.md b/plugins/docs/content/publishing-a-theme.md similarity index 100% rename from docs/guide/publishing-a-theme.md rename to plugins/docs/content/publishing-a-theme.md diff --git a/docs/guide/writing-a-plugin.md b/plugins/docs/content/writing-a-plugin.md similarity index 100% rename from docs/guide/writing-a-plugin.md rename to plugins/docs/content/writing-a-plugin.md diff --git a/docs/guide/writing-a-theme.md b/plugins/docs/content/writing-a-theme.md similarity index 100% rename from docs/guide/writing-a-theme.md rename to plugins/docs/content/writing-a-theme.md diff --git a/plugins/docs/content_test.go b/plugins/docs/content_test.go new file mode 100644 index 00000000..b6731326 --- /dev/null +++ b/plugins/docs/content_test.go @@ -0,0 +1,176 @@ +package docs + +import ( + "reflect" + "regexp" + "strings" + "testing" + + "goblog/plugin/wasm" + "goblog/plugins/directory/registry" +) + +// internalLink matches /docs/[#anchor] links in rendered HTML. +var internalLink = regexp.MustCompile(`href="/docs(?:/([a-z0-9-]+))?(?:#([A-Za-z0-9_-]+))?"`) + +// samePageLink matches #anchor links in rendered HTML. +var samePageLink = regexp.MustCompile(`href="#([A-Za-z0-9_-]+)"`) + +// TestInternalLinksResolve fails when a page links to a slug that is not +// in the manifest or to an anchor that is not a heading on that page, or +// to a same-page anchor that is not one of its own headings. +func TestInternalLinksResolve(t *testing.T) { + p := New() + for _, pg := range pages { + r, _ := p.rendered(pg.Slug) + for _, m := range internalLink.FindAllStringSubmatch(string(r.HTML), -1) { + slug, anchor := m[1], m[2] + target, ok := p.rendered(slug) + if !ok { + t.Errorf("%s links to unknown page /docs/%s", pg.File, slug) + continue + } + if anchor == "" { + continue + } + if !strings.Contains(string(target.HTML), ` id="`+anchor+`"`) { + t.Errorf("%s links to /docs/%s#%s but %s has no such heading", pg.File, slug, anchor, target.File) + } + } + for _, m := range samePageLink.FindAllStringSubmatch(string(r.HTML), -1) { + if !strings.Contains(string(r.HTML), ` id="`+m[1]+`"`) { + t.Errorf("%s links to #%s but has no such heading", pg.File, m[1]) + } + } + } +} + +// TestLicenseListsMatchRegistry: the pages that spell out the accepted +// licenses name every one the directory accepts. +func TestLicenseListsMatchRegistry(t *testing.T) { + p := New() + for _, slug := range []string{"publishing-a-plugin", "publishing-a-theme", "writing-a-plugin"} { + r, _ := p.rendered(slug) + for _, l := range registry.KnownLicenses() { + if !strings.Contains(string(r.HTML), ""+l+"") { + t.Errorf("%s does not list the %s license", r.File, l) + } + } + } +} + +// TestNoAbsoluteSelfLinks keeps a self-hosted copy self-contained. +func TestNoAbsoluteSelfLinks(t *testing.T) { + p := New() + for _, pg := range pages { + r, _ := p.rendered(pg.Slug) + if strings.Contains(string(r.HTML), "goblog.live/docs") { + t.Errorf("%s links to goblog.live/docs; use /docs/", pg.File) + } + } +} + +// jsonTags collects the json field names of a struct type (embedded structs +// included), so the docs' field tables are checked against the real shapes. +func jsonTags(t reflect.Type, into map[string]bool) { + for i := 0; i < t.NumField(); i++ { + f := t.Field(i) + if f.Anonymous { + jsonTags(f.Type, into) + continue + } + if tag, _, _ := strings.Cut(f.Tag.Get("json"), ","); tag != "" && tag != "-" { + into[tag] = true + } + } +} + +// knownIdentifiers is every snake_case name the docs may put in a code span: +// wasm exports and host functions, the JSON fields of the wire types, and +// an explicit allowlist for setting keys, env vars and file names. A rename +// in code without a docs change fails TestSnakeCaseIdentifiersExist; a new +// term in the docs that is not in code fails it too, which is the point. +func knownIdentifiers() map[string]bool { + known := map[string]bool{} + for _, e := range wasm.Exports { + known[e] = true + } + for _, h := range wasm.HostFunctions { + known[h] = true + } + for _, t := range []reflect.Type{reflect.TypeOf(registry.IndexEntry{}), reflect.TypeOf(registry.DetailDoc{}), reflect.TypeOf(registry.ReleaseDoc{}), reflect.TypeOf(registry.ThemeManifest{}), reflect.TypeOf(registry.Manifest{})} { + jsonTags(t, known) + } + for _, w := range wasm.ContractFieldNames() { + known[w] = true + } + for _, s := range []string{ + // Extism's own built-in host function, distinct from goblog's + // store_* functions in wasm.HostFunctions (plugin-api.md "http"). + "http_request", + + // Template data keys goblog's own templates render, added by + // blog/blog.go and admin/*.go render calls. + "nav_pages", "is_admin", "logged_in", "admin_page", "recent_posts", + "post_type", "post_types", "comment_error", "comment_token", "comment_user", + "outbound_links", "external_backlinks", "client_id", "email_login_enabled", + "plugin_settings", + + // Template data keys added by plugin/registry.go and plugin/wasm/wasm.go + // for plugin-owned pages (plugin-api.md "render_page"). + "has_plugin_content", "plugin_content", "plugin_head_html", "plugin_footer_html", + + // Reserved page slugs a plugin/theme may not claim (plugin/registry.go). + "test_db", "wizard_db", + + // json tag on plugin/installer.Status and theme/installer.Status + // (IndexFetchedAt): when the in-memory index copy was last fetched. + "index_fetched_at", + + // Setting keys seeded in tools/migrate.go and read via + // blog.SettingValue / ctx.Settings elsewhere. + "plugin_directory_url", "theme_directory_url", "refresh_minutes", "github_token", + "site_url", "custom_header_code", "custom_footer_code", + + // comments_require_login is both a template data key (blog/blog.go + // post.html render calls) and the setting blog.CommentsRequireLogin + // reads (blog/blog.go, blog/comment.go). + "comments_require_login", + + // semantic_scholar_id and cache_hours are setting keys of the worked + // example plugin itself (github.com/goblogplatform/goblog-plugin-scholar, + // main.go), not part of goblog's own contract. + "semantic_scholar_id", "cache_hours", + } { + known[s] = true + } + return known +} + +// snakeCase matches a snake_case span, with or without a dotted +// prefix (request.sub_path): the last segment is what is linted. +var snakeCase = regexp.MustCompile(`(?:[a-z][a-z0-9_]*\.)*([a-z][a-z0-9]*(?:_[a-z0-9]+)+)`) + +// TestSnakeCaseIdentifiersExist lints every snake_case span in +// the rendered pages against the real identifiers in the code, so a rename +// in code without a matching docs change fails CI instead of shipping stale +// documentation. +func TestSnakeCaseIdentifiersExist(t *testing.T) { + known := knownIdentifiers() + p := New() + for _, pg := range pages { + r, _ := p.rendered(pg.Slug) + for _, m := range snakeCase.FindAllStringSubmatch(string(r.HTML), -1) { + if !known[m[1]] { + t.Errorf("%s names `%s`, which is not an export, host function, wire field or allowlisted name — renamed in code, or a typo?", pg.File, m[1]) + } + } + } + // And the reference page must mention every export and host function. + api, _ := p.rendered("plugin-api") + for _, name := range append(append([]string{}, wasm.Exports...), wasm.HostFunctions...) { + if !strings.Contains(string(api.HTML), ""+name+"") { + t.Errorf("plugin-api.md does not document %s", name) + } + } +} diff --git a/plugins/docs/docs.go b/plugins/docs/docs.go new file mode 100644 index 00000000..5f684c19 --- /dev/null +++ b/plugins/docs/docs.go @@ -0,0 +1,174 @@ +package docs + +import ( + "bytes" + "embed" + "errors" + "fmt" + "html/template" + "log" + "strings" + + "goblog/blog" + gplugin "goblog/plugin" + + "github.com/gin-gonic/gin" + "gorm.io/gorm" +) + +// PageType is the page type this plugin owns. +const PageType = "docs" + +//go:embed content/*.md +var contentFS embed.FS + +//go:embed templates/page.html +var pageTemplateSrc string + +var pageTemplate = template.Must(template.New("page").Parse(pageTemplateSrc)) + +// renderedPage is a content file rendered once at construction. +type renderedPage struct { + page + HTML template.HTML + TOC []Heading +} + +// Plugin serves the builder documentation at /docs. +type Plugin struct { + gplugin.BasePlugin + bySlug map[string]renderedPage +} + +// New renders every page. A page that fails to render is a build defect, +// not a runtime condition, so it panics — the package tests catch it first. +func New() *Plugin { + p := &Plugin{bySlug: make(map[string]renderedPage, len(pages))} + for _, pg := range pages { + src, err := contentFS.ReadFile("content/" + pg.File) + if err != nil { + panic(fmt.Sprintf("docs: %s: %v", pg.File, err)) + } + html, toc, err := Render(src) + if err != nil { + panic(fmt.Sprintf("docs: render %s: %v", pg.File, err)) + } + p.bySlug[pg.Slug] = renderedPage{page: pg, HTML: html, TOC: toc} + } + return p +} + +func (p *Plugin) Name() string { return "docs" } +func (p *Plugin) DisplayName() string { return "Documentation" } +func (p *Plugin) Version() string { return "1.0.0" } + +func (p *Plugin) Settings() []gplugin.SettingDefinition { + return []gplugin.SettingDefinition{ + {Key: "enabled", Type: "text", DefaultValue: "false", Label: "Enabled", + Description: "Set to 'true' to publish the plugin and theme documentation at /docs"}, + } +} + +func (p *Plugin) Pages() []gplugin.PageDefinition { + return []gplugin.PageDefinition{{ + PageType: PageType, + Title: "Docs", + Slug: "docs", + ShowInNav: true, + NavOrder: 32, + Description: "How to build and publish goblog plugins and themes", + }} +} + +// OnInit ensures the page row exists (the registry normally creates it +// first; this is the fallback). A foreign page or a post type on the "docs" +// slug is left alone with a log line, as the directory plugin does, so Init +// continues. +func (p *Plugin) OnInit(db *gorm.DB) error { + var existing blog.Page + err := db.Where("page_type = ?", PageType).First(&existing).Error + if err == nil { + return nil + } + if !errors.Is(err, gorm.ErrRecordNotFound) { + return fmt.Errorf("docs plugin: query page: %w", err) + } + def := p.Pages()[0] + if err := db.Where("slug = ?", def.Slug).First(&existing).Error; err == nil { + log.Printf("Docs plugin: page slug %q is already used by a %q page; rename it and restart to create the docs page", def.Slug, existing.PageType) + return nil + } else if !errors.Is(err, gorm.ErrRecordNotFound) { + return fmt.Errorf("docs plugin: query slug: %w", err) + } + var postType blog.PostType + if err := db.Where("slug = ?", def.Slug).First(&postType).Error; err == nil { + log.Printf("Docs plugin: page slug %q is already used by the %q post type; rename it and restart to create the docs page", def.Slug, postType.Name) + return nil + } else if !errors.Is(err, gorm.ErrRecordNotFound) { + return fmt.Errorf("docs plugin: query post type slug: %w", err) + } + row := blog.Page{Title: def.Title, Slug: def.Slug, PageType: def.PageType, ShowInNav: def.ShowInNav, NavOrder: def.NavOrder, Enabled: true} + if err := db.Create(&row).Error; err != nil { + return fmt.Errorf("docs plugin: create page: %w", err) + } + log.Println("Docs plugin: created docs page") + return nil +} + +// rendered looks a page up by slug. +func (p *Plugin) rendered(slug string) (renderedPage, bool) { + r, ok := p.bySlug[slug] + return r, ok +} + +// RenderPage serves the index ("") and one page per slug; anything else is +// declined so blog answers 404. +func (p *Plugin) RenderPage(ctx *gplugin.HookContext, pageType string) (string, gin.H) { + if pageType != PageType { + return "", nil + } + r, ok := p.rendered(ctx.SubPath) + if !ok { + return "", nil + } + base := basePath(ctx.GinContext) + return "page_content.html", gin.H{"has_plugin_content": true, "plugin_content": sidebarAndArticle(base, ctx.SubPath, r), "title": r.Title} +} + +// basePath is the page's URL prefix ("/docs"), from the request so links +// follow a renamed slug. +func basePath(c *gin.Context) string { + path := strings.TrimPrefix(c.Request.URL.Path, "/") + slug, _, _ := strings.Cut(path, "/") + return "/" + slug +} + +// sidebarAndArticle lays out the sidebar (every page, current one marked), +// the table of contents when the page is long enough to need one, and the +// article. +func sidebarAndArticle(base, current string, r renderedPage) string { + type item struct { + Href, Title string + Current bool + } + items := make([]item, 0, len(pages)) + for _, pg := range pages { + href := base + if pg.Slug != "" { + href += "/" + pg.Slug + } + items = append(items, item{Href: href, Title: pg.Title, Current: pg.Slug == current}) + } + var buf bytes.Buffer + err := pageTemplate.Execute(&buf, map[string]any{ + "Items": items, + "TOC": r.TOC, + "HasTOC": len(r.TOC) > 3, + "HTML": r.HTML, + }) + if err != nil { + log.Printf("Docs plugin: render layout: %v", err) + return string(r.HTML) + } + return buf.String() +} diff --git a/plugins/docs/docs_test.go b/plugins/docs/docs_test.go new file mode 100644 index 00000000..ac441d15 --- /dev/null +++ b/plugins/docs/docs_test.go @@ -0,0 +1,183 @@ +package docs + +import ( + "net/http" + "net/http/httptest" + "strings" + "testing" + + "goblog/blog" + gplugin "goblog/plugin" + + "github.com/gin-gonic/gin" + "gorm.io/driver/sqlite" + "gorm.io/gorm" +) + +func renderCtx(t *testing.T, path, subPath string) (*gplugin.HookContext, *httptest.ResponseRecorder) { + t.Helper() + gin.SetMode(gin.TestMode) + w := httptest.NewRecorder() + c, _ := gin.CreateTestContext(w) + c.Request = httptest.NewRequest(http.MethodGet, path, nil) + return &gplugin.HookContext{GinContext: c, Settings: map[string]string{"enabled": "true"}, SubPath: subPath}, w +} + +func TestPlugin_Identity(t *testing.T) { + p := New() + if p.Name() != "docs" || p.DisplayName() != "Documentation" || p.Version() == "" { + t.Errorf("identity: %q %q %q", p.Name(), p.DisplayName(), p.Version()) + } + s := p.Settings() + if len(s) != 1 || s[0].Key != "enabled" || s[0].DefaultValue != "false" { + t.Errorf("settings = %+v", s) + } + pg := p.Pages() + if len(pg) != 1 || pg[0].PageType != PageType || pg[0].Slug != "docs" || pg[0].Title != "Docs" || pg[0].NavOrder != 32 || !pg[0].ShowInNav { + t.Errorf("pages = %+v", pg) + } + var _ gplugin.Plugin = p +} + +func TestPagesManifest(t *testing.T) { + want := []page{ + {"", "Overview", "overview.md"}, + {"writing-a-plugin", "Writing a plugin", "writing-a-plugin.md"}, + {"plugin-api", "Plugin API reference", "plugin-api.md"}, + {"publishing-a-plugin", "Publishing a plugin", "publishing-a-plugin.md"}, + {"writing-a-theme", "Writing a theme", "writing-a-theme.md"}, + {"publishing-a-theme", "Publishing a theme", "publishing-a-theme.md"}, + {"directory-formats", "Directory formats", "directory-formats.md"}, + } + if len(pages) != len(want) { + t.Fatalf("pages = %+v", pages) + } + for i := range want { + if pages[i] != want[i] { + t.Errorf("page %d = %+v, want %+v", i, pages[i], want[i]) + } + } + p := New() + for _, pg := range pages { + r, ok := p.rendered(pg.Slug) + if !ok { + t.Fatalf("page %q not rendered", pg.Slug) + } + if !strings.Contains(string(r.HTML), `

"+pg.Title+"

") { + t.Errorf("page %q must start with an H1 equal to its title; got:\n%.200s", pg.Slug, r.HTML) + } + } +} + +func TestOnInit_CreatesPage(t *testing.T) { + db, _ := gorm.Open(sqlite.Open(":memory:")) + db.AutoMigrate(&blog.Page{}, &blog.PostType{}) + p := New() + if err := p.OnInit(db); err != nil { + t.Fatal(err) + } + if err := p.OnInit(db); err != nil { + t.Fatal(err) + } + var rows []blog.Page + db.Where("page_type = ?", PageType).Find(&rows) + if len(rows) != 1 || rows[0].Slug != "docs" || rows[0].Title != "Docs" || !rows[0].Enabled { + t.Errorf("rows = %+v", rows) + } +} + +// TestOnInit_ForeignSlug: a page of another type or a post type already at +// "docs" is left alone with a log line; OnInit neither fails nor creates a +// docs page. +func TestOnInit_ForeignSlug(t *testing.T) { + for name, seed := range map[string]any{ + "page": &blog.Page{Title: "Mine", Slug: "docs", PageType: blog.PageTypeCustom, Enabled: true}, + "post type": &blog.PostType{Name: "Docs", Slug: "docs"}, + } { + db, _ := gorm.Open(sqlite.Open(":memory:")) + db.AutoMigrate(&blog.Page{}, &blog.PostType{}) + if err := db.Create(seed).Error; err != nil { + t.Fatal(err) + } + if err := New().OnInit(db); err != nil { + t.Fatalf("%s: OnInit must not fail when the slug is taken, got %v", name, err) + } + var count int64 + db.Model(&blog.Page{}).Where("page_type = ?", PageType).Count(&count) + if count != 0 { + t.Errorf("%s: expected no docs page, got %d", name, count) + } + } +} + +func TestRenderPage(t *testing.T) { + p := New() + ctx, _ := renderCtx(t, "/docs", "") + if tmpl, _ := p.RenderPage(ctx, "other"); tmpl != "" { + t.Error("other page types are declined") + } + tmpl, data := p.RenderPage(ctx, PageType) + html, _ := data["plugin_content"].(string) + if tmpl != "page_content.html" || data["has_plugin_content"] != true || data["title"] != "Overview" { + t.Fatalf("index: %q %v", tmpl, data) + } + for _, want := range []string{`

Overview

`, `href="/docs/plugin-api"`, `href="/docs/directory-formats"`, `aria-current="page"`} { + if !strings.Contains(html, want) { + t.Errorf("index missing %q", want) + } + } + ctx, _ = renderCtx(t, "/docs/plugin-api", "plugin-api") + _, data = p.RenderPage(ctx, PageType) + html, _ = data["plugin_content"].(string) + if data["title"] != "Plugin API reference" || !strings.Contains(html, `

`) { + t.Errorf("plugin-api page: title=%v", data["title"]) + } + // Sidebar follows the page slug, and marks the current page. + ctx, _ = renderCtx(t, "/manual/plugin-api", "plugin-api") + _, data = p.RenderPage(ctx, PageType) + html, _ = data["plugin_content"].(string) + if !strings.Contains(html, `href="/manual/writing-a-theme"`) || !strings.Contains(html, ``) { + t.Errorf("sidebar:\n%s", html) + } + for _, sp := range []string{"nope", "plugin-api/", "../x", "overview.md"} { + ctx, _ := renderCtx(t, "/docs/"+sp, sp) + if tmpl, _ := p.RenderPage(ctx, PageType); tmpl != "" { + t.Errorf("%q should be declined", sp) + } + } +} + +// TestTOC_OnlyForLongerPages: a page gets a table of contents iff it has +// more than three H2/H3 headings. The reference page is the long one; every +// real page is checked against the iff; and because every shipped page now +// has more than three headings, the no-TOC side is exercised with a +// synthetic three-heading page rather than left to chance. +func TestTOC_OnlyForLongerPages(t *testing.T) { + p := New() + long, _ := p.rendered("plugin-api") + if len(long.TOC) <= 3 { + t.Fatalf("plugin-api has %d headings; the test needs more than three", len(long.TOC)) + } + out := sidebarAndArticle("/docs", "plugin-api", long) + if !strings.Contains(out, `class="docs-toc `) || !strings.Contains(out, `href="#exports"`) { + t.Error("plugin-api should have a table of contents with an #exports entry") + } + for _, pg := range pages { + r, _ := p.rendered(pg.Slug) + has := strings.Contains(sidebarAndArticle("/docs", pg.Slug, r), `class="docs-toc `) + if has != (len(r.TOC) > 3) { + t.Errorf("%s: %d headings, toc=%v", pg.File, len(r.TOC), has) + } + } + html, toc, err := Render([]byte("# Short\n\n## One\n\n## Two\n\n### Three\n")) + if err != nil { + t.Fatal(err) + } + if len(toc) != 3 { + t.Fatalf("synthetic page has %d headings, want 3", len(toc)) + } + short := renderedPage{page: page{Slug: "short", Title: "Short", File: "short.md"}, HTML: html, TOC: toc} + if strings.Contains(sidebarAndArticle("/docs", "short", short), `class="docs-toc `) { + t.Error("a page with three headings should have no table of contents") + } +} diff --git a/plugins/docs/pages.go b/plugins/docs/pages.go new file mode 100644 index 00000000..93d77305 --- /dev/null +++ b/plugins/docs/pages.go @@ -0,0 +1,18 @@ +package docs + +// page is one documentation page: its URL segment under /docs, the sidebar +// title (also the page's H1), and its file in content/. +type page struct { + Slug, Title, File string +} + +// pages is the sidebar, in order. Slug "" is the index. +var pages = []page{ + {"", "Overview", "overview.md"}, + {"writing-a-plugin", "Writing a plugin", "writing-a-plugin.md"}, + {"plugin-api", "Plugin API reference", "plugin-api.md"}, + {"publishing-a-plugin", "Publishing a plugin", "publishing-a-plugin.md"}, + {"writing-a-theme", "Writing a theme", "writing-a-theme.md"}, + {"publishing-a-theme", "Publishing a theme", "publishing-a-theme.md"}, + {"directory-formats", "Directory formats", "directory-formats.md"}, +} diff --git a/plugins/docs/render.go b/plugins/docs/render.go new file mode 100644 index 00000000..e32c88f1 --- /dev/null +++ b/plugins/docs/render.go @@ -0,0 +1,76 @@ +// Package docs serves goblog's builder documentation — how to write and +// publish plugins and themes — from markdown embedded in the binary, so a +// site always documents the version it runs. +package docs + +import ( + "bytes" + "html/template" + + "github.com/yuin/goldmark" + "github.com/yuin/goldmark/ast" + "github.com/yuin/goldmark/extension" + "github.com/yuin/goldmark/parser" + "github.com/yuin/goldmark/renderer/html" + "github.com/yuin/goldmark/text" +) + +// Heading is one H2/H3 of a rendered page, for its table of contents. +type Heading struct { + Level int + ID string + Text string +} + +// md is configured once: GitHub-flavoured markdown (tables, strikethrough, +// autolinks), stable heading IDs so sections are linkable, and raw HTML +// allowed — the content is ours and embedded, never user-supplied. +var md = goldmark.New( + goldmark.WithExtensions(extension.GFM), + goldmark.WithParserOptions(parser.WithAutoHeadingID()), + goldmark.WithRendererOptions(html.WithUnsafe()), +) + +// Render converts one page to HTML and lists its H2/H3 headings in order. +func Render(src []byte) (template.HTML, []Heading, error) { + doc := md.Parser().Parse(text.NewReader(src)) + var heads []Heading + err := ast.Walk(doc, func(n ast.Node, entering bool) (ast.WalkStatus, error) { + h, ok := n.(*ast.Heading) + if !ok || !entering || h.Level < 2 || h.Level > 3 { + return ast.WalkContinue, nil + } + id, _ := h.AttributeString("id") + heads = append(heads, Heading{Level: h.Level, ID: string(id.([]byte)), Text: plainText(h, src)}) + return ast.WalkContinue, nil + }) + if err != nil { + return "", nil, err + } + var buf bytes.Buffer + if err := md.Renderer().Render(&buf, src, doc); err != nil { + return "", nil, err + } + return template.HTML(buf.String()), heads, nil +} + +// plainText flattens a heading's inline children (text, code spans, +// emphasis) to the words a table of contents shows. +func plainText(n ast.Node, src []byte) string { + var buf bytes.Buffer + var walk func(ast.Node) + walk = func(n ast.Node) { + for c := n.FirstChild(); c != nil; c = c.NextSibling() { + switch t := c.(type) { + case *ast.Text: + buf.Write(t.Segment.Value(src)) + case *ast.CodeSpan: + walk(t) + default: + walk(c) + } + } + } + walk(n) + return buf.String() +} diff --git a/plugins/docs/render_test.go b/plugins/docs/render_test.go new file mode 100644 index 00000000..dd8109c6 --- /dev/null +++ b/plugins/docs/render_test.go @@ -0,0 +1,36 @@ +package docs + +import ( + "strings" + "testing" +) + +func TestRender(t *testing.T) { + src := []byte("# Title\n\nIntro with `code` and a [link](/docs/plugin-api#exports).\n\n## Exports\n\n| a | b |\n|---|---|\n| 1 | 2 |\n\n### Identity export\n\n
raw
\n\n## Limits\n") + html, heads, err := Render(src) + if err != nil { + t.Fatal(err) + } + out := string(html) + for _, want := range []string{`

Title

`, `

Exports

`, `

Identity export

`, ``, ``, `code`, `href="/docs/plugin-api#exports"`} { + if !strings.Contains(out, want) { + t.Errorf("missing %q in:\n%s", want, out) + } + } + want := []Heading{{2, "exports", "Exports"}, {3, "identity-export", "Identity export"}, {2, "limits", "Limits"}} + if len(heads) != len(want) { + t.Fatalf("headings = %+v", heads) + } + for i := range want { + if heads[i] != want[i] { + t.Errorf("heading %d = %+v, want %+v", i, heads[i], want[i]) + } + } +} + +func TestRender_HeadingTextWithInlineCode(t *testing.T) { + _, heads, err := Render([]byte("## The `identity` export\n")) + if err != nil || len(heads) != 1 || heads[0].Text != "The identity export" || heads[0].ID != "the-identity-export" { + t.Errorf("heads = %+v, %v", heads, err) + } +} diff --git a/plugins/docs/templates/page.html b/plugins/docs/templates/page.html new file mode 100644 index 00000000..5aa1d205 --- /dev/null +++ b/plugins/docs/templates/page.html @@ -0,0 +1,25 @@ + +
+ +
+ {{ if .HasTOC }} + + {{ end }} + {{ .HTML }} +
+
From ebc744be1693afdad2a534d889bbc52919dd5a0b Mon Sep 17 00:00:00 2001 From: Jason Ernst Date: Sun, 20 Sep 2026 16:58:10 -0700 Subject: [PATCH 2/3] Docs: page-row rule names post types; read the heading id with a type switch Co-Authored-By: Claude Opus 5 (1M context) --- plugins/docs/content/plugin-api.md | 2 +- plugins/docs/render.go | 20 ++++++++++++++++++-- 2 files changed, 19 insertions(+), 3 deletions(-) diff --git a/plugins/docs/content/plugin-api.md b/plugins/docs/content/plugin-api.md index 7ded5783..31d14b1e 100644 --- a/plugins/docs/content/plugin-api.md +++ b/plugins/docs/content/plugin-api.md @@ -81,7 +81,7 @@ func settings() int32 { | `nav_order` | Its position there (ascending). | | `description` | Help text; not shown anywhere today. | -**What goblog does:** at startup and after an install or update, it creates a page row for each `page_type` that has none yet, from `title`, `slug`, `show_in_nav` and `nav_order`, enabled. The row is the admin's from then on — title, hero, nav placement and even the slug can be edited under **Admin → Pages** without touching the plugin, because requests are routed by `page_type`. A slug that is invalid, reserved, or already used by a page of another type is logged and no page is created. Uninstalling the plugin deletes the rows it created. +**What goblog does:** at startup and after an install or update, it creates a page row for each `page_type` that has none yet, from `title`, `slug`, `show_in_nav` and `nav_order`, enabled. The row is the admin's from then on — title, hero, nav placement and even the slug can be edited under **Admin → Pages** without touching the plugin, because requests are routed by `page_type`. A slug that is invalid, reserved, or already used by a page of another type or by a post type is logged and no page is created. Uninstalling the plugin deletes the rows it created. ```go //go:wasmexport pages diff --git a/plugins/docs/render.go b/plugins/docs/render.go index e32c88f1..cd57d1c7 100644 --- a/plugins/docs/render.go +++ b/plugins/docs/render.go @@ -40,8 +40,7 @@ func Render(src []byte) (template.HTML, []Heading, error) { if !ok || !entering || h.Level < 2 || h.Level > 3 { return ast.WalkContinue, nil } - id, _ := h.AttributeString("id") - heads = append(heads, Heading{Level: h.Level, ID: string(id.([]byte)), Text: plainText(h, src)}) + heads = append(heads, Heading{Level: h.Level, ID: headingID(h), Text: plainText(h, src)}) return ast.WalkContinue, nil }) if err != nil { @@ -74,3 +73,20 @@ func plainText(n ast.Node, src []byte) string { walk(n) return buf.String() } + +// headingID reads the auto-generated id attribute. goldmark stores it as +// []byte today; a string is accepted too so a library change degrades to +// an empty id (and a failing anchor test) rather than a panic at startup. +func headingID(h *ast.Heading) string { + id, ok := h.AttributeString("id") + if !ok { + return "" + } + switch v := id.(type) { + case []byte: + return string(v) + case string: + return v + } + return "" +} From 220faa10669ee1d07281c40ba7d704462f163064 Mon Sep 17 00:00:00 2001 From: Jason Ernst Date: Sun, 20 Sep 2026 16:59:58 -0700 Subject: [PATCH 3/3] Spec: record the reverted WASM-plugin revision Co-Authored-By: Claude Opus 5 (1M context) --- docs/superpowers/plans/2026-09-20-docs-plugin-rev2.md | 2 ++ docs/superpowers/specs/2026-09-20-docs-plugin-design.md | 4 ++++ 2 files changed, 6 insertions(+) diff --git a/docs/superpowers/plans/2026-09-20-docs-plugin-rev2.md b/docs/superpowers/plans/2026-09-20-docs-plugin-rev2.md index 5ad9d021..8d921e44 100644 --- a/docs/superpowers/plans/2026-09-20-docs-plugin-rev2.md +++ b/docs/superpowers/plans/2026-09-20-docs-plugin-rev2.md @@ -1,5 +1,7 @@ # Documentation as a WASM plugin (rev 2) — Implementation Plan +> **Reverted.** Executed and merged in #591, then reverted: the per-release content sync was a non-starter. The compiled-in design of `2026-09-20-docs-plugin.md` stands. Kept for the record. + > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** Take the documentation out of the goblog binary: the pages stay in the goblog repo (with their CI lint) and are served on goblog.live by a separate WASM plugin, `goblogplatform/goblog-plugin-docs`. diff --git a/docs/superpowers/specs/2026-09-20-docs-plugin-design.md b/docs/superpowers/specs/2026-09-20-docs-plugin-design.md index 0ac9c75d..260354fa 100644 --- a/docs/superpowers/specs/2026-09-20-docs-plugin-design.md +++ b/docs/superpowers/specs/2026-09-20-docs-plugin-design.md @@ -84,3 +84,7 @@ goblog.live URL, so a self-hosted copy stays self-contained. - Versioned docs for older releases (the page documents the running version; older versions have their README). - Search. + +## Revision 2 (2026-09-20): tried as a WASM plugin, reverted + +Between 076ad07 and the merge of #591 the serving side was moved out of the binary into `goblogplatform/goblog-plugin-docs` (pages and lint in `docs/guide/`, content vendored per goblog release). That merged, and was reverted in the follow-up PR: every documentation change would have needed a sync-commit-tag-release cycle in a second repo, which Jason judged a non-starter. The docs are therefore a **compiled-in plugin, off by default**, on the same footing as `directory`: goblog.live enables it, other installs never see it. The plugin repo was deleted; `docs/superpowers/plans/2026-09-20-docs-plugin-rev2.md` is kept as the record of the attempt.
raw