Glossary System

An SEO-friendly glossary add-on for Larapen with A–Z navigation, categories, search, and structured data markup for definitions and technical terms.

Use Cases

Technical Documentation Site

You run a software product site and want to help users understand technical jargon.

• Create categories like “Programming”, “Networking”, “Security”.
• Add terms with short definitions and extended content with code examples.
• Use abbreviations (e.g., API, DNS, SSL) for quick reference.
• Structured data markup helps search engines display definitions in rich snippets.

Industry Knowledge Base

You maintain a professional website in finance, healthcare, or legal services and need a glossary of industry terms.

• Group terms by domain (e.g., “Accounting”, “Tax”, “Compliance”).
• Provide clear, translatable definitions in multiple languages.
• Use the paginated display mode for glossaries with hundreds of entries.

Educational Website

A school or training platform wants students to quickly look up concepts.

• Students browse by letter or search for terms.
• Related terms link to each other for deeper learning.
• View counts help identify the most-referenced terms.

Requirements

• Larapen CMS v1.0.0 or later
• PHP 8.3+
• MySQL 8.0+

Installation

Step 1: Place the Add-on

Copy or symlink the glossary folder into your Larapen "extensions/addons" directory:

Step 2: Activate the Add-on

Go to Admin → Add-ons → Installed Add-ons and activate Glossary System.

Step 3: Run Migrations

This creates the glossary_terms table. Categories are stored in the core categories table with categorizable_type = 'glossary'.

Step 4: Set Permissions

The add-on registers 10 permissions (see Permissions). Assign them to admin roles via Admin → Users → Roles & Permissions.

Step 5: Configure (Optional)

Navigate to Admin → Glossary → Settings to choose the display mode and items per page. Defaults work out of the box. See Configuration.

Step 6: Build Theme Assets

If your active theme includes glossary-specific SCSS files, rebuild the Vite manifest:

Configuration

Configuration defaults are defined in config/glossary.php and can be overridden from the admin panel at Admin → Glossary → Settings (stored in the settings table, group glossary).

Setting	Description	Default
glossary_display_mode	Front-end display mode: grouped (all terms grouped by letter) or paginated (paginated list).	grouped
glossary_per_page	Number of terms per page in paginated mode, search results, letter filtering, and category filtering.	20

Config File Defaults

Admin: Terms

The Terms page (Glossary → All Terms) is the primary management interface for glossary entries.

Terms List

A paginated table (20 per page by default) showing:

• Letter: the first letter of the term, displayed as a badge
• Term: the term name with a truncated definition preview below
• Category: assigned category badge (or dash if uncategorized)
• Abbreviation: shown as inline code (e.g., API, CSS)
• Status: colored badge (Draft/Published/Archived)
• Views: front-end view count

Per-term actions: Edit, Delete (with confirmation).

Filtering

The listing supports three filter controls:

• Search: text input that searches across term names, definitions, and abbreviations
• Status filter: dropdown to filter by Draft, Published, or Archived
• Category filter: dropdown to filter by glossary category

Creating & Editing Terms

The create/edit form is organized into sections:

Content (Translatable)

A language selector allows switching between active languages. For each language:

• Term: the term name (required for the default language)
• Slug: URL-friendly slug (auto-generated if left empty)
• Definition: short definition text (required for the default language)
• Extended Content: longer explanation, examples, or rich content

SEO & Meta (Translatable)

• Meta Title: up to 70 characters
• Meta Description: up to 160 characters

Publishing Sidebar

• Status: Draft, Published, or Archived
• Category: select from glossary categories (optional)
• Abbreviation: short form or acronym (e.g., API, CSS, ML): up to 50 characters

Admin: Categories

The Categories page (Glossary → Categories) manages glossary categories using the core unified category system.

Categories List

A paginated table showing categories with nesting indicators:

• Name: with indentation for nested categories
• Slug: shown as inline code
• Status: Active or Inactive badge

Per-category actions: Edit, Delete (with confirmation).

Creating & Editing Categories

Categories use the core StoreCategoryRequest / UpdateCategoryRequest form requests. All glossary categories are stored in the categories table with categorizable_type = 'glossary'.

Category fields include translatable name, slug, description, meta title, and meta description, plus an optional parent category for nesting.

Admin: Settings

The settings page (Glossary → Settings) configures front-end display behavior.

Display Mode

Two mutually exclusive display modes, selectable via styled radio cards:

• Grouped by Letter: all terms loaded at once, organized under A–Z headings. Best for small-to-medium glossaries (fewer than ~200 terms).
• Paginated List: terms loaded page by page with pagination controls. Recommended for large glossaries with many entries.

Items Per Page

Dropdown selector with options: 10, 15, 20, 30, 50, 100. Controls pagination in paginated mode, search results, letter filtering, and category filtering.

