Example: Adding an Icon to glyphicons-v2

1. Add the SVG file

Drop the file into the sub-folder, following the existing naming pattern (glyphicons-halflings-<number>-<name>.svg, numbered one past the last one in the folder):

icons/glyphicons-v2/halflings/glyphicons-halflings-331-arrow-diagonal.svg

2. Add the entry to mapping.json

{
  // ...existing entries
  "arrow-diagonal": "glyphicons-halflings-331-arrow-diagonal.svg"
}

3. Regenerate mapping-with-filepath.json

glyphicons-v2 loads its icon data from one combined file, not the individual mapping.jsons — see the import question. Rebuild it:

cd icons/
python ../script/generate-mapping.py ./glyphicons-v2
mv mapping-with-filepath.json glyphicons-v2/

Confirm the new key landed in icons/glyphicons-v2/mapping-with-filepath.json:

"glyphicons-v2/halflings arrow-diagonal": "glyphicons-v2/halflings/glyphicons-halflings-331-arrow-diagonal.svg"

4. (Recommended) Regenerate the master mapping

Not read by the app, but this is the repo’s only duplicate-key check across every library — cheap insurance:

cd icons/
python ../script/generate-master-mapping.py .

If arrow-diagonal (scoped to glyphicons-v2/halflings) already existed anywhere else, this exits with an error naming both files. No output error here means you’re clear.

5. Regenerate keywords.json

icons/glyphicons-v2/halflings/mapping.json is already one of the hand-written tuples in script/generate-keywords.py’s sets list (see the keywords question) — no edit needed there for an existing sub-folder. Just re-run the generator:

python3 script/generate-keywords.py

Trace of what it just did for arrow-diagonal (see Keywords & Translations for the full algorithm):

1. Split: "arrow-diagonal" → ["arrow", "diagonal"]
2. Translate: arrow → "flèche" (already in translations-en-fr.json), diagonal → not found, falls back to "diagonal" unchanged
3. FR phrase "flèche diagonal" differs from EN "arrow diagonal" → added as a keyword
4. More than one word → no-separator join "arrowdiagonal" also added
5. No entry for this icon in keyword-overrides.json → nothing extra merged

"arrow-diagonal": ["flèche diagonal", "arrowdiagonal"]

6. (Optional) Fix the grammar with a real translation

"flèche diagonal" is grammatically off (diagonal should agree as diagonale). Add the missing word to the dictionary:

{
  // ...existing entries
  "diagonal": "diagonale"
}

Re-run the same command as step 5. The dictionary is global (see When word-by-word translation isn’t enough for why that matters), so this also silently improves every other icon whose classname contains diagonal, if any exist — check the script’s console output (X/Y icons got keywords) doesn’t drop before assuming that’s safe.

"arrow-diagonal": ["flèche diagonale", "arrowdiagonal"]

7. IconDropdown.tsx — no change needed

This is an existing sub-folder: iconsGlyphiconsV2 and iconsGlyphiconsV2HalflingsKeywords are already imported and already wired into v2KeywordSets. Nothing to touch here for this case — that’s only required when the sub-folder itself is brand new (see Adding a whole new icon set).

8. Verify

Run the app, open IconDropdown, and confirm the icon is findable by:

• arrow-diagonal (English classname)
• flèche diagonale (French translation)
• arrowdiagonal (no-separator English)