Skip to content

Commit

Permalink
feat: create documentation with vitepress
Browse files Browse the repository at this point in the history
stafyniaksacha committed Jan 6, 2023

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature.
1 parent 5e75ff6 commit dd9b374
Showing 19 changed files with 2,131 additions and 1,079 deletions.
59 changes: 59 additions & 0 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
name: docs

on:
# trigger deployment on push to main branch and if docs/ is updated
push:
branches: [main]
paths:
- "docs/**"
# trigger deployment manually
workflow_dispatch:

jobs:
docs:
runs-on: ubuntu-latest

steps:
- uses: actions/checkout@v2
with:
# fetch all commits to get last updated time or other git log info
fetch-depth: 0

- name: Setup Node.js
uses: actions/setup-node@v1
with:
# choose node.js version to use
node-version: "14"

# cache node_modules
- name: Cache dependencies
uses: actions/cache@v2
id: yarn-cache
with:
path: |
**/node_modules
key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
restore-keys: |
${{ runner.os }}-yarn-
# install dependencies if the cache did not hit
- name: Install dependencies
if: steps.yarn-cache.outputs.cache-hit != 'true'
run: yarn --frozen-lockfile

# run build script
- name: Build VitePress site
run: yarn docs:build

# please check out the docs of the workflow for more details
# @see https://github.com/crazy-max/ghaction-github-pages
- name: Deploy to GitHub Pages
uses: crazy-max/ghaction-github-pages@v2
with:
# deploy to gh-pages branch
target_branch: gh-pages
# deploy the default output dir of VitePress
build_dir: docs/.vitepress/dist
env:
# @see https://docs.github.com/en/actions/reference/authentication-in-a-workflow#about-the-github_token-secret
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
31 changes: 31 additions & 0 deletions .github/workflows/gh-release.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
name: release

on:
# trigger release on every tag push
push:
tags:
- 'v*.*.*'

jobs:
release:
runs-on: ubuntu-latest

