Skip to content

Commit ba6e077

Browse files
brendtbrendt
authored
docs: add markdown and responsive-image packages (#2140)
1 parent 2b5e44b commit ba6e077

2 files changed

Lines changed: 208 additions & 0 deletions

File tree

‎docs/3-packages/03-responsive-image.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
---
2+
title: Responsive images
3+
description: "A standalone package to render responsive images"
4+
---
5+
6+
7+
## Quickstart
8+
9+
```
10+
composer require tempest/responsive-image
11+
```
12+
13+
```php
14+
use Tempest\ResponsiveImage\ResponsiveImageFactory;
15+
use Tempest\ResponsiveImage\ResponsiveImageConfig;
16+
17+
$config = new ResponsiveImageConfig(
18+
srcPath: __DIR__ . '/path/to/image/sources',
19+
publicPath: __DIR__ . '/../public',
20+
);
21+
22+
$imageFactory = new ResponsiveImageFactory($config);
23+
24+
$image = $imageFactory->create('/parrot.jpg');
25+
26+
echo $image->html;
27+
```
28+
29+
```html
30+
<img src="/parrot.jpg" srcset="/parrot-1920-1280.jpg 1920w, /parrot-1606-1070.jpg 1606w, /parrot-1214-809.jpg 1214w, /parrot-607-404.jpg 607w">
31+
```
32+
33+
## In depth
34+
35+
The goal of this package is to render [responsive images for better web performance](https://developer.mozilla.org/en-US/docs/Web/HTML/Guides/Responsive_images). You provide it with a single image source, and this package will generate several responsive downscaled versions of that image. It will then move all images to the correct place and render the image HTML for you. Optionally, you can use [tempest/command-bus](/docs/features/command-bus) to generate responsive images in the background.
36+
37+
### Basic setup
38+
39+
Responsive images are generated with the `Tempest\ResponsiveImage\ResponsiveImageFactory` class. It takes one argument: a `Tempest\ResponsiveImage\ResponsiveImageConfig` object. This object looks like this:
40+
41+
```php
42+
use Tempest\ResponsiveImage\ResponsiveImageConfig;
43+
use Intervention\Image\Drivers\Gd\Driver;
44+
use Intervention\Image\ImageManager;
45+
46+
$config = new ResponsiveImageConfig(
47+
srcPath: __DIR__ . '/../resources/src/',
48+
publicPath: __DIR__ . '/../public/',
49+
async: true,
50+
cache: true,
51+
imageManager: new ImageManager(new Driver()),
52+
);
53+
```
54+
| Parameter | Description |
55+
|--------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
56+
| `{:hl-property:srcPath:}` | The path to the directory where all source images are stored. |
57+
| `{:hl-property:publicPath:}` | The path to the public directory where rendered images should be served from. |
58+
| `{:hl-property:async:}` | Whether responsive images should be generated in the background. This paramater is only taken into account if Tempest's command bus is installed. |
59+
| `{:hl-property:cache:}` | Whether generated responsive variants should be cached. If true, then responsive variants won't be generated as long as the main image file exists in the public path. Cache clearing should be done manually on your end. |
60+
| `{:hl-property:imageManager:}` | The Intervention imagemanager. Refer to the [Intervention docs](https://image.intervention.io/v4) for all options. |
61+
62+
### Image rendering
63+
64+
With a `ResponsiveImageFactory` in place, you can now render images. The only thing you need to do is pass it the image source (like it would be used in the HTML tag), and the factory will handle the rest. The final result will be an `Image` object that can be rendered to HTML.
65+
66+
```php
67+
$imageFactory = new ResponsiveImageFactory($config);
68+
69+
$image = $imageFactory->create('/parrot.jpg');
70+
// This image `/parrot.jpg` is assumed to be present in the defined `srcPath`.
71+
// It will be copied, together with its responsive variants to `publicPath`
72+
73+
echo $image->html;
74+
75+
// <img src="/parrot.jpg" srcset="/parrot-1920-1280.jpg 1920w, /parrot-1606-1070.jpg 1606w, /parrot-1214-809.jpg 1214w, /parrot-607-404.jpg 607w">
76+
```
77+
78+
### Image rendering options
79+
80+
The factory will fill in and generate the image's `{:hl-property:srcset:}` for you based on image file sizes. However, you can also pass additional attributes to be added to the image's HTML:
81+
82+
```php
83+
$image = $factory->create(
84+
src: '/parrot.jpg',
85+
alt: 'A parrot',
86+
sizes: [new Size(maxWidth: 1000, width: 300), new Size(maxWidth: 1500, width: 500)],
87+
lazy: true,
88+
);
89+
```
90+
91+
```html
92+
<img
93+
src="/parrot.jpg"
94+
alt="A parrot"
95+
srcset="/parrot-1920-1280.jpg 1920w, /parrot-1606-1070.jpg 1606w, /parrot-1214-809.jpg 1214w, /parrot-607-404.jpg 607w"
96+
sizes="(max-width: 1000px) 300px, (max-width: 1500px) 500px"
97+
loading="lazy"
98+
>
99+
```
100+
101+
## Integrations
102+
103+
### Async image processing
104+
105+
You can combine this package with [tempest/command-bus](/docs/features/command-bus) to enable async image processing. This will make it so that the responsive variations of an image are rendered in the background. The main image will still be copied immediately, so you won't have to wait until processing is done.
106+
107+
Read about how to install Tempest's command bus as a standalone component [here](/docs/extra-topics/standalone-components#tempest-command-bus).
108+
109+
### Markdown parsing
110+
111+
This package is used by [`tempest/markdown`](/docs/packages/markdown) to render responsive images from markdown files.

‎docs/3-packages/04-markdown.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
---
2+
title: Markdown
3+
description: "Fast and extensible Markdown in PHP"
4+
---
5+
6+
`tempest/markdown` is a Markdown parser written in PHP. It's designed to be fast and extensible and has a bunch of additional features built-in like code highlighting, responsive images, tables, and frontmatter support.
7+
8+
## Quickstart
9+
10+
```sh
11+
composer require tempest/markdown
12+
```
13+
14+
Render Markdown like this:
15+
16+
```php
17+
use Tempest\Markdown\Markdown;
18+
19+
$markdown = new Markdown();
20+
21+
$parsed = $markdown->parse(file_get_contents('README.md'));
22+
23+
echo $parsed->frontMatter['title'];
24+
echo $parsed->html;
25+
```
26+
27+
## Integrations
28+
29+
### Code highlighting
30+
31+
`tempest/markdown` comes with code highlighting out of the box powered by [`tempest/highlight`](/docs/packages/highlight). You can configure the highlighter by passing a new instance into the markdown parser:
32+
33+
```php
34+
use Tempest\Markdown\Markdown;
35+
use Tempest\Highlight\Highlighter;
36+
37+
$markdown = new Markdown(
38+
highlighter: new Highlighter(
39+
// Configure theme, etc
40+
),
41+
);
42+
```
43+
44+
Language definitions work in both inline and pre code blocks:
45+
46+
<pre>
47+
This is an inline PHP codeblock: `{php}echo "Hello";`
48+
</pre>
49+
50+
<pre>
51+
This is a pre PHP codeblock:
52+
53+
&#96;&#96;&#96;php
54+
echo "world";
55+
&#96;&#96;&#96;
56+
</pre>
57+
58+
You can disable all code highlighting by passing in `{php}null`:
59+
60+
```php
61+
$markdown = new Markdown(
62+
highlighter: null,
63+
);
64+
```
65+
66+
### Responsive images
67+
68+
`tempest/markdown` has support for responsive images powered by [`tempest/responsive-image`](/docs/packages/responsive-image). You'll need to configure the responsive image factory before being able to use it.
69+
70+
```php
71+
use Tempest\Markdown\Markdown;
72+
use Tempest\ResponsiveImage\ResponsiveImageConfig;
73+
use Tempest\ResponsiveImage\ResponsiveImageFactory;
74+
75+
$imageConfig = new ResponsiveImageConfig(
76+
srcPath: __DIR__ . '/../resources/images',
77+
publicPath: __DIR__ . '/../public',
78+
);
79+
80+
$markdown = new Markdown(
81+
imageFactory: new ResponsiveImageFactory($imageConfig),
82+
);
83+
```
84+
85+
## Performance
86+
87+
This package began as a challenge to make a more performant Markdown parser in pure PHP. The primary performance gain is from not relying on regex but instead using a simple lexer to tokenize Markdown files and convert them to HTML.
88+
89+
Benchmarks are included in this repo and can be run with `composer bench` after installing all dev dependencies. Here are the results on a local machine rendering the full Tempest docs:
90+
91+
| Package | Memory | Time to parse |
92+
|------------------------|----------|---------------|
93+
| tempest/markdown | 5.944mb | 6.281ms |
94+
| league/commonmark | 21.114mb | 56.993ms |
95+
| michelf/php-markdown | 7.343mb | 23.215ms |
96+
| erusev/parsedown-extra | 8.485mb | 15.163ms |
97+

0 commit comments

Comments
 (0)