Skip to main content
Discussions power community engagement on Aya through threaded comments with voting, nesting, and moderation tools.

​
Overview

The discussion system supports:
  • Threaded comments with up to 6 levels of nesting
  • Upvote/downvote scoring with vote counts
  • Comment sorting (hot, newest, oldest)
  • Pin important comments
  • Hide spam or inappropriate comments
  • Lock threads to prevent new comments

​
Discussion Threads

Threads are created automatically when:
  • A story has feat_discussions enabled
  • A profile has discussions module enabled
Each thread is anchored to either a story or profile and tracks:
  • Total comment count
  • Lock status
  • Created/updated timestamps

​
Creating Comments

1

Navigate to story or profile

Open any story or profile with discussions enabled
2

Write your comment

Use the comment box to write content (3-10,000 characters)
Comments support plain text. Markdown rendering may be added in future versions.
3

Submit comment

Your comment appears immediately in the thread

​
Reply to Comments

1

Click reply on any comment

Each comment has a reply button
2

Write your reply

Reply box appears nested under the parent comment
3

Submit reply

Reply is nested up to 6 levels deep with automatic depth tracking
Maximum nesting depth is 6 levels. Beyond this, replies appear at level 6 to maintain readability.

​
Comment Content

Requirements:
  • Minimum length: 3 characters
  • Maximum length: 10,000 characters
  • Must be authenticated user
  • Thread must not be locked
Displayed Information:
  • Author profile (name, picture, slug)
  • Comment content
  • Vote score (upvotes - downvotes)
  • Individual upvote/downvote counts
  • Reply count
  • Pinned status badge
  • Hidden status (if applicable)
  • Edited indicator
  • Created/updated timestamps

​
Voting System

Upvote

+1 to comment score, shows your appreciation

Downvote

-1 to comment score, signals disagreement

​
How Voting Works

1

Cast your vote

Click upvote or downvote arrow on any comment
2

Vote is recorded

Your vote direction is stored and displayed to you
3

Score updated

Comment score = upvotes - downvotes
4

Change your vote

Click the same direction to remove vote, or opposite direction to change
Vote Statistics:
  • vote_score: Net score (upvotes minus downvotes)
  • upvote_count: Total number of upvotes
  • downvote_count: Total number of downvotes
  • viewer_vote_direction: Your current vote (1, -1, or 0)

​
Comment Sorting

Sorts by engagement score combining vote score and recency. Surfaces trending discussions.Algorithm weights:
  • Recent comments with positive scores rank higher
  • Older comments with very high scores remain visible
  • Balances freshness and quality
Shows most recent comments first. Best for following ongoing conversations.
Shows oldest comments first. Useful for reading discussions chronologically.
Pinned comments always appear at the top regardless of sort mode.

​
Moderation Features

​
Pinning Comments

Who can pin:
  • Story authors
  • Profile maintainers and above
  • Admin users
Use cases:
  • Highlight important announcements
  • Feature the best answer
  • Provide context updates
1

Open comment menu

Click the moderation menu on any comment
2

Select 'Pin comment'

Comment moves to top of thread with pin badge
3

Unpin if needed

Select ‘Unpin comment’ to return to normal position

​
Hiding Comments

Who can hide:
  • Comment author (hide their own)
  • Story authors
  • Profile maintainers and above
  • Admin users
What happens:
  • Comment marked with is_hidden: true
  • Hidden from normal view (unless moderator)
  • Moderators see hidden comments with indicator
  • Can be unhidden at any time
Use hide instead of delete to preserve thread structure while removing inappropriate content.

​
Locking Threads

Who can lock:
  • Story authors
  • Profile owners
  • Admin users
Effect:
  • No new comments can be created
  • No replies to existing comments
  • Existing comments remain visible
  • Voting still enabled
Use cases:
  • Archive old discussions
  • Prevent off-topic tangents
  • Close resolved threads
  • Prevent brigading
1

Open thread settings

Access moderation panel on story or profile
2

Lock thread

Toggle lock status to prevent new comments
3

Display lock indicator

Users see locked icon and cannot add comments

​
Editing Comments

1

Click edit on your comment

Only available on your own comments
2

Modify content

Update text while maintaining character limits
3

Save changes

Comment shows “edited” indicator with updated timestamp
Comment edits are tracked via is_edited flag and updated_at timestamp. Edit history is not currently preserved.

​
Deleting Comments

Who can delete:
  • Comment author
  • Profile maintainers and above (for comments on their profiles/stories)
  • Admin users
Deletion is permanent and cannot be undone. Consider using hide instead for moderation purposes.

​
Permission System

​
Creating Comments

  • Must be authenticated
  • Thread must not be locked
  • Must have access to view the story/profile

​
Editing Comments

  • Must be comment author
  • Thread must not be locked

​
Moderation Actions

Pin/Hide/Delete:
  • Comment author (own comments only)
  • Story author (on their stories)
  • Profile maintainers+ (on their profiles/stories)
  • Admin users (globally)
Lock Thread:
  • Story author (on their stories)
  • Profile owners (on their profiles)
  • Admin users (globally)

​
Pagination

Default Page Size

25 comments per page

Maximum Page Size

100 comments per page
Comments are paginated with:
  • limit: Number of comments per page (default 25, max 100)
  • offset: Starting position for pagination
  • Parent ID filtering for nested replies

​
Nested Thread Display

Comments display with visual nesting: 
┌─ Comment (Depth 0)
│  └─ Reply (Depth 1)
│     └─ Reply (Depth 2)
│        └─ Reply (Depth 3)
│           └─ Reply (Depth 4)
│              └─ Reply (Depth 5)
│                 └─ Reply (Depth 6 - Max)
Reply Count: Each comment shows total direct replies, helping users navigate conversations.

​
Viewing Hidden Comments

For Moderators:
  • Hidden comments appear with visual indicator
  • Can view full content
  • Option to unhide
For Regular Users:
  • Hidden comments not displayed by default
  • May see “comment hidden” placeholder
  • Cannot view content unless author

​
Discussion Statistics

Thread statistics provide engagement metrics:
  • comment_count: Total comments in thread
  • Per-comment reply_count: Direct replies only
  • Vote statistics per comment

​
Enabling Discussions

​
On Stories

Set feat_discussions: true when creating or editing a story: 
{
  "title": "My Article",
  "feat_discussions": true
}
Or use profile default setting: 
{
  "option_story_discussions_by_default": true
}

​
On Profiles

Set profile feature visibility: 
{
  "feature_discussions": "public" // or "hidden" or "disabled"
}
  • Public: Discussions shown in navigation
  • Hidden: Discussions enabled but not in nav
  • Disabled: Discussions return 404

​
Best Practices

  • Pin important context at the top
  • Hide spam immediately to maintain quality
  • Lock threads only when necessary (archives, resolved topics)
  • Respond to questions to encourage engagement
  • Set clear community guidelines
  • Be respectful and constructive
  • Use replies to maintain conversation threads
  • Upvote valuable contributions
  • Edit typos rather than deleting and reposting
  • Stay on topic
  • Use pinned comments for updates
  • Consider locking resolved discussions
  • Monitor for quality control
  • Set expectations in story summaries

​
Next Steps

Stories

Learn how to enable discussions on stories

Profiles

Configure profile discussion settings

Communities

Build engaged communities with discussions

Mailbox

Manage direct communication with members

Build docs developers (and LLMs) love

Get started for freeTalk to us