fontist 2.1.4 → 2.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 53b62fd1983ad3739ec4869071a9a3517ead3f581f0cbc04987bd5cc8ac6bdbf
-  data.tar.gz: ce3a64130bfcb4310f3adeeb79c8a62cfe3412f20c1cacb6c68482b11ad60ef6
+  metadata.gz: 05672d3a03b438efbe391225909a93826f3bc28796cce2e85a07594b5079e1f7
+  data.tar.gz: 4797833807c35169995bf31ad5b4141e03d21975a292b82bb3b0e9f075e18cbb
 SHA512:
-  metadata.gz: 36addd8934bcbd3a128c6850921cd66739e992ecaae65464c01457509f7b68c410a83a55efbf5698f0ae88b789f9d620ffb17751effcea718b2f876b4531c99d
-  data.tar.gz: 27f7c34fdfbd88460a95d0b3bdb03c34fc1aa4cdbcd2cd835d520e6363b288e5fd5a8417b69227c34fd3bf45f78c86b8b0fd2cf139e13931bfcced52271941f4
+  metadata.gz: 9480bdbb4afd3b90dc3de5e7ea943d7284919f43daa4edea7a3e12559037472d2deea3eec932f4feb6aea29985c67992bab8de24703c09465a8201cca461b061
+  data.tar.gz: 423929c85c2525661fe196e62dce2f49141ec67be5e68daa0b2be8920846e18d95b2ea3206f32f2b8400633f46f6c17bb35db9968d00f547a313bd6669b20637

data/.gitignore

@@ -33,3 +33,4 @@ CLAUDE.md
 # macOS font catalogs (downloaded via rake task)
 /spec/fixtures/macos_catalogs/com_apple_MobileAsset_Font*.xml
 
+.lycheecache

data/.rubocop_todo.yml

@@ -1,40 +1,441 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-01-21 22:46:14 UTC using RuboCop version 1.82.1.
+# on 2026-03-18 01:55:49 UTC using RuboCop version 1.85.1.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 25
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Gemspec/RequireMFA:
+  Exclude:
+    - 'docs/node_modules/speakingurl/speakingurl-rails.gemspec'
+
+# Offense count: 1
+Gemspec/RequiredRubyVersion:
+  Exclude:
+    - 'docs/node_modules/speakingurl/speakingurl-rails.gemspec'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Layout/ElseAlignment:
+  Exclude:
+    - 'lib/fontist/font_path.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Layout/EmptyLineAfterGuardClause:
+  Exclude:
+    - 'spec/fontist/font_spec.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyleAlignWith.
+# SupportedStylesAlignWith: keyword, variable, start_of_line
+Layout/EndAlignment:
+  Exclude:
+    - 'lib/fontist/font_path.rb'
+
+# Offense count: 4
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowForAlignment, AllowBeforeTrailingComments, ForceEqualSignAlignment.
+Layout/ExtraSpacing:
+  Exclude:
+    - 'docs/node_modules/speakingurl/lib/speakingurl-rails.rb'
+    - 'docs/node_modules/speakingurl/speakingurl-rails.gemspec'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: Width, EnforcedStyleAlignWith, AllowedPatterns.
+# SupportedStylesAlignWith: start_of_line, relative_to_receiver
+Layout/IndentationWidth:
+  Exclude:
+    - 'lib/fontist/font_path.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowDoxygenCommentStyle, AllowGemfileRubyComment, AllowRBSInlineAnnotation, AllowSteepAnnotation.
+Layout/LeadingCommentSpace:
+  Exclude:
+    - 'spec/fontist/install_locations/system_location_spec.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Layout/LeadingEmptyLines:
+  Exclude:
+    - 'lib/fontist/macos_import_source.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: space, no_space
+Layout/LineContinuationSpacing:
+  Exclude:
+    - 'lib/fontist/import/google/data_sources/github.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: aligned, indented
+Layout/LineEndStringConcatenationIndentation:
+  Exclude:
+    - 'lib/fontist/errors.rb'
+
+# Offense count: 576
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
 Layout/LineLength:
