fontist 2.1.3 → 2.1.5

data/docs/guide/platforms/macos.md

@@ -0,0 +1,151 @@
+---
+title: macOS Platform Guide
+---
+
+# macOS Platform Guide
+
+Fontist provides special support for macOS supplementary fonts, a framework introduced in macOS 10.12 (Sierra) for dynamically downloading licensed fonts on demand.
+
+## Supplementary Fonts Overview
+
+macOS provides a "supplementary fonts" framework (shared with iOS) for dynamically downloading and installing a wide range of licensed fonts. These fonts are typically commercial fonts that come free with macOS.
+
+### Typical Use Cases
+
+- CI jobs on macOS environments using specially-licensed fonts
+- Automating installation of macOS add-on fonts
+- Accessing platform-specific fonts not available elsewhere
+
+::: warning Non-macOS Installation
+Fontist does not allow installing macOS-specific fonts on non-macOS platforms due to font license restrictions.
+:::
+
+---
+
+## Framework Versioning
+
+The macOS supplementary font catalog is bound to specific framework versions. Different versions contain different sets of fonts, and often different versions of the same fonts.
+
+### Version Compatibility
+
+| macOS Version | Framework Version | Platform Tag |
+|---------------|-------------------|--------------|
+| macOS 10.12 (Sierra) | Font 3 | `macos-font3` |
+| macOS 10.13 (High Sierra) | Font 4 | `macos-font4` |
+| macOS 10.14 (Mojave) | Font 5 | `macos-font5` |
+| macOS 10.15 (Catalina) | Font 6 | `macos-font6` |
+| macOS 11 (Big Sur) | Font 6 | `macos-font6` |
+| macOS 12 (Monterey) | Font 7 | `macos-font7` |
+| macOS 13 (Ventura) | Font 7 | `macos-font7` |
+| macOS 14 (Sonoma) | Font 7 | `macos-font7` |
+| macOS 15 (Sequoia) | Font 7 | `macos-font7` |
+| macOS 26+ (Tahoe) | Font 8 | `macos-font8` |
+
+### How Versioning Works
+
+A macOS system can only download fonts from the catalog version corresponding to its framework version. Fontist respects this limitation when installing these fonts.
+
+When you install a macOS add-on font, Fontist automatically detects your macOS version and installs the appropriate font version:
+
+```sh
+fontist install "Al Bayan"
+# On macOS 15: installs Font7 version formula
+# On macOS 26: installs Font8 version formula
+```
+
+This ensures you always get the font version compatible with your system.
+
+---
+
+## Platform Tags
+
+In Fontist Formulas, each supplementary font is backed by a formula specifying the font framework version using platform tags.
+
+### Tag Format
+
+Platform tags follow the pattern: `macos-fontX` where `X` is the catalog version number.
+
+### Version Compatibility Checking
+
+Fontist controls version compatibility through platform tags:
+
+```sh
+# On macOS 14.2 (Sonoma), trying to install a Font8-only formula:
+fontist install "Font8OnlyFont"
+
+# Error output:
+# Font 'Font8OnlyFont' is only available for: macos-font8.
+# Your current platform is: macos. Your macOS version is: 14.2.1.
+# This font requires macOS 26.0 or later.
+# This font cannot be installed on your system.
+```
+
+---
+
+## Manual Installation Methods
+
+On macOS, supplementary fonts can also be installed manually:
+
+### Method 1: Application Trigger
+
+User applications can trigger installation when needed, as described in Apple's ["DownloadFont" sample code](https://developer.apple.com/library/archive/samplecode/DownloadFont/Introduction/Intro.html).
+
+### Method 2: Font Book
+
+1. Open **Font Book.app**
+2. Search for the desired font
+3. Click "Download"
+
+Both methods trigger a download from Apple's Mobile Asset Server.
+
+---
+
+## Asset Catalog Locations
+
+The asset catalog XML files are located at:
+
+| Version | System Path |
+|---------|-------------|
+| Font 3 | `/System/Library/Assets/com_apple_MobileAsset_Font3/com_apple_MobileAsset_Font3.xml` |
+| Font 4 | `/System/Library/Assets/com_apple_MobileAsset_Font4/com_apple_MobileAsset_Font4.xml` |
+| Font 5 | `/System/Library/AssetsV2/com_apple_MobileAsset_Font5/com_apple_MobileAsset_Font5.xml` |
+| Font 6 | `/System/Library/AssetsV2/com_apple_MobileAsset_Font6/com_apple_MobileAsset_Font6.xml` |
+| Font 7 | `/System/Library/AssetsV2/com_apple_MobileAsset_Font7/com_apple_MobileAsset_Font7.xml` |
+| Font 8 | `/System/Library/AssetsV2/com_apple_MobileAsset_Font8/com_apple_MobileAsset_Font8.xml` |
+
+::: note Schema Differences
+The Assets and AssetsV2 frameworks use slightly different Plist schemas.
+:::
+
+---
+
+## Font Sources by macOS Version
+
+For the complete list of available fonts on each macOS version, see Apple's support pages:
+
+| macOS Version | Apple Support Link |
+|---------------|-------------------|
+| macOS 15 (Sequoia) | [Fonts included with macOS Sequoia](https://support.apple.com/en-us/120414) |
+| macOS 14 (Sonoma) | [Fonts included with macOS Sonoma](https://support.apple.com/en-us/108939) |
+
+::: note Older macOS Versions
+Apple may remove or relocate support articles for older macOS versions. For Ventura, Monterey, Big Sur, and earlier versions, use Font Book on your Mac to view available fonts, or search Apple Support for the specific version.
+:::
+
+---
+
+## Example: Installing Canela
+
+Canela is a commercial font that comes free with macOS:
+
+```sh
+fontist install Canela
+```
+
+---
+
+## See Also
+
+- [How Fontist Works](/guide/how-it-works) - Architecture and indexes
+- [Formulas Guide](/guide/formulas) - How formulas work
+- [Fontist Blog: Installing macOS-specific add-on fonts](https://www.fontist.org/blog/2022-02-11-macos-fonts)

data/docs/guide/platforms/windows.md

@@ -0,0 +1,220 @@
+---
+title: Windows Platform Guide
+---
+
+# Windows Platform Guide
+
+Fontist provides comprehensive Windows platform support, allowing installation and management of fonts on Windows 7 and later.
+
+## Windows Font Management
+
+Windows font management differs from Unix systems in several key ways:
+
+| Difference | Description |
+|------------|-------------|
+| Path separator | Uses backslash (`\`) instead of forward slash (`/`) |
+| Font locations | Registry-based and directory-based locations |
+| File locking | Stricter file locking during operations |
+| Permissions | Case-insensitive but case-preserving filesystem |
+
+---
+
+## Windows Font Locations
+
+Fontist supports three installation locations on Windows:
+
+### System Fonts
+
+| Property | Value |
+|----------|-------|
+| Location | `C:\Windows\Fonts` |
+| Requires Admin | Yes |
+| Available To | All users |
+
+### User Fonts
+
+| Property | Value |
+|----------|-------|
+| Location | `%LOCALAPPDATA%\Microsoft\Windows\Fonts` |
+| Requires Admin | No |
+| Available To | Current user only |
+| Windows Version | Windows 10+ |
+
+### Fontist Library
+
+| Property | Value |
+|----------|-------|
+| Location | `%USERPROFILE%\.fontist\fonts` |
+| Requires Admin | No |
+| Available To | Current user only |
+| Default | Yes |
+
+Fontist creates a `fontist` subdirectory within user and system font directories to avoid cluttering the main font directory.
+
+---
+
+## Installation Examples
+
+### Install to Fontist Library (Default)
+
+```powershell
+# No administrator privileges required
+fontist install "Roboto"
+```
+
+### Install to User Fonts Directory
+
+```powershell
+# No administrator privileges required (Windows 10+)
+fontist install "Roboto" --location=user
+```
+
+### Install to System Fonts Directory
+
+```powershell
+# Run as Administrator
+fontist install "Roboto" --location=system
+```
+
+---
+
+## Windows-Specific Considerations
+
+### File Locking
+
+Windows uses stricter file locking than Unix systems. Fontist handles this with automatic retry logic when encountering locked files during cleanup operations.
+
+If you encounter file locking issues:
+1. Close applications that might be using the font
+2. Retry the operation
+3. Use Task Manager to identify processes locking the file
+
+### Path Handling
+
+Fontist automatically handles Windows path separators and drive letters. Font paths are returned in Windows-native format:
+
+```
+C:\Users\user\.fontist\fonts\font.ttf
+```
+
+### Registry Integration
+
+While Windows historically used registry-based font registration, modern Windows (10+) supports directory-based fonts. Fontist uses directory-based installation for maximum compatibility and ease of management.
+
+### Administrator Privileges
+
+| Operation | Admin Required |
+|-----------|----------------|
+| Install to `fontist` location | No |
+| Install to `user` location | No |
+| Install to `system` location | Yes |
+| Uninstall from system fonts | Yes |
+
+---
+
+## Platform Compatibility
+
+| Windows Version | Support Status | Notes |
+|-----------------|----------------|-------|
+| Windows 11 | ✅ Fully Supported | All features available |
+| Windows 10 | ✅ Fully Supported | User font directory available |
+| Windows 8/8.1 | ✅ Supported | System and fontist locations only |
+| Windows 7 | ⚠️ Limited Support | System and fontist locations only |
+
+::: warning Windows 7 Support
+Extended support for Windows 7 ended January 14, 2020. Fontist is tested on Windows 10 and later. Earlier versions may work but are not actively tested.
+:::
+
+---
+
+## Ruby Installation on Windows
+
+### Prerequisites
+
+1. **RubyInstaller with DevKit** - Required for native gem extensions
+2. **MSYS2** - Required for building native extensions
+3. **Git for Windows** - Required for `fontist update` and `fontist repo` commands
+
+### Installation Steps
+
+1. Download [RubyInstaller](https://rubyinstaller.org/downloads/) (select "Ruby+Devkit" version)
+
+2. Run the installer and check "Add Ruby executables to your PATH"
+
+3. After installation, run MSYS2 setup:
+   ```powershell
+   ridk install
+   ```
+   Select option 3 (MSYS2 and MINGW development toolchain) when prompted.
+
+4. Install [Git for Windows](https://git-scm.com/download/win)
+
+5. Install Fontist:
+   ```powershell
+   gem install fontist
+   ```
+
+---
+
+## Troubleshooting
+
+### Native Extension Errors
+
+If you see errors about failed compilations:
+
+```powershell
+# Ensure MSYS2 is properly installed
+ridk install
+
+# Reinstall the gem with verbose output
+gem install fontist --verbose
+```
+
+### Permission Errors
+
+If you get permission errors:
+
+```powershell
+# Option 1: Install to user directory
+fontist install "Roboto" --location=user
+
+# Option 2: Run as Administrator for system fonts
+# Right-click PowerShell → "Run as administrator"
+fontist install "Roboto" --location=system
+```
+
+### Path Too Long Errors
+
+Windows has a 260 character path limit by default. If you encounter path issues:
+
+1. Enable long paths in Windows (requires admin):
+   ```powershell
+   # Run as Administrator
+   New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" `
+     -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force
+   ```
+
+2. Or use a shorter installation path via environment variable:
+   ```powershell
+   $env:FONTIST_PATH = "C:\f"
+   fontist install "Roboto"
+   ```
+
+---
+
+## Environment Variables
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `FONTIST_PATH` | Base directory for Fontist data | `C:\fontist` |
+| `FONTIST_INSTALL_LOCATION` | Default install location | `user` |
+| `FONTIST_USER_FONTS_PATH` | Custom user fonts path | `C:\Users\me\Fonts` |
+| `FONTIST_SYSTEM_FONTS_PATH` | Custom system fonts path | `C:\Windows\Fonts` |
+
+---
+
+## See Also
+
+- [Installation Guide](/guide/installation) - General installation instructions
+- [Install Command](/cli/install) - CLI reference for install
+- [How Fontist Works](/guide/how-it-works) - Architecture overview

data/docs/guide/quick-start.md

@@ -0,0 +1,76 @@
+---
+title: Quick Start
+---
+
+# Quick Start
+
+Get up and running with Fontist in 5 minutes. This guide walks through installing a font, checking its status, and using it in a manifest.
+
+## Step 1: Install a Font
+
+Install your first font using the `install` command:
+
+```sh
+fontist install "Fira Code"
+```
+
+Some fonts may require you to accept license terms. Use the `--accept-all-licenses` flag to skip prompts (useful for CI):
+
+```sh
+fontist install "Fira Code" --accept-all-licenses
+```
+
+## Step 2: Check Installation Status
+
+Verify the font was installed correctly:
+
+```sh
+fontist status
+```
+
+This shows all installed fonts and their paths:
+
+```
+Fira Code
+  Regular: ~/.fontist/fonts/FiraCode-Regular.ttf
+  Bold: ~/.fontist/fonts/FiraCode-Bold.ttf
+```
+
+To see all available fonts (installed and installable):
+
+```sh
+fontist list
+```
+
+## Step 3: Use a Manifest
+
+Manifests let you define project fonts in a YAML file for reproducible installations.
+
+Create a `fonts.yml` file:
+
+```yaml
+Fira Code:
+Open Sans:
+Roboto:
+```
+
+Install all fonts from the manifest:
+
+```sh
+fontist manifest install fonts.yml
+```
+
+Get the installation paths for manifest fonts:
+
+```sh
+fontist manifest locations fonts.yml
+```
+
+This outputs a YAML structure with font paths, which can be used in your build scripts or applications.
+
+## What's Next?
+
+- [Manifests Guide](/guide/manifests) - Deep dive into manifest format and use cases
+- [Formulas Guide](/guide/formulas) - Learn how Fontist finds and downloads fonts
+- [CLI Reference](/cli/) - Explore all available commands
+- [Ruby API](/api/) - Use Fontist programmatically from Ruby

data/docs/guide/why.md

@@ -1,3 +1,7 @@
+---
+title: Why Fontist?
+---
+
 # Why Fontist?
 
 In general, fonts can be downloaded manually and placed in a system folder. Some fonts are even pre-installed with an OS. **This is inconsistent across Windows, macOS, and Linux.**

data/docs/index.md

@@ -1,40 +1,72 @@
 ---
-# https://vitepress.dev/reference/default-theme-home-page
 layout: home
+pageClass: my-index-page
 
 hero:
-  # name: "Fontist"
-  text: "Manage your fonts effortlessly"
-  tagline: Fontist brings cross-platform font management to the command line for Windows, Linux, and macOS. Free and open source.
-  image:
-    src: /hero.png
+  name: "Fontist"
+  text: "Cross-platform font management"
+  tagline: Install, manage, and build fonts programmatically. Works identically on Windows, macOS, and Linux.
   actions:
     - theme: brand
-      text: 🚀 Get started
+      text: Get Started
       link: /guide/
     - theme: alt
-      text: 💎 Ruby API
-      link: /guide/api-ruby
+      text: CLI Reference
+      link: /cli/
     - theme: alt
-      text: 🍰 Formulas
-      link: https://fontist.org/formulas/
-      target: _self
+      text: Ruby API
+      link: /api/
+
+features:
+  - title: "🌐 Cross-Platform"
+    details: Same commands work identically on Windows, macOS, and Linux. No platform-specific paths to remember.
+  - title: "📦 Formula-Based"
+    details: 3000+ fonts available through community-maintained formulas with automatic download and license handling.
+  - title: "📋 Manifest Support"
+    details: Define font requirements in YAML for reproducible installations across environments and CI/CD pipelines.
+  - title: "🔄 CI/CD Ready"
+    details: Perfect for automated environments with non-interactive installation. GitHub Action available.
+  - title: "🔍 System Detection"
+    details: Detects and indexes fonts already installed on your system. No redundant downloads.
+  - title: "⚡ Fontconfig Integration"
+    details: Optional fontconfig integration for seamless font discovery in Linux environments.
 ---
 
-<!-- Excerpt from the Getting Started guide page. Try to keep it in sync! -->
+<WithinHero>
+<HeroCodeBlock title="fontist"><div class="line"><span class="comment"># 🚀 Install a font by name</span></div><div class="line"><span class="prompt">$</span> <span class="cmd">fontist</span> install "Open Sans"</div><div class="line"><span class="success">✓</span> Open Sans installed to ~/.fontist/fonts</div><div class="line">&nbsp;</div><div class="line"><span class="comment"># 📜 Install from manifest</span></div><div class="line"><span class="prompt">$</span> <span class="cmd">fontist</span> manifest-install manifest.yml</div><div class="line"><span class="success">✓</span> All fonts from manifest installed</div><div class="line">&nbsp;</div><div class="line"><span class="comment"># 🔍 Check font status</span></div><div class="line"><span class="prompt">$</span> <span class="cmd">fontist</span> status "Fira Code"</div><div class="line"><span class="success">✓</span> Fira Code Regular, Bold installed</div></HeroCodeBlock>
+</WithinHero>
 
-```sh
-gem install fontist
-```
+## Quick Start
 
-💎 Don't have Ruby installed? You can [download Ruby from the official Ruby website](https://www.ruby-lang.org/en/downloads/).
+```bash
+# Install a font by name
+fontist install "Open Sans"
 
-Now you're ready to start using Fontist to install fonts on your machine! 🤩
+# Install from a manifest file
+fontist manifest-install manifest.yml
 
-```sh
-fontist install "Fira Code"
-fontist install "Open Sans"
-fontist install "Consolas"
+# Check font status
+fontist status "Fira Code"
 ```
 
-[📚 Read more in the Getting Started guide](/guide/)
+## Use Cases
+
+**CI/CD Pipelines** — Automatically install fonts in GitHub Actions, GitLab CI, or any automation system. Non-interactive mode ensures reliable, reproducible builds.
+
+**Document Publishing** — Essential for Metanorma, Asciidoctor, and other document generation tools that require specific fonts for PDF rendering.
+
+**Development Environments** — Ensure consistent fonts across team machines without manual installation. One command sets up everything.
+
+## Why Fontist?
+
+Most font management approaches are either manual (download, unzip, install) or platform-specific (apt-get, brew). Fontist provides a unified, scriptable interface that works the same everywhere.
+
+| Feature | Fontist | Manual Install | apt-get/brew |
+|--------|---------|----------------|--------------|
+| Cross-platform | Same commands | Platform-specific | No |
+| Formula-based | 3000+ fonts | Manual download | Limited selection |
+| Manifest support | YAML-based | Not available | Not available |
+| CI/CD Ready | Non-interactive | Complex setup | Complex setup |
+| System Detection | Detects existing fonts | May miss fonts | May miss fonts |
+
+[Learn more about why Fontist might be right for your project →](/guide/why)

data/docs/lychee.toml

@@ -0,0 +1,33 @@
+# Lychee Link Checker Configuration
+# https://github.com/lycheeverse/lychee
+
+# Cache results to avoid re-checking same URLs
+cache = true
+max_cache_age = "1d"
+
+# Check verbatim URLs in code blocks
+include_verbatim = false
+
+# Exclude patterns for URLs (regex)
+exclude = [
+  ".git",
+  ".github",
+  "node_modules",
+  # Exclude GitHub issues (may require authentication)
+  'github\.com/fontist/fontist/issues',
+  # Exclude internal /fontist/ links - these are deployment base paths
+  # that work correctly when deployed but fail in local file:// checking
+  '^file://.*/fontist/',
+  # Exclude malformed escaped URLs (VitePress footer issue)
+  '%22https://',
+  # Exclude proxy placeholder examples
+  'proxyhost:port',
+  '\*\*\*proxy',
+  # Exclude trailing slash version of formulas guide (VitePress clean URL issue)
+  'fontist\.org/formulas/guide/create-formula/$',
+]
+
+# Exclude paths from checking
+exclude_path = [
+  "node_modules",
+]