update docs

Author: muhammad-fiaz

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Muhammad Fiaz
+Copyright (c) 2026 Muhammad Fiaz
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

docs/.vitepress/config.mts

@@ -54,17 +54,17 @@ export default defineConfig({
     ["meta", { property: "og:url", content: SITE_URL }],
     ["meta", { property: "og:title", content: SITE_NAME }],
     ["meta", { property: "og:description", content: SITE_DESCRIPTION }],
-    ["meta", { property: "og:image", content: `${SITE_URL}/cover.png` }],
+    ["meta", { property: "og:image", content: `${SITE_URL}/loader-thumbnail.png` }],
     ["meta", { property: "og:image:width", content: "1200" }],
     ["meta", { property: "og:image:height", content: "630" }],
-    ["meta", { property: "og:image:alt", content: "loaders.zig - High-performance terminal loading indicators for Zig" }],
+    ["meta", { property: "og:image:alt", content: "loaders.zig - High-performance terminal loading indicators and progress bars for Zig" }],
     ["meta", { property: "og:site_name", content: SITE_NAME }],
     ["meta", { property: "og:locale", content: "en_US" }],
     ["meta", { name: "twitter:card", content: "summary_large_image" }],
     ["meta", { name: "twitter:url", content: SITE_URL }],
     ["meta", { name: "twitter:title", content: SITE_NAME }],
     ["meta", { name: "twitter:description", content: SITE_DESCRIPTION }],
-    ["meta", { name: "twitter:image", content: `${SITE_URL}/cover.png` }],
+    ["meta", { name: "twitter:image", content: `${SITE_URL}/loader-thumbnail.png` }],
     ["meta", { name: "twitter:creator", content: "@muhammadfiaz_" }],
 
     ["link", { rel: "icon", href: "/loaders.zig/favicon.ico" }],
@@ -164,6 +164,7 @@ gtag('config', '${GA_ID}');`,
       { text: "Home", link: "/" },
       { text: "Guide", link: "/guide/" },
       { text: "API", link: "/api/" },
+      { text: "Examples", link: "/examples/" },
     ],
 
     sidebar: [
@@ -172,6 +173,7 @@ gtag('config', '${GA_ID}');`,
         items: [
           { text: "Guide Overview", link: "/guide/" },
           { text: "API Reference", link: "/api/" },
+          { text: "Examples", link: "/examples/" },
         ],
       },
       {
@@ -187,6 +189,27 @@ gtag('config', '${GA_ID}');`,
           { text: "Advanced", link: "/guide/advanced" },
         ],
       },
+      {
+        text: "Examples",
+        items: [
+          { text: "Overview", link: "/examples/" },
+          { text: "Basic Bar", link: "/examples/01-basic-bar" },
+          { text: "Basic Bar (100)", link: "/examples/basic-bar" },
+          { text: "Styled Bar", link: "/examples/02-styled-bar" },
+          { text: "Custom Style", link: "/examples/custom-style" },
+          { text: "Themed Bar", link: "/examples/themed-bar" },
+          { text: "ETA and Rate", link: "/examples/eta-and-rate" },
+          { text: "Download Simulation", link: "/examples/download-simulation" },
+          { text: "Advanced Options", link: "/examples/advanced-options" },
+          { text: "Custom Template", link: "/examples/custom-template" },
+          { text: "Nested Bars", link: "/examples/nested-bars" },
+          { text: "Spinner", link: "/examples/spinner" },
+          { text: "Multi Spinner", link: "/examples/multi-spinner" },
+          { text: "Multi Progress", link: "/examples/multi-progress" },
+          { text: "Iterator Wrap", link: "/examples/iterator-wrap" },
+          { text: "Animations", link: "/examples/animations" },
+        ],
+      },
     ],
 
     socialLinks: [
@@ -195,7 +218,7 @@ gtag('config', '${GA_ID}');`,
 
     footer: {
       message: "Released under the MIT License.",
-      copyright: `Copyright © 2025-${new Date().getFullYear()} Muhammad Fiaz`,
+      copyright: `Copyright © 2026-${new Date().getFullYear()} Muhammad Fiaz`,
     },
 
     search: {
@@ -246,7 +269,7 @@ gtag('config', '${GA_ID}');`,
       ["meta", { name: "description", content: pageDescription }],
       ["meta", { name: "twitter:title", content: `${pageTitle} | ${SITE_NAME}` }],
       ["meta", { name: "twitter:description", content: pageDescription }],
-      ["meta", { name: "twitter:image", content: `${SITE_URL}/cover.png` }],
+      ["meta", { name: "twitter:image", content: `${SITE_URL}/loader-thumbnail.png` }],
     );
 
     if (pageData.frontmatter.description) {
@@ -294,7 +317,7 @@ gtag('config', '${GA_ID}');`,
       name: isHome ? SITE_NAME : pageTitle,
       description: pageDescription,
       url: canonicalUrl,
-      image: `${SITE_URL}/cover.png`,
+      image: `${SITE_URL}/loader-thumbnail.png`,
       author: authorSchema,
       publisher: {
         "@type": "Organization",
@@ -334,7 +357,7 @@ gtag('config', '${GA_ID}');`,
           "@type": "WebPage",
           "@id": canonicalUrl,
         },
-        datePublished: "2025-01-01T00:00:00Z",
+        datePublished: "2026-01-01T00:00:00Z",
         dateModified: lastUpdated,
       });
     }

docs/examples/01-basic-bar.md

@@ -0,0 +1,58 @@
+---
+description: Minimal progress bar example with loaders.zig. Create a 50-step bar with percentage display in under 20 lines.
+head:
+  - - meta
+    - name: keywords
+      content: loaders.zig basic progress bar, zig progress bar example, minimal loading bar
+  - - meta
+    - property: og:title
+      content: Basic Bar Example — loaders.zig
+  - - meta
+    - property: og:description
+      content: Minimal progress bar example with loaders.zig. Create a 50-step bar with percentage display.
+---
+
+# Basic Bar
+
+Minimal 50-step progress bar with percentage display.
+
+---
+
+## Source
+
+```zig
+const std = @import("std");
+const loaders = @import("loaders");
+
+pub fn main(init: std.process.Init) !void {
+    const io = init.io;
+    const total: usize = 50;
+
+    var bar = loaders.Bar.init(io, .{
+        .label = "Processing",
+        .total = total,
+        .show_percent = true,
+    });
+    defer bar.done();
+
+    for (0..total) |i| {
+        bar.setCompleted(i + 1);
+        bar.render();
+        try io.sleep(std.Io.Duration.fromMilliseconds(40), .awake);
+    }
+}
+```
+
+## Run
+
+```bash
+zig build run-01_basic_bar
+```
+
+## Output
+
+```
+Processing [██████████████████████████████████████████████████] 100%
+```
+
+The bar animates from 0% to 100%, overwriting the same line on each frame.

docs/examples/02-styled-bar.md

@@ -0,0 +1,78 @@
+---
+description: Side-by-side comparison of 7 built-in bar styles in loaders.zig. Block, ascii, shaded, green, cyan, gradient, and minimal.
+head:
+  - - meta
+    - name: keywords
+      content: loaders.zig bar styles comparison, zig bar presets, progress bar styles
+  - - meta
+    - property: og:title
+      content: Styled Bar Example — loaders.zig
+  - - meta
+    - property: og:description
+      content: Side-by-side comparison of 7 built-in bar styles.
+---
+
+# Styled Bar
+
+7 bar styles rendered side by side at 30 columns wide.
+
+---
+
+## Source
+
+```zig
+const std = @import("std");
+const loaders = @import("loaders");
+
+pub fn main(init: std.process.Init) !void {
+    const io = init.io;
+    const total: usize = 40;
+
+    const styles = [_]struct { name: []const u8, style: loaders.BarStyle }{
+        .{ .name = "block   ", .style = .{} },
+        .{ .name = "ascii   ", .style = .ascii },
+        .{ .name = "shaded  ", .style = .shaded },
+        .{ .name = "green   ", .style = .green },
+        .{ .name = "cyan    ", .style = .cyan },
+        .{ .name = "gradient", .style = .gradient },
+        .{ .name = "minimal ", .style = .minimal },
+    };
+
+    for (styles) |s| {
+        var bar = loaders.Bar.init(io, .{
+            .label = s.name,
+            .total = total,
+            .style = s.style,
+            .show_percent = true,
+            .width = 30,
+        });
+        defer bar.done();
+
+        for (0..total) |i| {
+            bar.setCompleted(i + 1);
+            bar.render();
+            try io.sleep(std.Io.Duration.fromMilliseconds(20), .awake);
+        }
+    }
+}
+```
+
+## Run
+
+```bash
+zig build run-02_styled_bar
+```
+
+## Output
+
+```
+block    [██████████████████████████████] 100%
+ascii    [##############################] 100%
+shaded   [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒] 100%
+green    [██████████████████████████████] 100%
+cyan     [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒] 100%
+gradient [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒] 100%
+minimal  ──────────────────────────────▶─ 100%
+```
+
+Each style renders at a fixed 30-column width for easy visual comparison.

docs/examples/advanced-options.md

@@ -0,0 +1,84 @@
+---
+description: Advanced progress customization with decorators, timestamps, colored labels, responsive width, and dynamic messages in loaders.zig.
+head:
+  - - meta
+    - name: keywords
+      content: loaders.zig advanced options, zig progress bar decorators, colored progress bar, zig timestamps
+  - - meta
+    - property: og:title
+      content: Advanced Options Example — loaders.zig
+  - - meta
+    - property: og:description
+      content: Advanced progress customization with decorators, timestamps, and colored labels.
+---
+
+# Advanced Options
+
+Custom decorators, timestamps, colored labels, responsive width, and dynamic messages.
+
+---
+
+## Source
+
+```zig
+const std = @import("std");
+const loaders = @import("loaders");
+
+pub fn main(init: std.process.Init) !void {
+    const io = init.io;
+
+    const total_steps = 100;
+
+    var bar = loaders.Bar.init(io, .{
+        .total = total_steps,
+        .label = "Processing",
+        .label_color = .bright_cyan,
+        .show_percent = true,
+        .percent_color = .bright_green,
+        .bracket_color = .bright_black,
+        .show_count = true,
+        .show_elapsed = true,
+        .show_eta = true,
+        .show_rate = true,
+        .message = "initializing...",
+        .complete_message = "Done! All steps complete.",
+
+        .custom_start = "🚀 ",
+        .custom_end = " [Task #1]",
+
+        .show_date = false,
+        .show_time = true,
+        .timezone_offset_sec = 19800,
+
+        .width = 0,
+        .style = loaders.BarStyle.gradient,
+    });
+    defer bar.done();
+
+    for (0..total_steps) |i| {
+        bar.setCompleted(i + 1);
+        bar.render();
+        try io.sleep(std.Io.Duration.fromMilliseconds(80), .awake);
+    }
+}
+```
+
+## Run
+
+```bash
+zig build run-advanced_options
+```
+
+## Output
+
+```
+🚀 [17:19:41] Processing [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100% 100/100 00:08 12.5/s initializing... [Task #1]
+🚀 [17:19:41] Processing [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100% 100/100 00:08 12.5/s Done! All steps complete. [Task #1]
+```
+
+Key features demonstrated:
+- `custom_start` / `custom_end` — line decorators
+- `show_time` + `timezone_offset_sec` — local time prefix
+- `label_color`, `percent_color`, `bracket_color` — per-element colors
+- `message` / `complete_message` — dynamic text before/after completion
+- `width = 0` — auto-resizes to terminal width