+  Enabled: false
+
+# Offense count: 5
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowForAlignment, EnforcedStyleForExponentOperator, EnforcedStyleForRationalLiterals.
+# SupportedStylesForExponentOperator: space, no_space
+# SupportedStylesForRationalLiterals: space, no_space
+Layout/SpaceAroundOperators:
   Exclude:
-    - 'spec/fontist/manifest_spec.rb'
-    - 'spec/support/platform_fonts.rb'
+    - 'docs/node_modules/speakingurl/lib/speakingurl-rails.rb'
+    - 'docs/node_modules/speakingurl/speakingurl-rails.gemspec'
 
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowComments.
-Lint/EmptyConditionalBody:
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: final_newline, final_blank_line
+Layout/TrailingEmptyLines:
+  Exclude:
+    - 'spec/fontist/utils/github_url_spec.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowInHeredoc.
+Layout/TrailingWhitespace:
   Exclude:
     - 'spec/fontist/manifest_spec.rb'
 
-# Offense count: 8
+# Offense count: 5
+# This cop supports safe autocorrection (--autocorrect).
+Lint/AmbiguousOperatorPrecedence:
+  Exclude:
+    - 'lib/fontist/import/import_display.rb'
+    - 'lib/fontist/utils/downloader.rb'
+    - 'lib/fontist/utils/system.rb'
+
+# Offense count: 1
+Lint/CopDirectiveSyntax:
+  Exclude:
+    - 'spec/support/fontist_helper.rb'
+
+# Offense count: 3
+# Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
+Lint/DuplicateBranch:
+  Exclude:
+    - 'lib/fontist/helpers.rb'
+    - 'lib/fontist/import/import_display.rb'
+    - 'lib/fontist/utils/downloader.rb'
+
+# Offense count: 2
+Lint/DuplicateMethods:
+  Exclude:
+    - 'lib/fontist/import/recursive_extraction.rb'
+    - 'lib/fontist/system_index.rb'
+
+# Offense count: 9
+# Configuration parameters: AllowComments, AllowEmptyLambdas.
+Lint/EmptyBlock:
+  Exclude:
+    - 'spec/fontist/resources/apple_cdn_resource_spec.rb'
+    - 'spec/fontist/utils/file_ops_spec.rb'
+
+# Offense count: 28
+# This cop supports unsafe autocorrection (--autocorrect-all).
+Lint/NonAtomicFileOperation:
+  Exclude:
+    - 'lib/fontist/cache/store.rb'
+    - 'spec/fontist/cache/manager_spec.rb'
+    - 'spec/fontist/cache/store_spec.rb'
+    - 'spec/fontist/indexes/directory_change_spec.rb'
+    - 'spec/fontist/indexes/directory_snapshot_spec.rb'
+    - 'spec/fontist/indexes/incremental_index_updater_spec.rb'
+    - 'spec/fontist/indexes/incremental_scanner_spec.rb'
+    - 'spec/fontist/manifest_spec.rb'
+    - 'spec/fontist/path_scanning_spec.rb'
+    - 'spec/fontist/utils/file_ops_spec.rb'
+    - 'spec/support/fontist_helper.rb'
+    - 'spec/support/spec_isolation_manager.rb'
+    - 'spec/support/system_fonts.rb'
+    - 'spec/support/windows_test_helper.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowUnusedKeywordArguments, IgnoreEmptyMethods, IgnoreNotImplementedMethods, NotImplementedExceptions.
+# NotImplementedExceptions: NotImplementedError
+Lint/UnusedMethodArgument:
+  Exclude:
+    - 'lib/fontist/validator.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: ContextCreatingMethods, MethodCreatingMethods.
+Lint/UselessAccessModifier:
+  Exclude:
+    - 'lib/fontist/utils/downloader.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Lint/UselessAssignment:
+  Exclude:
+    - 'lib/fontist/cache/store.rb'
+
+# Offense count: 98
+# Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
+Metrics/AbcSize:
+  Enabled: false
+
+# Offense count: 10
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 # AllowedMethods: refine
 Metrics/BlockLength:
