Dictionary System Guide

This guide explains how to use the dictionary system for managing vocabulary notes with English-Urdu translations using YAML data files and accordion rendering.

System Overview

The dictionary system consists of:

1. Content Pages: Markdown files in content/docs/dictionary/[topic]/index.md
2. Data Files: YAML files in data/dictionary/[topic]/vocabulary.yaml
3. Shortcodes: Reusable components for rendering vocabulary
4. Archetype: Template for creating new dictionary pages

Architecture

 1.
 2├── content/docs/dictionary/
 3│   ├── _index.md                 # Main dictionary index
 4│   └── [topic-name]/
 5│       └── index.md              # Topic page (renders from data)
 6│
 7├── data/dictionary/
 8│   └── [topic-name]/
 9│       └── vocabulary.yaml       # Vocabulary data
10│
11├── layouts/shortcodes/
12│   ├── vocabulary-accordion.html  # Accordion renderer
13│   └── vocabulary-list.html       # Table renderer
14│
15└── archetypes/
16    └── dictionary.md              # Template for new pages

Creating a New Dictionary Topic

Step 1: Create Content Page

Use Hugo’s archetype command:

1hugo new content/docs/dictionary/[topic-name]/index.md --kind dictionary

Example:

1hugo new content/docs/dictionary/ibm-rag-course/index.md --kind dictionary

Step 2: Create Data File

Create the YAML file structure:

1mkdir -p data/dictionary/[topic-name]
2touch data/dictionary/[topic-name]/vocabulary.yaml

Step 3: Configure Content Page

Edit content/docs/dictionary/[topic-name]/index.md:

 1---
 2title: "RAG Course Vocabulary"
 3linkTitle: "RAG Course"
 4description: |
 5  Vocabulary from IBM RAG and Agentic AI Course
 6sourceType: course
 7sourceName: "IBM RAG and Agentic AI Professional Certificate"
 8topic: "RAG, LangChain, Vector Databases"
 9tags:
10  - vocabulary
11  - rag
12  - ai
13categories:
14  - dictionary
15  - courses
16series:
17  - Dictionary
18nav_weight: 3
19---

Update the shortcode reference:

1{{< vocabulary-accordion "dictionary.ibm-rag-course.vocabulary" >}}

YAML Data Structure

Basic Entry Format

1- word: string              # Required: The English word
2  part_of_speech: string    # Required: noun, verb, adjective, etc.
3  urdu_meaning: string      # Required: Urdu translation
4  example_en: string        # Required: English example sentence
5  example_ur: string        # Required: Urdu example sentence
6  additional_example_ur: string  # Optional: Additional Urdu example

Note: Tags and categories are managed in the page frontmatter (index.md), not in individual vocabulary entries.

Complete Example

 1- word: retrieval
 2  part_of_speech: noun
 3  urdu_meaning: بازیافت، واپس لانا
 4  example_en: Efficient retrieval of information is crucial for RAG systems.
 5  example_ur: RAG سسٹمز کے لیے معلومات کی موثر بازیافت بہت اہم ہے۔
 6  additional_example_ur: ڈیٹا بیس سے دستاویزات کی بازیافت تیزی سے ہونی چاہیے۔
 7
 8- word: embedding
 9  part_of_speech: noun
10  urdu_meaning: سرایت، پیوستگی، ویکٹر نمائندگی
11  example_en: Text embeddings convert words into numerical vectors.
12  example_ur: ٹیکسٹ ایمبیڈنگز الفاظ کو عددی ویکٹرز میں تبدیل کرتی ہیں۔

Field Guidelines

Required Fields

• word: Use lowercase, hyphens for compound words
• part_of_speech: Common values:
  • noun, verb, adjective, adverb
  • noun/verb (for words with multiple uses)
  • phrase, technical-term, abbreviation
• urdu_meaning: Use accurate Urdu script, separate multiple meanings with commas
• example_en: Clear, contextual sentence
• example_ur: Natural Urdu translation with proper grammar

Optional Fields

• additional_example_ur: Use when:
  • Multiple contexts exist
  • Different usage scenarios
  • Related expressions

Available Shortcodes

1. Vocabulary Accordion (Recommended)

Best for: Detailed vocabulary with multiple examples

