chore: add docs

packages/docs/docs/guide/configuration.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 3
+sidebar_position: 1
 ---
 
 # Configuration

packages/docs/docs/guide/pipes/_category_.yml

@@ -1,3 +1,3 @@
 label: Optimisations
-position: 1
+position: 2
 collapsed: false

packages/docs/docs/guide/pipes/cache-buster.mdx

@@ -0,0 +1,59 @@
+---
+sidebar_position: 2
+---
+
+import { ImageToggle } from '@site/src/components/ImageToggle';
+
+# Cache Buster
+
+The `cacheBuster` plugin is an essential tool for ensuring that assets are correctly updated when they change.
+When the `cacheBuster` plugin is added to the AssetPack configuration file, it generates unique hashes and appends them to file names.
+This process ensures that when assets are modified, the updated versions are correctly re-downloaded by the user's browser, bypassing any cached versions.
+
+## Example
+
+<ImageToggle image={'cache/cache-buster'} height={350} />
+
+To use the `cacheBuster` plugin, include it in your AssetPack pipeline.
+It's crucial to note that the order of plugins in the pipeline affects the final output. For optimal results,
+ensure that the `cacheBuster` transformation occurs at the correct stage in your pipeline.
+
+```ts
+// assetpack.config.ts
+import { cacheBuster } from "assetpack";
+
+export default {
+ ...
+ pipes: {
+ ...
+ // make sure these pipes are added after plugins that generate files
+ cacheBuster(),
+ },
+};
+```
+
+## Spine and Texture Packer
+
+When integrating with the [`texturePacker`](/docs/guides/pipes/texture-packer) plugin or your porject has spine atlas files,
+you need to add the `texturePackerCacheBuster` / `spineAtlasCacheBuster` pipes immediately after the `cacheBuster` pipe.
+
+The `texturePackerCacheBuster` ensures that the JSON files internally update their asset names to reflect the newly hashed file names.
+The `spineAtlasCacheBuster` pipe performs a similar function for spine atlas files.
+
+### Example
+
+```ts
+// assetpack.config.ts
+import { cacheBuster, texturePackerCacheBuster, spineAtlasCacheBuster } from "assetpack";
+
+export default {
+ ...
+ pipes: {
+ ...
+ // make sure these pipes are added after plugins that generate files
+ cacheBuster(),
+ texturePackerCacheBuster(),
+ spineAtlasCacheBuster(),
+ },
+};
+```

packages/docs/docs/guide/pipes/ffmpeg.mdx

@@ -0,0 +1,79 @@
+---
+sidebar_position: 2
+---
+
+import { ImageToggle } from '@site/src/components/ImageToggle';
+
+# Audio & FFmpeg
+
+The AssetPack library includes powerful plugins for audio conversion and file format manipulation using FFmpeg. These plugins, audio and ffmpeg, provide robust solutions for handling a variety of media file formats.
+
+## Audio
+
+The audio plugin converts and compresses audio files (`mp3`, `wav`, and `ogg`) to `mp3` and `ogg` formats. This is particularly useful for ensuring compatibility and optimizing file sizes for web delivery.
+
+### Example
+
+<ImageToggle image={'audio/audio'} height={350} />
+
+```ts
+// assetpack.config.ts
+import { audio } from "assetpack";
+
+export default {
+ ...
+ pipes: [
+ audio: audio(),
+ ],
+};
+```
+
+## FFmpeg
+
+The `ffmpeg` plugin exposes the full FFmpeg API, allowing for the conversion of any file type to any other file type. This provides a high level of customization and control over the conversion process, enabling a wide range of media processing tasks.
+
+## API
+
+The plugin takes an input array of file extensions and produces an output based on the options.
+
+- `inputs`: An array of file extensions to be processed.
+- `outputs`: An array of objects containing the output formats and options for each format.
+ - `formats`: An array of file extensions to be output.
+ - `recompress`: A boolean value indicating whether the input file should be compressed if the output format is the same as the input format.
+ - `options`: An object containing the FFmpeg options for the output file.
+
+### Example
+
+```ts
+// assetpack.config.ts
+import { ffmpeg } from "assetpack";
+
+export default {
+ ...
+ pipes: [
+ ffmpeg({
+ inputs: ['.mp3', '.ogg', '.wav'],
+ outputs: [
+ {
+ formats: ['.mp3'],
+ recompress: false,
+ options: {
+ audioBitrate: 96,
+ audioChannels: 1,
+ audioFrequency: 48000,
+ },
+ },
+ {
+ formats: ['.ogg'],
+ recompress: false,
+ options: {
+ audioBitrate: 32,
+ audioChannels: 1,
+ audioFrequency: 22050,
+ },
+ },
+ ],
+ }),
+ ],
+};
+```