-  Max: 320
+  Max: 63
 
-# Offense count: 2
+# Offense count: 57
+# Configuration parameters: AllowedMethods, AllowedPatterns, Max.
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+# Offense count: 160
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
-  Max: 14
+  Max: 129
+
+# Offense count: 3
+# Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
+Metrics/ParameterLists:
+  Max: 6
+
+# Offense count: 46
+# Configuration parameters: AllowedMethods, AllowedPatterns, Max.
+Metrics/PerceivedComplexity:
+  Enabled: false
+
+# Offense count: 3
+# Configuration parameters: MinNameLength, AllowNamesEndingInNumbers, AllowedNames, ForbiddenNames.
+# AllowedNames: as, at, by, cc, db, id, if, in, io, ip, of, on, os, pp, to
+Naming/MethodParameterName:
+  Exclude:
+    - 'spec/fontist/memoizable_spec.rb'
+
+# Offense count: 4
+# Configuration parameters: Mode, AllowedMethods, AllowedPatterns, AllowBangMethods, WaywardPredicates.
+# AllowedMethods: call
+# WaywardPredicates: infinite?, nonzero?
+Naming/PredicateMethod:
+  Exclude:
+    - 'lib/fontist.rb'
+    - 'lib/fontist/font.rb'
+    - 'lib/fontist/import/google/models/metadata.rb'
+    - 'spec/fontist/memoizable_spec.rb'
+
+# Offense count: 4
+# Configuration parameters: MinSize.
+Performance/CollectionLiteralInLoop:
+  Exclude:
+    - 'lib/fontist/cache/manager.rb'
+    - 'lib/fontist/import/otf/font_file.rb'
+    - 'spec/fontist/import/create_formula_spec.rb'
+
+# Offense count: 16
+# This cop supports unsafe autocorrection (--autocorrect-all).
+Performance/MapCompact:
+  Exclude:
+    - 'lib/fontist/font.rb'
+    - 'lib/fontist/formula.rb'
+    - 'lib/fontist/import/formula_builder.rb'
+    - 'lib/fontist/import/google/data_sources/github.rb'
+    - 'lib/fontist/import/google/font_database.rb'
+    - 'lib/fontist/import/google/metadata_adapter.rb'
+    - 'lib/fontist/indexes/incremental_scanner.rb'
+    - 'lib/fontist/macos/catalog/asset.rb'
+    - 'lib/fontist/system_index.rb'
+    - 'lib/fontist/validation.rb'
+    - 'lib/fontist/validator.rb'
+
+# Offense count: 2
+Security/MarshalLoad:
+  Exclude:
+    - 'lib/fontist/cache/store.rb'
+    - 'spec/fontist/cache/store_spec.rb'
+
+# Offense count: 4
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: trailing_conditional, ternary
+Style/EmptyStringInsideInterpolation:
+  Exclude:
+    - 'lib/fontist/import/import_display.rb'
+    - 'lib/fontist/import/macos.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+Style/ExpandPathArguments:
+  Exclude:
+    - 'docs/node_modules/speakingurl/lib/speakingurl-rails.rb'
+    - 'docs/node_modules/speakingurl/speakingurl-rails.gemspec'
+
+# Offense count: 12
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowedVars, DefaultToNil.
+Style/FetchEnvVar:
+  Exclude:
+    - 'lib/fontist/utils/system.rb'
+    - 'spec/fontist/import/google/data_sources/base_spec.rb'
+    - 'spec/fontist/import/google/data_sources/ttf_spec.rb'
+    - 'spec/fontist/import/google/data_sources/vf_spec.rb'
+    - 'spec/fontist/import/google/data_sources/woff2_spec.rb'
+    - 'spec/fontist/install_locations/system_location_spec.rb'
+    - 'spec/support/fontist_helper.rb'
+    - 'spec/support/fresh_home.rb'
+    - 'spec/support/vcr_setup.rb'
+
+# Offense count: 1
+Style/FileOpen:
+  Exclude:
+    - 'lib/fontist/utils/locking.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Style/FileWrite:
+  Exclude:
+    - 'lib/fontist/import/upgrade_formulas.rb'
+
+# Offense count: 1
+# This cop supports unsafe autocorrection (--autocorrect-all).
+# Configuration parameters: AllowSplatArgument.
+Style/HashConversion:
+  Exclude:
+    - 'lib/fontist/system_index.rb'
 
 # Offense count: 1
 # Configuration parameters: MinBranchesCount.
 Style/HashLikeCase:
   Exclude:
     - 'spec/support/platform_fonts.rb'
