Skip to content

Commit df4deb3

Browse files
nberlettenberlette
authored
docs: add basic gh-pages docs for @nick/resvg package
Added documentation for the @nick/resvg package, including API details, options, fonts, and usage examples. Signed-off-by: Nicholas Berlette <nick@berlette.com>
1 parent 86de3bb commit df4deb3

1 file changed

Lines changed: 184 additions & 0 deletions

File tree

‎docs/index.md‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
<div align="center">
2+
3+
# `@nick/resvg`
4+
5+
TypeScript + WebAssembly bindings for [`resvg`].
6+
7+
</div>
8+
9+
---
10+
11+
## API
12+
13+
### `render`
14+
15+
Renders a string or `BufferSource` object containing an [SVG] into a [PNG]
16+
image, optionally with a custom set of options to control the rendering
17+
behavior.
18+
19+
Returns a `Uint8Array` containing the rasterized PNG image data.
20+
21+
#### Signature
22+
23+
```ts ignore
24+
render(svg: string | BufferSource, options?: Options): Uint8Array;
25+
```
26+
27+
#### Parameters
28+
29+
- `svg` - The SVG data to render, either as a string or `BufferSource` object.
30+
- `options` - An optional object with [`Options`](#options) for controlling the
31+
renderer.
32+
33+
#### Returns
34+
35+
The rasterized PNG image data as a `Uint8Array`.
36+
37+
---
38+
39+
### `Options`
40+
41+
The `Options` interface provides numerous options for customizing the rendering
42+
process. All the options from the `resvg` crate are available, as well as some
43+
additional options specific to this package.
44+
45+
| Option | Type | Description | Default |
46+
| ---------------- | -------------------- | ------------------------------------------------------------ | --------------------------- |
47+
| `autofix` | `boolean` | Automatically fix common SVG issues. | `true` |
48+
| `defaultSize` | [`Size`] | The default size of the SVG. | See [`Size`] below. |
49+
| `dpi` | `number` | The DPI (dots per inch) of the output. | `96` |
50+
| `fontSize` | `number` | The default font size to use if one isn't specified. | `12` |
51+
| `fontFamily` | `string` | The default font family to use. | `sans-serif` |
52+
| `fontFamilies` | [`FontFamilies`] | Maps generic font types to their specific font families. | See [`FontFamilies`] below. |
53+
| `fontFaces` | [`Array<FontFace>`] | An array of [`FontFace`] objects to preload in the renderer. | `[]` |
54+
| `languages` | `string[]` | An array of language tags to use for font selection. | `["en"]` |
55+
| `styles` | `string`, `string[]` | A string or array of CSS styles to apply to the SVG. | `[]` |
56+
| `shapeRendering` | [`ShapeRendering`] | The default `shape-rendering` value (when set to `auto`). | `"crispEdges"` |
57+
| `imageRendering` | [`ImageRendering`] | The default `image-rendering` value (when set to `auto`). | `"optimizeQuality"` |
58+
| `textRendering` | [`TextRendering`] | The default `text-rendering` value (when set to `auto`). | `"optimizeLegibility"` |
59+
60+
[`Size`]: #size "Size interface"
61+
[`FontFamilies`]: #fontfamilies "FontFamilies interface"
62+
[`Array<FontFace>`]: #fontface "FontFace interface"
63+
[`FontFace`]: #fontface "FontFace interface"
64+
[`ShapeRendering`]: #shaperendering "ShapeRendering enum"
65+
[`TextRendering`]: #textrendering "TextRendering enum"
66+
[`ImageRendering`]: #imagerendering "ImageRendering enum"
67+
68+
---
69+
70+
### Fonts
71+
72+
- `Bitter` is the default and the _serif_ font.
73+
- `Inter` is the _sans-serif_ font.
74+
- `JetBrains Mono` is the _monospace_ font.
75+
76+
---
77+
78+
### Examples
79+
80+
#### Basic Usage: Rendering SVG to PNG
81+
82+
```ts
83+
import { render } from "jsr:@nick/resvg@0.1.0-rc.1";
84+
85+
const data = render(`<?xml version="1.0" encoding="UTF-8"?>
86+
<svg width="820px" height="312px" viewBox="0 0 820 312" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
87+
<title>Testing</title>
88+
<g id="testing" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
89+
<rect fill="#FFFFFF" x="0" y="0" width="820" height="312"></rect>
90+
<text id="test-text" font-family="sans-serif" font-size="32" font-weight="bold" fill="#111827">
91+
<tspan x="51" y="90">Testing Testing Testing</tspan>
92+
</text>
93+
<text id="monospace" font-family="monospace" font-size="32" font-weight="normal" fill="#2D53A4">
94+
<tspan x="502" y="233">Monospace</tspan>
95+
</text>
96+
</g>
97+
</svg>`);
98+
99+
await Deno.writeFile("example.png", data);
100+
```
101+
102+
#### Advanced Usage: Custom Fonts
103+
104+
```ts
105+
import { type Options, render } from "jsr:@nick/resvg@0.1.0-rc.1";
106+
107+
const operatorMono = await fetch(
108+
"https://raw.githubusercontent.com/nberlette/resvg/main/fonts/OperatorMonoNerd/OperatorMonoNerd-Book.ttf"
109+
).then((r) => r.bytes());
110+
111+
const fontFaces = [
112+
{
113+
kind: "monospace",
114+
name: "Operator Mono",
115+
weight: 400,
116+
style: "normal",
117+
data: operatorMono,
118+
},
119+
];
120+
121+
const options = {
122+
fontFaces,
123+
fontFamily: "OperatorMono Nerd Font",
124+
styles: [
125+
`.monospace {
126+
font-family: "OperatorMono Nerd Font", monospace;
127+
font-size: 32px;
128+
font-weight: 400;
129+
fill: #2D53A4;
130+
}`,
131+
],
132+
} satisfies Options;
133+
134+
const svg = `<?xml version="1.0" encoding="UTF-8"?>
135+
<svg width="820px" height="312px" viewBox="0 0 820 312" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
136+
<title>Testing</title>
137+
<g id="testing" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
138+
<rect fill="#FFFFFF" x="0" y="0" width="820" height="312"></rect>
139+
<text id="test-text" font-family="sans-serif" font-size="32" font-weight="bold" fill="#111827">
140+
<tspan x="51" y="90">Testing Testing Testing</tspan>
141+
</text>
142+
<text class="monospace">
143+
<tspan x="502" y="233">Monospace</tspan>
144+
</text>
145+
</g>
146+
</svg>`;
147+
148+
const data = render(svg, options);
149+
150+
import { image } from "jsr:@cliffy/ansi@1.0.0-rc.8/ansi-escapes";
151+
152+
console.log(image(data, { preserveAspectRatio: 1 }));
153+
```
154+
155+
---
156+
157+
<div align="center">
158+
159+
**[MIT] © [Nicholas Berlette]. All rights reserved.**
160+
161+
<small>
162+
163+
[github] · [issues] · [jsr] · [docs] · [license]
164+
165+
</small></div>
166+
167+
[`resvg`]: https://github.com/RazrFalcon/resvg "Give RazrFalcon/resvg a star on GitHub!"
168+
[license]: https://nick.mit-license.org/2024 "MIT © Nicholas Berlette. All rights reserved."
169+
[MIT]: https://nick.mit-license.org/2024 "MIT © Nicholas Berlette. All rights reserved."
170+
[Nicholas Berlette]: https://github.com/nberlette "Follow @nberlette on GitHub for more projects!"
171+
[GitHub]: https://github.com/nberlette/resvg "Give nberlette/resvg a star on GitHub!"
172+
[Issues]: https://github.com/nberlette/resvg/issues "View issues for nberlette/resvg on GitHub"
173+
[JSR]: https://jsr.io/@nick/resvg "View @nick/resvg on JSR!"
174+
[Docs]: https://jsr.io/@nick/resvg/doc "View @nick/resvg documentation on JSR"
175+
[kitsonk]: https://github.com/kitsonk "Follow Kitson P. Kelly on GitHub!"
176+
[Deno]: https://deno.land "Deno is a secure runtime for JavaScript and TypeScript"
177+
[Bun]: https://bun.sh "Bun is a fast all-in-one JavaScript runtime"
178+
[Node.js]: https://nodejs.org "Node.js is a JavaScript runtime built on Chrome's V8 JavaScript engine"
179+
[WebAssembly]: https://webassembly.org "WebAssembly is a binary instruction format for a stack-based virtual machine"
180+
[SVGspec]: https://www.w3.org/TR/SVG11/ "Scalable Vector Graphics (SVG) 1.1 (Second Edition)"
181+
[PNGspec]: https://www.w3.org/TR/PNG/ "Portable Network Graphics (PNG) Specification (Second Edition)"
182+
[SVG2spec]: https://www.w3.org/TR/SVG2/ "Scalable Vector Graphics (SVG) 2"
183+
[SVG]: https://developer.mozilla.org/en-US/docs/Web/SVG "Scalable Vector Graphics (SVG) is an XML-based vector image format for two-dimensional graphics with support for interactivity and animation"
184+
[PNG]: https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Image_types#png "Portable Network Graphics (PNG) is a raster graphics file format that supports lossless data compression"

0 commit comments

Comments
 (0)