From 24852705c7f3410ed32232ace67b1ac49441be2a Mon Sep 17 00:00:00 2001 From: siddhi seth Date: Sun, 1 Mar 2026 21:10:40 +0530 Subject: [PATCH 1/3] docs: restructure README and move detailed guides to /docs --- README.md | 579 +----------------------------------- docs/callbacks.md | 13 + docs/customization.md | 148 +++++++++ docs/index.md | 24 ++ docs/installation-cdn.md | 8 + docs/installation-npm.md | 12 + docs/nextjs-app-router.md | 49 +++ docs/nextjs-pages-router.md | 45 +++ docs/react.md | 34 +++ docs/spa-dynamic-url.md | 19 ++ docs/troubleshooting.md | 46 +++ docs/vanilla-js.md | 21 ++ docs/vue-angular.md | 21 ++ 13 files changed, 455 insertions(+), 564 deletions(-) create mode 100644 docs/callbacks.md create mode 100644 docs/customization.md create mode 100644 docs/index.md create mode 100644 docs/installation-cdn.md create mode 100644 docs/installation-npm.md create mode 100644 docs/nextjs-app-router.md create mode 100644 docs/nextjs-pages-router.md create mode 100644 docs/react.md create mode 100644 docs/spa-dynamic-url.md create mode 100644 docs/troubleshooting.md create mode 100644 docs/vanilla-js.md create mode 100644 docs/vue-angular.md diff --git a/README.md b/README.md index 8345a7b..11423e8 100644 --- a/README.md +++ b/README.md @@ -53,11 +53,11 @@ Lightweight social sharing component for web applications. Zero dependencies, framework-agnostic. - [![npm version](https://img.shields.io/npm/v/social-share-button-aossie.svg)](https://www.npmjs.com/package/social-share-button-aossie) [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](LICENSE) --- + ## Features - 🌐 Multiple platforms: WhatsApp, Facebook, X, LinkedIn, Telegram, Reddit, Email @@ -79,584 +79,33 @@ Lightweight social sharing component for web applications. Zero dependencies, fr ``` ---- - -## Quick Start Guide - -> 🚫 **IMPORTANT:** Do NOT create new files like `ShareButton.jsx` or `ShareButton.tsx`! -> ✅ Add code directly to your **existing** component (Header, Navbar, etc.) - -
-📦 Create React App - -### Step 1: Add CDN to `public/index.html` - -```html - - - - -
- - -``` - -### Step 2: In your **existing** React component (e.g., `MainLayout.jsx`, `Header.jsx`, or wherever you want the button): - -```jsx -import { useEffect, useRef } from 'react'; - -function YourComponent() { // Use your actual component name (Header, Navbar, etc.) - const shareButtonRef = useRef(null); - const initRef = useRef(false); - - useEffect(() => { - if (initRef.current || !window.SocialShareButton) return; - - shareButtonRef.current = new window.SocialShareButton({ - container: '#share-button' - }); - initRef.current = true; - - return () => { - if (shareButtonRef.current?.destroy) { - shareButtonRef.current.destroy(); - } - initRef.current = false; - }; - }, []); - - return ( -
-
-
- ); -} -``` - -
- -
-▲ Next.js (App Router) - -### Step 1: Add CDN to `app/layout.tsx` - -```tsx -import Script from 'next/script'; - -export default function RootLayout({ children }: { children: React.ReactNode }) { - return ( - - - - - - {children} - - - - ); -} -``` - -### Step 2: In your **existing** component (e.g., `components/Header.tsx`, or wherever you want the button): - -```tsx -import { useEffect, useRef } from 'react'; - -export default function YourComponent() { // Use your actual component name - const shareButtonRef = useRef(null); - const containerRef = useRef(null); - const initRef = useRef(false); - - useEffect(() => { - const initButton = () => { - if (initRef.current || !window.SocialShareButton || !containerRef.current) return; - - shareButtonRef.current = new window.SocialShareButton({ - container: '#share-button' - }); - initRef.current = true; - }; - - if (window.SocialShareButton) { - initButton(); - } else { - const checkInterval = setInterval(() => { - if (window.SocialShareButton) { - clearInterval(checkInterval); - initButton(); - } - }, 100); - - return () => { - clearInterval(checkInterval); - if (shareButtonRef.current?.destroy) { - shareButtonRef.current.destroy(); - } - initRef.current = false; - }; - } - - return () => { - if (shareButtonRef.current?.destroy) { - shareButtonRef.current.destroy(); - } - initRef.current = false; - }; - }, []); - - return ( -
-
-
- ); -} - -declare global { - interface Window { - SocialShareButton: any; - } -} -``` - -
- -
-⚡ Vite / Vue / Angular - -### Step 1: Add CDN to `index.html` - -```html - - - - -
- - -``` - -### Step 2: Initialize in component - -```javascript -new window.SocialShareButton({ - container: '#share-button' -}); -``` - -
- ---- - -## Configuration - -### Basic Options - -```jsx -new SocialShareButton({ - container: '#share-button', // Required: CSS selector or DOM element - url: 'https://example.com', // Optional: defaults to window.location.href - title: 'Custom Title', // Optional: defaults to document.title - buttonText: 'Share', // Optional: button label text - buttonStyle: 'primary', // default | primary | compact | icon-only - theme: 'dark', // dark | light - platforms: ['twitter', 'linkedin'] // Optional: defaults to all platforms -}); -``` - -### All Available Options - -| Option | Type | Default | Description | -|--------|------|---------|-------------| -| `container` | string/Element | - | **Required.** CSS selector or DOM element | -| `url` | string | `window.location.href` | URL to share | -| `title` | string | `document.title` | Share title/headline | -| `description` | string | `''` | Additional description text | -| `hashtags` | array | `[]` | Hashtags for posts (e.g., `['js', 'webdev']`) | -| `via` | string | `''` | Twitter handle (without @) | -| `platforms` | array | All platforms | Platforms to show (see below) | -| `buttonText` | string | `'Share'` | Button label text | -| `buttonStyle` | string | `'default'` | `default`, `primary`, `compact`, `icon-only` | -| `buttonColor` | string | `''` | Custom button background color | -| `buttonHoverColor` | string | `''` | Custom button hover color | -| `customClass` | string | `''` | Additional CSS class for button | -| `theme` | string | `'dark'` | `dark` or `light` | -| `modalPosition` | string | `'center'` | Modal position on screen | -| `showButton` | boolean | `true` | Show/hide the share button | -| `onShare` | function | `null` | Callback when user shares: `(platform, url) => {}` | -| `onCopy` | function | `null` | Callback when user copies link: `(url) => {}` | - -**Available Platforms:** -`whatsapp`, `facebook`, `twitter`, `linkedin`, `telegram`, `reddit`, `email` - -### Customize Share Message/Post Text - -Control the text that appears when users share to social platforms: - -```jsx -new SocialShareButton({ - container: '#share-button', - url: 'https://myproject.com', - title: 'Check out my awesome project!', // Main title/headline - description: 'An amazing tool for developers', // Additional description - hashtags: ['javascript', 'webdev', 'opensource'], // Hashtags included in posts - via: 'MyProjectHandle' // Your Twitter handle -}); -``` - -**How messages are customized per platform:** -- **WhatsApp:** `title` + `description` + `hashtags` + link -- **Facebook:** `title` + `description` + `hashtags` + link -- **Twitter/X:** `title` + `description` + `hashtags` + `via` handle + link -- **Telegram:** `title` + `description` + `hashtags` + link -- **LinkedIn:** `title` + `description` + link -- **Reddit:** `title` - `description` (used as title) -- **Email:** Subject = `title`, Body = `description` + link - -### Customize Button Color & Appearance - -**Option 1: Use Pre-built Styles** (Easiest) - -```jsx -new SocialShareButton({ - container: '#share-button', - buttonStyle: 'primary' // or 'default', 'compact', 'icon-only' -}); -``` - -**Option 2: Programmatic Color Customization** (Recommended) - -Pass `buttonColor` and `buttonHoverColor` to match your project's color scheme: - -```jsx -new SocialShareButton({ - container: '#share-button', - buttonColor: '#ff6b6b', // Button background color - buttonHoverColor: '#ff5252' // Hover state color -}); -``` - -**Option 3: CSS Class Customization** (Advanced) - -For more complex styling, use a custom CSS class: - -```jsx -new SocialShareButton({ - container: '#share-button', - buttonStyle: 'primary', - customClass: 'my-custom-button' -}); -``` - -Then in your CSS file: - -```css -/* Override the button background color */ -.my-custom-button.social-share-btn { - background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); - color: white; -} - -/* Customize hover state */ -.my-custom-button.social-share-btn:hover { - background: linear-gradient(135deg, #764ba2 0%, #667eea 100%); -} -``` - -**Color Examples:** - -```jsx -// Material Design Red -new SocialShareButton({ - container: '#share-button', - buttonColor: '#f44336', - buttonHoverColor: '#da190b' -}); - -// Tailwind Blue -new SocialShareButton({ - container: '#share-button', - buttonColor: '#3b82f6', - buttonHoverColor: '#2563eb' -}); - -// Custom Brand Color -new SocialShareButton({ - container: '#share-button', - buttonColor: '#your-brand-color', - buttonHoverColor: '#your-brand-color-dark' -}); -``` - -### Button Styles +### Via npm -| Style | Description | -|-------|-------------| -| `default` | Standard button with icon and text | -| `primary` | Gradient button (recommended) | -| `compact` | Smaller size for tight spaces | -| `icon-only` | Icon without text | - -### Callbacks - -```jsx -new SocialShareButton({ - container: '#share-button', - onShare: (platform, url) => { - console.log(`Shared on ${platform}: ${url}`); - }, - onCopy: (url) => { - console.log('Link copied:', url); - } -}); +```bash +npm install social-share-button-aossie ``` --- -## Advanced Usage - -### Using npm Package +## Quick Start ```javascript -import SocialShareButton from 'social-share-button-aossie'; -import 'social-share-button-aossie/src/social-share-button.css'; - new SocialShareButton({ container: '#share-button' }); ``` -### React Wrapper Component (Optional) - -If you want a reusable React component, copy `src/social-share-button-react.jsx` to your project: - -```jsx -import { SocialShareButton } from './components/SocialShareButton'; - -function App() { - return ; -} -``` - -### Update URL Dynamically (SPA) - -```jsx -const shareButton = useRef(null); - -useEffect(() => { - shareButton.current = new window.SocialShareButton({ - container: '#share-button' - }); -}, []); - -useEffect(() => { - if (shareButton.current) { - shareButton.current.updateOptions({ - url: window.location.href - }); - } -}, [pathname]); // Update on route change -``` - ---- - -## Troubleshooting - -
-Multiple buttons appearing - -**Cause:** Component re-renders creating duplicate instances - -**Solution:** Use `useRef` to track initialization (already in examples above) - -
- -
-Button not appearing - -**Cause:** Script loads after component renders - -**Solution:** Add null check: -```jsx -if (window.SocialShareButton) { - new window.SocialShareButton({ container: '#share-button' }); -} -``` - -
+Add this HTML element: -
-Modal not opening - -**Cause:** CSS not loaded or ID mismatch - -**Solution:** -- Verify CSS CDN link in `` -- Match container ID: `container: '#share-button'` = `
` - -
- -
-TypeError: SocialShareButton is not a constructor - -**Cause:** CDN script not loaded yet - -**Solution:** Use interval polling (see Next.js example above) - -
- -
-URL not updating on navigation - -**Cause:** Component initialized once, doesn't track routes - -**Solution:** Use `updateOptions()` method (see Advanced Usage above) - -
- ---- - -## Examples - -### Mobile Menu - -```jsx - -``` - -### Custom Platforms - -```jsx -// Professional networks only -new SocialShareButton({ - container: '#share-button', - platforms: ['linkedin', 'twitter', 'email'] -}); - -// Messaging apps only -new SocialShareButton({ - container: '#share-button', - platforms: ['whatsapp', 'telegram'] -}); -``` - -### Custom Styling - -```jsx -new SocialShareButton({ - container: '#share-button', - buttonStyle: 'icon-only', - theme: 'light' -}); +```html +
``` --- -## Demo +## Full Documentation -Open `index.html` in your browser to see all features. -Tutorial: https://youtu.be/cLJaT-8rEvQ?si=CLipA0Db4WL0EqKM +For framework-specific guides, configuration options, customization, and troubleshooting, visit the complete documentation in the [`/docs` directory](./docs/index.md). --- @@ -677,7 +126,9 @@ If you encounter bugs, need help, or have feature requests: We appreciate your feedback and contributions! -This project is licensed under the GNU General Public License v3.0. -See the [LICENSE](LICENSE) file for details. - --- + +## License + +This project is licensed under the GNU General Public License v3.0. +See the [LICENSE](LICENSE) file for details. \ No newline at end of file diff --git a/docs/callbacks.md b/docs/callbacks.md new file mode 100644 index 0000000..4eef912 --- /dev/null +++ b/docs/callbacks.md @@ -0,0 +1,13 @@ +# Callbacks + +```jsx +new SocialShareButton({ + container: '#share-button', + onShare: (platform, url) => { + console.log(`Shared on ${platform}: ${url}`); + }, + onCopy: (url) => { + console.log('Link copied:', url); + } +}); +``` \ No newline at end of file diff --git a/docs/customization.md b/docs/customization.md new file mode 100644 index 0000000..6fd2d59 --- /dev/null +++ b/docs/customization.md @@ -0,0 +1,148 @@ +# Customization & Configuration + +## Basic Options + +```jsx +new SocialShareButton({ + container: '#share-button', // Required: CSS selector or DOM element + url: 'https://example.com', // Optional: defaults to window.location.href + title: 'Custom Title', // Optional: defaults to document.title + buttonText: 'Share', // Optional: button label text + buttonStyle: 'primary', // default | primary | compact | icon-only + theme: 'dark', // dark | light + platforms: ['twitter', 'linkedin'] // Optional: defaults to all platforms +}); +``` + +## All Available Options + +| Option | Type | Default | Description | +|--------|------|---------|-------------| +| `container` | string/Element | - | **Required.** CSS selector or DOM element | +| `url` | string | `window.location.href` | URL to share | +| `title` | string | `document.title` | Share title/headline | +| `description` | string | `''` | Additional description text | +| `hashtags` | array | `[]` | Hashtags for posts (e.g., `['js', 'webdev']`) | +| `via` | string | `''` | Twitter handle (without @) | +| `platforms` | array | All platforms | Platforms to show (see below) | +| `buttonText` | string | `'Share'` | Button label text | +| `buttonStyle` | string | `'default'` | `default`, `primary`, `compact`, `icon-only` | +| `buttonColor` | string | `''` | Custom button background color | +| `buttonHoverColor` | string | `''` | Custom button hover color | +| `customClass` | string | `''` | Additional CSS class for button | +| `theme` | string | `'dark'` | `dark` or `light` | +| `modalPosition` | string | `'center'` | Modal position on screen | +| `showButton` | boolean | `true` | Show/hide the share button | +| `onShare` | function | `null` | Callback when user shares: `(platform, url) => {}` | +| `onCopy` | function | `null` | Callback when user copies link: `(url) => {}` | + +**Available Platforms:** +`whatsapp`, `facebook`, `twitter`, `linkedin`, `telegram`, `reddit`, `email` + +## Customize Share Message/Post Text + +Control the text that appears when users share to social platforms: + +```jsx +new SocialShareButton({ + container: '#share-button', + url: 'https://myproject.com', + title: 'Check out my awesome project!', // Main title/headline + description: 'An amazing tool for developers', // Additional description + hashtags: ['javascript', 'webdev', 'opensource'], // Hashtags included in posts + via: 'MyProjectHandle' // Your Twitter handle +}); +``` + +**How messages are customized per platform:** +- **WhatsApp:** `title` + `description` + `hashtags` + link +- **Facebook:** `title` + `description` + `hashtags` + link +- **Twitter/X:** `title` + `description` + `hashtags` + `via` handle + link +- **Telegram:** `title` + `description` + `hashtags` + link +- **LinkedIn:** `title` + `description` + link +- **Reddit:** `title` - `description` (used as title) +- **Email:** Subject = `title`, Body = `description` + link + +## Customize Button Color & Appearance + +**Option 1: Use Pre-built Styles** (Easiest) + +```jsx +new SocialShareButton({ + container: '#share-button', + buttonStyle: 'primary' // or 'default', 'compact', 'icon-only' +}); +``` + +**Option 2: Programmatic Color Customization** (Recommended) + +Pass `buttonColor` and `buttonHoverColor` to match your project's color scheme: + +```jsx +new SocialShareButton({ + container: '#share-button', + buttonColor: '#ff6b6b', // Button background color + buttonHoverColor: '#ff5252' // Hover state color +}); +``` + +**Option 3: CSS Class Customization** (Advanced) + +For more complex styling, use a custom CSS class: + +```jsx +new SocialShareButton({ + container: '#share-button', + buttonStyle: 'primary', + customClass: 'my-custom-button' +}); +``` + +Then in your CSS file: + +```css +/* Override the button background color */ +.my-custom-button.social-share-btn { + background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); + color: white; +} + +/* Customize hover state */ +.my-custom-button.social-share-btn:hover { + background: linear-gradient(135deg, #764ba2 0%, #667eea 100%); +} +``` + +**Color Examples:** + +```jsx +// Material Design Red +new SocialShareButton({ + container: '#share-button', + buttonColor: '#f44336', + buttonHoverColor: '#da190b' +}); + +// Tailwind Blue +new SocialShareButton({ + container: '#share-button', + buttonColor: '#3b82f6', + buttonHoverColor: '#2563eb' +}); + +// Custom Brand Color +new SocialShareButton({ + container: '#share-button', + buttonColor: '#your-brand-color', + buttonHoverColor: '#your-brand-color-dark' +}); +``` + +## Button Styles + +| Style | Description | +|-------|-------------| +| `default` | Standard button with icon and text | +| `primary` | Gradient button (recommended) | +| `compact` | Smaller size for tight spaces | +| `icon-only` | Icon without text | diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..d5a1051 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,24 @@ +# 📚 Documentation + +## Installation + +- [Installation via CDN](./installation-cdn.md) +- [Installation via npm](./installation-npm.md) + +## Framework Guides + +- [Vanilla JavaScript](./vanilla-js.md) +- [React](./react.md) +- [Next.js (App Router)](./nextjs-app-router.md) +- [Next.js (Pages Router)](./nextjs-pages-router.md) +- [Vue / Angular / Vite](./vue-angular.md) + +## Configuration & Customization + +- [Customization & Configuration](./customization.md) +- [Callbacks](./callbacks.md) +- [Dynamic URL Updates (SPA)](./spa-dynamic-url.md) + +## Troubleshooting + +- [Troubleshooting Guide](./troubleshooting.md) \ No newline at end of file diff --git a/docs/installation-cdn.md b/docs/installation-cdn.md new file mode 100644 index 0000000..cec6426 --- /dev/null +++ b/docs/installation-cdn.md @@ -0,0 +1,8 @@ +# Installation via CDN + +### Via CDN (Recommended) + +```html + + +``` \ No newline at end of file diff --git a/docs/installation-npm.md b/docs/installation-npm.md new file mode 100644 index 0000000..47fc86e --- /dev/null +++ b/docs/installation-npm.md @@ -0,0 +1,12 @@ +# Installation via npm + +### Using npm Package + +```javascript +import SocialShareButton from 'social-share-button-aossie'; +import 'social-share-button-aossie/src/social-share-button.css'; + +new SocialShareButton({ + container: '#share-button' +}); +``` diff --git a/docs/nextjs-app-router.md b/docs/nextjs-app-router.md new file mode 100644 index 0000000..5861d77 --- /dev/null +++ b/docs/nextjs-app-router.md @@ -0,0 +1,49 @@ +# Next.js (App Router) + +### Step 1: Add CDN to `app/layout.tsx` + +```tsx +import Script from 'next/script'; + +export default function RootLayout({ children }: { children: React.ReactNode }) { + return ( + + + + + + {children} + + + + ); +} +``` + +### Step 2: In your component: + +```tsx +import { useEffect } from 'react'; + +export default function Header() { + useEffect(() => { + new window.SocialShareButton({ + container: '#share-button' + }); + }, []); + + return ( +
+
+
+ ); +} +``` diff --git a/docs/react.md b/docs/react.md new file mode 100644 index 0000000..a6ccf71 --- /dev/null +++ b/docs/react.md @@ -0,0 +1,34 @@ +# React (Create React App) + +### Step 1: Add CDN to `public/index.html` + +```html + + + + +
+ + +``` + +### Step 2: In your component: + +```jsx +import { useEffect } from 'react'; + +function Header() { + useEffect(() => { + new window.SocialShareButton({ + container: '#share-button' + }); + }, []); + + return ( +
+
+
+ ); +} + +export default Header; diff --git a/docs/spa-dynamic-url.md b/docs/spa-dynamic-url.md new file mode 100644 index 0000000..4628d34 --- /dev/null +++ b/docs/spa-dynamic-url.md @@ -0,0 +1,19 @@ +# Update URL Dynamically (SPA) + +```jsx +const shareButton = useRef(null); + +useEffect(() => { + shareButton.current = new window.SocialShareButton({ + container: '#share-button' + }); +}, []); + +useEffect(() => { + if (shareButton.current) { + shareButton.current.updateOptions({ + url: window.location.href + }); + } +}, [pathname]); // Update on route change +``` diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 0000000..8a35dc5 --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,46 @@ +# Troubleshooting + +## Multiple buttons appearing + +**Cause:** Component re-renders creating duplicate instances + +**Solution:** Use `useRef` to track initialization (already in examples above) + +--- + +## Button not appearing + +**Cause:** Script loads after component renders + +**Solution:** Add null check: +```jsx +if (window.SocialShareButton) { + new window.SocialShareButton({ container: '#share-button' }); +} +``` + +--- + +## Modal not opening + +**Cause:** CSS not loaded or ID mismatch + +**Solution:** +- Verify CSS CDN link in `` +- Match container ID: `container: '#share-button'` = `
` + +--- + +## TypeError: SocialShareButton is not a constructor + +**Cause:** CDN script not loaded yet + +**Solution:** Use interval polling (see Next.js example above) + +--- + +## URL not updating on navigation + +**Cause:** Component initialized once, doesn't track routes + +**Solution:** Use `updateOptions()` method (see Advanced Usage above) diff --git a/docs/vanilla-js.md b/docs/vanilla-js.md new file mode 100644 index 0000000..81d78ee --- /dev/null +++ b/docs/vanilla-js.md @@ -0,0 +1,21 @@ +# Vanilla JavaScript + +### Step 1: Add CDN to `index.html` + +```html + + + + +
+ + +``` + +### Step 2: Initialize in component + +```javascript +new window.SocialShareButton({ + container: '#share-button' +}); +``` diff --git a/docs/vue-angular.md b/docs/vue-angular.md new file mode 100644 index 0000000..f3653d5 --- /dev/null +++ b/docs/vue-angular.md @@ -0,0 +1,21 @@ +# Vue / Angular / Vite + +### Step 1: Add CDN to `index.html` + +```html + + + + +
+ + +``` + +### Step 2: Initialize in component + +```javascript +new window.SocialShareButton({ + container: '#share-button' +}); +``` From 40ac883f03c4b9d9c40fdddcc7467a1b2bf8b84d Mon Sep 17 00:00:00 2001 From: siddhi seth Date: Sun, 1 Mar 2026 21:42:43 +0530 Subject: [PATCH 2/3] docs: fix heading hierarchy and example inconsistencies --- docs/installation-cdn.md | 2 +- docs/installation-npm.md | 2 +- docs/nextjs-app-router.md | 4 ++-- docs/nextjs-pages-router.md | 4 ++-- docs/react.md | 4 ++-- docs/spa-dynamic-url.md | 6 ++++++ docs/troubleshooting.md | 4 ++-- docs/vanilla-js.md | 6 +++--- docs/vue-angular.md | 4 ++-- 9 files changed, 21 insertions(+), 15 deletions(-) diff --git a/docs/installation-cdn.md b/docs/installation-cdn.md index cec6426..0eeb847 100644 --- a/docs/installation-cdn.md +++ b/docs/installation-cdn.md @@ -1,6 +1,6 @@ # Installation via CDN -### Via CDN (Recommended) +## Via CDN (Recommended) ```html diff --git a/docs/installation-npm.md b/docs/installation-npm.md index 47fc86e..343c3fa 100644 --- a/docs/installation-npm.md +++ b/docs/installation-npm.md @@ -1,6 +1,6 @@ # Installation via npm -### Using npm Package +## Using npm Package ```javascript import SocialShareButton from 'social-share-button-aossie'; diff --git a/docs/nextjs-app-router.md b/docs/nextjs-app-router.md index 5861d77..91d5116 100644 --- a/docs/nextjs-app-router.md +++ b/docs/nextjs-app-router.md @@ -1,6 +1,6 @@ # Next.js (App Router) -### Step 1: Add CDN to `app/layout.tsx` +## Step 1: Add CDN to `app/layout.tsx` ```tsx import Script from 'next/script'; @@ -26,7 +26,7 @@ export default function RootLayout({ children }: { children: React.ReactNode }) } ``` -### Step 2: In your component: +## Step 2: In your component: ```tsx 'use client'; diff --git a/docs/nextjs-pages-router.md b/docs/nextjs-pages-router.md index 10e3432..2eba90f 100644 --- a/docs/nextjs-pages-router.md +++ b/docs/nextjs-pages-router.md @@ -1,6 +1,6 @@ # Next.js (Pages Router) -### Step 1: Add CDN to `pages/_document.tsx` +## Step 1: Add CDN to `pages/_document.tsx` ```tsx import { Html, Head, Main, NextScript } from 'next/document'; @@ -24,7 +24,7 @@ export default function Document() { } ``` -### Step 2: In your component: +## Step 2: In your component: ```tsx import { useEffect } from 'react'; diff --git a/docs/react.md b/docs/react.md index a6ccf71..9e50198 100644 --- a/docs/react.md +++ b/docs/react.md @@ -1,6 +1,6 @@ # React (Create React App) -### Step 1: Add CDN to `public/index.html` +## Step 1: Add CDN to `public/index.html` ```html @@ -12,7 +12,7 @@ ``` -### Step 2: In your component: +## Step 2: In your component: ```jsx import { useEffect } from 'react'; diff --git a/docs/spa-dynamic-url.md b/docs/spa-dynamic-url.md index 4628d34..19433e8 100644 --- a/docs/spa-dynamic-url.md +++ b/docs/spa-dynamic-url.md @@ -1,5 +1,11 @@ # Update URL Dynamically (SPA) +**Note:** This example requires obtaining the `pathname` variable from your router. The approach depends on your framework: + +- **Next.js (App Router):** `import { usePathname } from 'next/navigation'; const pathname = usePathname();` +- **React Router:** `import { useLocation } from 'react-router-dom'; const { pathname } = useLocation();` +- **Other frameworks:** Use your framework's routing hook to access the current path + ```jsx const shareButton = useRef(null); diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 8a35dc5..7408d15 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -35,7 +35,7 @@ if (window.SocialShareButton) { **Cause:** CDN script not loaded yet -**Solution:** Use interval polling (see Next.js example above) +**Solution:** Use interval polling or check if it's available before initializing (see your framework guide) --- @@ -43,4 +43,4 @@ if (window.SocialShareButton) { **Cause:** Component initialized once, doesn't track routes -**Solution:** Use `updateOptions()` method (see Advanced Usage above) +**Solution:** Use `updateOptions()` method (see [Dynamic URL Updates (SPA)](./spa-dynamic-url.md)) diff --git a/docs/vanilla-js.md b/docs/vanilla-js.md index 81d78ee..773ff6e 100644 --- a/docs/vanilla-js.md +++ b/docs/vanilla-js.md @@ -1,18 +1,18 @@ # Vanilla JavaScript -### Step 1: Add CDN to `index.html` +## Step 1: Add CDN to `index.html` ```html -
+
``` -### Step 2: Initialize in component +## Step 2: Initialize in component ```javascript new window.SocialShareButton({ diff --git a/docs/vue-angular.md b/docs/vue-angular.md index f3653d5..0ae02d4 100644 --- a/docs/vue-angular.md +++ b/docs/vue-angular.md @@ -1,6 +1,6 @@ # Vue / Angular / Vite -### Step 1: Add CDN to `index.html` +## Step 1: Add CDN to `index.html` ```html @@ -12,7 +12,7 @@ ``` -### Step 2: Initialize in component +## Step 2: Initialize in component ```javascript new window.SocialShareButton({ From 914a622a39b71385374ad3d18647b3ab68a86d65 Mon Sep 17 00:00:00 2001 From: siddhi seth Date: Mon, 2 Mar 2026 12:12:24 +0530 Subject: [PATCH 3/3] docs: enhance README with demo, docs links, and improved onboarding --- README.md | 34 +++++++++++++++++++++++++++++++--- docs/vue-angular.md | 2 +- 2 files changed, 32 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 11423e8..149263a 100644 --- a/README.md +++ b/README.md @@ -103,13 +103,41 @@ Add this HTML element: --- -## Full Documentation +## 📚 Documentation & Getting Started -For framework-specific guides, configuration options, customization, and troubleshooting, visit the complete documentation in the [`/docs` directory](./docs/index.md). +Choose your framework and start sharing in minutes — no dependencies, no setup friction. + +**Start here if you're new to SocialShareButton:** + +### Installation Guides +- [CDN Setup](./docs/installation-cdn.md) - Fastest way to get started +- [npm Package](./docs/installation-npm.md) - For build-based workflows + +### Framework Guides +- [Vanilla JavaScript](./docs/vanilla-js.md) – Zero-build, script-tag usage +- [React](./docs/react.md) – Create React App & React projects +- [Next.js (App Router)](./docs/nextjs-app-router.md) – Recommended for new Next.js apps +- [Next.js (Pages Router)](./docs/nextjs-pages-router.md) – Legacy Next.js support +- [Vue / Angular / Vite](./docs/vue-angular.md) – Framework-agnostic setup + +### Customize & Configure +- [Configuration Options](./docs/customization.md) - Colors, styles, button variants, and messaging +- [Callbacks](./docs/callbacks.md) - Track share events in your app +- [Dynamic URLs (SPA)](./docs/spa-dynamic-url.md) - Update share URL on route changes + +### Help & Support +- [Troubleshooting](./docs/troubleshooting.md) - Common issues and solutions +- [View all docs](./docs/index.md) - Complete documentation index --- -## Contributing +## 🎬 Demo + +See SocialShareButton in action! Open `index.html` in your browser to explore all features. + +📺 **Video Tutorial:** [Watch on YouTube](https://youtu.be/cLJaT-8rEvQ?si=CLipA0Db4WL0EqKM) + +--- We welcome contributions of all kinds! To contribute: diff --git a/docs/vue-angular.md b/docs/vue-angular.md index 0ae02d4..6a0bd97 100644 --- a/docs/vue-angular.md +++ b/docs/vue-angular.md @@ -7,7 +7,7 @@ -
+
```