packages/docs/src/components/ImageToggle.tsx

@@ -0,0 +1,138 @@
+import { useState } from 'react';
+
+export const Toggle = ({ toggleImage, showImage1 }) => (
+ <div style={{ width: '100%' }}>
+ <div
+ style={{
+ display: 'flex',
+ justifyContent: 'right',
+ alignItems: 'center',
+ width: '100%',
+ height: '100%',
+ padding: '10px',
+ }}
+ >
+ <p style={{ margin: '0 10px' }}>{showImage1 ? 'Original' : 'Processed'}</p>
+ <div
+ onClick={toggleImage}
+ style={{
+ position: 'relative',
+ width: '60px', // Width of the toggle
+ height: '30px', // Height of the toggle
+ backgroundColor: 'hsl(225 6% 13%)', // Background color of the toggle
+ borderRadius: '15px', // Makes it pill-shaped
+ cursor: 'pointer',
+ transition: 'background-color 0.3s',
+ border: '2px solid #696969', // Border color of the toggle
+ }}
+ >
+ <div
+ style={{
+ position: 'absolute',
+ top: '3px', // Small top margin to center vertically
+ left: showImage1 ? '5px' : '32px', // Moves the dot based on the toggle state
+ width: '20px', // Width of the dot
+ height: '20px', // Height of the dot
+ backgroundColor: showImage1 ? 'var(--ifm-color-secondary)' : 'var(--ifm-color-primary)', // Color of the dot
+ borderRadius: '50%', // Makes it circular
+ transition: 'left 0.3s', // Smooth transition for moving left and right
+ }}
+ />
+ </div>
+ </div>
+ </div>
+);
+
+export const ImageToggle = ({ image, height }) =>
+{
+ const [showImage1, setShowImage1] = useState(true);
+
+ const toggleImage = () =>
+ {
+ setShowImage1(!showImage1);
+ };
+
+ height ??= 600;
+ const image1 = `/assetpack/screenshots/${image}.png`;
+ const image2 = `/assetpack/screenshots/${image}-pro.png`;
+
+ return (
+ <div
+ style={{
+ display: 'flex',
+ flexDirection: 'column',
+ alignItems: 'center',
+ width: '100%',
+ paddingBottom: '20px',
+ }}
+ >
+ <Toggle toggleImage={toggleImage} showImage1={showImage1} />
+ <div style={{ position: 'relative', pointerEvents: 'none', width: '100%', height }}>
+ <div
+ style={{
+ transition: 'opacity 0.5s ease-in-out',
+ opacity: showImage1 ? 1 : 0,
+ position: 'absolute',
+ width: '100%',
+ height: '100%',
+ }}
+ >
+ <div
+ style={{
+ width: '100%',
+ height: '100%',
+ margin: '0 auto',
+ display: 'flex',
+ justifyContent: 'center',
+ alignItems: 'center',
+ position: 'absolute',
+ }}
+ >
+ <img
+ src={image1}
+ alt="Input Image"
+ style={{
+ maxWidth: '100%',
+ maxHeight: '100%',
+ objectFit: 'contain',
+ boxShadow: '0 0 20px rgba(0, 0, 0, 0.5)',
+ }}
+ />
+ </div>
+ </div>
+ <div
+ style={{
+ transition: 'opacity 0.5s ease-in-out',
+ opacity: showImage1 ? 0 : 1,
+ position: 'absolute',
+ width: '100%',
+ height: '100%',
+ }}
+ >
+ <div
+ style={{
+ width: '100%',
+ height: '100%',
+ margin: '0 auto',
+ display: 'flex',
+ justifyContent: 'center',
+ alignItems: 'center',
+ position: 'absolute',
+ }}
+ >
+ <img
+ src={image2}
+ alt="Processed Image"
+ style={{
+ maxWidth: '100%',
+ maxHeight: '100%',
+ objectFit: 'contain',
+ boxShadow: '0 0 20px rgba(0, 0, 0, 0.5)',
+ }}
+ />
+ </div>
+ </div>
+ </div>
+ </div>
+ );
+};