+
+# Offense count: 6
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, EnforcedShorthandSyntax, UseHashRocketsWithSymbolValues, PreferHashRocketsForNonAlnumEndingSymbols.
+# SupportedStyles: ruby19, hash_rockets, no_mixed_keys, ruby19_no_mixed_keys
+# SupportedShorthandSyntax: always, never, either, consistent, either_consistent
+Style/HashSyntax:
+  Exclude:
+    - 'docs/node_modules/speakingurl/lib/speakingurl-rails.rb'
+    - 'spec/fontist/font_spec.rb'
+    - 'spec/fontist/formulas_isolation_spec.rb'
+    - 'spec/fontist/manifest_spec.rb'
+
+# Offense count: 4
+# This cop supports unsafe autocorrection (--autocorrect-all).
+Style/IdenticalConditionalBranches:
+  Exclude:
+    - 'lib/fontist/helpers.rb'
+    - 'lib/fontist/import/import_display.rb'
+
+# Offense count: 3
+# This cop supports unsafe autocorrection (--autocorrect-all).
+Style/MapToHash:
+  Exclude:
+    - 'lib/fontist/system_index.rb'
+    - 'lib/fontist/utils/downloader.rb'
+    - 'spec/fontist/indexes/incremental_scanner_spec.rb'
+
+# Offense count: 1
+# This cop supports unsafe autocorrection (--autocorrect-all).
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: literals, strict
+Style/MutableConstant:
+  Exclude:
+    - 'lib/fontist/utils/github_url.rb'
+
+# Offense count: 1
+Style/OpenStructUse:
+  Exclude:
+    - 'spec/fontist/cache/store_spec.rb'
+
+# Offense count: 1
+# This cop supports unsafe autocorrection (--autocorrect-all).
+Style/PartitionInsteadOfDoubleSelect:
+  Exclude:
+    - 'spec/fontist/import/google/data_sources/vf_spec.rb'
+
+# Offense count: 3
+# This cop supports unsafe autocorrection (--autocorrect-all).
+Style/ReduceToHash:
+  Exclude:
+    - 'lib/fontist/import/google/font_database.rb'
+    - 'lib/fontist/indexes/directory_snapshot.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Style/RedundantBegin:
+  Exclude:
+    - 'spec/fontist/font_spec.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Style/RedundantRegexpArgument:
+  Exclude:
+    - 'lib/fontist/repo.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+Style/RescueModifier:
+  Exclude:
+    - 'lib/fontist/cache/store.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: implicit, explicit
+Style/RescueStandardError:
+  Exclude:
+    - 'lib/fontist/cache/store.rb'
+
+# Offense count: 1
+# Configuration parameters: Max.
+Style/SafeNavigationChainLength:
+  Exclude:
+    - 'lib/fontist/system_index.rb'
+
+# Offense count: 2
+# This cop supports unsafe autocorrection (--autocorrect-all).
+# Configuration parameters: Mode.
+Style/StringConcatenation:
+  Exclude:
+    - 'lib/fontist/cache/store.rb'
+    - 'spec/fontist/system_index_spec.rb'
+
+# Offense count: 5
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, ConsistentQuotesInMultiline.
+# SupportedStyles: single_quotes, double_quotes
+Style/StringLiterals:
+  Exclude:
+    - 'docs/node_modules/speakingurl/lib/speakingurl-rails.rb'
+    - 'docs/node_modules/speakingurl/speakingurl-rails.gemspec'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Style/SuperArguments:
+  Exclude:
+    - 'lib/fontist/import/google/models/font_family.rb'
+
+# Offense count: 6
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyleForMultiline.
+# SupportedStylesForMultiline: comma, consistent_comma, diff_comma, no_comma
+Style/TrailingCommaInArguments:
+  Exclude:
+    - 'lib/fontist/utils/github_url.rb'
+    - 'spec/fontist/system_index_spec.rb'
+    - 'spec/fontist/utils/github_url_spec.rb'

