MkDocs Fontkit

Note: This project is maintained primarily for personal use. While bug reports and corrections are welcome, new feature requests may not be implemented as I have limited bandwidth for maintenance. Thank you for scanning this corner of the open source world!

MkDocs Fontkit is a high-performance, static analysis-based font builder designed for privacy-conscious and speed-optimized web projects. It enables you to self-host fonts from Adobe Fonts (Typekit) and Google Fonts without relying on client-side JS or external CDNs, and provides tools to optimize large custom font files (like partial CJK fonts) through splitting.

✨ Features

• 🛡️ Privacy & Performance: Eliminates third-party tracking and reduces layout shifts by serving all fonts locally.
• 🧠 Static Analysis for Typekit: Reverses Typekit's dynamic loading logic to generate stable WOFF2 URLs and CSS using Bloom filters and hash generation—no Headless Chrome (Puppeteer/Playwright) required.
• 📦 Google Fonts Downloader: Automatically fetches CSS and font binaries from Google Fonts, rewriting paths for local usage.
• ⚡ Smart CJK Font Splitting: Integrates cn-font-split to chunk large font files (e.g., Chinese/Japanese/Korean) into smaller pieces for faster initial load times.
• 🎨 Custom CSS Bundling: Automatically compiles and minifies a custom.css alongside your font definitions.
• 🚀 Production Ready: Outputs optimized fonts.min.css and fonts.css ready for immediate deployment.

🛠️ Installation

You can install this tool globally via npm or use it directly from the source.

via NPM

npm install -g @raineblog/mkdocs-fontkit

via Git (Recommended for development)

git clone https://github.com/raineblog/mkdocs-fontkit.git
cd mkdocs-fontkit
npm install

⚙️ Configuration

Create a fontkit.config.json file in the root of your project to define your font sources:

{
  "typekit": ["your-kit-id"],
  "google": [
    "Inter:[email protected]",
    "Fira+Code"
  ],
  "offline": [
    {
      "file": "source-han-serif.otf",
      "family": "Source Han Serif",
      "weight": "400",
      "style": "normal"
    }
  ]
}

Configuration Options

| Option | Type | Description | | :--- | :--- | :--- | | typekit | string[] | Array of Adobe Fonts (Typekit) Kit IDs. | | google | string[] | Array of Google Font families (supports standard API query format). | | offline | object[] | Array of local font configurations for splitting/processing. |

🚀 Usage

Run the build command to generate your font kit:

fontkit
# OR if running from source
npm run build

Output

The build process will generate a dist/ directory containing:

• fonts.css: Complete, uncompressed CSS definitions.
• fonts.min.css: Minified CSS for production use.
• custom.css / custom.min.css: Processed custom styles (if present).
• fonts/: Directory containing all downloaded and split font assets.

🤝 Contributing

This project is a personal utility that I've open-sourced in hopes it might be useful to others.

• Bug Reports: Very welcome! If something breaks, please open an issue.
• Pull Requests: Fixes for bugs or documentation errors are appreciated.
• Feature Requests: Generally, I am not looking to add new features unless they align strictly with my personal use cases. This helps me keep the project maintainable.

🤖 AI Generation Disclosure

This README and recent project updates were generated by Antigravity (Google DeepMind) in collaboration with the project owner. The content has been reviewed to ensure accuracy and compliance with the project's goals.