docs: restructure to 13-page IA + verified content audit [1.x]#15
docs: restructure to 13-page IA + verified content audit [1.x]#15ManukMinasyan merged 19 commits into1.xfrom
Conversation
There was a problem hiding this comment.
Pull request overview
Restructures the documentation site to a 13-page information architecture with newly split/added pages (Quick start, Concepts, Recipes, Testing, Caching, Configuration, Troubleshooting, Community) and updated navigation/SEO metadata to match the new structure.
Changes:
- Adds new focused docs pages (Concepts + split Essentials pages + Recipes + Testing + Troubleshooting + Community) and section navigation files.
- Updates the home page CTAs/feature copy and adds
seo:frontmatter where missing. - Removes the previous “kitchen-sink” Essentials pages (API reference, database schema, customization, integration patterns, troubleshooting) in favor of the new structure.
Reviewed changes
Copilot reviewed 27 out of 29 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/content/index.md | Adds Quick start CTA button; tweaks feature copy (“Smart Pagination”). |
| docs/content/1.getting-started/1.installation.md | Expands installation page with indexing, Tailwind, and plugin guidance. |
| docs/content/1.getting-started/2.quick-start.md | New 5-minute end-to-end quick start page. |
| docs/content/2.concepts/.navigation.yml | Adds Concepts section navigation metadata. |
| docs/content/2.concepts/1.how-it-works.md | New canonical “mental model” / pipeline / taxonomy page. |
| docs/content/3.essentials/.navigation.yml | Adds Essentials section navigation metadata. |
| docs/content/3.essentials/1.sources.md | New Sources reference (builder from*() and addSource() APIs). |
| docs/content/3.essentials/2.filament-ui.md | New Filament UI surface reference (infolist/relation manager/action + URL filters). |
| docs/content/3.essentials/3.refining-the-timeline.md | New builder refinement reference (filters/sort/dedup/paginate/get/count). |
| docs/content/3.essentials/4.customization.md | New renderer customization reference and registration channels. |
| docs/content/3.essentials/5.caching.md | New caching reference (TTL caching + key composition + invalidation caveat). |
| docs/content/3.essentials/6.configuration.md | New configuration key reference table + known dead key callout. |
| docs/content/4.recipes/.navigation.yml | Adds Recipes section navigation metadata. |
| docs/content/4.recipes/1.crm-person-feed.md | New end-to-end CRM “person feed” recipe. |
| docs/content/4.recipes/2.audit-log-for-admins.md | New “admin audit log” recipe with redaction + gating pattern. |
| docs/content/5.testing/.navigation.yml | Adds Testing section navigation metadata. |
| docs/content/5.testing/1.index.md | New consumer-app testing patterns page (Pest/Livewire/Filament). |
| docs/content/6.troubleshooting/.navigation.yml | Adds Troubleshooting section navigation metadata. |
| docs/content/6.troubleshooting/1.index.md | New troubleshooting/known limitations page with issue links. |
| docs/content/7.community/.navigation.yml | Adds Community section navigation metadata. |
| docs/content/7.community/1.contributing.md | Adds seo: frontmatter to contributing page. |
| docs/content/7.community/2.license.md | Adds seo: frontmatter to license page. |
| docs/content/2.essentials/.navigation.yml | Removes old Essentials navigation entry (legacy IA). |
| docs/content/2.essentials/1.integration-patterns.md | Removes legacy integration patterns page (superseded by new pages). |
| docs/content/2.essentials/2.customization.md | Removes legacy customization page (superseded by new Customization). |
| docs/content/2.essentials/3.database-schema.md | Removes legacy database schema page (folded into Installation). |
| docs/content/2.essentials/4.api-reference.md | Removes legacy API reference page (split across new Essentials pages). |
| docs/content/2.essentials/5.troubleshooting.md | Removes legacy troubleshooting page (replaced by new Troubleshooting section). |
| .gitignore | Ignores .planning/ directory. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| } | ||
| ``` | ||
|
|
||
| `LogsActivity` (paired with `getActivitylogOptions`) makes spatie record create / update / delete events into the `activity_log` table. `HasTimeline` plus the `InteractsWithTimeline` trait give you `timeline()`, `paginateTimeline()`, and `forgetTimelineCache()` on the model. `fromActivityLog()` is the simplest source — the subject's own log. |
There was a problem hiding this comment.
InteractsWithTimeline doesn’t provide timeline(); consumers must implement it to satisfy HasTimeline. This paragraph currently implies the trait “gives you timeline()” — suggest rewording to say it provides paginateTimeline() / forgetTimelineCache() helpers while you define timeline() yourself.
| `LogsActivity` (paired with `getActivitylogOptions`) makes spatie record create / update / delete events into the `activity_log` table. `HasTimeline` plus the `InteractsWithTimeline` trait give you `timeline()`, `paginateTimeline()`, and `forgetTimelineCache()` on the model. `fromActivityLog()` is the simplest source — the subject's own log. | |
| `LogsActivity` (paired with `getActivitylogOptions`) makes spatie record create / update / delete events into the `activity_log` table. `HasTimeline` requires your model to define `timeline()`, while the `InteractsWithTimeline` trait provides helpers like `paginateTimeline()` and `forgetTimelineCache()`. `fromActivityLog()` is the simplest source — the subject's own log. |
|
|
||
| ## `->cached(int $ttlSeconds)` | ||
|
|
||
| Position in the chain: call **before** `paginate()` or `get()`. It has no effect on `count()` (which runs through `get()` un-cached internally — see [/essentials/refining-the-timeline](/essentials/refining-the-timeline) for why). |
There was a problem hiding this comment.
->cached() currently only affects paginate(); TimelineBuilder::get() does not consult cacheTtl, so saying it works when called before get() is inaccurate. Update the docs to state caching applies to paginate() only (and therefore also not to count(), which calls get() internally), or implement caching for get() in code if that’s intended.
| Position in the chain: call **before** `paginate()` or `get()`. It has no effect on `count()` (which runs through `get()` un-cached internally — see [/essentials/refining-the-timeline](/essentials/refining-the-timeline) for why). | |
| Position in the chain: call **before** `paginate()`. It currently applies to `paginate()` only; it does **not** affect `get()` or `count()` (which runs through `get()` internally — see [/essentials/refining-the-timeline](/essentials/refining-the-timeline) for why). |
|
|
||
| ## Configuration knobs | ||
|
|
||
| Short reference here; the full table lives on [/essentials/configuration#cache](/essentials/configuration#cache). |
There was a problem hiding this comment.
The link /essentials/configuration#cache points to an anchor that doesn’t exist on the Configuration page (there is no ## Cache section). Either add a ## Cache heading there or change this link to a valid anchor (e.g. the ## Keys section).
| Short reference here; the full table lives on [/essentials/configuration#cache](/essentials/configuration#cache). | |
| Short reference here; the full table lives on [/essentials/configuration](/essentials/configuration). |
| ### Config | ||
|
|
||
| For **static defaults** that don't depend on runtime state. Lives in `config/activity-log.php`. | ||
|
|
||
| ```php | ||
| // config/activity-log.php | ||
| 'renderers' => [ | ||
| 'email_sent' => \App\Timeline\Renderers\EmailSentRenderer::class, | ||
| ], | ||
| ``` |
There was a problem hiding this comment.
Docs currently present a “Config” channel (config/activity-log.php 'renderers' => [...]) as a working way to register renderers, but the package never reads config('activity-log.renderers') and never registers those bindings (service provider only registers the built-in 'activity_log' renderer). Either remove/mark this as a known limitation or add code to auto-register renderers from config during boot.
| | `source_priorities.related_activity_log` | `int` | `10` | Priority for `RelatedActivityLogSource`. **Note**: priority key only — entries from this source carry `type='activity_log'`, NOT `'related_activity_log'`. See [/concepts/how-it-works#type-taxonomy](/concepts/how-it-works#type-taxonomy). | | ||
| | `source_priorities.related_model` | `int` | `20` | Priority for `RelatedModelSource`. | | ||
| | `source_priorities.custom` | `int` | `30` | Priority for `CustomEventSource`. | | ||
| | `renderers` | `array` | `[]` | Event-or-type → renderer map. See [/essentials/customization#registration-channels](/essentials/customization#registration-channels). | |
There was a problem hiding this comment.
The renderers config key is documented as an “Event-or-type → renderer map”, but nothing in src/ loads and registers it into RendererRegistry. As written, users editing this key won’t see any effect; document it as reserved/unused (similar to cache.ttl_seconds) or implement support for it.
| | `renderers` | `array` | `[]` | Event-or-type → renderer map. See [/essentials/customization#registration-channels](/essentials/customization#registration-channels). | | |
| | `renderers` | `array` | `[]` | Reserved; not currently consulted by `RendererRegistry`. Editing this key has no effect. Use the supported registration channels described in [/essentials/customization#registration-channels](/essentials/customization#registration-channels). | |
| ## Removed key: `date_groups` | ||
|
|
||
| ::callout{icon="i-lucide-alert-triangle" color="warning"} | ||
| Earlier docs (and the published config still ships) a `date_groups` key listing 6 bucket labels (`today`, `yesterday`, `this_week`, `last_week`, `this_month`, `older`). |
There was a problem hiding this comment.
Section title “Removed key: date_groups” is misleading because the key still exists in the shipped config/activity-log.php (it’s just unused). Consider renaming to “Unused/Dead key” (and fix the sentence “published config still ships) a date_groups key” → “still ships with a date_groups key”).
| ## Removed key: `date_groups` | |
| ::callout{icon="i-lucide-alert-triangle" color="warning"} | |
| Earlier docs (and the published config still ships) a `date_groups` key listing 6 bucket labels (`today`, `yesterday`, `this_week`, `last_week`, `this_month`, `older`). | |
| ## Unused/Dead key: `date_groups` | |
| ::callout{icon="i-lucide-alert-triangle" color="warning"} | |
| Earlier docs (and the published config still ships with a `date_groups` key) list 6 bucket labels (`today`, `yesterday`, `this_week`, `last_week`, `this_month`, `older`). |
|
|
||
| ## Core building blocks | ||
|
|
||
| **Subject.** Any Eloquent model implementing `Relaticle\ActivityLog\Contracts\HasTimeline`. In practice you get this for free by using the `Relaticle\ActivityLog\Concerns\InteractsWithTimeline` trait, which provides `timeline()`, `paginateTimeline()`, and `forgetTimelineCache()`. The subject is passed into every source's `resolve()` call. |
There was a problem hiding this comment.
InteractsWithTimeline does not implement timeline()—it only provides paginateTimeline() and forgetTimelineCache() (the HasTimeline contract still requires consumers to define timeline(): TimelineBuilder). Update this sentence to avoid implying timeline() comes “for free” from the trait.
| **Subject.** Any Eloquent model implementing `Relaticle\ActivityLog\Contracts\HasTimeline`. In practice you get this for free by using the `Relaticle\ActivityLog\Concerns\InteractsWithTimeline` trait, which provides `timeline()`, `paginateTimeline()`, and `forgetTimelineCache()`. The subject is passed into every source's `resolve()` call. | |
| **Subject.** Any Eloquent model implementing `Relaticle\ActivityLog\Contracts\HasTimeline`. The `Relaticle\ActivityLog\Concerns\InteractsWithTimeline` trait provides helper methods such as `paginateTimeline()` and `forgetTimelineCache()`, but models still need to define `timeline(): TimelineBuilder` to satisfy the contract. The subject is passed into every source's `resolve()` call. |
Summary
Restructure the docs site from 8 pages to 13 focused pages following Spatie / Filament / Laravel docs IA conventions. Single-home policy: every concept has exactly one canonical page; cross-references everywhere else. Stops documenting four code/docs contradictions found during a source-code audit (filed as separate issues; see below). Adds Quick start, Concepts, Recipes (×2), Testing, Caching, and Configuration as new pages. Splits the kitchen-sink "API Reference" into Filament UI / Refining / Caching / Configuration. Folds "Database Schema" into Installation. Folds the Tailwind
@sourcedirective to a single home.Page tree
Spinoff issues (non-blocking; tracked separately)
The audit surfaced four doc/code contradictions and one perf smell. Docs ship honestly describing current behavior; code fixes are tracked as separate issues:
date_groupsconfig keyRelatedActivityLogSourceemitstype='activity_log'(filter mismatch)TimelineCache::forget()flushes the entire cache storeRelaticle\ActivityLog\ActivityLogPlugin(root namespace)RelatedActivityLogSourceloads all related rows unbounded (N+1 risk)The new docs reference these issues from "known limitation" callouts on the relevant pages (Configuration, Caching, Troubleshooting).
Test plan
cd docs && npm run devboots; every sidebar entry returns 200 (16 URLs verified)cd docs && npm run buildcompletes without errors (71 routes pre-rendered, 8.5s)grep -r "PLACEHOLDER\|TBD\|TODO" docs/content/returns no matchesseo:frontmatter2.essentials/paths or links remain@sourcedirective only in InstallationOut of scope (deliberate)