Includes Picture

Builds picture element from FrontMatter and includes

⬆️ Top of Document
🏗️ Requirements
⚡ Quick Start
- 📝 Edit Your ReadMe File
- 💾 Commit and Push
🧰 Usage
🔣 API
- url
  - base
  - filter
- img
  - src
  - alt
  - height
  - width
  - loading
  - decoding
- sources
  - srcset
  - media
🗒 Notes
- Converting .png images to .jpeg and .avif
- Converting .png images to .webp
📈 Contributing
- 🔱 Forking
- 💱 Sponsor
📇 Attribution
⚖️ Licensing

Requirements

This repository depends upon Jekyll which is supported by GitHub Pages, further details about setup can be found from documentation published by the Jekyll maintainers regarding GitHub Pages.

Quick Start

This repository encourages the use of Git Submodules to track dependencies

Bash Variables

_module_name='includes-picture'
_module_https_url="https://github.com/liquid-utilities/includes-picture.git"
_module_base_dir='_includes/modules'
_module_path="${_module_base_dir}/${_module_name}"

Bash Submodule Commands

cd "<your-git-project-path>"


git checkout gh-pages

mkdir -vp "${_module_base_dir}"


git submodule add -b main\
                  --name "${_module_name}"\
                  "${_module_https_url}"\
                  "${_module_path}"

Your ReadMe File

Suggested additions for your ReadMe.md file so everyone has a good time with submodules

Clone with the following to avoid incomplete downloads


    git clone --recurse-submodules <url-for-your-project>


Update/upgrade submodules via


    git submodule update --init --merge --recursive

Commit and Push

git add .gitmodules
git add "${_module_path}"


## Add any changed files too


git commit -F- <<'EOF'
:heavy_plus_sign: Adds `liquid-utilities/includes-picture#1` submodule



**Additions**


- `.gitmodules`, tracks submodules AKA Git within Git _fanciness_

- `README.md`, updates installation and updating guidance

- `_includes/modules/includes-picture`, Builds `picture` element from FrontMatter and includes
EOF


git push origin gh-pages

🎉 Excellent 🎉 your project is now ready to begin unitizing code from this repository!

Usage

2021-03-24-example-picture-includes.md (FrontMatter Snip)

pictures:
  funny_cat:
    url:
      base: assets/images/funny_cat/
      filter: absolute_url

    img:
      alt: Picture of a funny cat playing with yarn ball
      src: playful-yarn.jpeg
      width: 300
      height: 200
      loading: lazy
      decoding: async

    sources:
      - srcset: playful-yarn.png

      - srcset:
        - playful-yarn-480.webp
        - playful-yarn-480-2x.webp 2x
        media: '(min-width: 600px)'

2021-03-24-example-picture-includes.md (Content Snip)

{% include modules/includes-picture/picture.html name='funny_cat' %}

Note, the name parameter corresponds to the FrontMatter key under picture hash-map.

2021/03/24/example-picture-includes.html (HTML Snip)

<picture>
  <source type="image/png"
          srcset="/includes-picture/assets/images/funny_cat/playful-yarn.png"
  />

  <source type="image/webp"
          srcset="/includes-picture/assets/images/funny_cat/playful-yarn-480.webp,
                  /includes-picture/assets/images/funny_cat/playful-yarn-480-2x.webp 2x"
          media="(min-width: 600px)"
  />

  <img src="/includes-picture/assets/images/funny_cat/playful-yarn.jpeg"
       height="300"
       width="200"
       alt="Picture of a funny cat playing with yarn ball"
       loading="lazy"
       decoding="async"
  />
</picture>

Note, type is automatically parsed from first listed srcset path from each of listed sources

And height/width generally should only be defined if all picture variants are of the same dimensions

API

Including the picture.html code requires that name parameter be defined, and point to a name within the pictures name-space for either the page/post or layout, eg...

{% include modules/includes-picture/picture.html name='left-side-bar' %}

{% include modules/includes-picture/picture.html name='right-side-bar' %}

... each of above refer to a left-side-bar and right-side-bar FrontMatter configuration within a pictures name-space, eg...

pictures:
  left-side-bar:
    url: ...
    img: ...
    sources: ...

  right-side-bar:
    url: ...
    img: ...
    sources: ...

`url`

Type: Hash

Optional, if defined modifies src and srcset paths

`url.base`

Type: string

Optional, if defined url.base will prepend each src and srcset path

Note, no path dividing slash (/) is inserted between url.base and paths

`url.filter`

Type: absolute_url | relative_url

Optional, if defined each src and srcset path will be piped through the defined Liquid filter

