User Keywords

This page defines the user-extensible vocabulary for flexible content tagging and organization. User keywords are configuration-driven and defined in config/app-default-config.json under ngdpbase.userKeywords.

Vocabulary model note (2026-07): user keywords are the human tagging bucket — what a page is about, chosen by people. Two kinds of terms no longer belong here:

• Lifecycle state (draft / review / published) now lives in the single-valued status: frontmatter field, set via the Status select in the editor. Absent status means published. Legacy pages still carrying these as keywords are migrated automatically on save.
• capture (pages created by the capture bookmarklet) is machine provenance and now lives in System Keywords.

User Keywords is part of Page Metadata Documentation

"ngdpbase.maximum.user-keywords":

"ngdpbase.maximum.user-keywords":

Configuration Structure

Showing Current User Keywords

Configuration Properties

Each user keyword has the following properties:

Usage in Page Metadata

User keywords are used in the user-keywords frontmatter field as an array:

---
title: Example Medical Research Page
system-category: documentation
status: review
user-keywords:
  - medicine
  - research
slug: medical-research-example
---

Metadata Rules

• Maximum Keywords: Up to 5 keywords per page (configurable via ngdpbase.maximum.user-keywords)
• Case Sensitivity: Keywords are case-insensitive
• Array Format: Must be YAML array format
• Validation: Warnings for keywords not in configuration (but still allowed)

User Keywords vs System Categories

Example Usage

---
title: Introduction to Oceanography
system-category: documentation  # ← Single category (WHERE to store)
user-keywords:                   # ← Multiple keywords (WHAT it's about)
  - oceanography
  - geology
slug: intro-oceanography
---

Backend Integration

UI Population

The backend reads ngdpbase.userKeywords configuration to:

• Populate keyword dropdown/autocomplete in the editor
• Validate keywords during page save
• Generate keyword suggestions based on content
• Enforce access control rules

Keyword Validation

The ValidationManager can validate user keywords:

• Check if keyword exists in configuration
• Warn about unknown keywords (but allow them)
• Enforce maximum keyword limit
• Validate access control restrictions

Proposing New Keywords

Users with Editor role or higher can propose new keywords:

1. Identify Need: Determine if existing keywords don't fit
2. Check Documentation: Review this page for existing keywords
3. Create Proposal: Document the keyword purpose and usage
4. Submit Request: Contact admin or create a ticket
5. Admin Reviews: Admin adds to custom config if approved

Proposal Template

Future Enhancement

**Keyword**: astronomy
**Category**: subject
**Description**: Astronomy and space science content
**Reason**: We have 15 pages about astronomy with no appropriate keyword
**Schema.org Mapping**: (optional) AstronomicalObject

Keyword Usage Statistics

>

Note: Statistics tracking not yet implemented - Future Enhancement

Migration Notes

From Old System

If migrating from a different keyword system:

1. Map Old → New: Create mapping of old keywords to new keywords
2. Update Metadata: Batch update all pages with new keywords
3. Add Custom Config: Add frequently-used old keywords to custom config
4. Document Changes: Update this page with migration details

Related pages

• System Keywords - System category definitions
• System Keywords - System-level keywords
• ValidationManager Documentation
• Access Control Lists - ACL system overview