Skip to content

Commit

Permalink
update demos
Browse files Browse the repository at this point in the history
  • Loading branch information
Maya Shavin committed Nov 8, 2020
1 parent 818fa5d commit 6f715a8
Show file tree
Hide file tree
Showing 24 changed files with 813 additions and 111 deletions.
2 changes: 1 addition & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

> [Cloudinary](https://cloudinary.com) integration for [Gridsome](https://gridsome.org)
[Demo site](https://gridsome-cloudinary.netlify.app/)
[Demo site](https://gridsome-cloudinary.netlify.app/demo)

Optimize and manage your images and videos in your Gridsome application with the available Cloudinary plugins.

Expand Down
60 changes: 1 addition & 59 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,59 +1 @@
[![Netlify Status](https://api.netlify.com/api/v1/badges/de44d168-eb1d-47a5-8731-d77bb40af7c8/deploy-status)](https://app.netlify.com/sites/jamdocs/deploys)

# ![Jamdocs](https://github.com/samuelhorn/jamdocs/blob/master/src/assets/img/logo-dark.svg)

The ultimate static generated documentation theme for the JAM-stack. Highly customizable, based on Gridsome, ready to deploy to Netlify in one click. [DEMO](https://jamdocs.samuelhorn.com/)

_Beware, Jamdocs is still in heavy development and will probably change a lot in the near future. And the docs for it is still not completed._

## Fast by default

Jamdocs is optimized to be as fast as possible, right now generating 100/100/100/100 score in Google Lighthouse. And 100/100 score in Google Page Speed Insights.

![100/100/100/100 Lighthouse scores](https://github.com/samuelhorn/jamdocs/blob/master/src/assets/img/pagespeed.png)

## Local installation for development

1. `git clone https://github.com/samuelhorn/jamdocs project-name`.
2. `cd project-name`
3. `gridsome develop`.

## Deploy to Netlify

[![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/samuelhorn/jamdocs)

## Import to Forestry CMS

[![](https://assets.forestry.io/import-to-forestryK.svg)](https://app.forestry.io/quick-start?repo=samuelhorn/jamdocs&engine=other "Import to Forestry")

This project has been pre-configured to work with [Forestry](https://forestry.io). Any changes you make in Forestry will be commited back to your repo. ✨

![Forestry documentation in JAMdocs](static/screenshor-forestry-preview.png)

## Setup & configuration

See the [demo](https://jamdocs.samuelhorn.com/), which is also the documentation, obviously!

## Todos

1. Improve the actual documentation for Jamdocs, in Jamdocs :)
2. ~~Build the homepage better, dividing stuff into components and so on.~~
3. Implement Algolia search.
4. ~~Add a link to this repository from the demo.~~

## Credits

* Creds to the [Netlify](https://www.netlify.com/) team for making an awesome all in one hosting soluiton for the JAM-stack.
* Creds to the [Gridsome](https://gridsome.org/) team for developing a great foundation to build static sites.
* Creds to [Evan You](https://twitter.com/youyuxi) for making [Vue](https://vuejs.org/).
* Creds to [Cole Bemis](https://twitter.com/colebemis) for making [feathericons](https://feathericons.com/), my favourite icon set.
* Creds to [Egoist](https://github.com/egoist), who's not that egoistic. Because he made [vue-feather-icons](https://github.com/egoist/vue-feather-icons).
* Creds to [Forestry](https://forestry.io/) for finalizing the Forestry configuration and writing about it in the docs, adding their great headless CMS to the mix.

## License

[MIT](https://github.com/samuelhorn/jamdocs/blob/master/LICENSE)

## Finally

Enjoy Jamdocs, and if you like and use this project commercially, please consider sponsoring on Github since I have put a lot of spare time into this.
Documentation site of Cloudinary plugins for Gridsome
12 changes: 12 additions & 0 deletions docs/content-examples/example.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
---
title: First Blog!
coverPhoto1:
cloudinaryAsset: true
publicId: examples/94002
coverPhoto2:
cloudinaryAsset: true
publicId: examples/kitten_2
---
You're a very talented young man, with your own clever thoughts and ideas. Do you need a manager? You know what? It is beets. I've crashed into a beet truck. God creates dinosaurs. God destroys dinosaurs. God creates Man. Man destroys God. Man creates Dinosaurs.

![kitty](http://res.cloudinary.com/mayashavin/image/upload/c_scale,h_300,w_300/r_/a_0/e_vectorize/v1/examples/pgelbwe2eit11)
2 changes: 1 addition & 1 deletion docs/docs/cloudinary-transformer/cloudinary-transformer.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ categoryPosition: 3
position: 1
---

[Demo site](/demo)
[Demo site](/demo/cloudinary-transformer)

To use the plugin, you need a Cloudinary account first. [Register for a free account](https://cloudinary.com/users/register/free) if you haven't got one yet.

Expand Down
289 changes: 285 additions & 4 deletions docs/docs/cloudinary-transformer/usage.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,12 +9,293 @@ To use the plugin, you need to have an account with [Cloudinary](https://cloudin

This plugin fetches the desired media files from your Cloudinary account to the Gridsome's Data layer, and transforms them into two set of images - fixed and responsive. The approach is based on `srcset` of `img` tag, as indicated in [Responsive image documentation](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images).

Upon querying, the transformer expose the media file under the schema `CldAsset`. You can then query your media using GraphQL, and apply further transformations for a fixed-width image, or responsive image.
## Automatic format and quality serving

## Fixed-width images
The plugin *automatically* apply the following optimization to all the media files fetched from [Cloudinary](https://cloudinary.com), which covers **more than 60% image optimization** use cases.

## Responsive images
* `f_auto` - Auto detect and provide the most suitable media format for the request media on-the-fly. For example, with the same image URL, Cloudinary will return WEBP for Chrome or any browser supports it, or JPG, JP2, and even AVIF if this is the preferred media format by browser.

## GIF images
* `q_auto` - Auto detect the device resolution and provide the **most suitable quality** media accordingly. This is to save the bandwidth and ensure that users will enjoy the best quality media per device, while keeping the download size as optimal as possible.

## `cloudinaryAsset` - Use images ready on Cloudinary

To create GraphQL nodes for images that are already stored in Cloudinary, you need to have the nodes containing those images' stored information. To indicate the image is from Cloudinary, we use the flag `cloudinaryAsset`.

For example, to use a Cloudinary image as cover photo for a blog post written using markdown, we have the Front matter block inside the post similar to the following:

```yaml
---
title: Example blog post
description: It's just another hello world with cover photo
coverPhoto:
cloudinaryAsset: true
publicId: 'example'
---
```

By setting `cloudinaryAsset` to true, it indicates that this property field `coverPhoto` is a Cloudinary asset. Upon creating the GraphQL node, it will fetch the image from Cloudinary and replace the original property with a new node - `CldAsset` node that can be used with `g-image`.

You can then query your media using GraphQL, and apply further transformations for a fixed-width image, or responsive image.

## Fixed-width images with `fixed()`

To have your image served in **same size** for different resolutions, use the fixed-width image query - `fixed(width, height, baseTrans, chainedTrans)`.

```html
<page-query>
query {
allCldAsset {
edges {
node {
fixed(
width:500
height:500
baseTrans: {
gravity: "auto"
crop: "fill"
}
chainedTrans: [{
effect: "grayscale"
}]
){
src
srcSet
}
}
}
}
}
</page-query>
```

The `fixed` field of `CldAsset` receives the following agruments:

* `width`
* Type: `Integer`
* Indicate the desired width for the querying image. If not presented, the width will be calculated by the aspect ratio between the original width and the passed `height` (if any).
* `height`
* Type: `Integer`
* Indicate the desired height for the querying image.
* `baseTrans`
* Type: `CldTransformation` (`Object`)
* The base transformations to apply on the image on-the-fly. Check [Transformations](/transformations) for acceptable properties.
* `chainedTrans`
* Type: `CldTransformation[]`
* The chaining group of advanced transformation to apply on the image. Check [Transformations](/transformations) for acceptable properties.

It returns a nested node which contains the following fields:

* `height` - the desired height (or calculated height based on the width) of image.
* `width` - the desired width of image
* `src` - the main delivery URL of the image with all the base and chained transformation. `f_auto` and `q_auto` are added by default.
* `srcSet` - the set of delivery URLs for the same image, in different resolutions (1x, 1.5x, 2x and 3x)

Upon querying the images successfully, you can use `g-image` and `srcSet` to display the fixed-width images:

```html
<template>
<Layout>
<section>
<g-image
v-for="image in images"
:key="image.publicId"
:src="image.fixed.src"
:srcSet="image.fixed.srcSet"
/>
</section>
</Layout>
</template>
<script>
export default {
computed: {
images() {
return this.$page.allCldAsset.edges.map(({ node }) => node)
}
},
}
</script>
```

For more examples, see the [Demo](/demo/cloudinary-transformer).

## Responsive images with `responsive()`

To have your image served in **different sizes** for different resolutions, use the responsize image query - `responsize( maxWidth, baseTrans, chainedTrans)`.

```html
<page-query>
query {
allCldAsset {
edges {
node {
responsive(
maxWidth: 1000
baseTrans: {
gravity: "auto"
crop: "fill"
}
chainedTrans: [{
effect: "grayscale"
}]
){
src
srcSet
sizes
}
}
}
}
}
</page-query>
```

The `fixed` field of `CldAsset` receives the following agruments:

* `maxWidth`
* Type: `Integer`
* The maximum width for responsive images. If not presented, the original width will be used.
* `baseTrans`
* Type: `CldTransformation` (`Object`)
* The base transformations to apply on the image on-the-fly. Check [Transformations](/transformations) for acceptable properties.
* `chainedTrans`
* Type: `CldTransformation[]`
* The chaining group of advanced transformation to apply on the image. Check [Transformations](/transformations) for acceptable properties.

It returns a nested node which contains the following fields:

* `viewHeight` - the desired height (or calculated height based on the width) of image.
* `viewWidth` - the desired width of image
* `src` - the main delivery URL of the image with all the base and chained transformation. `f_auto` and `q_auto` are added by default.
* `srcSet` - the set of delivery URLs for the same image, with indicating of size per image, separating by comma. Browser will choose the right image url to serve from this set.
* `sizes` - the set of screen widths indicating to the browser which image size to choose best if the width considition is met.

Upon querying the images successfully, you can use `g-image`, `srcSet`, and `sizes` to display the fixed-width images:

```html
<template>
<Layout>
<section>
<g-image
v-for="image in images"
:key="image.publicId"
:src="image.responsive.src"
:srcSet="image.responsive.srcSet"
:sizes="image.responsive.sizes"
/>
</section>
</Layout>
</template>
<script>
export default {
computed: {
images() {
return this.$page.allCldAsset.edges.map(({ node }) => node)
}
},
}
</script>
```

## Manual creating Cloudinary data for Gridsome image

In addition, the transformer exposes two functionalities which you can import and use them to create fixed and responsive images accordingly.

### `async createFixedImage()`

* `publicId`
* Type: `string`
* `required`
* The path/to/the/image stored in Cloudinary.
* `baseTrans`
* Type: `Object`
* The base transformations to apply on the image on-the-fly. Check [Transformations](/transformations) for acceptable properties.
* `width`
* Type: `Integer`
* Indicate the desired width for the querying image. If not presented, the width will be calculated by the aspect ratio between the original width and the passed `height` (if any).
* `height`
* Type: `Integer`
* Indicate the desired height for the querying image.
* `chainedTrans`
* Type: `Object[]`
* The chaining group of advanced transformation to apply on the image. Check [Transformations](/transformations) for acceptable properties.

Others parameters for further configuring Cloudinary, such as:

Property | Type | Default | Required | Description
--- | --- | --- | --- | ---
`type` | string | `upload` | no | Delivery (storage) type of the asset: <br>`upload` <br> `private`<br>`authenticated`<br>`facebook`, `twitter`<br>`gravatar`, `youtube`, `hulu`<br>`vimeo`, `animoto`
`resourceType` | string | `image` | no | Type of the asset:<br>`image` (*also for gif*)<br>`raw`<br>`video` (*includes audio like .mp3*)
`cloudName` | string | n/a | no | The cloud where the queried image is stored. <br>Not needed if provided in the `gridsome.config.js` file.

Returns an Object which contains the following information for a fixed-width image:

* `height` - the desired height (or calculated height based on the width) of image.
* `width` - the desired width of image
* `src` - the main delivery URL of the image with all the base and chained transformation. `f_auto` and `q_auto` are added by default.
* `srcSet` - the set of delivery URLs for the same image, in different resolutions (1x, 1.5x, 2x and 3x)

```js
createFixedImage({
publicId: "sample",
width:500,
height:500,
baseTrans: {
gravity: "auto"
crop: "fill"
},
chainedTrans: [{
effect: "grayscale"
}],
cloudName: "demo",
})
```

### `async createResponsiveImage()`

* `publicId`
* Type: `string`
* `required`
* The path/to/the/image stored in Cloudinary.
* `breakpoints`
* Type: `Integer[]`
* Default: `[200, 400, 600]`
* Define the breakpoints for calculating the sizes of responsive image accordingly.
* `maxWidth`
* Type: `Integer`
* The maximum width for responsive images. If not presented, the original width will be used.
* `baseTrans`
* Type: `CldTransformation` (`Object`)
* The base transformations to apply on the image on-the-fly. Check [Transformations](/transformations) for acceptable properties.
* `chainedTrans`
* Type: `CldTransformation[]`
* The chaining group of advanced transformation to apply on the image. Check [Transformations](/transformations) for acceptable properties.
* Others parameters for further configuring Cloudinary, such as:

Property | Type | Default | Required | Description
--- | --- | --- | --- | ---
`type` | string | `upload` | no | Delivery (storage) type of the asset: <br>`upload` <br> `private`<br>`authenticated`<br>`facebook`, `twitter`<br>`gravatar`, `youtube`, `hulu`<br>`vimeo`, `animoto`
`resourceType` | string | `image` | no | Type of the asset:<br>`image` (*also for gif*)<br>`raw`<br>`video` (*includes audio like .mp3*)
`cloudName` | string | n/a | no | The cloud where the queried image is stored. <br>Not needed if provided in the `gridsome.config.js` file.

It returns an `Object` which contains the following fields for a responsive image:

* `viewHeight` - the desired height (or calculated height based on the width) of image.
* `viewWidth` - the desired width of image
* `src` - the main delivery URL of the image with all the base and chained transformation. `f_auto` and `q_auto` are added by default.
* `srcSet` - the set of delivery URLs for the same image, with indicating of size per image, separating by comma. Browser will choose the right image url to serve from this set.
* `sizes` - the set of screen widths indicating to the browser which image size to choose best if the width considition is met.

```js
createFixedImage({
publicId: "sample",
maxWidth: 1000,
baseTrans: {
gravity: "auto"
crop: "fill"
},
chainedTrans: [{
effect: "grayscale"
}],
cloudName: "demo",
})
```
Loading

0 comments on commit 6f715a8

Please sign in to comment.