# docs/options.md

# Options

There are [Plugin Options](#plugin-options) and [Swiper Options](#swiper-options).

_Note: String parameters do **not** begin with a `:` but all other types do._

### Plugin Options

You must provide `:slides` or a `base-url` but **not both**.

| Property Name             |    Default Value     |  Type   | Description of Value                                                            |
| :----------------------------- | :-----------------------: | :-----: | :---------------------------------------------------------------------------------------- |
| **:slides** <CB />             |      or **base-url**      |  Array  | Base URL for image sources                                                                |
| **base-url** **¹** <CB />      |      or **:slides**       | String  | Base URL for image sources                                                                |
| :number-of-slides **¹** <CB /> |            `1`            | Number  | Number of slides to generate                                                              |
| :start-at **¹** <CB />         |            `1`            | Number  | Number to start generation                                                                |
| file-ext **¹** <CB />          |          `.jpg`           | String  | Extension for file names                                                                  |
| :pad-start **¹** <CB />        |            `1`            | Number  | Pad file names with `0`'s                                                                 |
| file-name-prefix **¹** <CB />  |            ` `            | String  | Prefix for file names                                                                     |
| alt-text-prefix <CB />         |         `Loading`         | String  | Prefix for `alt` attributes                                                               |
| button-text <CB />             |   `View in Fullscreen`    | String  | Text for fullscreen button                                                                |
| no-fullscreen <CB />           |          `false`          | Boolean | Disable fullscreen button                                                                 |
| height <CB />                  |          `null`           | String  | [CSS height](https://developer.mozilla.org/en-US/docs/Web/CSS/height) (default: auto)     |
| margin <CB />                  |          `null`           | String  | [CSS margin](https://developer.mozilla.org/en-US/docs/Web/CSS/margin)                     |
| background-color <CB />        | `var(--vp-code-block-bg)` | String  | [CSS background-color](https://developer.mozilla.org/en-US/docs/Web/CSS/background-color) |
| border-radius <CB />           |           `8px`           | String  | [CSS border-radius](https://developer.mozilla.org/en-US/docs/Web/CSS/border-radius)       |

> **¹** Only used with [Dynamic URL's](../guides/dynamic.md)

### Swiper Options

Swiper Parameters: https://swiperjs.com/swiper-api#parameters

| Property&nbsp;Name                                                                      |   Default    |  Type   | Description&nbsp;of&nbsp;Value      |
| :-------------------------------------------------------------------------------------- | :----------: | :-----: | :---------------------------------- |
| [:slides-per-view](https://swiperjs.com/swiper-api#param-slidesPerView) <CB />          |     `1`      | Number  | Number of slides shown per view     |
| [:space-between](https://swiperjs.com/swiper-api#param-spaceBetween) <CB />             |     `0`      | Number  | Space between slides in pixels      |
| [:lazy-preload-prev-next](https://swiperjs.com/swiper-api#param-spaceBetween) <CB />    |     `1`      | Number  | Number of lazy loaded slides        |
| [:breakpoints](https://swiperjs.com/swiper-api#param-breakpoints) <CB />                |    `null`    | Object  | Breakpoints parameters              |
| [:pagination](https://swiperjs.com/swiper-api#pagination-parameters) <CB />             |    `true`    | Object  | Pagination parameters               |
| [:keyboard](https://swiperjs.com/swiper-api#param-keyboard) <CB />                      |    `true`    | Boolean | Enable keyboard navigation          |
| [:mousewheel](https://swiperjs.com/swiper-api#param-mousewheel) <CB />                  |    `true`    | Boolean | Enable mouse wheel navigation       |
| [:navigation](https://swiperjs.com/swiper-api#param-navigation) <CB />                  |    `true`    | Boolean | Enable side navigation arrows       |
| [:grab-cursor](https://swiperjs.com/swiper-api#param-grabCursor) <CB />                 |    `true`    | Boolean | Enable grab cursor on hover         |
| [:loop](https://swiperjs.com/swiper-api#param-loop) <CB />                              |    `true`    | Boolean | Enable continuous loop              |
| [:autoplay](https://swiperjs.com/swiper-api#param-autoplay) <CB />                      |   `false`    | Object  | Can be `true` or parameters         |
| [:centered-slides](https://swiperjs.com/swiper-api#param-centeredSlides) <CB />         |   `false`    | Boolean | Center slides vs left aligned       |
| [:direction](https://swiperjs.com/swiper-api#param-direction) <CB />                    | `horizontal` | String  | If `vertical` must set `height`     |
| [:initial-slide](https://swiperjs.com/swiper-api#param-initialSlide) <CB />             |     `0`      | Number  | Initial slide index                 |
| [:one-way-movement](https://swiperjs.com/swiper-api#param-oneWayMovement) <CB />        |   `false`    | Boolean | Only allow swiping forward          |
| [:speed](https://swiperjs.com/swiper-api#param-speed) <CB />                            |    `300`     | Number  | Slide transition speed in ms        |
| [effect](https://swiperjs.com/swiper-api#param-effect) <CB />                           |   `slide`    | String  | `coverflow`, `cube`, `fade`, `flip` |
| [:coverflow-effect](https://swiperjs.com/swiper-api#coverflow-effect-parameters) <CB /> |    `{ }`     | Object  | EffectCoverflow parameters          |
| [:cube-effect](https://swiperjs.com/swiper-api#cube-effect-parameters) <CB />           |    `{ }`     | Object  | EffectCube parameters               |
| [:fade-effect](https://swiperjs.com/swiper-api#fade-effect-parameters) <CB />           |    `{ }`     | Object  | EffectFade parameters               |
| [:flip-effect](https://swiperjs.com/swiper-api#flip-effect-parameters) <CB />           |    `{ }`     | Object  | EffectFlip parameters               |

&nbsp;

See the [Usage](../guides/get-started.md#usage) guide or the [Examples](../examples/index.md)
for details on using the `<VPSwiper>` tag.

If your images are named numerically and sequentially, check out the [Dynamic URL's](../guides/dynamic.md) guide.

&nbsp;

::: tip ❔ ADDITIONAL OPTIONS
If you need more options, please [request a feature](../support.md).
:::

---

# guides/dynamic.md

# Dynamic URL Generation

This can greatly help reduce boilerplate and footprint when creating Swipers.

::: tip ❗ IMPORTANT
This only works if your files are named numerically and ordered sequentially.
:::

This generates numbers for filenames and appends them to the base url as follows:

`base-url` + `/` + `file-name-prefix` + `file#` + `file-ext`

### Basic

```vue [Markdown ~vscode-icons:file-type-text~]
<VPSwiper base-url="https://example.com/path" :number-of-slides="3" />
```

Resulting URL's:

```text
https://example.com/path/1.jpg
https://example.com/path/2.jpg
https://example.com/path/3.jpg
```

### Additional Options

```vue [Markdown ~vscode-icons:file-type-text~]
<VPSwiper
  base-url="https://example.com/path"
  :number-of-slides="4"
  :start-at="8"
  :pad-start="2"
  file-name-prefix="slide-"
  file-ext=".png"
  :pagination="{ clickable: true }"
  :grab-cursor="false"
  margin-top="40px"
  effect="fade"
/>
```

Resulting URL's:

```text
https://example.com/path/slide-08.png
https://example.com/path/slide-09.png
https://example.com/path/slide-10.png
https://example.com/path/slide-11.png
```

Make sure to check out the [Additional Options](../docs/options.md).

_Note: HTML tags must be seperated from Markdown with one blank line._

&nbsp;

::: info 🖼️ LIVE DEMOS
You can view more on the [Examples page](../examples/index.md).
:::

---

# guides/get-started.md

# Getting Started

A [VitePress](https://vitepress.dev/) Plugin to Easily add a [SwiperJS](https://swiperjs.com/) Photo Gallery or Image Slideshow.

Start by [installing](#install) the package, [setting](#setup) up the plugin, and [using](#usage) the component.

## Install

<span class="search-keywords">Install or Download from NPM npmjs.com</span>

Install directly to your VitePress with the following command.

::: code-group

```shell [npm]
npm i @cssnr/vitepress-swiper
```

```shell [pnpm]
pnpm i @cssnr/vitepress-swiper
```

```shell [yarn]
yarn add @cssnr/vitepress-swiper
```

```shell [bun]
bun i @cssnr/vitepress-swiper
```

:::

_Note: you can also [copy the source](source.md) file to your project._

## Setup

Add these 3 lines to your `index.[js,ts]`.

_If you don't have a [.vitepress/theme/index.ts](https://vitepress.dev/guide/custom-theme#theme-resolving) file, create one._

```javascript [.vitepress/theme/index.ts]
import DefaultTheme, { VPBadge } from 'vitepress/theme' // [!code highlight]

import VPSwiper from '@cssnr/vitepress-swiper' // [!code ++]
import '@cssnr/vitepress-swiper/style.css' // [!code ++]

export default {
  ...DefaultTheme,
  enhanceApp({ app }) {
    app.component('Badge', VPBadge) // [!code highlight]
    app.component('VPSwiper', VPSwiper) // [!code ++]
  },
}
```

<Badge type="info">VPBadge</Badge> Only required if you are using the VitePress [Badge](https://vitepress.dev/reference/default-theme-badge#badge).

## Usage

Add a `<VPSwiper>` tag to your Markdown where you want the Swiper to appear.

::: code-group

```vue [Basic ~vscode-icons:file-type-text~]
<VPSwiper
  :slides="[
    'https://example.com/path/1.jpg',
    'https://example.com/path/2.jpg',
    'https://example.com/path/3.jpg',
  ]"
/>
```

```vue [Additional Options ~vscode-icons:file-type-text~]
<VPSwiper
  :slides="[
    'https://example.com/path/1.jpg',
    'https://example.com/path/2.jpg',
    'https://example.com/path/3.jpg',
  ]"
  :pagination="{ type: 'fraction' }"
  :mousewheel="false"
  button-text="Fullscreen"
  margin-top="30px"
  effect="coverflow"
  :coverflow-effect="{ slideShadows: false }"
/>
```

```vue [Dynamic URLs ~vscode-icons:file-type-text~]
<VPSwiper base-url="https://example.com/path" :number-of-slides="3" />
```

:::

Make sure to check out the [Additional Options](../docs/options.md).

_Note: HTML tags must be seperated from Markdown with one blank line._

::: info 🖼️ LIVE DEMOS
You can view more on the [Examples page](../examples/index.md).
:::

### Dynamic URLs

You can generate URL's dynamically using numbers to reduce boilerplate.

See the [Dynamic URL's Page](dynamic.md) for more details.

&nbsp;

::: tip ❔ GET HELP
If you have any trouble getting started, [support is available](../support.md).
:::

---

# guides/source.md

# Use from Source

You can easily add the source file to your project for full control over the template.

::: tip ❗ IMPORTANT
This method is manual and does not provide updates or support.
:::

Download or copy the [VPSwiper.vue](https://github.com/cssnr/vitepress-swiper/blob/master/src/VPSwiper.vue)
file to your project.

- Source File: [VPSwiper.vue](https://github.com/cssnr/vitepress-swiper/blob/master/src/VPSwiper.vue)
- Target Location: `.vitepress/theme/components/VPSwiper.vue`

Install the dependency, [SwiperJS](https://www.npmjs.com/package/swiper).

::: code-group

```shell [npm]
npm i swiper
```

```shell [pnpm]
pnpm i swiper
```

```shell [yarn]
yarn add swiper
```

```shell [bun]
bun i swiper
```

:::

Add these 2 lines to your `index.[js,ts]`.

```javascript [.vitepress/theme/index.ts]
import DefaultTheme, { VPBadge } from 'vitepress/theme' // [!code highlight]

import VPSwiper from './components/VPSwiper.vue' // [!code ++]

export default {
  ...DefaultTheme,
  enhanceApp({ app }) {
    app.component('Badge', VPBadge) // [!code highlight]
    app.component('VPSwiper', VPSwiper) // [!code ++]
  },
}
```

<Badge type="info">VPBadge</Badge> Only required if you are using the VitePress [Badge](https://vitepress.dev/reference/default-theme-badge#badge).

<div class="tip custom-block" style="padding-top: 8px; margin-top: 32px;">

See the [Usage Guide](get-started.md#usage) for instructions on adding the `<VPSwiper>` tag.

</div>

---

# support.md

# Support

If you run into any issues or want to see any new features, please let us know!

Contributing is as easy as telling us [what features or changes](https://github.com/cssnr/vitepress-swiper/issues/new?template=1-feature.yaml) you want to see next…

[[toc]]

### GitHub Discussions

If you have a question or need help with anything,
start a discussion in [General](https://github.com/cssnr/vitepress-swiper/discussions/categories/general)
or [Q&A](https://github.com/cssnr/vitepress-swiper/discussions/categories/q-a).

If you want to see a new feature, submit a [Feature Requests](https://github.com/cssnr/vitepress-swiper/issues/new?template=1-feature.yaml).

[![Start A Discussion](https://img.shields.io/badge/Start_A_Discussion-blue?style=for-the-badge&logo=github)](https://github.com/cssnr/vitepress-swiper/discussions)

### GitHub Issues

If you run into any problems or find a bug, please [open an issue](https://github.com/cssnr/vitepress-swiper/issues).

**These reports are treated with the highest priority.**

[![Report an Issue](https://img.shields.io/badge/Report_an_Issue-blue?style=for-the-badge&logo=github)](https://github.com/cssnr/vitepress-swiper/issues)

### Discord Chat

You can chat with us about anything [on discord](https://discord.gg/wXy6m2X8wY).

[![Chat on Discord](https://img.shields.io/badge/Chat_on_Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/wXy6m2X8wY)

&nbsp;

[![Support on Ko-fi](https://cdn.prod.website-files.com/5c14e387dab576fe667689cf/670f5a01c01ea9191809398c_support_me_on_kofi_blue.png){ width="360" }](https://ko-fi.com/cssnr)

<a href="https://github.com/cssnr/vitepress-swiper">
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=cssnr/vitepress-swiper&type=date&legend=bottom-right&theme=dark" />
   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=cssnr/vitepress-swiper&type=date&legend=bottom-right" />
   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=cssnr/vitepress-swiper&type=date&legend=bottom-right" />
 </picture>
</a>