Skip to content

liquid-utilities/includes-picture

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

3 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

Includes Picture

Builds picture element from FrontMatter and includes

Byte size of Includes Picture Open Issues Open Pull Requests Latest commits includes-picture Demos



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 sponsor__shields_io__liberapay 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.