### Step-by-Step Guides Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/CONTENTS.txt Provides guides for common tasks such as adding icons, aliases, and project setup. ```APIDOC ## Step-by-Step Guides This section offers practical guides for common tasks: - Adding new icons (7 steps) - Adding aliases (3 steps) - Project setup - Development workflow - Release process ``` -------------------------------- ### Initial Project Setup Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/development-guide.md Clone the repository, install dependencies, and run initial checks to verify the project setup. ```bash git clone https://github.com/microsoft/vscode-codicons.git cd vscode-codicons npm install npm run check-metadata ``` -------------------------------- ### SVGO Configuration Example Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/INDEX.md Example configuration for SVGO, including plugin configuration, fill attribute handling, and currentColor addition. ```javascript module.exports = { plugins: [ // ... plugin configurations ], // ... other settings }; ``` -------------------------------- ### Code Examples Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/CONTENTS.txt Offers over 100 practical code examples for various integration scenarios. ```APIDOC ## Code Examples This section contains over 100 practical code examples demonstrating various usage patterns: - HTML/CSS usage patterns - TypeScript integration - SVG sprite usage - Build script invocation - Troubleshooting examples ``` -------------------------------- ### Complete Metadata Example Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/icon-system.md A comprehensive example of the metadata.json file, showcasing entries for 'add', 'lightbulb', 'alert', and 'github' icons with their respective tags, categories, and descriptions. ```json { "add": { "tags": ["plus", "new", "create", "combine", "more", "insert"], "category": "action", "description": "Add or create new item" }, "lightbulb": { "tags": ["idea", "suggestion", "insight", "bright", "inspiration"], "category": "action", "description": "Lightbulb or idea icon" }, "alert": { "tags": ["warning", "error", "danger", "notification", "triangle"], "category": "status", "description": "Alert or warning indicator" }, "github": { "tags": ["source-control", "git", "vcs", "repository"], "category": "source-control", "description": "GitHub social media icon" } } ``` -------------------------------- ### Install Project Dependencies Source: https://github.com/microsoft/vscode-codicons/blob/main/README.md After cloning the repository, install the necessary development dependencies using npm. ```bash npm install ``` -------------------------------- ### mapping.json Structure Example Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/icon-system.md Provides an example of the mapping.json file, which serves as the canonical source of truth for icon identity and naming. ```json { "60000": [ "add", "plus", "gist-new", "repo-create" ], "60001": [ "lightbulb", "light-bulb" ], "60002": [ "repo", "repo-delete" ], ... "60612": [ "run-compact" ] } ``` -------------------------------- ### Fantasticon Configuration Example Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/INDEX.md Example configuration for Fantasticon, specifying core settings, codepoint mapping transformations, template configuration, and font format options. ```javascript module.exports = { // Core settings name: 'codicon', prefix: 'codicon', // ... other settings }; ``` -------------------------------- ### Install VS Code Codicons Dependencies Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/README.md Commands to clone the repository, navigate into the directory, and install project dependencies using npm. ```bash # Clone repository git clone https://github.com/microsoft/vscode-codicons.git cd vscode-codicons # Install dependencies npm install # Verify setup npm run check-metadata npm run build ``` -------------------------------- ### Icon Naming Aliases Example Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/README.md Demonstrates how multiple aliases can map to the same icon codepoint, allowing for flexible naming conventions. ```text Codepoint 60000 → "add" | "plus" | "gist-new" | "repo-create" (all identical) Codepoint 60001 → "lightbulb" | "light-bulb" (all identical) ``` -------------------------------- ### Icon Metadata Example Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/types.md Shows an example of icon metadata, mapping icon names to their associated search tags, category, and a human-readable description. ```json { "add": { "tags": ["plus", "new", "create", "combine", "more", "insert"], "category": "action", "description": "Add or create new item" }, "lightbulb": { "tags": ["idea", "suggestion", "insight", "bright"], "category": "action", "description": "Lightbulb or idea icon" }, "alert": { "tags": ["warning", "error", "danger", "notification", "triangle", "exclamation"], "category": "status", "description": "Alert or warning" } } ``` -------------------------------- ### Install @vscode/codicons NPM Package Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/export-formats.md Install the codicons package using npm. ```bash npm install @vscode/codicons ``` -------------------------------- ### Install Codicons via npm Source: https://github.com/microsoft/vscode-codicons/blob/main/README.md Install the Codicons package into your project using npm. This is the recommended way to use Codicons in your applications. ```bash npm i @vscode/codicons ``` -------------------------------- ### Icon Mapping Example Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/types.md Illustrates how decimal Unicode codepoints are represented as strings and mapped to arrays of icon alias names. ```json { "60000": ["add", "plus", "gist-new", "repo-create"], "60001": ["lightbulb", "light-bulb"], "60002": ["repo", "repo-delete"], "60003": ["gist-fork", "repo-forked"], // ... "60612": ["run-compact"] } ``` -------------------------------- ### CSV Metadata Output Example Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/api-reference.md Example of the CSV file format generated by the `export-to-csv` script. It includes short name, character, and unicode for each icon. ```text short_name,character,unicode add,➕,EA60 lightbulb,💡,EA61 ``` -------------------------------- ### Viewbox Specification Example Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/export-formats.md Illustrates the standard viewBox attribute for Codicon symbols, which is '0 0 24 24', enabling aspect-ratio-preserving scaling. ```xml ``` -------------------------------- ### Install VS Code Codicons in Project Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/README.md Instructions for installing the VS Code Codicons package in your project, either from npm or a local repository path. ```bash # Install from NPM npm install @vscode/codicons # Or use from cloned repo npm install /path/to/vscode-codicons ``` -------------------------------- ### Source Icon Mapping Format Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/README.md Example of the source mapping format used in mapping.json, showing codepoint to icon name associations. ```json { "60000": ["add", "plus", "gist-new"] } ``` -------------------------------- ### Generate WOFF2 Font Format Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/development-guide.md Example command to generate WOFF2 font format, which is smaller and optimized for the web. Requires modification to `.fantasticonrc.js`. ```bash # Generate WOFF2 (much smaller, web-optimized) # Requires modification to .fantasticonrc.js # WOFF2: ~150KB, WOFF: ~250KB, TTF: ~500KB ``` -------------------------------- ### Verify Font Declaration in HTML Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/development-guide.md Includes an example of how to link the Codicon stylesheet or manually declare the font using `@font-face` in HTML. ```html ``` -------------------------------- ### Coloring Codicon Icons in HTML Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/export-formats.md Provides examples of how to color codicon icons using CSS, either by defining specific color classes (e.g., `.error-icon`) or by applying inline `style` attributes. ```html ``` -------------------------------- ### Icon Alias Example Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/icon-system.md Illustrates how multiple SVG files can be aliased to represent the same icon design. This is useful for providing alternative filenames for the same icon. ```text Codepoint 60001: ├─ lightbulb.svg (primary) └─ light-bulb.svg (same design, alternative filename) ``` -------------------------------- ### Using Codicons in VS Code Extensions Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/export-formats.md Provides an example of integrating codicons into a VS Code extension, demonstrating safe, type-checked icon usage with VS Code's API. ```typescript // In VS Code extension or core import { codiconsLibrary } from './codiconsLibrary'; // Safe type-checked icon usage const buttonIcon = codiconsLibrary.add; const indicator = codiconsLibrary.circleSmall; // Used with VS Code's icon system registerCommand('cmd', () => { showMessage('Added', { icon: buttonIcon }); }); ``` -------------------------------- ### Embedded Metadata JSON Example Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/export-formats.md Example of the metadata JSON structure embedded within the HTML preview page, showing icon properties like tags, category, and description. ```javascript let metadata = { "add": { "tags": ["plus", "new", "create", "combine", "more", "insert"], "category": "action", "description": "Add or create new item" }, // ... 600+ icons }; ``` -------------------------------- ### Hex Codepoint Format in TypeScript Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/export-formats.md Explains the hexadecimal format used for codepoints in the TypeScript library, showing decimal to hex conversion examples. ```typescript 60000 (decimal) → 0xea60 (hex) 60001 (decimal) → 0xea61 (hex) 60612 (decimal) → 0xea84 (hex) ``` -------------------------------- ### Individual Icon CSS Classes Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/export-formats.md Examples of individual icon classes generated in `codicon.css`, such as `.codicon-add` and `.codicon-plus`, which use the `::before` pseudo-element to insert the correct content (Unicode codepoint). ```css .codicon-add::before { content: '\ea60'; } .codicon-plus::before { content: '\ea60'; } .codicon-lightbulb::before { content: '\ea61'; } /* ... 600+ icon classes */ ``` -------------------------------- ### CSS Class Format for Icons Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/types.md Examples of HTML elements using the generated CSS classes for displaying icons. Each icon alias is available as a class name prefixed with 'codicon-'. ```html
``` -------------------------------- ### Understand Project Overview Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/00_START_HERE.md Read the README.md project overview section to understand the project. ```markdown Read: README.md → Project overview section ``` -------------------------------- ### Verify Build and Output Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/development-guide.md Build the project and list the contents of the distribution directory to ensure all expected files are generated. ```bash npm run build ls -la dist/ # Should show: codicon.ttf, codicon.css, codicon.svg, codiconsLibrary.ts, etc. ``` -------------------------------- ### Read Build Process Documentation Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/00_START_HERE.md Consult build-system.md for information regarding the 9-stage build pipeline. ```markdown Read: build-system.md → 9-Stage Pipeline section ``` -------------------------------- ### Open HTML Preview Page Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/export-formats.md Instructions for opening the generated `dist/codicon.html` preview page in a web browser using command-line tools. ```bash # Open preview page open dist/codicon.html # Or on Linux xdg-open dist/codicon.html # Or on Windows start dist/codicon.html ``` -------------------------------- ### Reference API and Configuration Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/00_START_HERE.md Use api-reference.md and configuration.md for detailed information on APIs and configuration options. ```markdown Use: api-reference.md, configuration.md, types.md for details ``` -------------------------------- ### Spreadsheet Import Instructions Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/export-formats.md Provides step-by-step instructions for importing the dist/codicon.csv file into spreadsheet software like Excel or Google Sheets. ```text 1. Open dist/codicon.csv in Excel/Google Sheets 2. Each row represents one glyph 3. Column A: glyph name 4. Column B: rendered character (may appear as boxes if font not installed) 5. Column C: Unicode codepoint in hexadecimal ``` -------------------------------- ### Embedded SVG Data Example Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/export-formats.md Example of the SVG source code structure embedded within the HTML preview page, providing the raw SVG string for each icon. ```javascript let svgData = { "add": "", "lightbulb": "...", // ... 600+ SVG source strings }; ``` -------------------------------- ### Project File Structure Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/00_START_HERE.md Overview of the file locations within the /workspace/home/output/ directory. ```bash output/ ├── 00_START_HERE.md ← You are here ├── CONTENTS.txt ← Text summary ├── INDEX.md ← Navigation guide ├── README.md ← Project overview ├── api-reference.md ← Build scripts ├── types.md ← Data structures ├── configuration.md ← Configuration options ├── build-system.md ← Build pipeline ├── icon-system.md ← Icon management ├── export-formats.md ← Output formats └── development-guide.md ← Development guide ``` -------------------------------- ### Read Icon System Documentation Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/00_START_HERE.md Refer to the icon-system.md file for details on the icon identity within the project. ```markdown Read: icon-system.md → Icon Identity section ``` -------------------------------- ### SVG Sprite Sheet Output Example Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/api-reference.md Example of the generated SVG sprite sheet structure. Each icon is represented as a `` element with its ID corresponding to the icon's primary alias. ```xml ... ... ``` -------------------------------- ### Usage of SVG Sprite Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/build-system.md Example of how to use the generated SVG sprite in HTML to display an icon. ```html ``` -------------------------------- ### Integration Testing: Full Build and Output Verification Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/development-guide.md Executes the full build process and then verifies the existence of all expected output files in the dist directory, including fonts, CSS, sprites, TypeScript definitions, CSV, and metadata. ```bash # Full build npm run build # Verify all outputs test -f dist/codicon.ttf && echo "✓ Font" test -f dist/codicon.css && echo "✓ CSS" test -f dist/codicon.svg && echo "✓ Sprite" test -f dist/codiconsLibrary.ts && echo "✓ TypeScript" test -f dist/codicon.csv && echo "✓ CSV" test -f dist/metadata.json && echo "✓ Metadata" ``` -------------------------------- ### Lookup Icons using grep Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/export-formats.md Demonstrates how to use the grep command-line utility to find icons within the dist/codicon.csv file based on codepoint or name. ```bash # Find all icons with codepoint EA60 grep "EA60" dist/codicon.csv # Output: # add,➕,EA60 # plus,➕,EA60 # gist-new,➕,EA60 # repo-create,➕,EA60 # Find specific icon grep "^lightbulb," dist/codicon.csv # Output: # lightbulb,💡,EA61 ``` -------------------------------- ### Default Build Command Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/api-reference.md The default command to initiate the entire build process for VSCode Codicons. ```bash npm run build ``` -------------------------------- ### Read Output Formats Documentation Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/00_START_HERE.md Explore export-formats.md to understand how to choose your desired output format. ```markdown Read: export-formats.md → Choose your format section ``` -------------------------------- ### Project Structure Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/README.md Illustrates the directory layout of the vscode-codicons project, showing source files, scripts, configuration, and generated outputs. ```bash vscode-codicons/ ├── src/ │ ├── icons/ # 600+ SVG icon files │ │ ├── add.svg │ │ ├── lightbulb.svg │ │ └── ... (SVG files) │ └── template/ │ ├── mapping.json # Icon ID mapping (codepoint → aliases) │ ├── metadata.json # Icon metadata (tags, categories, descriptions) │ ├── styles.hbs # CSS generation template │ └── preview.hbs # HTML preview template ├── scripts/ │ ├── export-to-ts.js # TypeScript library generator │ ├── export-to-csv.js # CSV character map generator │ ├── svg-sprite.js # SVG sprite sheet generator │ ├── check-metadata.js # Metadata validation │ ├── embed-metadata.js # Metadata embedding │ ├── embed-svg-data.js # SVG data embedding │ ├── patch-fantasticon.js # Windows compatibility patch │ ├── version-bump.js # Version management │ └── reset.js # Clean build directory ├── .fantasticonrc.js # Fantasticon configuration ├── svgo.config.js # SVG optimization configuration ├── package.json # Project metadata and scripts ├── dist/ # Generated outputs │ ├── codicon.ttf # TrueType font │ ├── codicon.css # CSS stylesheet │ ├── codicon.html # Interactive preview page │ ├── codicon.svg # SVG sprite sheet │ ├── codicon.csv # Character map │ ├── codiconsLibrary.ts # TypeScript library │ └── metadata.json # Icon metadata └── _iconCloud/ # Design system integration files ``` -------------------------------- ### Example SVG Before and After Fill Attribute Removal Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/configuration.md Illustrates the effect of removing 'fill' attributes on an SVG element. The 'fill' attribute is stripped, allowing CSS to control the color. ```xml ``` -------------------------------- ### Release Checklist Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/development-guide.md A checklist for the release process, including checking status, validating metadata, building, testing, bumping versions, and pushing. ```bash # 1. Ensure all changes committed git status # 2. Validate metadata npm run check-metadata # 3. Full build and test npm run build # 4. Test in preview open dist/codicon.html # 5. Bump versions npm run version:tag # 6. Push to remote git push origin main --tags # 7. Create GitHub release (optional) # Use git tags as release notes ``` -------------------------------- ### Visual Testing: Open Preview Page Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/development-guide.md Opens the generated HTML preview page in the default browser for visual inspection. This step is crucial for verifying icon rendering, metadata display, search functionality, and copy features. ```bash # Open preview page open dist/codicon.html # Visually inspect: # - All icons render correctly # - Metadata displays properly # - Search works # - Copy functions work ``` -------------------------------- ### Development Build Command Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/build-system.md Combines build and deployment steps. Requires the vscode-codicons repo to be cloned at the same directory level as the vscode repo. ```bash npm run build && cp -R ./dist/codicon.ttf ../vscode/src/vs/base/browser/ui/codicons/codicon/ && cp ./dist/codiconsLibrary.ts ../vscode/src/vs/base/common/ ``` -------------------------------- ### Example SVG After Adding currentColor Fill Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/configuration.md Shows an SVG element after the 'addAttributesToSVGElement' SVGO transformation. The 'fill="currentColor"' attribute is added to the root SVG element. ```xml ``` -------------------------------- ### Build Tool Interactions Diagram Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/build-system.md Illustrates the flow of the build process, showing how source files are processed by various tools to produce output artifacts. ```text Source Files ├─ SVG Icons (src/icons/) ├─ Mapping (src/template/mapping.json) └─ Metadata (src/template/metadata.json) ↓ [SVGO] - Optimize SVGs ↓ [Fantasticon] - Generate font & CSS ↓ [opentype.js] - Parse font to CSV ↓ [svg-sprite] - Create sprite ↓ [Embedding Scripts] - Inject metadata & SVG data ↓ Output Artifacts (dist/) ``` -------------------------------- ### Recommended CI/CD Pipeline Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/build-system.md A suggested sequence of steps for integrating the build process into a Continuous Integration/Continuous Deployment pipeline. ```yaml 1. install: npm install 2. validate: npm run check-metadata 3. build: npm run build 4. test: (run any tests) 5. publish: npm publish (if version tag) 6. deploy: npm run dev (if building for vscode) ``` -------------------------------- ### Handlebars Template for CSS Generation Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/development-guide.md Example of a Handlebars template used for generating CSS. It includes base styles and iterates over glyphs to create CSS classes for each icon. Custom size variants are also demonstrated. ```handlebars .codicon { font-family: '@fontName'; font-style: normal; font-weight: normal; display: inline-block; -webkit-font-smoothing: antialiased; -moz-osx-font-smoothing: grayscale; } {{#each @glyphs}} .codicon-{{this.name}}::before { content: '{{this.unicode}}'; } {{/each}} /* New addition: size variants */ .codicon-small { font-size: 12px; } .codicon-large { font-size: 32px; } ``` -------------------------------- ### Local Testing: Build and Test Individual Stages Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/development-guide.md Commands to clean the project and test individual build stages like SVG optimization, font generation, and TypeScript export. Verifies the existence of output files. ```bash # Build and test individual stage npm run clean npm run svgo # Test SVG optimization npm run fonts # Test font generation npm run export-to-ts # Test TypeScript export # Verify outputs exist ls -la dist/ ``` -------------------------------- ### Verify Updated Icon Design Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/development-guide.md Open the HTML preview to visually inspect the changes made to an icon's design. ```bash # Open preview to visually inspect open dist/codicon.html # Search for "add" to see updated icon ``` -------------------------------- ### Build Pipeline Summary Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/README.md This diagram outlines the stages of the VSCode Codicons build pipeline, from input processing to final output generation. ```text ┌─────────────────────────────────────────────────────────────┐ │ INPUT: SVG Icons + Mapping + Metadata │ ├─────────────────────────────────────────────────────────────┤ │ Stage 1: Clean → Remove dist/ directory │ │ Stage 2: Optimize → SVGO removes fills, adds currentColor │ │ Stage 3: Font Gen → Fantasticon creates TTF + CSS + HTML │ │ Stage 4: TypeScript → Export camelCase properties │ │ Stage 5: CSV Export → Parse font to character map │ │ Stage 6: Copy Meta → Copy metadata.json to dist/ │ │ Stage 7: Embed Meta → Inject metadata into HTML │ │ Stage 8: Embed SVG → Inject SVG sources into HTML │ │ Stage 9: Sprite → Create SVG symbol sprite │ ├─────────────────────────────────────────────────────────────┤ │ OUTPUT: Font + CSS + TypeScript + SVG + CSV + HTML + JSON │ └─────────────────────────────────────────────────────────────┘ ``` -------------------------------- ### Basic HTML Usage of Codicon CSS Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/export-formats.md Illustrates the fundamental way to use codicons in HTML by applying the `codicon` base class along with a specific icon class, like `codicon-add`. ```html ``` -------------------------------- ### Icon Naming Aliases Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/icon-system.md Shows how multiple names (aliases) can point to the same icon codepoint, facilitating flexible usage. ```text Codepoint 60000: ├─ "add" (primary alias) ├─ "plus" (synonym) ├─ "gist-new" (context-specific) └─ "repo-create" (context-specific) All four names render the same icon in the font. ``` -------------------------------- ### Build Stages for Icons Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/development-guide.md Execute specific build stages for optimizing SVGs, generating fonts, or exporting TypeScript definitions. ```bash # Full build npm run build # Or test individual stages npm run svgo # Optimize SVG npm run fonts # Generate font npm run export-to-ts # Generate TypeScript ``` -------------------------------- ### Run SVGO Build Script Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/configuration.md Command to execute the SVGO build process. This command processes all SVG files in the specified directory using a configuration file. ```bash npm run svgo ``` -------------------------------- ### Build Pipeline Stage: Metadata Copy Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/INDEX.md Command to execute the metadata copy stage of the build pipeline, which involves file copying. ```bash npm run copy-metadata ``` -------------------------------- ### Build Pipeline Stage: Font Generation Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/INDEX.md Command to execute the font generation stage of the build pipeline using Fantasticon. ```bash npm run generate-font ``` -------------------------------- ### Build Pipeline Stage: SVG Optimization Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/INDEX.md Command to execute the SVG optimization stage of the build pipeline using SVGO. ```bash npm run optimize-svg ``` -------------------------------- ### Build Codicons Project Source: https://github.com/microsoft/vscode-codicons/blob/main/README.md Compile the icon font and related assets from the source files. This command generates the final distributable files. ```bash npm run build ``` -------------------------------- ### Run Specific Build Stages Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/development-guide.md Executes specific stages of the build process (SVGO optimization, font generation) for rapid iteration during development. ```bash npm run svgo npm run fonts ``` -------------------------------- ### Programmatic Access to Metadata JSON Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/export-formats.md Demonstrates how to fetch and parse the `dist/metadata.json` file in JavaScript to access icon metadata programmatically. ```javascript fetch('dist/metadata.json') .then(r => r.json()) .then(metadata => { const addMeta = metadata['add']; console.log(addMeta.description); // "Add or create new item" console.log(addMeta.tags); // ["plus", "new", "create", ...] console.log(addMeta.category); // "action" }); ``` -------------------------------- ### Generate Fonts and Stylesheets Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/build-system.md Generates TrueType fonts, CSS stylesheets, and an HTML preview page from optimized SVGs and mapping templates. Includes Windows-specific path normalization. ```bash npm run fonts ``` -------------------------------- ### Manually Patch Fantasticon and Generate Fonts Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/development-guide.md Manually runs the script to patch Fantasticon and then generates the font files. Use this if Windows builds fail due to Fantasticon path issues. ```bash node scripts/patch-fantasticon.js npm run fonts ``` -------------------------------- ### Namespace Wrapping for Codicons Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/export-formats.md Illustrates a common pattern in VS Code for creating a namespace to selectively export and organize codicons for easier usage. ```typescript // Common pattern in VS Code import { codiconsLibrary } from './codiconsLibrary'; export namespace Codicons { export const add = codiconsLibrary.add; export const lightbulb = codiconsLibrary.lightbulb; export const repository = codiconsLibrary.repo; // ... selective exports } // Usage: const icon = Codicons.add; ``` -------------------------------- ### Find Icon by Name or Codepoint Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/README.md Use command-line tools like grep and jq to search for icons by name, category, or to look up codepoints. ```bash # Search mapping for icon name grep -r '"add"' src/template/mapping.json # Find all icons in a category jq 'to_entries[] | select(.value.category == "action") | .key' src/template/metadata.json # Look up codepoint to hex # Decimal: 60000 → Hex: 0xEA60 ``` -------------------------------- ### API Reference Documentation Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/CONTENTS.txt Provides details on build scripts, function signatures, return types, and error conditions. ```APIDOC ## API Reference This section details the complete API reference for VS Code Codicons. ### Build Scripts - All 9 build scripts are fully documented. - Includes function signatures with parameter types. - Specifies return types and output details. - Documents error conditions and exit codes. ### Data Structure Definitions - Provides TypeScript type definitions. - Includes JSON schema examples. - Describes fields and their constraints. - Explains usage context and relationships. ### Configuration Reference - Documents all configuration options. - Lists default values and valid ranges. - Details environment variables and platform-specific settings. ``` -------------------------------- ### Build Pipeline Stage: SVG Sprite Creation Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/INDEX.md Command to execute the SVG sprite creation stage of the build pipeline. ```bash npm run create-svg-sprite ``` -------------------------------- ### TypeScript Codicons Library Structure Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/export-formats.md Illustrates the structure of the generated TypeScript module, showing how icons are registered with their names and hexadecimal codepoints. ```typescript export const codiconsLibrary = { // Aliases converted to camelCase add: register('add', 0xea60), plus: register('plus', 0xea60), gistNew: register('gist-new', 0xea60), repoCreate: register('repo-create', 0xea60), lightbulb: register('lightbulb', 0xea61), lightBulb: register('light-bulb', 0xea61), // ... 600+ more icons runCompact: register('run-compact', 0xea84), } as const; ``` -------------------------------- ### Build Pipeline Stage: TypeScript Export Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/INDEX.md Command to execute the TypeScript export stage of the build pipeline, generating the library. ```bash npm run export-ts ``` -------------------------------- ### Verify Generated Output Files Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/development-guide.md Check for the presence of generated font, CSS, and TypeScript files, and search for specific class names or properties. ```bash # Check font was generated ls -la dist/codicon.ttf # Check TypeScript export grep "newIconName" dist/codiconsLibrary.ts # Check CSS class grep ".codicon-new-icon-name" dist/codicon.css # Check in preview open dist/codicon.html # Search for "new-icon-name" ``` -------------------------------- ### Fantasticon Configuration Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/api-reference.md Configuration for the fantasticon font builder. Converts icon aliases to codepoints for font generation. ```javascript { name: 'codicon', // Font family name prefix: 'codicon', // CSS class prefix codepoints: { alias1: code, ... }, // All icon aliases mapped to Unicode codepoints inputDir: 'src/icons', // SVG source directory outputDir: 'dist', // Output directory fontTypes: ['ttf'], // Output font formats normalize: true, // Normalize glyph metrics assetTypes: ['css', 'html'], // Generate CSS and HTML templates: { html: 'src/template/preview.hbs', // HTML preview template css: 'src/template/styles.hbs' // CSS stylesheet template }, formatOptions: { ttf: { url: string, // Package URL description: string, // Font description from package.json version: string // Font version from package.json } } } ``` -------------------------------- ### Use Icons in TypeScript/JavaScript Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/README.md Import the type-safe library to access icons by name and use them within your framework. ```typescript // 1. Import type-safe library import { codiconsLibrary } from './codiconsLibrary'; // 2. Access icon by name const addIcon = codiconsLibrary.add; const saveIcon = codiconsLibrary.save; // 3. Use in framework renderButton({ icon: addIcon, label: 'Add' }); ``` -------------------------------- ### Add New Development Dependency Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/development-guide.md Use this command to add a new package as a dev dependency. Remember to commit both package.json and package-lock.json. ```bash # Add package npm install --save-dev package-name # Update package-lock.json npm install # Commit both files git add package.json package-lock.json git commit -m "chore: add package-name for [purpose]" ``` -------------------------------- ### Build Pipeline Stage: Metadata Embedding Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/INDEX.md Command to execute the metadata embedding stage of the build pipeline, used for HTML injection. ```bash npm run embed-metadata ``` -------------------------------- ### Programmatic CSV Parsing in JavaScript Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/export-formats.md Shows how to fetch and parse the dist/codicon.csv file using JavaScript's Fetch API and basic string manipulation. ```javascript fetch('dist/codicon.csv') .then(r => r.text()) .then(csv => { const lines = csv.trim().split('\n'); const headers = lines[0].split(','); const data = lines.slice(1).map(line => { const [name, char, unicode] = line.split(','); return { name, char, unicode }; }); console.log(data); }); ``` -------------------------------- ### HTML/CSS Integration with TrueType Font Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/export-formats.md Demonstrates how to integrate the codicon font into an HTML document using both CSS classes and direct Unicode codepoint references. Ensure the `dist/codicon.css` is linked. ```html ``` -------------------------------- ### SVG Color Handling - Original Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/icon-system.md Shows the original SVG structure with hardcoded fill colors before SVGO optimization. ```xml ``` -------------------------------- ### Update metadata.json for New Icon Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/development-guide.md Add metadata for a new icon, including tags, category, and a human-readable description. ```json { "new-icon-name": { "tags": ["keyword1", "keyword2", "keyword3", "keyword4", "keyword5"], "category": "action", "description": "Brief description of icon purpose (50-150 chars)" } } ``` -------------------------------- ### Codepoint Reference using Decimal Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/export-formats.md Lists codepoint mappings from decimal values (and their hexadecimal equivalents) to icon names. This is useful for understanding the direct mapping of icons to Unicode values. ```javascript 60000 (0xEA60) → "add", "plus", "gist-new", "repo-create" 60001 (0xEA61) → "lightbulb", "light-bulb" 60002 (0xEA62) → "repo", "repo-delete" ... 60612 (0xEA84) → "run-compact" ``` -------------------------------- ### Perform Automatic Versioning and Tagging Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/development-guide.md Automatically bumps the patch version, commits the changes, and creates a Git tag. Does not push to the remote repository. ```bash npm run version:tag ``` -------------------------------- ### Recommended SVG Structure Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/icon-system.md Presents the recommended structure for individual SVG icon files, emphasizing the viewBox attribute and vector shapes. ```xml ``` -------------------------------- ### Sizing Codicon Icons in HTML Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/export-formats.md Demonstrates how to control the size of codicon icons by adjusting the `font-size` property, either through inline styles or CSS classes, to match different UI requirements. ```html ``` -------------------------------- ### Fantasticon Format Transformation Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/icon-system.md Demonstrates the transformation of mapping.json data into the format required by Fantasticon for font generation. ```javascript // Input (mapping.json) { "60000": ["add", "plus", "gist-new"] } // Output (for fantasticon) { "add": 60000, "plus": 60000, "gist-new": 60000 } // Transformation (in .fantasticonrc.js) const codepoints = {}; Object.entries(mapping).forEach(([code, aliases]) => { const codeNum = parseInt(code); aliases.forEach(alias => { codepoints[alias] = codeNum; }); }); ``` -------------------------------- ### Use Icons in Web Application Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/README.md Link the codicon stylesheet and use the 'codicon' CSS class to display icons in your HTML elements. ```html ``` -------------------------------- ### Validate Metadata and Icon Consistency Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/development-guide.md Run the check-metadata script to ensure all icons have complete and consistent metadata. ```bash # Check metadata completeness and consistency npm run check-metadata # Expected output: # Total icons: xxx # Icons with metadata: xxx # Coverage: 100% # ✓ All icons have metadata and no orphaned entries found! ``` -------------------------------- ### Version Management Commands Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/build-system.md Commands to manage project versioning, including bumping package and font versions, committing changes, tagging, and pushing to git. These scripts update package.json fields and perform git operations. ```bash npm run version:bump # Patch package, minor font ``` ```bash npm run version:patch # Same as above ``` ```bash npm run version:minor # Minor package, major font ``` ```bash npm run version:major # Major package, major font ``` ```bash npm run version:commit # Bump + commit to git ``` ```bash npm run version:tag # Bump + commit + create tag ``` ```bash npm run version:push # Bump + commit + tag + push ``` -------------------------------- ### Font Testing in Application: Copy Outputs to VS Code Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/development-guide.md Copies the generated font files to the VS Code development directory and restarts VS Code to load the new font. This assumes the VS Code repository is located in the parent directory. ```bash # Copy outputs to VS Code npm run dev # This assumes vscode repo at ../vscode # Restarts VS Code to load new font ``` -------------------------------- ### Metadata Validation Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/development-guide.md Runs a script to check the coverage and consistency of the metadata. The expected output indicates 100% coverage with no reported issues. ```bash # Check coverage and consistency npm run check-metadata # Expected output shows 100% coverage with no issues ``` -------------------------------- ### Validate JSON File Syntax Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/development-guide.md Checks the syntax of mapping.json and metadata.json files using Node.js. ```bash node -e "require('fs').readFileSync('src/template/mapping.json')" && echo "✓ mapping.json valid" ``` ```bash node -e "require('fs').readFileSync('src/template/metadata.json')" && echo "✓ metadata.json valid" ``` -------------------------------- ### Animating Codicon Icons in HTML Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/export-formats.md Shows how to animate codicon icons using CSS animations, specifically demonstrating a spinning effect applied to a loading icon by defining a `@keyframes` rule and applying a `.spinning` class. ```html ``` -------------------------------- ### Font Metrics Configuration Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/types.md Configuration object for generating font files, specifying normalization, desired font types, and format-specific options like description and version for TTF output. ```javascript { normalize: true, // Normalize glyph metrics fontTypes: ['ttf'], // TrueType format formatOptions: { ttf: { description: "The icon font for Visual Studio Code", version: "1.15" // From package.json fontVersion } } } ``` -------------------------------- ### Build Pipeline Stage: Clean Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/INDEX.md Command to execute the clean stage of the build pipeline, which removes the dist directory. ```bash npm run clean ``` -------------------------------- ### HTML/CSS Icon Usage Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/icon-system.md Apply icons using HTML and CSS by adding the 'codicon' class along with the specific icon alias class. This is a common way to integrate icons into web pages. ```html
``` -------------------------------- ### Manually Control Version Bumping and Pushing Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/development-guide.md Manually bumps the version, pushes changes to the remote, and pushes tags. ```bash npm run version:patch git push git push --tags ``` -------------------------------- ### CSS Format Transformation Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/icon-system.md Illustrates the generated CSS format, where each icon alias is mapped to its corresponding codepoint for stylesheet usage. ```css /* Generated from fantasticon */ .codicon-add { --codepoint: "\ea60"; } .codicon-plus { --codepoint: "\ea60"; } .codicon-gist-new { --codepoint: "\ea60"; } .codicon-repo-create { --codepoint: "\ea60"; } ``` -------------------------------- ### Direct Unicode in HTML with TrueType Font Source: https://github.com/microsoft/vscode-codicons/blob/main/_autodocs/export-formats.md Shows how to use icons directly in HTML by referencing their Unicode codepoints using numeric entities. Named entities are mentioned but noted as non-standard. ```html &add; (not standard) ```