steps:
# extract tag from the github ref (e.g. refs/tags/v1.2.3)
- name: Set up tag meta
id: meta
run: |
echo ::set-output name=tag::${GITHUB_REF#refs/tags/}
# create a new release on github with discussion
- name: Create release
uses: softprops/action-gh-release@v1
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
with:
tag_name: ${{ steps.meta.outputs.tag }}
name: Release ${{ steps.meta.outputs.tag }}
body: View [CHANGELOG.md](https://github.com/strapi-community/strapi-plugin-rest-cache/blob/main/CHANGELOG.md) for details
draft: false
prerelease: false
discussion_category_name: announcements
4 changes: 3 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
@@ -135,4 +135,6 @@ schema.graphql

front-workspace.code-workspace
.yarn
.yarnrc
.yarnrc

cache
75 changes: 2 additions & 73 deletions README.md
Original file line number Diff line number Diff line change
@@ -32,80 +32,9 @@ No extra configuration needed, the modifiers will be applied based on the url.

This is made by [ipx](https://github.com/unjs/ipx)

## 🖐 Installation


**Add plugin dependency**
```bash
yarn add strapi-plugin-local-image-sharp
```

## 🚚 Usage

### Examples

This plugin works by setting modifiers either the path, or in the query string parameters.

Get original image:

`http://localhost:1337/uploads/buffalo.png`

#### Using path modifiers

Change format to `webp` and keep other things same as source:

`http://localhost:1337/uploads/f_webp/buffalo_56442f4096.png`

Keep original format `png` and set width to `200`:

`http://localhost:1337/uploads/w_200/buffalo_56442f4096.png`

You can combine modifiers using a coma, for example:
Resize to `200x200px` using `embed` method and change format to `webp`:

`http://localhost:1337/uploads/embed,f_webp,s_200x200/buffalo_56442f4096.png`

#### Using query parameters modifiers

Change format to `webp` and keep other things same as source:

`http://localhost:1337/uploads/buffalo_56442f4096.png?format=webp`

Keep original format `png` and set width to `200`:

`http://localhost:1337/uploads/buffalo_56442f4096.png?width=200`

You can combine modifiers using a coma, for example:
Resize to `200x200px` using `embed` method and change format to `webp`:

`http://localhost:1337/uploads/buffalo_56442f4096.png?format=webp&resize=200x200&embed`

### Modifiers

| Property | Docs | Example | Comments |
| --------------- | :-------------------------------------------------------------- | :---------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| width / w | [Docs](https://sharp.pixelplumbing.com/api-resize#resize) | `http://localhost:1337/uploads/width_200/buffalo.png` |
| height / h | [Docs](https://sharp.pixelplumbing.com/api-resize#resize) | `http://localhost:1337/uploads/height_200/buffalo.png` |
| resize / s | [Docs](https://sharp.pixelplumbing.com/api-resize#resize) | `http://localhost:1337/uploads/s_200x200/buffalo.png` |
| fit | [Docs](https://sharp.pixelplumbing.com/api-resize#resize) | `http://localhost:1337/uploads/s_200x200,fit_outside/buffalo.png` | Sets `fit` option for `resize`.
| position / pos | [Docs](https://sharp.pixelplumbing.com/api-resize#resize) | `http://localhost:1337/uploads/s_200x200,pos_top/buffalo.png` | Sets `position` option for `resize`.
| trim | [Docs](https://sharp.pixelplumbing.com/api-resize#trim) | `http://localhost:1337/uploads/trim_100/buffalo.png` |
| format | [Docs](https://sharp.pixelplumbing.com/api-output#toformat) | `http://localhost:1337/uploads/format_webp/buffalo.png` | Supported format: `jpg`, `jpeg`, `png`, `webp`, `avif`, `gif`, `heif` |
| quality / q | \_ | `http://localhost:1337/uploads/quality_50/buffalo.png` | Accepted values: 0 to 100 |
| rotate | [Docs](https://sharp.pixelplumbing.com/api-operation#rotate) | `http://localhost:1337/uploads/rotate_45/buffalo.png` |
| enlarge | \_ | `http://localhost:1337/uploads/enlarge,s_2000x2000/buffalo.png` | Allow the image to be upscaled. By default the returned image will never be larger than the source in any dimension, while preserving the requested aspect ratio. |
| flip | [Docs](https://sharp.pixelplumbing.com/api-operation#flip) | `http://localhost:1337/uploads/flip/buffalo.png` |
| flop | [Docs](https://sharp.pixelplumbing.com/api-operation#flop) | `http://localhost:1337/uploads/flop/buffalo.png` |
| sharpen | [Docs](https://sharp.pixelplumbing.com/api-operation#sharpen) | `http://localhost:1337/uploads/sharpen_30/buffalo.png` |
| median | [Docs](https://sharp.pixelplumbing.com/api-operation#median) | `http://localhost:1337/uploads/median_10/buffalo.png` |
| gamma | [Docs](https://sharp.pixelplumbing.com/api-operation#gamma) | `http://localhost:1337/uploads/gamma_3/buffalo.png` |
| negate | [Docs](https://sharp.pixelplumbing.com/api-operation#negate) | `http://localhost:1337/uploads/negate/buffalo.png` |
| normalize | [Docs](https://sharp.pixelplumbing.com/api-operation#normalize) | `http://localhost:1337/uploads/normalize/buffalo.png` |
| threshold | [Docs](https://sharp.pixelplumbing.com/api-operation#threshold) | `http://localhost:1337/uploads/threshold_10/buffalo.png` |
| tint | [Docs](https://sharp.pixelplumbing.com/api-colour#tint) | `http://localhost:1337/uploads/tint_1098123/buffalo.png` |
| grayscale | [Docs](https://sharp.pixelplumbing.com/api-colour#grayscale) | `http://localhost:1337/uploads/grayscale/buffalo.png` |
| animated | - | `http://localhost:1337/uploads/animated/buffalo.gif` | Experimental |
## 🚚 Getting Started

[Read the Docs to Learn More.](https://strapi-community.github.io/strapi-plugin-local-image-sharp/)

## Contributing

59 changes: 59 additions & 0 deletions docs/.vitepress/config.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
import { createRequire } from 'module'
import { defineConfig } from 'vitepress'

const require = createRequire(import.meta.url)
const pkg = require('../../package.json')

export default defineConfig({
title: "Local Image Sharp",
description: "Dynamically resize, format and optimize images based on url modifiers.",
base: "/strapi-plugin-local-image-sharp/",
lastUpdated: true,
themeConfig: {
socialLinks: [
{ icon: 'github', link: 'https://github.com/strapi-community/strapi-plugin-local-image-sharp' },
],
editLink: {
pattern: 'https://github.com/strapi-community/strapi-plugin-local-image-sharp/edit/main/docs/:path',
text: 'Edit this page on GitHub'
},
logo: {
src: "/icon.png",
},
outline: [2,3],
footer: {
message: 'Made with ❤️ by <a href="https://github.com/strapi-community/">Strapi Community</a>'
},
nav: [
{
text: "Guide",
link: "/guide/",
activeMatch: '/guide/',
},
{
text: pkg.version,
items: [
{
text: 'Changelog',
link: 'https://github.com/strapi-community/strapi-plugin-local-image-sharp/blob/main/CHANGELOG.md'
},
{
text: 'Strapi Community',
link: 'https://github.com/strapi-community'
}
]
}
],
sidebar: {
'/guide/': [
{
text: 'Guide',
items: [
{ text: 'Quick Start Guide', link: '/guide/' },
{ text: 'Modifiers', link: '/guide/modifiers' },
]
},
],
}
}
})
37 changes: 37 additions & 0 deletions docs/.vitepress/theme/Layout.vue
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
<script setup>
import { useData } from 'vitepress'
import DefaultTheme from 'vitepress/theme'
import Giscus from '@giscus/vue'
const { isDark } = useData()
const { Layout } = DefaultTheme
</script>

<template>
<Layout>
<template #doc-after>
<div class="comments">
<Giscus
repo="strapi-community/strapi-plugin-local-image-sharp"
repo-id="R_kgDOHHhI1w"
category="Documentation"
category-id="DIC_kwDOHHhI184CTblQ"
mapping="pathname"
strict="0"
reactions-enabled="1"
emit-metadata="0"
input-position="bottom"
:theme="isDark ? 'transparent_dark' : 'light'"
lang="en"
loading="lazy"
/>
</div>
</template>
</Layout>
</template>

<style scoped>
.comments {
margin-top: 2rem;
}
</style>
7 changes: 7 additions & 0 deletions docs/.vitepress/theme/custom.css
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
:root {
--vp-c-brand: #8e75ff;
--vp-c-brand-light: #a091ed;
--vp-c-brand-lighter: #a091ed;
--vp-c-brand-dark: #8e75ff;
--vp-c-brand-darker: #8e75ff;
}
10 changes: 10 additions & 0 deletions docs/.vitepress/theme/index.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
import DefaultTheme from 'vitepress/theme'
import Layout from './Layout.vue'
import './custom.css'

export default {
...DefaultTheme,
// override the Layout with a wrapper component that
// injects the slots
Layout
}
59 changes: 59 additions & 0 deletions docs/guide/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
---
title: Quick Start Guide
---

# Quick Start Guide

Convert any uploaded images with local provider using sharp modifier.
No extra configuration needed, the modifiers will be applied based on the url.

> This is made using [ipx](https://github.com/unjs/ipx)
To install this plugin, run the following command in your Strapi project:

```bash
yarn add strapi-plugin-local-image-sharp
```

## Usage

This plugin works by setting modifiers either the path, or in the query string parameters.

- Original image:
`http://localhost:1337/uploads/buffalo_56442f4096.png`
- WebP (Path modifier):
`http://localhost:1337/uploads/format_webp/buffalo_56442f4096.png`
- WebP (Query parameters):
`http://localhost:1337/uploads/buffalo_56442f4096.png?format=webp`



### Using path modifiers

Change format to `webp` and keep other things same as source:

`http://localhost:1337/uploads/f_webp/buffalo_56442f4096.png`

Keep original format `png` and set width to `200`:

`http://localhost:1337/uploads/w_200/buffalo_56442f4096.png`

You can combine modifiers using a coma, for example:
Resize to `200x200px` using `embed` method and change format to `webp`:

`http://localhost:1337/uploads/embed,f_webp,s_200x200/buffalo_56442f4096.png`

### Using query parameters modifiers

Change format to `webp` and keep other things same as source:

`http://localhost:1337/uploads/buffalo_56442f4096.png?format=webp`

Keep original format `png` and set width to `200`:

`http://localhost:1337/uploads/buffalo_56442f4096.png?width=200`

You can combine modifiers using a coma, for example:
Resize to `200x200px` using `embed` method and change format to `webp`:

`http://localhost:1337/uploads/buffalo_56442f4096.png?format=webp&resize=200x200&embed`
Loading

0 comments on commit dd9b374

Please sign in to comment.