Expand the pragmatics guide for ActivityPub objects#709
Expand the pragmatics guide for ActivityPub objects#709dahlia wants to merge 9 commits intofedify-dev:mainfrom
Conversation
Add the first pragmatics object entry so Fedify users can map Note content warnings and attachments to Mastodon UI when publishing short posts. fedify-dev#28 Assisted-by: OpenCode:gpt-5.4
Explain how Mastodon renders Article objects with a title, canonical URL, and hashtags so Fedify users can choose the right object type for long-form posts. This also tightens the highlighted line ranges in the existing Note and new Article examples so the docs emphasize the relevant properties more clearly. fedify-dev#28 Assisted-by: OpenCode:gpt-5.4
Describe how Mastodon turns Question objects into poll UI, including the mapping from options to choices and from metadata like voters and endTime to the footer below. fedify-dev#28 Assisted-by: OpenCode:gpt-5.4
Tighten the new pragmatics examples by switching from line-range highlights to field-level highlights, and crop the Mastodon screenshots so they focus on the relevant UI instead of the search chrome. Also ignore temporary Playwright and demo-server artifacts used while collecting documentation screenshots. fedify-dev#28 Assisted-by: OpenCode:gpt-5.4
Document how Fedify object properties map to Mastodon UI for short notes, content warnings, poll options, mentions, hashtags, and custom emoji. The new screenshots are refreshed at higher resolution and now match the example payloads, including separate views for single-choice and multiple-choice poll results. fedify-dev#28 Assisted-by: OpenCode:gpt-5.4
Make the object-property subheadings follow the same style as the Actors section by using bare property names, and expand the inclusiveOptions explanation with both the choice view and the results view. fedify-dev#28 Assisted-by: OpenCode:gpt-5.4
Update the pragmatics examples to match Mastodon's expected anchor attributes for mentions and hashtags, so the sample HTML matches how those tags are actually recognized in remote clients. Also document the hashtag context menu that Mastodon opens from a rendered hashtag instead of treating it as a plain external link. fedify-dev#28 Assisted-by: OpenCode:gpt-5.4
📝 WalkthroughWalkthroughAdds a new "Objects" section to the pragmatics documentation describing fediverse content object types and updates Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
@codex review |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/manual/pragmatics.md`:
- Around line 429-431: The three list entries for Article, Note, and Question
are repetitive because each starts with "represents"; update the wording to vary
phrasing for readability by rewording one or two items (for example: "`Article`
— a multi-paragraph written work.", "`Note` — a short post.", "`Question` — a
poll.") while preserving the same meanings and the symbols Article, Note, and
Question.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: e2b312e5-9a96-442a-97ac-2c462328e8cd
⛔ Files ignored due to path filters (10)
docs/manual/pragmatics/mastodon-article.pngis excluded by!**/*.pngdocs/manual/pragmatics/mastodon-emoji.pngis excluded by!**/*.pngdocs/manual/pragmatics/mastodon-hashtag-dropdown.pngis excluded by!**/*.pngdocs/manual/pragmatics/mastodon-hashtag.pngis excluded by!**/*.pngdocs/manual/pragmatics/mastodon-mention.pngis excluded by!**/*.pngdocs/manual/pragmatics/mastodon-note-body.pngis excluded by!**/*.pngdocs/manual/pragmatics/mastodon-note.pngis excluded by!**/*.pngdocs/manual/pragmatics/mastodon-question-multi-choices.pngis excluded by!**/*.pngdocs/manual/pragmatics/mastodon-question-multi.pngis excluded by!**/*.pngdocs/manual/pragmatics/mastodon-question.pngis excluded by!**/*.png
📒 Files selected for processing (2)
.gitignoredocs/manual/pragmatics.md
There was a problem hiding this comment.
Pull request overview
Expands the manual’s pragmatics guide from actor-focused details to practical, Mastodon-oriented rendering expectations for common ActivityPub object types, aiming to reduce interoperability surprises for Fedify users.
Changes:
- Added object-level guidance and examples for
Note,Article,Question,Mention,Hashtag, andEmoji, including Mastodon-specific HTML/tagging conventions. - Documented poll rendering behavior (option vote counts vs.
voters) with single- and multi-choice examples. - Refreshed/added Mastodon UI screenshots and updated
.gitignorefor local tooling artifacts.
Reviewed changes
Copilot reviewed 1 out of 12 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| docs/manual/pragmatics.md | Adds a new “Objects” section with pragmatic rendering guidance + example objects and screenshots. |
| docs/manual/pragmatics/mastodon-mention.png | Updated screenshot illustrating mention rendering. |
| docs/manual/pragmatics/mastodon-hashtag.png | Updated screenshot illustrating hashtag rendering. |
| docs/manual/pragmatics/mastodon-emoji.png | Updated screenshot illustrating custom emoji rendering. |
| .gitignore | Ignores .playwright-mcp/ and tmp/ directories. |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the .gitignore file to exclude Playwright and temporary directories and adds a comprehensive 'Objects' section to the pragmatics manual. This new documentation covers the usage and rendering of Note, Article, Question, Mention, Hashtag, and Emoji types within the fediverse, specifically focusing on Mastodon compatibility. Feedback suggests replacing the endTime property with closed in poll examples to ensure better interoperability with Mastodon and other ActivityPub implementations.
Codecov Report✅ All modified and coverable lines are covered by tests. 🚀 New features to boost your workflow:
|
Update the pragmatics guide to use `closed` instead of `endTime` in the poll examples and surrounding explanation, so the documented pattern matches Mastodon's poll deadline handling more closely. fedify-dev#709 (comment) fedify-dev#709 (comment) fedify-dev#709 (comment) Assisted-by: OpenCode:gpt-5.4
Rephrase the opening object list in the pragmatics guide so the entries do not all begin with the same verb, while keeping the same meanings and structure. fedify-dev#709 (comment) Assisted-by: OpenCode:gpt-5.4
|
@codex review |
|
/gemini review |
dahlia
moved this to In review
in STF 2025–2026 Milestone 5: Comprehensive Documentation and Examples
|
Codex Review: Didn't find any major issues. Keep them coming! ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
There was a problem hiding this comment.
Code Review
This pull request updates the .gitignore file to exclude .playwright-mcp/ and tmp/ directories. It also adds a substantial new section to docs/manual/pragmatics.md titled "Objects", which details the rendering conventions for various ActivityPub object types such as Note, Article, Question, Mention, Hashtag, and Emoji within the fediverse, including code examples and Mastodon-specific implementation notes. I have no feedback to provide.
|
Pre-release has been published for this pull request: Packages
DocumentationThe docs for this pull request have been published: |
issues-auto-labeler
Bot
added
activitypub/interop
dahlia
removed
component/federation
Closes #28.
Read it at https://bd790823.fedify.pages.dev/manual/pragmatics#objects.
Summary
This expands docs/manual/pragmatics.md beyond actor-focused guidance and documents how common ActivityPub object types are interpreted by Mastodon in practice.
It adds pragmatic guidance for
Note,Article,Question,Mention,Hashtag, andEmoji, including the HTML and tagging conventions that Mastodon expects for mentions and hashtags, and the way poll option counts map to rendered results.It also refreshes the supporting screenshots in docs/manual/pragmatics/ so they match the documented examples, with separate captures for content warnings, single-choice polls, multiple-choice polls, hashtag interactions, and custom emoji rendering.
Why
The existing pragmatics guide was useful for actor metadata, but it left a gap around object-level behavior. In practice, this is where Fedify users tend to run into interoperability problems: an object may be valid ActivityPub, but remote software does not render it the way they expect.
This change makes those expectations explicit by tying concrete object properties to concrete Mastodon UI behavior. That should make the guide more useful when someone is deciding which object type to publish, how to structure
content, and how to pair HTML markup withtagsso remote clients treat mentions, hashtags, emoji, and polls correctly.Scope
The changes are limited to docs/manual/pragmatics.md and the screenshots under docs/manual/pragmatics/.
Verification
mise run fmtmise run docs:build