chore: implement self-hosted fonts for improved privacy and performance by VGalaxies · Pull Request #418 · apache/hugegraph-doc

VGalaxies · 2025-09-28T09:46:41Z

🚀 Description

This PR implements self-hosted fonts for the HugeGraph documentation website, replacing external CDN font loading with local font files. This change improves website privacy, performance, and reliability by eliminating external dependencies for font loading.

🔧 Changes Made

Font Implementation

Added 38 self-hosted font files supporting 4 font families:
- Open Sans (300, 400, 700 weights + italic variants) - Primary UI font
- Rubik (300, 400, 500, 600, 700 weights) - Hebrew language support
- Tajawal (300, 400, 500, 700 weights) - Arabic language support
- Vazir (300, 400, 500, 700 weights) - Persian/Farsi language support

Configuration Updates

Disabled external Google Fonts loading by setting $td-enable-google-fonts: false
Removed CDN font imports from RTL stylesheet for multilingual fonts
Added comprehensive @font-face declarations in assets/scss/_variables_project.scss
Implemented font-display: swap for optimal loading performance

Multilingual Support

Maintained full support for RTL languages (Arabic, Persian, Hebrew)
Preserved existing font fallback chains for compatibility
Ensured consistent typography across all supported languages

📈 Benefits

🔒 Privacy: No external requests to Google Fonts or other CDNs
⚡ Performance: Faster loading with local font files and font-display: swap
🛡️ Reliability: Eliminates dependency on external CDN availability
🌐 Offline Support: Fonts work without internet connectivity
📱 Consistency: Same fonts guaranteed across all users and environments

🧪 Testing

Website builds successfully with hugo server
All font weights and styles load correctly
Multilingual pages display proper fonts (Arabic, Persian, Hebrew)
No external font requests in browser network tab
Font fallbacks work as expected

📁 File Changes

Added: 38 font files in assets/fonts/ (WOFF and WOFF2 formats)
Modified: assets/scss/_variables_project.scss - Added @font-face declarations
Modified: themes/docsy/assets/scss/_variables.scss - Disabled Google Fonts
Modified: themes/docsy/assets/scss/rtl/_main.scss - Removed external font imports

🔗 Related Issues

Addresses website performance and privacy concerns by implementing self-hosted fonts as requested.

Total size: ~1.8MB of font files added
Formats supported: WOFF2 (modern browsers) + WOFF (fallback)
Languages supported: English, Arabic, Persian/Farsi, Hebrew

Copilot

Pull Request Overview

This PR implements self-hosted fonts to replace external Google Fonts CDN dependencies, improving privacy, performance, and reliability for the HugeGraph documentation website.

Disabled Google Fonts loading and removed external CDN font imports
Added comprehensive @font-face declarations for 4 font families with multiple weights
Maintained multilingual support for Arabic, Persian, and Hebrew languages

Reviewed Changes

Copilot reviewed 3 out of 41 changed files in this pull request and generated no comments.

File	Description
themes/docsy/assets/scss/_variables.scss	Disabled Google Fonts loading by setting flag to false
themes/docsy/assets/scss/rtl/_main.scss	Removed external font imports for RTL language support
assets/scss/_variables_project.scss	Added @font-face declarations for all self-hosted font families

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Copilot

Pull Request Overview

Copilot reviewed 3 out of 41 changed files in this pull request and generated no new comments.

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

imbajin · 2025-09-28T13:45:00Z

assets/scss/_variables_project.scss

+  font-style: normal;
+  font-weight: 300;
+  font-display: swap;
+  src: url('/assets/fonts/OpenSans-Light.woff2') format('woff2'),


Should Fix: Path consistency issue with font URLs

The font paths use absolute URLs (/assets/fonts/) which could break in subdirectory deployments or development environments. Consider using relative paths or Hugo's asset pipeline:

Suggested change

src: url('/assets/fonts/OpenSans-Light.woff2') format('woff2'),

src: url('../fonts/OpenSans-Light.woff2') format('woff2'),

url('../fonts/OpenSans-Light.woff') format('woff');

This applies to all 38 @font-face declarations. Using relative paths would ensure the fonts load correctly regardless of the deployment path.

imbajin · 2025-09-28T13:45:12Z

themes/docsy/assets/scss/_variables.scss

 $google_font_name: "Open Sans" !default;
 $google_font_family: "Open+Sans:300,300i,400,400i,700,700i" !default;
-$web-font-path: "https://fonts.googleapis.com/css?family=#{$google_font_family}&display=swap";
+// $web-font-path: "https://fonts.googleapis.com/css?family=#{$google_font_family}&display=swap"; // Disabled for self-hosted fonts


