jekyll_picture_tag 1.11.0 → 1.12.0

Sign up to get free protection for your applications and to get access to all the features.
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).