nodebb-plugin-rules-quiz

A NodeBB plugin that gates new (and optionally existing) users behind a configurable forum-rules quiz before they can post.

The goal: stop the constant flood of "I didn't know that was against the rules" posts by making every account read the rules and answer a few short questions before unlocking write access.

---

Features

• Multiple-choice rules quiz with single-choice, multi-choice, true/false, and free-text questions.
• Markdown + image support in question bodies; optional explanation shown after each answer.
• Per-question deep link back to the relevant section of your rules thread.
• Configurable gate scope: new users by default, or also existing users filtered by group / reputation / join date.
• Two block modes: block writing only (browse freely, gated at post time), or block all access.
• Per-reply and per-new-topic gates: require a fresh mini-quiz before each of the first N replies and the first M new topics (configurable per gate: question count, pass %, cooldown, how many posts/topics).
• Reputation exemption: users at/above a reputation threshold skip all gates.
• Pass criteria: all-or-nothing, percentage threshold, or "X correct out of Y".
• Failure handling: retry, cooldown, daily limit, or lock after N attempts. Admin chooses.
• On success: auto-add the user to a group (e.g. verified-rules) + welcome notification.
• Admin reports: pass/fail counters, hardest questions, full attempt log per user, alerts when a user fails 3+ times.
• i18n: Hebrew (RTL) and English out of the box.
• Bulk import of questions via JSON or CSV.

Compatibility

	Status
NodeBB 2.x	✅ tested
NodeBB 3.x	✅ tested
NodeBB 4.x	✅ tested
MongoDB	✅
Redis	✅
PostgreSQL	✅

The plugin only uses NodeBB's database abstraction layer, so all three storage backends are supported automatically.

Installation

From your NodeBB root directory:

./nodebb install nodebb-plugin-rules-quiz

Then activate it via ACP → Extend → Plugins and restart NodeBB.

Configuration

Open ACP → Plugins → Rules Quiz. Three tabs:

Settings

Section	What it controls
General	Master enable toggle, block mode, "notify admin after N failures", whether to log full answers
Applies To	Whether new users are gated, whether existing users are gated, target groups, min reputation, join-date window
Exempt Groups / Paths	Groups that always skip the quiz; URL prefixes that aren't gated
Rules	Whether to show a "read the rules first" gate, the URL of your rules thread, optional inline rules text, ack button label
Intro	Optional intro screen shown before the first question
Quiz	Sample size (0 = ask everything), shuffle questions/answers, pass mode, time limit
On Fail	Mode (retry / cooldown / lock_after_attempts / daily_limit), cooldown seconds, max attempts/day, lock threshold
On Success	Auto-add to group, send notification, post-pass redirect path
On Refuse	What happens if a user keeps refusing to take the quiz

Questions

Add, edit, delete, and bulk-import questions. The editor adapts to the question type (radio, checkbox, true/false, freetext).

Reports

• Live counters: how many users passed/failed in the last 30 days.
• "Hardest questions": the top 10 questions by failure count.
• Per-user attempt history: enter a UID, see every attempt with timestamps, scores, and (if enabled) full answer logs.
• Daily chart of pass/fail trend.

Importing questions

JSON shape

[
{
"type": "single",
"title": "What is allowed in the off-topic forum?",
"bodyMarkdown": "Optional **markdown** body.",
"imageUrl": "",
"ruleLinkUrl": "/topic/5489#rule-3",
"options": [
{ "id": "a", "text": "Anything", "correct": false },
{ "id": "b", "text": "On-topic only", "correct": false },
{ "id": "c", "text": "Per category rules","correct": true }
],
"explanationMarkdown": "Per the rules thread, each category has its own scope.",
"weight": 1,
"tags": ["off-topic"],
"sort": 100
}
]

type ∈ single | multi | truefalse | freetext. For freetext add answerText (or answerRegex) and omit options.

CSV shape

Columns:

type,title,bodyMarkdown,imageUrl,ruleLinkUrl,options,answerText,answerRegex,explanationMarkdown,weight,tags,sort

options encoded as semicolon-separated triples id|text|correctBool:

single,"What is allowed?",,,,"a|Anything|0;b|On-topic|1;c|Per category|0",,,"See rules.",1,off-topic,100

Tags accept JSON-array form (["a","b"]) or pipe-delimited (a|b).

API

All endpoints under /api/v3/plugins/rules-quiz.

User-facing

Method	Path	Purpose
GET	/quiz	JSON copy of the quiz page payload
POST	/ack	User acknowledges they've read the rules
POST	/submit	Submit { answers: { qid: value } } for scoring

Admin-facing (all require admin)

Method	Path	Purpose
GET	/admin/questions	List all questions
POST	/admin/questions	Create a question
PUT	/admin/questions/:qid	Update a question
DELETE	/admin/questions/:qid	Delete a question
POST	/admin/questions/import?format=json|csv	Bulk import
GET	/admin/settings	Read settings
PUT	/admin/settings	Save settings
GET	/admin/stats?from=…&to=…	Aggregated stats
GET	/admin/users/:uid/attempts	All attempts of a user

Architecture

 ┌─────────────────────────────┐
HTTP request ──► │ response:router.page hook │
│ lib/library.js#gate │
└──────────────┬──────────────┘
│ needsQuiz?
┌──────────────▼──────────────┐
│ lib/policy.js (pure) │
└──────────────┬──────────────┘
│ yes → redirect
┌──────────────▼──────────────┐
│ /quiz (controllers.js) │
│ ▸ rules ack screen │
│ ▸ intro screen │
│ ▸ quiz screen │
└──────────────┬──────────────┘
│ POST /submit
┌──────────────▼──────────────┐
│ score → applyOutcome → │
│ db.finishAttempt → notify │
└─────────────────────────────┘

i18n

Two locales bundled: en-GB and he (with full RTL support). To add a language, drop a new file at languages/<lang>/rulesquiz.json with the same key set as languages/en-GB/rulesquiz.json.

Development

nodebb-plugin-rules-quiz/
├─ library.js ← entry, hook handlers
├─ plugin.json ← NodeBB manifest
├─ package.json
├─ SPEC.md ← interface contract for contributors
├─ lib/
│ ├─ db.js ← all DB CRUD
│ ├─ defaults.js ← default settings + key namespace
│ ├─ policy.js ← pure scoring/gating logic
│ ├─ controllers.js ← HTTP controllers
│ ├─ routes.js ← route registration
│ ├─ notify.js ← notifications + group membership
│ └─ util.js ← admin gate, JSON helpers
├─ static/
│ ├─ templates/
│ │ ├─ quiz/index.tpl
│ │ ├─ quiz/result.tpl
│ │ └─ admin/plugins/rules-quiz.tpl
│ ├─ lib/
│ │ ├─ quiz.js ← user UI client
│ │ └─ admin.js ← ACP client
│ └─ style/
│ ├─ quiz.less
│ └─ admin.less
└─ languages/
├─ en-GB/rulesquiz.json
└─ he/rulesquiz.json

To test locally:

cd /path/to/NodeBB
ln -s /path/to/nodebb-plugin-rules-quiz node_modules/nodebb-plugin-rules-quiz
./nodebb activate nodebb-plugin-rules-quiz
./nodebb dev

License

MIT © 2026 bot-sync-up

---

תיעוד בעברית

תוסף NodeBB שמכריח משתמשים חדשים (ובאופן אופציונלי גם משתמשים קיימים) לעבור שאלון אמריקאי קצר על חוקי הפורום לפני שהם יכולים לפרסם.

המטרה: למנוע את הזרם הקבוע של "לא ידעתי שזה נגד החוקים" — כל משתמש חייב לקרוא את החוקים ולענות נכון על כמה שאלות לפני שנפתחת לו ההרשאה לכתוב.

יכולות עיקריות

• שאלון רב-ברירה: רדיו, צ'קבוקס, נכון/לא נכון, טקסט חופשי.
• תמיכה ב-Markdown ובתמונות בשאלות; הסבר אופציונלי אחרי כל תשובה.
• לינק ישיר לכל שאלה אל המקטע הרלוונטי באשכול החוקים.
• היקף הגיטינג גמיש: ברירת מחדל למשתמשים חדשים, אופציה גם למשתמשים קיימים לפי קבוצה / מוניטין / תאריך הצטרפות.
• שלושה מצבי חסימה: מודל רך, חסימת כתיבה בלבד, או חסימה מוחלטת.
• תנאי מעבר: הכל-או-לא-כלום, אחוז סף, או "X נכונות מתוך Y".
• טיפול בכישלון: ניסיון מיידי, cooldown, מגבלה יומית, או נעילה אחרי N ניסיונות.
• בהצלחה: הוספה אוטומטית לקבוצה (למשל verified-rules) + הודעת ברוכים הבאים.
• דו"ח מנהל: מי עבר/נכשל, השאלות הקשות ביותר, היסטוריית ניסיונות מלאה לכל משתמש, התראות על 3+ כישלונות.
• תמיכה מלאה בעברית RTL.

התקנה

מתיקיית הראשית של NodeBB:

./nodebb install nodebb-plugin-rules-quiz

ולאחר מכן הפעלה דרך ACP → תוספים ואתחול.

הגדרה

הכל בעמוד ACP → תוספים → Rules Quiz — שלוש לשוניות: הגדרות, שאלות, דו"חות.

תאימות

NodeBB 2.x / 3.x / 4.x. עובד אוטומטית עם MongoDB, Redis, או PostgreSQL.

רישוי

MIT — ראו קובץ הרישוי.