Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
VGalaxies merged 1 commit into from
Sep 28, 2025
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added assets/fonts/OpenSans-Bold.woff
View file
Open in desktop
Binary file not shown.
Binary file added assets/fonts/OpenSans-Bold.woff2
View file
Open in desktop
Binary file not shown.
Binary file added assets/fonts/OpenSans-BoldItalic.woff
View file
Open in desktop
Binary file not shown.
Binary file added assets/fonts/OpenSans-BoldItalic.woff2
View file
Open in desktop
Binary file not shown.
Binary file added assets/fonts/OpenSans-Italic.woff
View file
Open in desktop
Binary file not shown.
Binary file added assets/fonts/OpenSans-Italic.woff2
View file
Open in desktop
Binary file not shown.
Binary file added assets/fonts/OpenSans-Light.woff
View file
Open in desktop
Binary file not shown.
Binary file added assets/fonts/OpenSans-Light.woff2
View file
Open in desktop
Binary file not shown.
Binary file added assets/fonts/OpenSans-LightItalic.woff
View file
Open in desktop
Binary file not shown.
Binary file added assets/fonts/OpenSans-LightItalic.woff2
View file
Open in desktop
Binary file not shown.
Binary file added assets/fonts/OpenSans-Regular.woff
View file
Open in desktop
Binary file not shown.
Binary file added assets/fonts/OpenSans-Regular.woff2
View file
Open in desktop
Binary file not shown.
Binary file added assets/fonts/Rubik-Bold.woff
View file
Open in desktop
Binary file not shown.
Binary file added assets/fonts/Rubik-Bold.woff2
View file
Open in desktop
Binary file not shown.
Binary file added assets/fonts/Rubik-Light.woff
View file
Open in desktop
Binary file not shown.
Binary file added assets/fonts/Rubik-Light.woff2
View file
Open in desktop
Binary file not shown.
Binary file added assets/fonts/Rubik-Medium.woff
View file
Open in desktop
Binary file not shown.
Binary file added assets/fonts/Rubik-Medium.woff2
View file
Open in desktop
Binary file not shown.
Binary file added assets/fonts/Rubik-Regular.woff
View file
Open in desktop
Binary file not shown.
Binary file added assets/fonts/Rubik-Regular.woff2
View file
Open in desktop
Binary file not shown.
Binary file added assets/fonts/Rubik-SemiBold.woff
View file
Open in desktop
Binary file not shown.
Binary file added assets/fonts/Rubik-SemiBold.woff2
View file
Open in desktop
Binary file not shown.
Binary file added assets/fonts/Tajawal-Bold.woff
View file
Open in desktop
Binary file not shown.
Binary file added assets/fonts/Tajawal-Bold.woff2
View file
Open in desktop
Binary file not shown.
Binary file added assets/fonts/Tajawal-Light.woff
View file
Open in desktop
Binary file not shown.
Binary file added assets/fonts/Tajawal-Light.woff2
View file
Open in desktop
Binary file not shown.
Binary file added assets/fonts/Tajawal-Medium.woff
View file
Open in desktop
Binary file not shown.
Binary file added assets/fonts/Tajawal-Medium.woff2
View file
Open in desktop
Binary file not shown.
Binary file added assets/fonts/Tajawal-Regular.woff
View file
Open in desktop
Binary file not shown.
Binary file added assets/fonts/Tajawal-Regular.woff2
View file
Open in desktop
Binary file not shown.
Binary file added assets/fonts/Vazir-Bold.woff
View file
Open in desktop
Binary file not shown.
Binary file added assets/fonts/Vazir-Bold.woff2
View file
Open in desktop
Binary file not shown.
Binary file added assets/fonts/Vazir-Light.woff
View file
Open in desktop
Binary file not shown.
Binary file added assets/fonts/Vazir-Light.woff2
View file
Open in desktop
Binary file not shown.
Binary file added assets/fonts/Vazir-Medium.woff
View file
Open in desktop
Binary file not shown.
Binary file added assets/fonts/Vazir-Medium.woff2
View file
Open in desktop
Binary file not shown.
Binary file added assets/fonts/Vazir-Regular.woff
View file
Open in desktop
Binary file not shown.
Binary file added assets/fonts/Vazir-Regular.woff2
View file
Open in desktop
Binary file not shown.
176 changes: 176 additions & 0 deletions assets/scss/_variables_project.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,3 +4,179 @@ Add styles or override variables from the theme here.

*/

// Self-hosted font declarations
Copy link
Copy Markdown
Member

@imbajin imbajin Sep 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