Settings are stored in the settings table (group: glossary) and override the defaults in config/glossary.php.

Front-end: Glossary Index

The glossary index page is the main entry point for visitors, available at /{locale}/glossary.

Layout

• A–Z navigation bar: an alphabetical letter strip at the top. Letters with published terms are clickable; letters without terms are grayed out. An “All” link shows all terms.
• Search bar: full-text search across term names, definitions, and abbreviations.
• Category filter: optional dropdown or sidebar to filter by category.

Grouped Mode

When glossary_display_mode = 'grouped', all published terms are loaded at once and displayed under alphabetical section headings (A, B, C…). Each term shows its name, a truncated definition, abbreviation (if any), and category badge.

Paginated Mode

When glossary_display_mode = 'paginated', terms are paginated according to the glossary_per_page setting. Standard Laravel pagination links appear at the bottom.

Search

When a search query is submitted, the system always returns paginated results regardless of the configured display mode. The search matches against term names, definitions, and abbreviations in the current locale.

Front-end: Letter Filtering

Clicking a letter in the A–Z navigation navigates to /{locale}/glossary/letter/{letter}.

This page shows all published terms starting with the selected letter, paginated according to the per-page setting. The A–Z navigation bar remains visible with the active letter highlighted.

Only single alphanumeric characters are accepted (validated by the route constraint [A-Za-z0-9]).

Front-end: Category Filtering

Category pages are available at /{locale}/glossary/category/{slug}.

The category slug is translatable: each language can have its own URL-friendly slug. The controller resolves the category by slug in the current locale and shows all terms in that category, paginated. Alternate URLs are shared for the language switcher.

Front-end: Term Detail Page

Each term has a dedicated page at /{locale}/glossary/{slug}.

Page Content

• Letter badge: large letter indicator
• Term title (h1)
• Abbreviation: shown if set (with hash icon)
• Category badge: clickable link to the category page
• Definition: the core definition text
• Extended content: longer explanation, examples, or rich content
• Related terms: up to 5 terms from the same category, linking for further exploration

Breadcrumbs

Full breadcrumb trail: Home → Glossary → Letter → Category (if assigned) → Term.

View Counter

Each time a term detail page is loaded, the view_count is incremented. This count is visible in the admin listing and can be displayed on the front-end.

Language Switcher

Alternate URLs are shared for the language switcher, using the term’s translatable slug in each language via share_alternate_urls().

SEO & Structured Data

Meta Tags

Each page generates appropriate meta tags via SeoService::getMetaTags():

• Index page: uses the configured glossary title and description
• Letter page: “Glossary: Letter {letter}”
• Category page: uses the category’s meta title/description (falls back to name)
• Term detail: uses the term’s meta title (falls back to “{term}: Definition & Meaning”) and meta description (falls back to truncated definition, 160 chars)

Structured Data

The term detail page supports Schema.org DefinedTerm structured data markup, which helps search engines understand and potentially display definitions as rich snippets in search results.

Updating

Step 1: Replace Files

Replace the add-on directory with the new version.

Step 2: Run Migrations

Step 3: Rebuild Assets

Step 4: Clear Caches

Step 5: Verify

Visit Admin → Glossary → All Terms and the front-end glossary page to confirm everything works correctly.

Troubleshooting

Glossary page shows “No terms found”

• Ensure at least one term has Published status and a published_at date in the past.
• Draft and Archived terms are not shown on the front-end.
• If using category filtering, verify the category has published terms assigned to it.

A–Z navigation shows no clickable letters

The letter navigation only highlights letters that have at least one published term. Add and publish terms to populate the navigation.

Term detail page returns 404

• The term must be published (status = published and published_at ≤ now()).
• Verify the slug matches the current locale. Each language has its own translatable slug.
• Check that the slug does not conflict with other routes (e.g., letter or category).

Categories not appearing in the filter

• Categories must have is_active = true in the categories table.
• Categories must have categorizable_type = 'glossary'.
• Ensure you are creating categories through Admin → Glossary → Categories, not through another add-on’s category manager.

Letter is not auto-derived correctly

The letter column is derived from the first character of the term name (using the English translation, or the first available locale). If the term starts with a non-ASCII character, the letter may not map to A–Z. Terms starting with numbers use the digit as their letter.

Vite manifest error: “Unable to locate file”

If you see this error for glossary SCSS files, rebuild the Vite manifest:

This is required after adding new SCSS or JS files to theme asset directories.

Settings not taking effect

• Clear the config cache: php artisan config:clear
• Settings saved in the admin panel (stored in the settings table) override the defaults in config/glossary.php.
• Verify the settings group is glossary in the database.

Search returns no results

Search matches against the current locale’s term name and definition, plus the abbreviation field (which is not translatable). Ensure the search query matches content in the active language.