data/Gemfile

@@ -5,6 +5,7 @@ gemspec
 
 gem "bundler"
 gem "openssl", "~> 3.0"
+gem "ostruct"
 gem "pry"
 gem "rake"
 gem "rspec"

data/docs/.vitepress/config.ts

@@ -125,6 +125,23 @@ export default defineConfig({
             },
           ],
         },
+        {
+          text: "Platforms",
+          collapsed: true,
+          items: [
+            { text: "Overview", link: "/guide/platforms/" },
+            { text: "macOS", link: "/guide/platforms/macos" },
+            { text: "Windows", link: "/guide/platforms/windows" },
+          ],
+        },
+        {
+          text: "Maintainer Docs",
+          collapsed: true,
+          items: [
+            { text: "Overview", link: "/guide/maintainer/" },
+            { text: "Importing Fonts", link: "/guide/maintainer/import" },
+          ],
+        },
       ],
       "/cli/": [
         {

data/docs/cli/create-formula.md

@@ -41,6 +41,12 @@ fontist create-formula https://example.com/fonts/myfont.zip --file-pattern "*.ot
 
 # Add mirror URLs
 fontist create-formula https://example.com/fonts/myfont.zip --mirror https://mirror.example.com/fonts/myfont.zip
+
+# Create formula with name prefix (for compatibility fonts)
+fontist create-formula https://dl.winehq.org/wine/source/10.x/wine-10.18.tar.xz \
+  --subdir fonts \
+  --file-pattern "*.ttf" \
+  --name-prefix "Wine "
 ```
 
 ## How It Works

data/docs/cli/import.md

@@ -2,6 +2,10 @@
 
 Import fonts from external sources and create Fontist formulas.
 
+::: warning Maintainer Only
+These commands are for Fontist formula maintainers only. End users should use [`fontist install`](/cli/install) to install fonts from the official repository.
+:::
+
 ## Subcommands
 
 | Command | Description |

data/docs/guide/formulas.md

@@ -184,6 +184,79 @@ Private repos are stored alongside the main formulas:
 
 See the [repo command reference](/cli/repo) for complete command documentation.
 
+---
+
+## Advanced Formula Features
+
+### Overriding Font Metadata
+
+Some fonts (especially older ones) contain inconsistent or imperfect metadata. For example, some fonts apply different OTF `Family` values for different font styles, which prevents all styles from being registered under the same family.
+
+The `override:` key allows you to correct metadata without modifying the font files:
+
+```yaml
+fonts:
+- name: Frutiger 45 Light
+  styles:
+  - family_name: Frutiger 45 Light
+    type: Regular
+    full_name: Frutiger-Light
+    post_script_name: Frutiger-Light
+    override:
+      preferred_family_name: Frutiger
+```
+
+This override:
+- Does not modify the actual font file
+- Only affects Fontist's internal indexing
+- Allows all Frutiger fonts to be installed together:
+
+```sh
+fontist install "Frutiger" --preferred-family
+```
+
+### HTTP Authentication
+
+Private formula repositories may require authentication. Configure this when setting up the repository:
+
+```sh
+# GitLab example with private token
+fontist repo setup company-fonts \
+  "https://user:${PRIVATE_TOKEN}@gitlab.com/company/font-formulas.git"
+```
+
+### Authorization Headers
+
+For private archives (e.g., GitHub releases), add authorization headers to the formula:
+
+```yaml
+resources:
+  fonts.zip:
+    urls:
+    - url: https://github.com/company/fonts/releases/assets/12345
+      headers:
+        Accept: application/octet-stream
+        Authorization: token ghp_your_token_here
+```
+
+::: warning Token Scopes
+GitHub tokens need at least the `repo` scope for access to release assets. Generate tokens at [GitHub Settings > Tokens](https://github.com/settings/tokens).
+:::
+
+### Name Prefix Option
+
+When creating formulas for compatibility or replacement fonts, use `--name-prefix` to distinguish them:
+
+```sh
+# Create formula for Wine compatibility fonts
+fontist create-formula https://dl.winehq.org/wine/source/10.x/wine-10.18.tar.xz \
+  --subdir fonts \
+  --file-pattern '*.ttf' \
+  --name-prefix 'Wine '
+```
+
+This generates a formula where all fonts have names prefixed with "Wine ", making it clear these are Wine compatibility fonts rather than the original Microsoft fonts.
+
 ## Related
 
 - [How Fontist Works](/guide/how-it-works) - Internal architecture and indexes

data/docs/guide/installation.md

@@ -43,6 +43,34 @@ macOS comes with Ruby pre-installed. If you encounter permission issues, conside
 
 On Windows, we recommend using [RubyInstaller](https://rubyinstaller.org/) which includes the DevKit needed for native extensions.
 
+#### Windows Installation Steps
+
+1. **Download RubyInstaller** from [rubyinstaller.org](https://rubyinstaller.org/downloads/)
+   - Select the **"Ruby+Devkit"** version (not the plain Ruby version)
+   - Example: `Ruby+Devkit 3.2.X (x64)`
+
+2. **Run the installer**
+   - Check "Add Ruby executables to your PATH"
+   - Check "Associate .rb files with this Ruby installation"
+
+3. **Set up MSYS2** (required for native extensions):
+   ```powershell
+   ridk install
+   ```
+   Select option **3** (MSYS2 and MINGW development toolchain) when prompted.
+
+4. **Install Git for Windows** from [git-scm.com](https://git-scm.com/download/win)
+   - Required for `fontist update` and `fontist repo` commands
+
+5. **Verify installation**:
+   ```powershell
+   ruby --version
+   gem install fontist
+   fontist version
+   ```
+
+See the [Windows Platform Guide](/guide/platforms/windows) for Windows-specific considerations.
+
 ### Linux
 
 Most Linux distributions have Ruby available through their package managers:
@@ -94,6 +122,40 @@ sudo dnf install gcc ruby-devel
 xcode-select --install
 ```
 
+## Native Dependencies
+
+Fontist depends on several gems with native C/C++ extensions. The following table shows what's required:
+
+| Gem | Compiler | Purpose |
+|-----|----------|---------|
+| `json` | gcc | JSON parsing |
+| `brotli` (via fontisan) | gcc | WOFF2 font decompression |
+| `seven-zip` (via excavate) | g++ | 7z archive extraction |
+| `libmspack` (via excavate) | gcc | CAB/CHM archive extraction |
+| `ffi-libarchive-binary` (via excavate) | gcc | Archive extraction (zip, tar, etc.) |
+
+::: note Prebuilt Binaries
+Some gems like `nokogiri` and `ffi` provide prebuilt binaries for common platforms, so they typically don't require compilation.
+:::
+
+### Windows DevKit Setup
+
+On Windows, native extensions require the RubyInstaller DevKit:
+
+1. Download [RubyInstaller](https://rubyinstaller.org/downloads/) with DevKit (select "Ruby+Devkit" version)
+
+2. Run the installer, checking "Add Ruby executables to your PATH"
+
+3. After installation, run the following in a command prompt:
+
+   ```cmd
+   ridk install
+   ```
+
+4. Select option **3** (MSYS2 and MINGW development toolchain) when prompted
+
+5. Install [Git for Windows](https://git-scm.com/download/win) for `fontist update` and `fontist repo` commands
+
 ### Proxy Configuration
 
 If you're behind a proxy, configure Git to use it: