jekyll_picture_tag 1.11.0 → 1.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. checksums.yaml +4 -4
  2. data/docs/Gemfile +4 -2
  3. data/docs/Gemfile.lock +14 -12
  4. data/docs/_config.yml +6 -10
  5. data/docs/devs/contributing/code.md +44 -0
  6. data/docs/devs/contributing/docs.md +13 -0
  7. data/docs/devs/contributing/index.md +15 -0
  8. data/docs/devs/contributing/setup.md +13 -0
  9. data/docs/devs/contributing/testing.md +41 -0
  10. data/docs/devs/index.md +7 -0
  11. data/docs/{releases.md → devs/releases.md} +24 -14
  12. data/docs/index.md +43 -27
  13. data/docs/users/configuration/cdn.md +35 -0
  14. data/docs/users/configuration/directories.md +34 -0
  15. data/docs/users/configuration/disable.md +24 -0
  16. data/docs/users/configuration/fast_build.md +28 -0
  17. data/docs/users/configuration/ignore_missing.md +23 -0
  18. data/docs/users/configuration/index.md +29 -0
  19. data/docs/users/configuration/kramdown_fix.md +20 -0
  20. data/docs/users/configuration/relative_urls.md +15 -0
  21. data/docs/users/configuration/suppress_warnings.md +16 -0
  22. data/docs/users/index.md +7 -0
  23. data/docs/users/installation.md +52 -0
  24. data/docs/users/liquid_tag/argument_reference/alternate_images.md +18 -0
  25. data/docs/users/liquid_tag/argument_reference/attributes.md +42 -0
  26. data/docs/users/liquid_tag/argument_reference/base_image.md +12 -0
  27. data/docs/users/liquid_tag/argument_reference/crop.md +48 -0
  28. data/docs/users/liquid_tag/argument_reference/link.md +16 -0
  29. data/docs/users/liquid_tag/argument_reference/preset.md +17 -0
  30. data/docs/users/liquid_tag/argument_reference/readme.md +9 -0
  31. data/docs/users/liquid_tag/examples.md +81 -0
  32. data/docs/users/liquid_tag/index.md +31 -0
  33. data/docs/users/notes/git_lfs.md +7 -0
  34. data/docs/users/notes/github_pages.md +5 -0
  35. data/docs/users/notes/html_attributes.md +5 -0
  36. data/docs/users/notes/index.md +6 -0
  37. data/docs/users/notes/input_checking.md +6 -0
  38. data/docs/users/notes/kramdown_bug.md +41 -0
  39. data/docs/users/notes/managing_images.md +21 -0
  40. data/docs/{migration.md → users/notes/migration.md} +0 -0
  41. data/docs/users/presets/cropping.md +61 -0
  42. data/docs/users/presets/default.md +23 -0
  43. data/docs/users/presets/examples.md +79 -0
  44. data/docs/users/presets/fallback_image.md +28 -0
  45. data/docs/users/presets/html_attributes.md +26 -0
  46. data/docs/users/presets/image_formats.md +21 -0
  47. data/docs/users/presets/image_quality.md +43 -0
  48. data/docs/users/presets/index.md +101 -0
  49. data/docs/users/presets/link_source.md +16 -0
  50. data/docs/users/presets/markup_formats/fragments.md +48 -0
  51. data/docs/users/presets/markup_formats/javascript_friendly.md +57 -0
  52. data/docs/users/presets/markup_formats/readme.md +43 -0
  53. data/docs/users/presets/markup_formats/standard_html.md +25 -0
  54. data/docs/users/presets/media_queries.md +36 -0
  55. data/docs/users/presets/nomarkdown_override.md +17 -0
  56. data/docs/users/presets/pixel_ratio_srcsets.md +32 -0
  57. data/docs/users/presets/width_height_attributes.md +34 -0
  58. data/docs/users/presets/width_srcsets.md +85 -0
  59. data/lib/jekyll_picture_tag/instructions/preset.rb +5 -1
  60. data/lib/jekyll_picture_tag/instructions/set.rb +5 -1
  61. data/lib/jekyll_picture_tag/version.rb +1 -1
  62. metadata +55 -14
  63. data/docs/_layouts/directory.html +0 -32
  64. data/docs/assets/style.css +0 -31
  65. data/docs/contributing.md +0 -109
  66. data/docs/example_presets.md +0 -116
  67. data/docs/global_configuration.md +0 -173
  68. data/docs/installation.md +0 -45
  69. data/docs/notes.md +0 -91
  70. data/docs/output.md +0 -63
  71. data/docs/presets.md +0 -391
  72. data/docs/usage.md +0 -157
data/docs/usage.md DELETED
@@ -1,157 +0,0 @@
1
- ---
2
- ---
3
-
4
- # How to use the Liquid Tag:
5
-
6
- This section describes how to use JPT's liquid tag; what options it takes and what kind of information you can pass through it to influence the form of the final HTML-markup.
7
-
8
- ## Format:
9
-
10
- {% raw %}
11
- `{% picture [preset] (image) [crop] [alternate images & crops] [attributes] %}`
12
- {% endraw %}
13
-
14
- The only required argument is the base image. Line breaks and extra spaces are fine, and you can
15
- use liquid variables anywhere.
16
-
17
- The `preset` determines the actual HTML code that gets written to your files;
18
- it is basically a recipy that takes information that you provide in the
19
- liquid tag and turns it into HTML markup. When the `preset` is omitted
20
- default settings will be used, in the simplest case resulting in an `img`-tag
21
- containing an srcset pointing to your newly generated image sizes. You are
22
- free to override the `default` preset and define your own presets, giving
23
- full flexibility in what JPT will write to your files. See [markup preset]({{
24
- site.baseurl }}/presets#markup-presets) for more information on this.
25
-
26
- ## Examples:
27
-
28
- {% raw %}
29
- `{% picture example.jpg %}`
30
-
31
- `{% picture {{ page.example_liquid_picture_var }} %}`
32
-
33
- `{% picture thumbnail example.jpg 1:1 --alt Example Image %}`
34
-
35
- `{% picture example.jpg 16:9 north --picture class="attribute-demo" %}`
36
-
37
- `{% picture blog_index {{ post.image }} --link {{ post.url }} %}`
38
-
39
- `{% picture "some example.jpg" mobile: other\ example.jpg %}`
40
-
41
- ```md
42
- {% picture
43
- hero
44
- example.jpg 16:9 east
45
- tablet: example_cropped.jpg 3:2 east
46
- mobile: example_cropped_more.jpg 1:1-50+0 east
47
- --alt Happy Puppy
48
- --picture class="hero"
49
- --link /
50
- %}
51
- ```
52
-
53
- {% endraw %}
54
-
55
- ## Argument reference
56
-
57
- Given in order:
58
-
59
- - **Preset**
60
-
61
- Select a [markup preset]({{ site.baseurl }}/presets#markup-presets), or omit to use the `default` preset. Presets
62
- are collections of settings that determine nearly everything about JPT's output, from the image
63
- formats used to the exact format your final HTML-markup will take.
64
-
65
- - **Base Image** (Required)
66
-
67
- Can be any raster image (as long as you have the required ImageMagick delegate). Relative to
68
- jekyll's root directory, or the `source` [setting]({{ site.baseurl }}/global_configuration) if you've configured it.
69
-
70
- For filenames with spaces, either use double quotes (`"my image.jpg"`) or a backslash (`my\ image.jpg`).
71
-
72
- - **Crop**
73
-
74
- **Check the [ installation guide ](installation) before using this feature.**
75
-
76
- Crop an image to a given aspect ratio or size. This argument is given as a `geometry` and
77
- (optionally) a `gravity`, which can appear in either order and are thin wrappers around
78
- ImageMagick's [geometry](http://www.imagemagick.org/script/command-line-processing.php#geometry)
79
- and [gravity](http://www.imagemagick.org/script/command-line-options.php#gravity) settings. The
80
- values given here will override the preset settings (if present), can be given after every image,
81
- and apply only to the preceding image.
82
-
83
- Geometry can take many forms, but most likely you'll want to set an aspect ratio-- given in the
84
- standard `width:height` ratio such as `3:2`. Gravity sets which portion of the image to keep, and
85
- is given in compass directions (`north`, `southeast`, etc) or `center` (default). Cropping happens
86
- before resizing; the preset `widths` setting is a post-crop value.
87
-
88
- If you'd like more fine-grained control, this can be offset by appending `+|-x` and (optionally)
89
- `y` pixel values to the _geometry_ (not the gravity!). Example: `1:1+400 west` means "Crop to a
90
- 1:1 aspect ratio, starting 400 pixels from the left side.", and `north 3:2+0+100` means "Crop to
91
- 3:2, starting 100 pixels from the top." These can get a bit persnickety; there's nothing to stop
92
- you from running off the side of the image. Pay attention.
93
-
94
- For detailed documentation, see ImageMagick's
95
- [crop](http://www.imagemagick.org/script/command-line-options.php#crop) tool.
96
-
97
- _Note:_ If you do a lot of trial and error with these, it's a good idea to manually delete your
98
- generated images folder more often as each change will build a new set of images without removing
99
- the old ones.
100
-
101
- - **Alternate images**
102
-
103
- _Format:_ `(media query preset): (filename) (...)`
104
-
105
- _Example:_ `tablet: img_cropped.jpg mobile: img_cropped_more.jpg`
106
-
107
- Optionally specify any number of alternate base images for given [screen
108
- sizes]({{ site.baseurl }}/presets/#media-presets) (specified in `_data/picture.yml`). This is called [art
109
- direction](http://usecases.responsiveimages.org/#art-direction), and is one of JPT's strongest
110
- features.
111
-
112
- Give your images in order of ascending specificity (The first image is the most general). They will
113
- be provided to the browser in reverse order, and it will select the first one with an applicable
114
- media query.
115
-
116
- - **Attributes**
117
-
118
- Optionally specify any number of HTML attributes, or an href target. These will be added to any
119
- attributes you've set in a preset.
120
-
121
- - **`--link`**
122
-
123
- _Format:_ `--link (some url)`
124
-
125
- _Examples_: `--link https://example.com`, `--link /blog/some_post/`
126
-
127
- Wrap the image in an anchor tag, with the `href` attribute set to whatever value you give it.
128
- This will override automatic source image linking, if you have enabled it.
129
-
130
- **Note**: If you get either mangled HTML or extra {::nomarkdown} tags when using this, read
131
- [here]({{ site.baseurl }}/notes).
132
-
133
- - **`--alt`**
134
-
135
- _Format:_ `--alt (alt text)`
136
-
137
- _Example:_ `--alt Here is my alt text!`
138
-
139
- Convenience shortcut for `--img alt="..."`
140
-
141
- - **`--(element)`**
142
-
143
- _Format:_ `--(picture|img|source|a|parent) (Standard HTML attributes)`
144
-
145
- _Example:_ `--img class="awesome-fade-in" id="coolio" --a data-awesomeness="11"`
146
-
147
- Apply attributes to a given HTML element. Your options are:
148
-
149
- - `picture`
150
- - `img`
151
- - `source`
152
- - `a` (anchor tag)
153
- - `parent`
154
-
155
- `--parent` will be applied to the `<picture>` if present, otherwise the `<img>`; useful when
156
- using an `auto` output format.
157
- **Note:** Attributes that are set in the liquid picture tag, but don't occur in the used `preset` will be ignored (e.g. adding `--picture class="cool-css"` with a preset that does not write a html `<picture>` tag).