Should Fix: Commented code should be removed instead of disabled

Rather than commenting out the $web-font-path variable, it would be cleaner to remove it entirely since it's no longer needed with self-hosted fonts. Dead code comments can cause confusion for future maintainers.

imbajin · 2025-09-28T13:45:24Z

assets/scss/_variables_project.scss

+  font-display: swap;
+  src: url('/assets/fonts/OpenSans-BoldItalic.woff2') format('woff2'),
+       url('/assets/fonts/OpenSans-BoldItalic.woff') format('woff');
+}


Nice to Have: Consider font subsetting for performance optimization

For the multilingual fonts (Arabic, Persian, Hebrew), consider using Unicode range subsetting to reduce file sizes for users who don't need these character sets:

Suggested change

}

@font-face {

font-family: 'Rubik';

font-style: normal;

font-weight: 300;

font-display: swap;

unicode-range: U+0590-05FF, U+FB1D-FB4F; /* Hebrew range */

src: url('/assets/fonts/Rubik-Light.woff2') format('woff2'),

url('/assets/fonts/Rubik-Light.woff') format('woff');

}

This would improve loading performance for users who don't need these specific language characters.

imbajin · 2025-09-28T13:45:36Z

assets/scss/_variables_project.scss


 */

+// Self-hosted font declarations


Nice to Have: Add documentation for font configuration

Consider adding a comment block at the top of this file documenting:

Total font file sizes per family

Browser compatibility notes (WOFF2 vs WOFF fallback strategy)

Instructions for adding new font families

Font preloading strategy for critical fonts

This would help future maintainers understand the font hosting setup and make informed decisions about modifications.

imbajin · 2025-09-28T13:46:10Z

PR Review Summary

✅ Overall Assessment

The implementation for self-hosting fonts is technically sound and achieves the stated goals of improving privacy, performance, and reliability. The PR effectively removes external CDN dependencies.

📋 Review Findings

Critical Problems: None identified

Should Fix (2 items):

Font URL paths using absolute paths could break in subdirectory deployments
Commented code should be removed rather than disabled

Nice to Have (3 items):

Unicode range subsetting for multilingual fonts to optimize performance
Font preloading strategy for critical fonts
Documentation improvements for future maintainers

🧪 Additional Testing Recommendations

Test font loading in subdirectory deployments (e.g., /docs/ instead of root /)
Verify font rendering in browsers without WOFF2 support
Test offline mode to confirm fonts load without network access
Measure performance impact with Lighthouse before/after comparison

✅ Pre-merge Checklist

✓ No breaking changes to public APIs
✓ Reasonable PR size (~1.8MB font files is acceptable)
✓ Clear rollback path available
✓ Privacy improvement achieved
⚠️ Consider documenting this change in release notes

The privacy and performance benefits justify the added font files. Main concerns are around path handling for different deployment scenarios. Great work on implementing this improvement! 👍

assets/scss/_variables_project.scss

imbajin · 2025-09-28T14:03:28Z

themes/docsy/assets/scss/_variables.scss

 $google_font_name: "Open Sans" !default;
 $google_font_family: "Open+Sans:300,300i,400,400i,700,700i" !default;
-$web-font-path: "https://fonts.googleapis.com/css?family=#{$google_font_family}&display=swap";
+// $web-font-path: "https://fonts.googleapis.com/css?family=#{$google_font_family}&display=swap"; // Disabled for self-hosted fonts


Commented-out code should be removed rather than left as a comment. Consider cleaner removal:

Suggested change

// $web-font-path: "https://fonts.googleapis.com/css?family=#{$google_font_family}&display=swap"; // Disabled for self-hosted fonts

// Removed for self-hosted fonts - see assets/scss/_variables_project.scss

This improves maintainability by avoiding commented-out code.

imbajin · 2025-09-28T14:07:19Z

themes/docsy/assets/scss/_variables.scss

@@ -13,7 +13,7 @@ $enable-shadows: true !default;



Critical: Avoid editing files under themes/. Set $td-enable-google-fonts: false in project override (assets/scss/_variables_project.scss) to prevent breakage on theme upgrades. Revert this change here and keep theme files pristine.

imbajin · 2025-09-28T14:07:26Z

themes/docsy/assets/scss/_variables.scss

@@ -66,7 +66,7 @@ $link-hover-decoration: none !default;



Not necessary to comment out $web-font-path here if $td-enable-google-fonts: false is set via project override. Prefer keeping the theme file untouched and place overrides in assets/scss/_variables_project.scss.