`img`

Type: Hash

Required, fallback/default for browsers that do not support source elements and/or when no source element is picked by the browser

`img.src`

Type: string

Required, path or URL of image file

`img.alt`

Type: string

Optional but recommend, text that describes picture element recommend for accessibility and SEO (Search Engine Optimization)

`img.height`

Type: number

Optional, defines height for all elements within named picture element

`img.width`

Type: number

Optional, defines width for all elements within named picture element

`img.loading`

Type: eager | lazy

Optional and requires browser has JavaScript enabled, defines priority for downloading image

`img.decoding`

Type: sync | async | auto

Optional and requires browser has JavaScript enabled, generally async is recommended for most use cases, default is auto

`sources`

Type: Array

Optional, define list of alternate image sources and/or formats for browser to choose

`sources[0].srcset`

Type: string | Array

Required, list of paths or URLs (comma separated) for browser to choose for a given file type

`sources[0].media`

Type: string

Optional, CSS media query that provides further hints for browser to use for deciding when to load an image

Notes

This repository may not be feature complete and/or fully functional, Pull Requests that add features or fix bugs are certainly welcomed.

Converting `.png` images to `.jpeg` and `.avif`

sudo apt-get install imagemagic

convert input.png output.jpeg

convert input.png output.avif

Converting `.png` images to `.webp`

sudo apt-get install cwebp

cwebp -q 60 input.png -o output.webp

Contributing

Options for contributing to includes-picture and liquid-utilities

Forking

Start making a Fork of this repository to an account that you have write permissions for.

Add remote for fork URL. The URL syntax is git@github.com:<NAME>/<REPO>.git...

cd ~/git/hub/liquid-utilities/includes-picture

git remote add fork git@github.com:<NAME>/includes-picture.git

Commit your changes and push to your fork, eg. to fix an issue...

cd ~/git/hub/liquid-utilities/includes-picture


git commit -F- <<'EOF'
:bug: Fixes #42 Issue


**Edits**


- `<SCRIPT-NAME>` script, fixes some bug reported in issue
EOF


git push fork main

Note, the -u option may be used to set fork as the default remote, eg. git push -u fork main however, this will also default the fork remote for pulling from too! Meaning that pulling updates from origin must be done explicitly, eg. git pull origin main

Then on GitHub submit a Pull Request through the Web-UI, the URL syntax is https://github.com/<NAME>/<REPO>/pull/new/<BRANCH>

Note; to decrease the chances of your Pull Request needing modifications before being accepted, please check the dot-github repository for detailed contributing guidelines.

Sponsor

Thanks for even considering it!

Via Liberapay you may on a repeating basis.

Regardless of if you're able to financially support projects such as includes-picture that liquid-utilities maintains, please consider sharing projects that are useful with others, because one of the goals of maintaining Open Source repositories is to provide value to the community.

Attribution

License

Builds `picture` element from FrontMatter and includes
Copyright (C) 2021 S0AndS0

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published
by the Free Software Foundation, version 3 of the License.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

For further details review full length version of AGPL-3.0 License.

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
.github		.github
.gitignore		.gitignore
LICENSE		LICENSE
picture.html		picture.html

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Includes Picture

Requirements

Quick Start

Your ReadMe File

Commit and Push

Usage

API

`url`

`url.base`

`url.filter`

`img`

`img.src`

`img.alt`

`img.height`

`img.width`

`img.loading`

`img.decoding`

`sources`

`sources[0].srcset`

`sources[0].media`

Notes

Converting `.png` images to `.jpeg` and `.avif`

Converting `.png` images to `.webp`

Contributing

Forking

Sponsor

Attribution

License

About

Releases

Sponsor this project

Languages

License

liquid-utilities/includes-picture

Folders and files

Latest commit

History

Repository files navigation

Includes Picture

Requirements

Quick Start

Your ReadMe File

Commit and Push

Usage

API

url

url.base

url.filter

img

img.src

img.alt

img.height

img.width

img.loading

img.decoding

sources

sources[0].srcset

sources[0].media

Notes

Converting .png images to .jpeg and .avif

Converting .png images to .webp

Contributing

Forking

Sponsor

Attribution

License

About

Resources

License

Code of conduct

Stars

Watchers

Forks

Releases

Sponsor this project

Languages

`url`

`url.base`

`url.filter`

`img`

`img.src`

`img.alt`

`img.height`

`img.width`

`img.loading`

`img.decoding`

`sources`

`sources[0].srcset`

`sources[0].media`

Converting `.png` images to `.jpeg` and `.avif`

Converting `.png` images to `.webp`