Skip to content

Commit 77ef73d

Browse files
mscoutermarshmscoutermarsh
committed
parameter doc for google fonts
1 parent 9e6cf9a commit 77ef73d

File tree

3 files changed

+162
-2
lines changed

3 files changed

+162
-2
lines changed

‎getting-started/using-the-api.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,7 @@ Optional parameters for greater control over your image.
5858

5959
| Name | Type | Description |
6060
|:-------------|:------------------|:------|
61-
| **google_fonts** | `String` | [Google fonts](/guides/using-google-fonts/) to be loaded. Example: `Roboto`. Multiple fonts can be loaded like this: `Roboto|Open Sans` |
61+
| **google_fonts** | `String` | [Google fonts](/parameters/google_fonts/) to be loaded. Example: `Roboto`. Multiple fonts can be loaded like this: `Roboto|Open Sans` |
6262
| **selector** | `String` | A [CSS selector](/guides/selector/) for an element on the webpage. We'll crop the image to this specific element. For example: `section#complete-toolkit.container-lg` |
6363
| **ms_delay** | `Integer` | The number of milliseconds the API should delay before generating the image. This is useful when waiting for JavaScript. We recommend starting with `500`. Large values slow down the initial render time. [Learn more](/parameters/ms_delay/). |
6464
| **device_scale** | `Double` | Controls the image resolution by adjusting the pixel ratio. Minimum: `1`, Maximum: `3`. Higher values increase image quality and file size. For example, `2` will double the resolution. [Learn more](/parameters/device_scale/). |

‎parameters/google_fonts.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
---
2+
layout: default
3+
title: Google Fonts
4+
permalink: /parameters/google_fonts/
5+
parent: Parameters
6+
nav_order: 2
7+
---
8+
9+
# Google Fonts Parameter
10+
{: .no_toc }
11+
{: .fs-9 }
12+
13+
Load and use any Google Font in your generated images.
14+
{: .fs-6 .fw-300 }
15+
16+
<hr>
17+
18+
## Parameter Details
19+
20+
| Name | Type | Required | Description |
21+
|:-----|:-----|:---------|:------------|
22+
| **google_fonts** | `String` | No | The names of Google Fonts to load, separated by `\|` for multiple fonts |
23+
24+
## Usage Examples
25+
26+
### Single Font
27+
28+
```json
29+
{
30+
"google_fonts": "Roboto",
31+
"html": "<div class='text'>Hello World</div>",
32+
"css": ".text { font-family: 'Roboto', sans-serif; }"
33+
}
34+
```
35+
36+
### Multiple Fonts
37+
38+
```json
39+
{
40+
"google_fonts": "Open Sans|Roboto|Montserrat",
41+
"html": "<div class='heading'>Title</div><div class='body'>Content</div>",
42+
"css": `
43+
.heading { font-family: 'Montserrat', sans-serif; }
44+
.body { font-family: 'Open Sans', sans-serif; }
45+
`
46+
}
47+
```
48+
49+
{% include hint.md title="Performance tip" text="Each additional font increases render time. Only load fonts you plan to use." %}
50+
51+
## Font Weights and Styles
52+
53+
### Specifying Font Weights
54+
55+
Google Fonts supports multiple weights for each font. You can specify which weights to load by including them in the `google_fonts` parameter.
56+
57+
**Explicit loading**: Specify the weight in the google_fonts parameter:
58+
59+
```json
60+
{
61+
"google_fonts": "Roboto:300,400,700", // Load light, regular, and bold weights
62+
"html": "<div class='text'>Hello World</div>",
63+
"css": ".text { font-family: 'Roboto', sans-serif; font-weight: 700; }"
64+
}
65+
```
66+
67+
Common font weights:
68+
- 300: Light
69+
- 400: Regular (default)
70+
- 500: Medium
71+
- 700: Bold
72+
- 900: Black
73+
74+
### Debugging Font Weights
75+
76+
If your font weights aren't appearing correctly, try these steps:
77+
78+
1. **Verify available weights**: Check [Google Fonts](https://fonts.google.com) to ensure the weight exists for your font
79+
```json
80+
{
81+
"google_fonts": "Roboto:300,400,700", // Only include weights that exist
82+
"html": "<div class='debug'>Weight Test</div>",
83+
"css": ".debug { font-family: 'Roboto'; font-weight: 700; }"
84+
}
85+
```
86+
87+
2. **Force weight loading**: Explicitly specify weights in the google_fonts parameter
88+
```json
89+
{
90+
"google_fonts": "Roboto:700", // Force load bold weight
91+
"html": "<div class='bold'>Bold Text</div>",
92+
"css": ".bold { font-family: 'Roboto'; font-weight: 700; }"
93+
}
94+
```
95+
96+
3. **Check for FOUT**: Add ms_delay if fonts aren't loading in time
97+
```json
98+
{
99+
"google_fonts": "Roboto:700",
100+
"ms_delay": 500, // Give extra time for font loading
101+
"html": "<div class='bold'>Bold Text</div>",
102+
"css": ".bold { font-family: 'Roboto'; font-weight: 700; }"
103+
}
104+
```
105+
106+
{% include hint.md title="Font weight tip" text="Not all fonts support all weights. Check Google Fonts for available weights before using them." %}
107+
108+
## Troubleshooting
109+
110+
### Flash of Unstyled Text (FOUT)
111+
112+
If fonts aren't rendering correctly, use the `ms_delay` parameter to allow time for font loading:
113+
114+
```json
115+
{
116+
"google_fonts": "Roboto",
117+
"ms_delay": 500,
118+
"html": "<div class='text'>Hello World</div>",
119+
"css": ".text { font-family: 'Roboto', sans-serif; }"
120+
}
121+
```
122+
123+
Start with `ms_delay: 500` and increase if needed.
124+
125+
### Common Issues
126+
127+
1. **Font not appearing**: Verify the font name matches exactly as shown on Google Fonts
128+
2. **Wrong font weight**: Ensure you're using a weight that exists for the chosen font
129+
3. **Incorrect quotes**: Use single quotes in CSS: `font-family: 'Roboto', sans-serif;`
130+
131+
## Live Example
132+
133+
This example loads both Montserrat and Roboto fonts:
134+
135+
<div class="code-example" markdown="1">
136+
<div class="hcti-container">
137+
{% cloudinary /assets/images/8e8c1093-d205-4994-845c-67419598d081.jpeg sizes="400px" alt="Convert html to an image using custom fonts" %}
138+
</div>
139+
</div>
140+
141+
```json
142+
{
143+
"google_fonts": "Montserrat|Roboto",
144+
"html": "<div class='text'>Hello World!</div>",
145+
"css": ".text { font-family: 'Montserrat'; }"
146+
}
147+
```
148+
149+
## Alternative Approaches
150+
151+
If you need to use fonts not available on Google Fonts:
152+
1. Use a different web font service by including their CSS in your HTML
153+
2. Convert your font to base64 and include it directly in your CSS
154+
3. Host the font files yourself and reference them via URL
155+
156+
[Try it yourself](https://htmlcsstoimage.com/demo){: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 .mr-2 }
157+
158+
{% include code_footer.md version=1 %}

‎workers-site/index.js‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,8 +46,10 @@ async function redirectOrHandleEvent(event) {
4646
return Response.redirect(site + '/guides/duplicate-image-detection/', 301);
4747
case "/getting-started/faq":
4848
return Response.redirect(site + '/faq', 301);
49+
case "/guides/using-google-fonts":
50+
return Response.redirect(site + '/parameters/google_fonts/', 301);
4951
case "/advanced-examples/using-google-fonts":
50-
return Response.redirect(site + '/guides/using-google-fonts', 301);
52+
return Response.redirect(site + '/parameters/google_fonts/', 301);
5153
case "/advanced-examples/rendering-emoji":
5254
return Response.redirect(site + '/guides/rendering-emoji', 301);
5355
case "/advanced-examples/image-charts-with-highcharts":

0 commit comments

Comments
 (0)