Grammar Admin Guide

How to create and manage grammar notes, categories, and exercises in ActiveAdmin.

All three resources are under the Grammar menu in the admin sidebar.

Grammar Categories

Categories organise grammar notes by topic within a language and CEFR level. Create categories before creating notes.

Creating a Category

  1. Go to Grammar > Grammar Categories > New.
  2. Fill in:
    • Target language – the language this category is for (e.g. fr).
    • Level – CEFR level (A1, A2, B1, B2, C1).
    • Name – descriptive topic name (e.g. “Verbs, Tenses & Conjugation”).
    • Position – display order within the level (0 = first).
  3. Save. The name must be unique per language + level combination.

Managing Categories

  • Edit a category to rename it or reorder with the position field.
  • Deleting a category nullifies the reference on its grammar notes (they become orphaned and must be reassigned).

Grammar Notes

Grammar notes are reference articles explaining a grammar concept. Content is written in GFM markdown and automatically rendered to HTML on save.

Creating a Note

  1. Go to Grammar > Grammar Notes > New.
  2. Fill in the Metadata section:
    • Target language – the language the note is written in.
    • Grammar category – required. Select from the dropdown (shows LANG LEVEL - Name).
    • Status – starts as draft (see Status Workflow below).
    • Level – CEFR level for the note itself.
  3. Fill in the Content section:
    • Title – the note title in the target language.
    • Note markdown – the full article content in GFM markdown. Supports tables, bold, italic, headings, lists. The textarea is monospace and 25 rows tall.
  4. Optionally add Translations (see below).
  5. Save.

Status Workflow

Status Meaning Visible to users?
draft Work in progress, not ready for review No
reviewable Content complete, waiting for someone to review No
published Approved and live Yes

Typical flow: draft -> reviewable -> published.

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

Editing a Note

  • From the index, click a note to view it, then click Edit Grammar Note.
  • The admin show page title links to the public user-facing view (opens in a new tab) so you can preview how it looks.

Markdown Tips

The note_markdown field accepts GitHub Flavored Markdown (GFM):

  • **bold** for bold, *italic* for italic
  • ## Heading for section headings
  • Pipe tables for conjugation grids: 
    | Subject | Aller |
|---------|-------|
| Je      | vais  |
| Tu      | vas   |
  • Bullet lists with - or *

The rendered HTML is cached automatically on save. You do not need to edit the note field.

Translations

Each grammar note can have translations in fluent languages (e.g. English, Spanish) so learners can toggle between target and fluent language views.

Adding a Translation

  1. Edit a grammar note.
  2. In the Translations section, click Add New Grammar Note Translation.
  3. Fill in:
    • Language – the fluent language (e.g. en).
    • Title – translated title.
    • Note markdown – translated content in markdown.
  4. Save. The markdown is rendered to HTML automatically.

Each language can only appear once per grammar note (enforced by a uniqueness constraint).

Removing a Translation

Check the Remove checkbox next to a translation and save.

Grammar Exercises

Exercises are fill-in-the-blank questions attached to a grammar note. They link a sentence to the note and define a word or phrase the learner must fill in.

Creating an Exercise (Two-Step Flow)

Exercises can only be created from a grammar note’s show page.

Step 1 – Select a sentence:

  1. From a grammar note’s admin show page, click Add Exercise.
  2. The grammar note is pre-selected and read-only. The sentence search is filtered to the note’s target language.
  3. Type in the Sentence Search box to find a published sentence. Results appear as you type (minimum 2 characters).
  4. Click a sentence to select it.
  5. Set the Position (display order, 0 = first).
  6. Click Create. The exercise is saved as a draft and you are redirected to the edit form.

Step 2 – Define the blank:

  1. The selected sentence is displayed at the top.
  2. In the Blank text field, type the exact word(s) from the sentence that the learner must fill in (e.g. vais from “Je vais au marche”).
  3. The system automatically calculates the character positions (blank_start and blank_end) on save. You do not enter these manually.
  4. Set the Exercise type (free_text or multiple_choice).
  5. Optionally add a Hint and Translation.
  6. For multiple choice: enter up to 3 incorrect options (distractors) in the distractor fields. The correct answer is the blank text.
  7. Save.

The Show Page Preview

The exercise show page displays a Preview row showing the sentence with the blank replaced by underscores (one per character), e.g.: Je ____ au marche.

Editing an Exercise

  • From the grammar note show page, click Edit next to an exercise.
  • From the exercises index, click an exercise to view it, then click Edit.
  • You can change the blank text, exercise type, distractors, hint, and translation.
  • You cannot change the sentence after creation. To use a different sentence, delete the exercise and create a new one.

Exercise Types

Type Behaviour
free_text Learner types the answer. Always available.
multiple_choice Learner picks from options. The blank text is the correct answer; distractors are the wrong options.

An exercise is always free_text by default. You can additionally make it multiple_choice by changing the type and adding distractors.

Data Model Summary 

GrammarCategory
  has_many :grammar_notes

GrammarNote
  belongs_to :grammar_category (required)
  has_many :grammar_note_translations
  has_many :grammar_exercises
  has_many :sentences (through grammar_exercises)

GrammarNoteTranslation
  belongs_to :grammar_note

GrammarExercise
  belongs_to :grammar_note
  belongs_to :sentence (optional until step 2)

Common Tasks

Task Where
Create a category Grammar > Grammar Categories > New
Create a grammar note Grammar > Grammar Notes > New
Add a translation Edit a grammar note > Translations section
Add an exercise Grammar note show page > Add Exercise
Preview how a note looks to users Click the title link on the grammar note show page
Filter notes by language Use the Target Language dropdown filter on the index
Find exercises for a note Grammar note show page > Exercises panel
This site uses Just the Docs, a documentation theme for Jekyll.