…ce (#418) 9d4337d

…ce (apache#418)

setup

7e094fb

dosubot bot added size:XS This PR changes 0-9 lines, ignoring generated files. enhancement New feature or request labels Sep 28, 2025

imbajin requested a review from Copilot September 28, 2025 10:36

Copilot AI reviewed Sep 28, 2025

View reviewed changes

VGalaxies requested review from Copilot and imbajin September 28, 2025 12:59

Copilot AI reviewed Sep 28, 2025

View reviewed changes

imbajin reviewed Sep 28, 2025

View reviewed changes

imbajin approved these changes Sep 28, 2025

View reviewed changes

dosubot bot added the lgtm This PR has been approved by a maintainer label Sep 28, 2025

imbajin reviewed Sep 28, 2025

View reviewed changes

assets/scss/_variables_project.scss Show resolved Hide resolved

imbajin reviewed Sep 28, 2025

View reviewed changes

This comment was marked as off-topic.

Sign in to view

dosubot bot removed the lgtm This PR has been approved by a maintainer label Sep 28, 2025

imbajin reviewed Sep 28, 2025

View reviewed changes

imbajin approved these changes Sep 28, 2025

View reviewed changes

dosubot bot added the lgtm This PR has been approved by a maintainer label Sep 28, 2025

VGalaxies merged commit 9d4337d into master Sep 28, 2025
1 check passed

VGalaxies deleted the local-font branch September 28, 2025 15:00

github-actions bot pushed a commit that referenced this pull request Sep 28, 2025

chore: implement self-hosted fonts for improved privacy and performan…

41e9278

…ce (#418) 9d4337d

imbajin pushed a commit to hugegraph/hugegraph-doc that referenced this pull request Oct 8, 2025

chore: implement self-hosted fonts for improved privacy and performan…

15b49fc

…ce (apache#418)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore: implement self-hosted fonts for improved privacy and performance#418

chore: implement self-hosted fonts for improved privacy and performance#418
VGalaxies merged 1 commit intomasterfrom
local-font

VGalaxies commented Sep 28, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

imbajin Sep 28, 2025

Uh oh!

imbajin Sep 28, 2025

Uh oh!

imbajin Sep 28, 2025

Uh oh!

imbajin Sep 28, 2025

Uh oh!

imbajin commented Sep 28, 2025

Uh oh!

Uh oh!

imbajin Sep 28, 2025

Uh oh!

This comment was marked as off-topic.

Uh oh!

imbajin Sep 28, 2025

Uh oh!

imbajin Sep 28, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	src: url('/assets/fonts/OpenSans-Light.woff2') format('woff2'),
	src: url('../fonts/OpenSans-Light.woff2') format('woff2'),
	url('../fonts/OpenSans-Light.woff') format('woff');

-}
+@font-face {
+  font-family: 'Rubik';
+  font-style: normal;
+  font-weight: 300;
+  font-display: swap;
+  unicode-range: U+0590-05FF, U+FB1D-FB4F; /* Hebrew range */
+  src: url('/assets/fonts/Rubik-Light.woff2') format('woff2'),
+       url('/assets/fonts/Rubik-Light.woff') format('woff');
+}

	// $web-font-path: "https://fonts.googleapis.com/css?family=#{$google_font_family}&display=swap"; // Disabled for self-hosted fonts
	// Removed for self-hosted fonts - see assets/scss/_variables_project.scss

Conversation

VGalaxies commented Sep 28, 2025

🚀 Description

🔧 Changes Made

Font Implementation

Configuration Updates

Multilingual Support

📈 Benefits

🧪 Testing

📁 File Changes

🔗 Related Issues

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

imbajin Sep 28, 2025

Choose a reason for hiding this comment

Uh oh!

imbajin Sep 28, 2025

Choose a reason for hiding this comment

Uh oh!

imbajin Sep 28, 2025

Choose a reason for hiding this comment

Uh oh!

imbajin Sep 28, 2025

Choose a reason for hiding this comment

Uh oh!

imbajin commented Sep 28, 2025

PR Review Summary

✅ Overall Assessment

📋 Review Findings

🧪 Additional Testing Recommendations

✅ Pre-merge Checklist

Uh oh!

Uh oh!

imbajin Sep 28, 2025

Choose a reason for hiding this comment

Uh oh!

This comment was marked as off-topic.

Uh oh!

imbajin Sep 28, 2025

Choose a reason for hiding this comment

Uh oh!

imbajin Sep 28, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants