Grammar Notes

Grammar notes are reference articles that explain grammar concepts in a learner’s target language.

Overview

Each grammar note represents a single grammar concept (e.g. “The Subjunctive”, “Adjective Agreement”) with content authored in the target language (e.g. French). Content is written in markdown and rendered to HTML when saved.

Grammar notes belong to a grammar category which groups related notes by topic (e.g. “Verbs, Tenses & Conjugation”) within a CEFR level and language.

CEFR Levels

Grammar notes and categories use CEFR levels: A1, A2, B1, B2, C1. C2 is not supported.

Grammar Categories

Categories group grammar notes by topic within a language and CEFR level. Example categories for French A1:

Verbs, Tenses & Conjugation
Pronouns
Nouns & Articles
Numbers, Time & Date
Adjectives & Adverbs
Prepositions & Conjunctions
Idiomatic Usage and Structures
Negative Words & Constructions

Categories are managed via ActiveAdmin and displayed in a read-only index for users.

Content Storage

title – note title in the target language (plain column)
note_markdown – markdown source in the target language
note – rendered HTML, cached on save via Kramdown (GFM)
target_language – e.g. “fr”
level – CEFR level (a1-c1)
status – draft, reviewable, published

Translations

Each grammar note can have translations in one or more fluent languages via GrammarNoteTranslation. Each translation has its own title, note_markdown, and note (rendered HTML). Translations also use the Markdownable concern.

Exercises

Grammar notes can have fill-in-the-blank exercises (GrammarExercise). Each exercise links a sentence to the grammar note and defines a blank (a word or phrase the learner must fill in). Exercises support free text and multiple choice types. See docs/features/admin_tools/grammar_admin_guide.md for the creation workflow.

Status Workflow

draft – work in progress, not ready for review
reviewable – content is ready, awaiting review before publishing
published – visible to all logged-in users

Only published notes appear in the user-facing index and show views.

Access Control

User views (index/show): Any logged-in user can browse. Only published notes are visible.
Editing: All creation and editing is done through ActiveAdmin. No front-end editing.
ActiveAdmin: Full CRUD for grammar notes, categories, and exercises.

Bookmarks

Grammar notes are bookmarkable. Users can bookmark notes from the index or show page, and filter the index to show only bookmarked notes.

Routes (User-Facing)

Path	Action	Description
`GET /grammar_notes`	index	List published notes
`GET /grammar`	index (alias)	Same as above
`GET /grammar_notes/:id`	show	View a single published note
`GET /grammar_categories`	index	List categories for user’s target language
`GET /grammar_categories/:id`	show	View notes in a category