// Open Sans font family
@font-face {
font-family: 'Open Sans';
font-style: normal;
font-weight: 300;
font-display: swap;
src: url('/assets/fonts/OpenSans-Light.woff2') format('woff2'),
Copy link
Copy Markdown
Member

@imbajin imbajin Sep 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

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

@font-face {
font-family: 'Open Sans';
font-style: italic;
font-weight: 300;
font-display: swap;
src: url('/assets/fonts/OpenSans-LightItalic.woff2') format('woff2'),
url('/assets/fonts/OpenSans-LightItalic.woff') format('woff');
}

@font-face {
font-family: 'Open Sans';
font-style: normal;
font-weight: 400;
font-display: swap;
src: url('/assets/fonts/OpenSans-Regular.woff2') format('woff2'),
url('/assets/fonts/OpenSans-Regular.woff') format('woff');
}

@font-face {
font-family: 'Open Sans';
font-style: italic;
font-weight: 400;
font-display: swap;
src: url('/assets/fonts/OpenSans-Italic.woff2') format('woff2'),
url('/assets/fonts/OpenSans-Italic.woff') format('woff');
}

@font-face {
font-family: 'Open Sans';
font-style: normal;
font-weight: 700;
font-display: swap;
src: url('/assets/fonts/OpenSans-Bold.woff2') format('woff2'),
url('/assets/fonts/OpenSans-Bold.woff') format('woff');
}

@font-face {
font-family: 'Open Sans';
font-style: italic;
font-weight: 700;
font-display: swap;
src: url('/assets/fonts/OpenSans-BoldItalic.woff2') format('woff2'),
url('/assets/fonts/OpenSans-BoldItalic.woff') format('woff');
}
Copy link
Copy Markdown
Member

@imbajin imbajin Sep 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


// Rubik font family (Hebrew)
@font-face {
font-family: 'Rubik';
font-style: normal;
font-weight: 300;
font-display: swap;
src: url('/assets/fonts/Rubik-Light.woff2') format('woff2'),
url('/assets/fonts/Rubik-Light.woff') format('woff');
}

@font-face {
font-family: 'Rubik';
font-style: normal;
font-weight: 400;
font-display: swap;
src: url('/assets/fonts/Rubik-Regular.woff2') format('woff2'),
url('/assets/fonts/Rubik-Regular.woff') format('woff');
}

@font-face {
font-family: 'Rubik';
font-style: normal;
font-weight: 500;
font-display: swap;
src: url('/assets/fonts/Rubik-Medium.woff2') format('woff2'),
url('/assets/fonts/Rubik-Medium.woff') format('woff');
}

@font-face {
font-family: 'Rubik';
font-style: normal;
font-weight: 600;
font-display: swap;
src: url('/assets/fonts/Rubik-SemiBold.woff2') format('woff2'),
url('/assets/fonts/Rubik-SemiBold.woff') format('woff');
}

@font-face {
font-family: 'Rubik';
font-style: normal;
font-weight: 700;
font-display: swap;
src: url('/assets/fonts/Rubik-Bold.woff2') format('woff2'),
url('/assets/fonts/Rubik-Bold.woff') format('woff');
}

// Tajawal font family (Arabic)
@font-face {
font-family: 'Tajawal';
font-style: normal;
font-weight: 300;
font-display: swap;
src: url('/assets/fonts/Tajawal-Light.woff2') format('woff2'),
url('/assets/fonts/Tajawal-Light.woff') format('woff');
}

@font-face {
font-family: 'Tajawal';
font-style: normal;
font-weight: 400;
font-display: swap;
src: url('/assets/fonts/Tajawal-Regular.woff2') format('woff2'),
url('/assets/fonts/Tajawal-Regular.woff') format('woff');
}

@font-face {
font-family: 'Tajawal';
font-style: normal;
font-weight: 500;
font-display: swap;
src: url('/assets/fonts/Tajawal-Medium.woff2') format('woff2'),
url('/assets/fonts/Tajawal-Medium.woff') format('woff');
}

@font-face {
font-family: 'Tajawal';
font-style: normal;
font-weight: 700;
font-display: swap;
src: url('/assets/fonts/Tajawal-Bold.woff2') format('woff2'),
url('/assets/fonts/Tajawal-Bold.woff') format('woff');
}

// Vazir font family (Persian/Farsi)
@font-face {
font-family: 'Vazir';
font-style: normal;
font-weight: 300;
font-display: swap;
src: url('/assets/fonts/Vazir-Light.woff2') format('woff2'),
url('/assets/fonts/Vazir-Light.woff') format('woff');
}

@font-face {
font-family: 'Vazir';
font-style: normal;
font-weight: 400;
font-display: swap;
src: url('/assets/fonts/Vazir-Regular.woff2') format('woff2'),
url('/assets/fonts/Vazir-Regular.woff') format('woff');
}

@font-face {
font-family: 'Vazir';
font-style: normal;
font-weight: 500;
font-display: swap;
src: url('/assets/fonts/Vazir-Medium.woff2') format('woff2'),
url('/assets/fonts/Vazir-Medium.woff') format('woff');
}

@font-face {
font-family: 'Vazir';
font-style: normal;
font-weight: 700;
font-display: swap;
src: url('/assets/fonts/Vazir-Bold.woff2') format('woff2'),
url('/assets/fonts/Vazir-Bold.woff') format('woff');
}

4 changes: 2 additions & 2 deletions themes/docsy/assets/scss/_variables.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ $enable-shadows: true !default;

Copy link
Copy Markdown
Member

@imbajin imbajin Sep 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

// Theme flags.

$td-enable-google-fonts: true !default;
$td-enable-google-fonts: false !default;

// Theme colors

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

Copy link
Copy Markdown
Member

@imbajin imbajin Sep 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

$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
Copy link
Copy Markdown
Member

@imbajin imbajin Sep 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Member

@imbajin imbajin Sep 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


$td-fonts-serif: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";

Expand Down
8 changes: 4 additions & 4 deletions themes/docsy/assets/scss/rtl/_main.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,16 +31,16 @@ body:lang(ur) {
}

body:lang(fa) {
@import url('https://cdn.jsdelivr.net/gh/rastikerdar/vazir-font@v27.0.1/dist/font-face.css');
// External font import removed for self-hosted fonts
font-family: 'Vazir', "Open Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
}

body:lang(he) {
@import url('https://fonts.googleapis.com/css2?family=Rubik:wght@300;400;500;600;700&display=swap');
// External font import removed for self-hosted fonts
font-family: 'Rubik', "Open Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
}

body:lang(ar) {
@import url('https://fonts.googleapis.com/css2?family=Tajawal:wght@300;400;500;700&display=swap');
// External font import removed for self-hosted fonts
font-family: 'Tajawal', "Open Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
}
}