Usage:

1{{< vocabulary-accordion "dictionary.topic-name.vocabulary" >}}

Features:

• ✅ Collapsible entries (clean, organized view)
• ✅ Displays all fields (meaning, examples)
• ✅ Urdu text with proper RTL formatting
• ✅ Easy to scan word list
• ✅ Click to expand for details

Example:

1{{< vocabulary-accordion "dictionary.army-and-war.vocabulary" >}}

2. Vocabulary List (Compact Table)

Best for: Quick reference, printable format

Usage:

1{{< vocabulary-list "dictionary.topic-name.vocabulary" >}}

Features:

• ✅ Table format (all visible at once)
• ✅ Compact display
• ✅ Better for printing
• ✅ Quick scanning
• ❌ Shows only main example (not additional)

Example:

1{{< vocabulary-list "dictionary.css-course-week-1.vocabulary" >}}

Choosing Between Formats

Data File Path Convention

Pattern:

1data/dictionary/[topic-name]/vocabulary.yaml

Shortcode Reference:

1"dictionary.[topic-name].vocabulary"

Examples:

Rules:

• Use hyphens, not underscores
• All lowercase
• Replace dots with hyphens in shortcode path
• Maintain folder structure consistency

Workflow for Adding Vocabulary

Quick Add (Single Word)

1. Open relevant YAML file: data/dictionary/[topic]/vocabulary.yaml

2. Add new entry at the end:

   1- word: newword
   2  part_of_speech: noun
   3  urdu_meaning: نیا لفظ
   4  example_en: This is the new word in a sentence.
   5  example_en: This is the new word in a sentence.
   6  example_ur: یہ جملے میں نیا لفظ ہے۔
   

3. Save and rebuild site

Batch Add (Multiple Words)

1. Prepare list in text file
2. Use AI assistant or manual conversion to YAML
3. Append to vocabulary.yaml
4. Validate YAML syntax
5. Test locally before committing

Migration from Existing Content

If you have vocabulary in markdown format:

Old format (manual markdown):

1## abandon
2- **part of speech:** verb
3- **urdu meaning:** چھوڑ دینا
4- **example:** He decided to abandon...

Convert to YAML:

1- word: abandon
2  part_of_speech: verb
3  urdu_meaning: چھوڑ دینا، ترک کرنا
4  example_en: He decided to abandon the project.
5  example_ur: اس نے منصوبہ چھوڑ دیا۔

Best Practices

Content Organization

1. Group by Source: One folder per course/book/topic
2. Consistent Naming: Use descriptive, hyphenated names
3. Logical Order: Alphabetical or frequency-based
4. Chunk Large Lists: Split >100 words into multiple files

YAML Maintenance

1. Validate Syntax: Use YAML linter before committing
2. Consistent Formatting: Follow indentation rules
3. UTF-8 Encoding: Ensure proper Urdu character support
4. Backup Regularly: Version control is essential

Urdu Text

1. Proper Script: Use authentic Urdu, not transliteration
2. Diacritics: Include when helpful for pronunciation
3. Natural Language: Use idiomatic expressions
4. Context: Ensure examples match the word’s usage

Frontmatter Tags Strategy

Note: Tags are used in page frontmatter (index.md) for categorization, not in individual vocabulary YAML entries.

1. Topic-based: Use tags to indicate subject matter
   • css, military, programming, ai
2. Consistent: Maintain a tag glossary across dictionary pages
3. Meaningful: Tags should help users find related vocabulary
4. Limited: 3-7 tags per page for effective categorization

Frontmatter Configuration

Essential Fields

1title: "Topic Vocabulary"        # Display title
2linkTitle: "Short Name"          # Navigation/sidebar
3description: |                    # SEO & summary
4  Detailed description...
5type: docs                        # Use 'docs' for dictionary
6sourceType: course                # course, book, video, article
7sourceName: "Course/Book Name"    # Full name of source
8topic: "Main Subject"             # Key topic/domain

Optional Enhancements

 1nav_weight: 1                     # Sidebar order
 2nav_icon:                         # Custom icon
 3  vendor: bootstrap
 4  name: book
 5  color: '#e24d0e'
 6
 7menu:                             # Add to main menu
 8  main:
 9    weight: 100
10    params:
11      icon:
12        vendor: bs
13        name: book
14
15draft: false                      # Publish status
16noindex: false                    # SEO indexing

Typography & Font System

Urdu Font Configuration

The dictionary system uses Jameel Noori Nastaleeq font for authentic Urdu text rendering. This professional Nastaliq-style font is locally hosted for better performance and control.

Font Files Location

1static/fonts/
2├── Jameel-Noori-Nastaleeq.ttf  # 14MB TrueType font
3└── README.md                    # Installation guide

Font Implementation

Both vocabulary shortcodes include embedded CSS with @font-face declarations:

Files:

• layouts/shortcodes/vocabulary-accordion.html
• layouts/shortcodes/vocabulary-list.html

Font Stack:

 1@font-face {
 2  font-family: 'Jameel Noori Nastaleeq';
 3  src: url('/fonts/Jameel-Noori-Nastaleeq.ttf') format('truetype');
 4  font-weight: normal;
 5  font-style: normal;
 6  font-display: swap;
 7}
 8
 9.urdu-text {
10  font-family: 'Jameel Noori Nastaleeq', 'Noto Nastaliq Urdu', 'Al Qalam Quran Majeed', 'Scheherazade New', serif;
11  font-size: 1.4em;          /* Accordion size */
12  line-height: 2.2;          /* Improved readability */
13  font-weight: normal;       /* Authentic Nastaliq rendering */
14  word-spacing: 0.2em;       /* Better word separation */
15}

List shortcode uses slightly smaller sizing:

1.vocabulary-list .urdu-text {
2  font-size: 1.3em;          /* Compact for table view */
3  line-height: 2.2;
4  word-spacing: 0.2em;
5}

Font Features

✅ Jameel Noori Nastaleeq (Primary)

• Authentic Nastaliq calligraphy style
• Widely used in Urdu publications
• Locally hosted (no external dependencies)
• Source: https://urdunigaar.com/

✅ Fallback Fonts (if primary fails):

1. Noto Nastaliq Urdu (Google Fonts)
2. Al Qalam Quran Majeed
3. Scheherazade New
4. Generic serif

✅ Typography Settings:

• Word spacing: 0.2em (comfortable reading)
• Line height: 2.2 (prevents text overlap)
• Font style: Normal (no italics for better readability)
• Direction: RTL (right-to-left for Urdu)

Font Installation

If font is missing, follow instructions in static/fonts/README.md:

1. Download: https://urdunigaar.com/download/jameel-noori-nastaleeq-font-ttf-file-download/
2. Place in: static/fonts/Jameel-Noori-Nastaleeq.ttf
3. Restart Hugo server

Customization Options

To adjust word spacing, edit the shortcode files:

1.urdu-text {
2  word-spacing: 0.3em;  /* Increase for more space */
3}

To change font size:

1.urdu-text {
2  font-size: 1.5em;  /* Larger text */
3}

To add letter spacing:

1.urdu-text {
2  letter-spacing: 0.02em;  /* Subtle character spacing */
3}

Color Themes

Accordion buttons use Bootstrap variables:

1.vocabulary-accordion .accordion-button:not(.collapsed) {
2  background-color: var(--bs-primary-bg-subtle);
3  color: var(--bs-primary-text);
4}

Troubleshooting

Common Issues

1. Shortcode Not Rendering

Problem: Blank space where vocabulary should appear

Solutions:

• Check data file path: data/dictionary/[topic]/vocabulary.yaml exists
• Verify shortcode reference matches file path
• Ensure YAML syntax is valid (no tabs, correct indentation)
• Rebuild site: hugo server --disableFastRender

2. Urdu Text Not Displaying

Problem: Boxes or garbled text instead of Urdu

Solutions:

• Check UTF-8 encoding in YAML file
• Verify Urdu font is loaded
• Ensure dir="rtl" attribute is present
• Test with different browsers

3. Accordion Not Collapsing

Problem: All items expanded or no interaction

Solutions:

• Verify Bootstrap JS is loaded
• Check browser console for errors
• Ensure unique IDs for each accordion item
• Test with updated Bootstrap version

4. YAML Parse Errors

Problem: Hugo build fails with YAML errors

Solutions:

• Validate YAML: yamllint.com or run script from package.json file.
• Check for special characters (use quotes if needed)
• Verify indentation (2 spaces, no tabs)
• Look for unescaped colons in text

Recent Improvements

Version History

v1.2 (Latest) - Font & Typography Enhancements

• ✅ Added Jameel Noori Nastaleeq local font support
• ✅ Removed Google Fonts dependency
• ✅ Added word-spacing: 0.2em for better readability
• ✅ Increased font sizes: 1.4em (accordion), 1.3em (list)
• ✅ Improved line-height to 2.2
• ✅ Removed italic styling from Urdu examples (example_ur, additional_example_ur)
• ✅ Changed font-weight to normal for authentic rendering
• ✅ Created static/fonts/ directory with installation guide

Git commit: b3c2e95d - feat: improve Urdu text rendering with Jameel Noori font

v1.1 - System Refinement

• ✅ Removed tags from YAML structure (use frontmatter instead)
• ✅ Added Google Fonts for Urdu (Noto Nastaliq Urdu)
• ✅ Improved documentation clarity

Git commit: 1411feab - refactor: improve dictionary system

v1.0 - Initial Release

• ✅ Implemented accordion and list shortcodes
• ✅ Created YAML data structure
• ✅ Added two example vocabularies (army-and-war, css-course-week-1)
• ✅ Created archetype template
• ✅ Wrote comprehensive documentation

Git commit: 10f078ba - feat: implement dictionary system

Typography Evolution

• Initial → Generic fallback fonts, small size, italic examples
• Phase 1 → Google Fonts (Noto Nastaliq Urdu), 1.1em size
• Phase 2 → Local Jameel Noori font, 1.3-1.4em, word-spacing
• Current → Optimized typography: larger size, better spacing, no italics

Key Design Decisions

1. Why local font hosting?

   • Faster loading (no external CDN)
   • Better control over styling
   • Works offline
   • Specific authentic Urdu font choice

2. Why remove italic styling?

   • Nastaliq fonts are harder to read in italic
   • Urdu script is naturally flowing and decorative
   • Normal text provides better clarity
   • Consistent with urdu_meaning display

3. Why word-spacing: 0.2em?

   • Urdu words can appear cramped
   • Improves scanning and comprehension
   • Balances density and readability

4. Why larger font sizes?

   • Nastaliq script has intricate details
   • Better visibility on various devices
   • Reduces eye strain
   • Maintains professional appearance

Future Enhancements (Planned)

Phase 2 Features

• Search Functionality: Filter words by text search
• Alphabetical Index: A-Z navigation
• Cross-linking: Link related words across topics
• Export Options: PDF, CSV, Flashcards
• Audio Pronunciation: Add audio examples
• Difficulty Levels: Beginner, intermediate, advanced badges
• Progress Tracking: Mark words as learned
• Quiz Mode: Test vocabulary knowledge
• Spaced Repetition: Review schedule based on forgetting curve

Examples Reference

Example 1: Army and War Vocabulary

File: data/dictionary/army-and-war/vocabulary.yaml

1- word: battalion
2  part_of_speech: noun
3  urdu_meaning: فوجی دستہ، بٹالین
4  example_en: The battalion was deployed to the border.
5  example_ur: بٹالین کو سرحد پر تعینات کیا گیا۔

Page: content/docs/dictionary/army-and-war/index.md

1{{< vocabulary-accordion "dictionary.army-and-war.vocabulary" >}}

Quick Reference Commands

 1# Create new dictionary topic
 2hugo new content/docs/dictionary/[topic]/index.md --kind dictionary
 3
 4# Create data directory
 5mkdir -p data/dictionary/[topic]
 6
 7# Create vocabulary file
 8touch data/dictionary/[topic]/vocabulary.yaml
 9
10# Start dev server
11npm run dev:memory
12
13# Build production
14npm run build:production-fast
15
16# Validate YAML online
17# Visit: http://www.yamllint.com/

Support & Questions

For issues or enhancements:

1. Check this guide first
2. Review example files in /data/dictionary/
3. Test with existing working examples
4. Ask for clarification if needed

Last Updated: {{ now.Format “2006-01-02” }}
Version: 1.0
Status: Active