From d4887fcdddd79c20d0aa53cb650f699e1a17dfcd Mon Sep 17 00:00:00 2001
From: rishichawda <rishichawda@users.noreply.github.com>
Date: Fri, 10 Oct 2025 18:49:35 +0530
Subject: [PATCH] update documentation

Signed-off-by: rishichawda <rishichawda@users.noreply.github.com>
---
 docs/docs/api/overview.md                     | 354 ++++++++++
 docs/docs/customization/styling.md            | 648 ++++++++++++++++++
 docs/docs/examples/note-types.mdx             | 393 +++++++++--
 docs/docs/guides/frameworks.md                | 516 ++++++++++++++
 docs/docs/guides/troubleshooting.md           | 564 +++++++++++++++
 docs/docs/intro.md                            | 235 ++++++-
 docs/docusaurus.config.ts                     | 120 +++-
 docs/sidebars.ts                              |  35 +-
 .../src/components/HomepageFeatures/index.tsx | 104 ++-
 .../HomepageFeatures/styles.module.css        | 144 +++-
 docs/src/css/custom.css                       | 325 +++++++--
 docs/src/pages/index.module.css               | 265 ++++++-
 docs/src/pages/index.tsx                      | 184 ++++-
 13 files changed, 3684 insertions(+), 203 deletions(-)
 create mode 100644 docs/docs/api/overview.md
 create mode 100644 docs/docs/customization/styling.md
 create mode 100644 docs/docs/guides/frameworks.md
 create mode 100644 docs/docs/guides/troubleshooting.md

diff --git a/docs/docs/api/overview.md b/docs/docs/api/overview.md
new file mode 100644
index 0000000..563cac2
--- /dev/null
+++ b/docs/docs/api/overview.md
@@ -0,0 +1,354 @@
+---
+sidebar_position: 1
+---
+
+# API Reference
+
+Complete TypeScript API reference for `remark-notes-plugin`.
+
+## Plugin Function
+
+### `remarkNotes(options?)`
+
+The main plugin function that transforms markdown blockquotes into styled note elements.
+
+**Type Signature:**
+
+```typescript
+function remarkNotes(options?: RemarkNotesOptions): (tree: Node) => void
+```
+
+**Parameters:**
+
+- `options` (optional): Configuration object of type `RemarkNotesOptions`
+
+**Returns:**
+
+A transformer function that processes the AST (Abstract Syntax Tree).
+
+**Example:**
+
+```typescript
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkNotes from 'remark-notes-plugin';
+import remarkRehype from 'remark-rehype';
+import rehypeStringify from 'rehype-stringify';
+
+const processor = unified()
+  .use(remarkParse)
+  .use(remarkNotes, { classPrefix: 'custom' })
+  .use(remarkRehype)
+  .use(rehypeStringify);
+
+const result = await processor.process('> [!note]\n> This is a note');
+```
+
+## Configuration Options
+
+### `RemarkNotesOptions`
+
+Configuration interface for the plugin.
+
+```typescript
+interface RemarkNotesOptions {
+  classPrefix?: string;
+  injectStyles?: boolean;
+}
+```
+
+#### `classPrefix`
+
+Custom prefix for all generated CSS class names.
+
+- **Type:** `string`
+- **Default:** `''` (empty string - no prefix)
+- **Optional:** Yes
+
+The prefix is **prepended** to the standard `remark-note` class names.
+
+**Default behavior (no prefix):**
+```html
+<blockquote class="remark-note remark-note-tip">
+  <div class="remark-note-header">
+    <span class="remark-note-icon">...</span>
+    <span class="remark-note-title">tip</span>
+  </div>
+  <div class="remark-note-content">...</div>
+</blockquote>
+```
+
+**With prefix (e.g., `'my'`):**
+```html
+<blockquote class="my-remark-note my-remark-note-tip">
+  <div class="my-remark-note-header">
+    <span class="my-remark-note-icon">...</span>
+    <span class="my-remark-note-title">tip</span>
+  </div>
+  <div class="my-remark-note-content">...</div>
+</blockquote>
+```
+
+**Example:**
+
+```typescript
+unified().use(remarkNotes, { classPrefix: 'docs' });
+// Generates: docs-remark-note, docs-remark-note-tip, etc.
+```
+
+> [!note]
+> The shipped CSS uses attribute selectors (e.g., `[class*="remark-note-icon"]`) and will work automatically with any prefix.
+
+#### `injectStyles`
+
+Controls whether the plugin automatically injects styles into the document.
+
+- **Type:** `boolean`
+- **Default:** `true`
+- **Optional:** Yes
+
+When `true`, the plugin injects a `<style>` tag containing note styles directly into the AST. When `false`, you must manually import the CSS file.
+
+**When to set to `false`:**
+
+- Using Server-Side Rendering (SSR) with separate CSS extraction
+- Building with tools that handle CSS imports separately (Vite, Webpack, etc.)
+- Providing completely custom styles
+- You want more control over style loading order
+
+**Example:**
+
+```typescript
+// Automatic style injection (default)
+unified().use(remarkNotes);
+
+// Manual CSS import required
+unified().use(remarkNotes, { injectStyles: false });
+// Then in your code:
+import 'remark-notes-plugin/styles.css';
+```
+
+## Types
+
+### `ValidNoteType`
+
+Union type of all valid note type strings.
+
+```typescript
+type ValidNoteType = 'note' | 'tip' | 'important' | 'quote' | 'bonus';
+```
+
+**Valid note types:**
+
+- `note` - General informational notes
+- `tip` - Helpful suggestions and advice
+- `important` - Critical information requiring attention
+- `quote` - Styled quote blocks
+- `bonus` - Additional information or advanced features
+
+**Usage in Markdown:**
+
+```markdown
+> [!note]
+> General information
+
+> [!tip]
+> Helpful advice
+
+> [!important]
+> Critical information
+
+> [!quote]
+> "A memorable quote"
+
+> [!bonus]
+> Advanced techniques
+```
+
+> [!important]
+> Note types are case-insensitive in markdown (`[!NOTE]`, `[!Note]`, `[!note]` all work), but the plugin normalizes them to lowercase.
+
+## Exports
+
+The package exports the following from its main entry point:
+
+```typescript
+// Default export
+export default function remarkNotes(options?: RemarkNotesOptions): Transformer;
+
+// Named type exports
+export type { RemarkNotesOptions };
+export type { ValidNoteType };
+```
+
+**Importing the plugin:**
+
+```typescript
+// ES Modules (recommended)
+import remarkNotes from 'remark-notes-plugin';
+import type { RemarkNotesOptions, ValidNoteType } from 'remark-notes-plugin';
+
+// CommonJS
+const remarkNotes = require('remark-notes-plugin');
+```
+
+**Importing styles:**
+
+```typescript
+// When injectStyles is false
+import 'remark-notes-plugin/styles.css';
+```
+
+## Package Exports
+
+The package.json defines the following exports:
+
+```json
+{
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./styles.css": "./dist/styles.css"
+  }
+}
+```
+
+This allows you to import:
+
+- The plugin: `import remarkNotes from 'remark-notes-plugin'`
+- Types: `import type { RemarkNotesOptions } from 'remark-notes-plugin'`
+- Styles: `import 'remark-notes-plugin/styles.css'`
+
+## HTML Output Structure
+
+The plugin generates the following HTML structure for each note:
+
+```html
+<blockquote class="remark-note remark-note-{type}">
+  <div class="remark-note-header">
+    <span class="remark-note-icon">
+      <!-- SVG icon -->
+    </span>
+    <span class="remark-note-title">{type}</span>
+  </div>
+  <div class="remark-note-content">
+    <!-- Original markdown content -->
+  </div>
+</blockquote>
+```
+
+**CSS Classes:**
+
+- `remark-note` - Base class applied to all notes
+- `remark-note-{type}` - Specific class for note type (e.g., `remark-note-tip`)
+- `remark-note-header` - Container for icon and title
+- `remark-note-icon` - Icon wrapper
+- `remark-note-title` - Title text (displays the note type)
+- `remark-note-content` - Content wrapper
+
+With a custom prefix (e.g., `'my'`), classes become:
+- `my-remark-note`
+- `my-remark-note-{type}`
+- `my-remark-note-header`
+- etc.
+
+## Browser and Environment Support
+
+- **Node.js:** v14.0.0 or higher
+- **Remark:** v13.0.0 or higher
+- **Module System:** ESM (ES Modules)
+- **TypeScript:** Full type definitions included
+
+**Browser Support:**
+
+The generated HTML and CSS work in all modern browsers:
+- Chrome/Edge (latest)
+- Firefox (latest)
+- Safari (latest)
+- Mobile browsers (iOS Safari, Chrome Mobile)
+
+## Error Handling
+
+The plugin implements graceful degradation:
+
+**Invalid note types:**
+
+If an invalid note type is encountered (e.g., `[!warning]`), the plugin leaves the blockquote unchanged. No error is thrown.
+
+```markdown
+> [!warning]
+> This is not a valid note type
+```
+
+Output: Regular blockquote (not transformed)
+
+**Valid note types:**
+
+Only these types are transformed:
+- `note`
+- `tip`
+- `important`
+- `quote`
+- `bonus`
+
+## Performance Considerations
+
+**Style Injection:**
+
+When `injectStyles` is `true`, styles are injected only once per document, regardless of how many notes are present.
+
+**AST Processing:**
+
+The plugin uses efficient AST traversal with `unist-util-visit`, processing only blockquote nodes.
+
+**Bundle Size:**
+
+- Plugin code: ~8KB minified
+- CSS file: ~2KB minified
+- Total: ~10KB for complete functionality
+
+## MDX Compatibility
+
+The plugin is fully compatible with MDX. It transforms markdown blockquotes in `.mdx` files just like in `.md` files.
+
+```mdx
+import { SomeComponent } from './components';
+
+> [!note]
+> This note works in MDX!
+
+<SomeComponent />
+
+> [!tip]
+> You can mix markdown notes with JSX components.
+```
+
+## TypeScript Usage
+
+Full type safety with TypeScript:
+
+```typescript
+import remarkNotes from 'remark-notes-plugin';
+import type { RemarkNotesOptions, ValidNoteType } from 'remark-notes-plugin';
+
+// Type-safe configuration
+const options: RemarkNotesOptions = {
+  classPrefix: 'docs',
+  injectStyles: false,
+};
+
+// Type-safe note type checking
+const noteType: ValidNoteType = 'tip'; // ✓ Valid
+const invalid: ValidNoteType = 'warning'; // ✗ TypeScript error
+```
+
+## Next Steps
+
+- [Installation Guide](/docs/getting-started/installation)
+- [Usage Examples](/docs/getting-started/usage)
+- [CSS Customization](/docs/customization/styling)
+- [Framework Integration](/docs/guides/frameworks)
diff --git a/docs/docs/customization/styling.md b/docs/docs/customization/styling.md
new file mode 100644
index 0000000..c660607
--- /dev/null
+++ b/docs/docs/customization/styling.md
@@ -0,0 +1,648 @@
+---
+sidebar_position: 1
+---
+
+# CSS Customization
+
+Learn how to customize the appearance of your notes to match your design system.
+
+## CSS Class Reference
+
+The plugin generates the following CSS classes for each note:
+
+### Container Classes
+
+```css
+.remark-note              /* Base class for all notes */
+.remark-note-{type}       /* Type-specific class (note, tip, important, quote, bonus) */
+```
+
+### Element Classes
+
+```css
+.remark-note-header       /* Container for icon and title */
+.remark-note-icon         /* Icon wrapper */
+.remark-note-title        /* Title text */
+.remark-note-content      /* Content wrapper */
+```
+
+### Complete HTML Structure
+
+```html
+<blockquote class="remark-note remark-note-tip">
+  <div class="remark-note-header">
+    <span class="remark-note-icon">
+      <!-- SVG icon -->
+    </span>
+    <span class="remark-note-title">tip</span>
+  </div>
+  <div class="remark-note-content">
+    <!-- Your markdown content -->
+  </div>
+</blockquote>
+```
+
+## Custom Class Prefix
+
+Add a custom prefix to all class names:
+
+```javascript
+import remarkNotes from 'remark-notes-plugin';
+
+unified().use(remarkNotes, { 
+  classPrefix: 'docs' 
+});
+```
+
+Generated classes:
+
+```css
+.docs-remark-note
+.docs-remark-note-tip
+.docs-remark-note-header
+.docs-remark-note-icon
+.docs-remark-note-title
+.docs-remark-note-content
+```
+
+> [!tip]
+> The default CSS uses attribute selectors like `[class*="remark-note"]`, so it works automatically with any prefix!
+
+## Overriding Default Styles
+
+### Method 1: CSS Variables (Recommended)
+
+Define custom CSS variables in your stylesheet:
+
+```css
+:root {
+  /* Note type colors */
+  --note-color: #4285f4;
+  --tip-color: #34a853;
+  --important-color: #ea4335;
+  --quote-color: #7e57c2;
+  --bonus-color: #ff9800;
+  
+  /* Note styling */
+  --note-border-radius: 12px;
+  --note-padding: 1.5rem;
+  --note-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
+}
+```
+
+### Method 2: Override Specific Classes
+
+Override the plugin's default styles:
+
+```css
+/* Override all notes */
+blockquote[class*="remark-note"] {
+  border-radius: 16px;
+  padding: 2rem;
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.12);
+}
+
+/* Override specific note type */
+blockquote[class*="remark-note-tip"] {
+  background: linear-gradient(135deg, #e8f5e9 0%, #c8e6c9 100%);
+  border-color: #4caf50;
+}
+
+/* Override header */
+[class*="remark-note-header"] {
+  margin-bottom: 1.5rem;
+  padding-bottom: 1rem;
+  border-bottom: 2px solid currentColor;
+}
+
+/* Override icon */
+[class*="remark-note-icon"] {
+  width: 48px;
+  height: 48px;
+  border-radius: 50%;
+  background: white;
+  padding: 8px;
+}
+```
+
+## Dark Mode Support
+
+Add dark mode variants for your notes:
+
+```css
+/* Light mode (default) */
+:root {
+  --note-bg: #e3f2fd;
+  --note-border: #2196f3;
+  --note-text: #1565c0;
+}
+
+/* Dark mode */
+[data-theme='dark'] {
+  --note-bg: #1a237e;
+  --note-border: #3f51b5;
+  --note-text: #7986cb;
+}
+
+/* Apply variables */
+blockquote[class*="remark-note-note"] {
+  background-color: var(--note-bg);
+  border-color: var(--note-border);
+  color: var(--note-text);
+}
+```
+
+### Framework-Specific Dark Mode
+
+**Tailwind CSS:**
+
+```css
+@layer components {
+  .remark-note {
+    @apply bg-gray-50 border-gray-300;
+    @apply dark:bg-gray-800 dark:border-gray-600;
+  }
+  
+  .remark-note-note {
+    @apply bg-blue-50 border-blue-500;
+    @apply dark:bg-blue-900/20 dark:border-blue-400;
+  }
+}
+```
+
+**CSS Modules:**
+
+```css
+.note {
+  background: #e3f2fd;
+  border-color: #2196f3;
+}
+
+:global([data-theme='dark']) .note {
+  background: #1a237e;
+  border-color: #3f51b5;
+}
+```
+
+## Complete Custom Theme
+
+Create a completely custom theme by overriding all default styles:
+
+```css
+/* Disable default styles */
+/* Set injectStyles: false in plugin options */
+
+/* Custom note container */
+.remark-note {
+  position: relative;
+  margin: 2rem 0;
+  padding: 1.5rem;
+  padding-left: 4rem;
+  border-left: 4px solid;
+  border-radius: 8px;
+  background: white;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+  transition: box-shadow 0.3s ease;
+}
+
+.remark-note:hover {
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.15);
+}
+
+/* Custom header */
+.remark-note-header {
+  position: absolute;
+  left: 1rem;
+  top: 1.5rem;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+/* Custom icon */
+.remark-note-icon {
+  width: 32px;
+  height: 32px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: 50%;
+  background: currentColor;
+  color: white;
+  padding: 6px;
+}
+
+/* Custom title */
+.remark-note-title {
+  font-size: 0.7rem;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  writing-mode: vertical-rl;
+  transform: rotate(180deg);
+}
+
+/* Custom content */
+.remark-note-content {
+  font-size: 1rem;
+  line-height: 1.6;
+  color: #333;
+}
+
+/* Type-specific colors */
+.remark-note-note {
+  border-color: #3b82f6;
+  background: linear-gradient(135deg, #eff6ff 0%, #dbeafe 100%);
+}
+
+.remark-note-tip {
+  border-color: #10b981;
+  background: linear-gradient(135deg, #ecfdf5 0%, #d1fae5 100%);
+}
+
+.remark-note-important {
+  border-color: #f59e0b;
+  background: linear-gradient(135deg, #fffbeb 0%, #fef3c7 100%);
+}
+
+.remark-note-quote {
+  border-color: #8b5cf6;
+  background: linear-gradient(135deg, #f5f3ff 0%, #ede9fe 100%);
+}
+
+.remark-note-bonus {
+  border-color: #ec4899;
+  background: linear-gradient(135deg, #fdf2f8 0%, #fce7f3 100%);
+}
+```
+
+## Minimal/Compact Theme
+
+A minimalist theme with less visual weight:
+
+```css
+.remark-note {
+  margin: 1rem 0;
+  padding: 0.75rem 1rem;
+  border-left: 3px solid currentColor;
+  background: transparent;
+  box-shadow: none;
+}
+
+.remark-note-header {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
+  margin-bottom: 0.5rem;
+}
+
+.remark-note-icon {
+  width: 20px;
+  height: 20px;
+}
+
+.remark-note-title {
+  font-size: 0.875rem;
+  font-weight: 600;
+  text-transform: capitalize;
+}
+
+.remark-note-content {
+  font-size: 0.95rem;
+  color: inherit;
+}
+
+.remark-note-content > *:first-child {
+  margin-top: 0;
+}
+
+.remark-note-content > *:last-child {
+  margin-bottom: 0;
+}
+```
+
+## GitHub-Style Theme
+
+Match GitHub's alert style:
+
+```css
+.remark-note {
+  margin: 16px 0;
+  padding: 8px 16px;
+  border-left: 4px solid;
+  border-radius: 0;
+  background: var(--note-bg);
+  box-shadow: none;
+}
+
+.remark-note-header {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin-bottom: 8px;
+  font-weight: 600;
+}
+
+.remark-note-icon {
+  width: 16px;
+  height: 16px;
+}
+
+.remark-note-title {
+  font-size: 14px;
+  text-transform: capitalize;
+}
+
+.remark-note-content {
+  font-size: 14px;
+  line-height: 1.5;
+}
+
+/* GitHub colors */
+.remark-note-note {
+  --note-bg: #ddf4ff;
+  border-color: #54aeff;
+  color: #0969da;
+}
+
+.remark-note-tip {
+  --note-bg: #d4f8d4;
+  border-color: #36c736;
+  color: #1a7f37;
+}
+
+.remark-note-important {
+  --note-bg: #fcf0d4;
+  border-color: #d4a72c;
+  color: #7d4e00;
+}
+
+.remark-note-quote {
+  --note-bg: #f0f0f0;
+  border-color: #656d76;
+  color: #1f2328;
+}
+```
+
+## Colorful Gradient Theme
+
+Bold gradients and modern styling:
+
+```css
+.remark-note {
+  margin: 2rem 0;
+  padding: 0;
+  border: none;
+  border-radius: 16px;
+  overflow: hidden;
+  box-shadow: 0 10px 40px rgba(0, 0, 0, 0.12);
+}
+
+.remark-note-header {
+  padding: 1.25rem 1.5rem;
+  background: var(--header-gradient);
+  color: white;
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+}
+
+.remark-note-icon {
+  width: 28px;
+  height: 28px;
+  filter: drop-shadow(0 2px 4px rgba(0, 0, 0, 0.2));
+}
+
+.remark-note-title {
+  font-size: 1.1rem;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
+.remark-note-content {
+  padding: 1.5rem;
+  background: white;
+  font-size: 1rem;
+  line-height: 1.6;
+}
+
+/* Gradient backgrounds */
+.remark-note-note {
+  --header-gradient: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+}
+
+.remark-note-tip {
+  --header-gradient: linear-gradient(135deg, #f093fb 0%, #f5576c 100%);
+}
+
+.remark-note-important {
+  --header-gradient: linear-gradient(135deg, #ffecd2 0%, #fcb69f 100%);
+}
+
+.remark-note-quote {
+  --header-gradient: linear-gradient(135deg, #a8edea 0%, #fed6e3 100%);
+}
+
+.remark-note-bonus {
+  --header-gradient: linear-gradient(135deg, #ffd89b 0%, #19547b 100%);
+}
+
+[data-theme='dark'] .remark-note-content {
+  background: #1a202c;
+  color: #e2e8f0;
+}
+```
+
+## Accessibility Considerations
+
+Ensure your custom styles maintain accessibility:
+
+```css
+/* Maintain sufficient color contrast */
+.remark-note-content {
+  color: #1a202c; /* Dark text on light background */
+}
+
+[data-theme='dark'] .remark-note-content {
+  color: #e2e8f0; /* Light text on dark background */
+}
+
+/* Focus styles for keyboard navigation */
+.remark-note:focus-within {
+  outline: 2px solid var(--ifm-color-primary);
+  outline-offset: 2px;
+}
+
+/* Ensure icons are decorative or have proper labels */
+.remark-note-icon {
+  aria-hidden: true;
+}
+
+/* Make titles screen-reader friendly */
+.remark-note-title {
+  /* Visually hidden but accessible */
+  clip-path: inset(50%);
+  /* Or visible as in default */
+}
+```
+
+## Print Styles
+
+Optimize notes for printing:
+
+```css
+@media print {
+  .remark-note {
+    page-break-inside: avoid;
+    border: 2px solid black;
+    box-shadow: none;
+  }
+  
+  .remark-note-icon svg {
+    stroke: black !important;
+    fill: black !important;
+  }
+  
+  .remark-note-note {
+    background: white;
+    border-color: black;
+  }
+}
+```
+
+## Mobile Optimization
+
+Responsive styles for mobile devices:
+
+```css
+@media (max-width: 768px) {
+  .remark-note {
+    margin: 1rem -1rem; /* Bleed to edges */
+    border-radius: 0;
+    padding: 1rem;
+  }
+  
+  .remark-note-header {
+    font-size: 0.9rem;
+  }
+  
+  .remark-note-icon {
+    width: 24px;
+    height: 24px;
+  }
+  
+  .remark-note-content {
+    font-size: 0.95rem;
+  }
+}
+```
+
+## Best Practices
+
+### 1. Use CSS Custom Properties
+
+Define colors and dimensions as variables for easy theming:
+
+```css
+:root {
+  --note-spacing: 1.5rem;
+  --note-radius: 8px;
+  --note-icon-size: 24px;
+}
+```
+
+### 2. Maintain Semantic HTML
+
+The plugin uses `<blockquote>` elements semantically. Preserve this in your styles:
+
+```css
+/* Good: Targets the generated structure */
+blockquote[class*="remark-note"] {
+  /* styles */
+}
+
+/* Avoid: Changing semantic meaning */
+.remark-note {
+  display: flex; /* Don't make blockquote a flex container */
+}
+```
+
+### 3. Test Across Themes
+
+Always test your custom styles in both light and dark modes:
+
+```css
+/* Light mode */
+.remark-note {
+  background: white;
+  color: black;
+}
+
+/* Dark mode */
+[data-theme='dark'] .remark-note {
+  background: #1a202c;
+  color: white;
+}
+```
+
+### 4. Consider Content Variety
+
+Test with different content types:
+
+- Short one-liners
+- Multiple paragraphs
+- Lists and code blocks
+- Nested elements
+
+## Example: Complete Custom Implementation
+
+Here's a production-ready custom theme:
+
+```css
+/* Disable auto-injection in plugin options */
+/* Use: { injectStyles: false } */
+
+/* Custom theme variables */
+:root {
+  --note-radius: 12px;
+  --note-shadow: 0 4px 12px rgba(0, 0, 0, 0.08);
+  --note-padding: 1.5rem;
+  --note-gap: 1rem;
+  
+  /* Color palette */
+  --note-blue: #3b82f6;
+  --note-green: #10b981;
+  --note-orange: #f59e0b;
+  --note-purple: #8b5cf6;
+  --note-pink: #ec4899;
+}
+
+[data-theme='dark'] {
+  --note-shadow: 0 4px 12px rgba(0, 0, 0, 0.4);
+  --note-blue: #60a5fa;
+  --note-green: #34d399;
+  --note-orange: #fbbf24;
+  --note-purple: #a78bfa;
+  --note-pink: #f472b6;
+}
+
+/* Base note styles */
+.remark-note {
+  margin: var(--note-gap) 0;
+  padding: var(--note-padding);
+  border-radius: var(--note-radius);
+  border: 1px solid;
+  box-shadow: var(--note-shadow);
+  transition: all 0.2s ease;
+}
+
+/* Import remaining styles... */
+```
+
+## Next Steps
+
+- [Framework Integration](/docs/guides/frameworks) - Use with popular frameworks
+- [API Reference](/docs/api/overview) - Complete API documentation
+- [Troubleshooting](/docs/guides/troubleshooting) - Common issues and solutions
diff --git a/docs/docs/examples/note-types.mdx b/docs/docs/examples/note-types.mdx
index 3452d97..f3a290b 100644
--- a/docs/docs/examples/note-types.mdx
+++ b/docs/docs/examples/note-types.mdx
@@ -4,100 +4,413 @@ sidebar_position: 1
 
 # Note Types
 
-`remark-notes-plugin` supports five different types of notes, each with its own styling. This page demonstrates all available note types and how to use them.
+Learn about all five note types, when to use them, and best practices for creating effective documentation.
 
-## Standard Note
+## Overview
 
-Used for providing general information or notes to the reader.
+`remark-notes-plugin` provides five distinct note types, each designed for a specific purpose. Using the right type helps readers quickly understand the importance and context of your message.
+
+| Type | Purpose | When to Use | Color |
+|------|---------|-------------|-------|
+| **Note** | General information | Definitions, context, explanations | Blue |
+| **Tip** | Helpful advice | Best practices, shortcuts, recommendations | Green |
+| **Important** | Critical information | Warnings, requirements, prerequisites | Orange |
+| **Quote** | Quotations | Testimonials, citations, highlights | Gray |
+| **Bonus** | Extra value | Advanced features, optional enhancements | Purple |
+
+---
+
+## 📘 Note - General Information
+
+### Purpose
+
+Use notes for general information, definitions, background context, or explanations that help readers understand the content better.
+
+### When to Use
+
+- Providing additional context
+- Explaining terminology
+- Offering related information
+- Clarifying concepts
+- Adding supplementary details
+
+### Example
 
 > [!note]
-> This is a standard note that provides additional information to the reader.
+> This plugin uses the unified/remark ecosystem for markdown processing. If you're new to remark, check out the [official documentation](https://github.com/remarkjs/remark) to learn more about how it works.
+
+### Best Practices
+
+✅ **Do:**
+- Keep notes informative but concise
+- Use for non-critical supplementary information
+- Provide helpful context without interrupting flow
+- Link to additional resources when relevant
+
+❌ **Don't:**
+- Use for urgent warnings (use Important instead)
+- Overuse - too many notes reduce impact
+- Include critical setup steps (use Important)
+
+### Markdown Syntax
 
-**Markdown Syntax**:
 ```markdown
 > [!note]
 > This is a standard note that provides additional information to the reader.
 ```
 
-## Tip Note
+### Accessibility Note
+
+Notes use semantic `<blockquote>` elements and include proper ARIA labels for screen readers.
+
+---
+
+## 💡 Tip - Helpful Advice
 
-Used for providing helpful tips and advice.
+### Purpose
+
+Use tips to share best practices, expert advice, helpful shortcuts, or recommendations that improve the reader's experience or results.
+
+### When to Use
+
+- Sharing best practices
+- Offering optimization suggestions
+- Providing pro tips or shortcuts
+- Recommending better approaches
+- Highlighting efficiency improvements
+
+### Example
 
 > [!tip]
-> Here's a helpful tip that can improve your workflow or code quality.
+> For better performance in production, disable style injection and import the CSS file directly in your layout. This enables better caching and reduces runtime overhead.
+
+### Best Practices
+
+✅ **Do:**
+- Share actionable, practical advice
+- Focus on improvements and optimizations
+- Keep tips specific and valuable
+- Explain why the tip is helpful
+
+❌ **Don't:**
+- State obvious information
+- Use for warnings (use Important)
+- Make tips too generic
+- Forget to explain the benefit
+
+### Markdown Syntax
 
-**Markdown Syntax**:
 ```markdown
 > [!tip]
 > Here's a helpful tip that can improve your workflow or code quality.
 ```
 
-## Important Note
+### Real-World Examples
+
+> [!tip]
+> When using with Next.js App Router, import the CSS in your root layout for optimal performance:
+> ```typescript
+> // app/layout.tsx
+> import 'remark-notes-plugin/styles.css';
+> ```
+
+---
+
+## ⚠️ Important - Critical Information
+
+### Purpose
+
+Use important notes for critical information that readers must not miss - warnings, requirements, prerequisites, breaking changes, or potential issues.
+
+### When to Use
 
-Used for highlighting critical information that requires special attention.
+- Highlighting breaking changes
+- Warning about potential issues
+- Stating requirements or prerequisites
+- Emphasizing critical setup steps
+- Preventing common mistakes
+- Security considerations
+
+### Example
 
 > [!important]
-> This information is crucial and requires your attention to avoid issues or errors.
+> This plugin requires Node.js 14 or higher and remark v13+. Using older versions will result in compatibility issues.
+
+### Best Practices
+
+✅ **Do:**
+- Be clear and specific about the issue
+- Explain the consequences
+- Provide solutions when possible
+- Use sparingly to maintain impact
+- Front-load critical information
+
+❌ **Don't:**
+- Overuse - reduces effectiveness
+- Use for general tips
+- Be vague or unclear
+- Forget to explain why it's important
+
+### Markdown Syntax
 
-**Markdown Syntax**:
 ```markdown
 > [!important]
 > This information is crucial and requires your attention to avoid issues or errors.
 ```
 
-## Quote Note
+### Real-World Examples
+
+> [!important]
+> When using with SSR frameworks like Next.js, set `injectStyles: false` to prevent hydration mismatches. Import the CSS in your layout instead.
+
+> [!important]
+> Invalid note types (like `[!warning]`) will silently fail and render as plain blockquotes. Only use supported types: note, tip, important, quote, bonus.
+
+---
+
+## 💬 Quote - Quotations & Highlights
+
+### Purpose
 
-Used for styling quotations in a distinctive way.
+Use quote notes for testimonials, citations, memorable quotes, or to highlight specific text in a visually distinct way.
+
+### When to Use
+
+- Displaying user testimonials
+- Citing sources or authorities
+- Highlighting memorable quotes
+- Showcasing feedback
+- Emphasizing key statements
+
+### Example
 
 > [!quote]
-> "The best way to predict the future is to invent it." — Alan Kay
+> "This plugin transformed our documentation from plain and boring to engaging and professional. The GitHub-compatible syntax made migration effortless!"  
+> — DevOps Team Lead, Tech Startup
+
+### Best Practices
+
+✅ **Do:**
+- Include attribution when appropriate
+- Use for actual quotes or testimonials
+- Keep quotes relevant to context
+- Consider length - shorter is better
+- Use proper quotation marks
+
+❌ **Don't:**
+- Fabricate quotes
+- Use for general information (use Note)
+- Omit attribution for famous quotes
+- Make quotes too long
+
+### Markdown Syntax
 
-**Markdown Syntax**:
 ```markdown
 > [!quote]
 > "The best way to predict the future is to invent it." — Alan Kay
 ```
 
-## Bonus Note
+### Real-World Examples
+
+> [!quote]
+> "Markdown is intended to be as easy-to-read and easy-to-write as is feasible."  
+> — John Gruber, Creator of Markdown
+
+---
+
+## ⭐ Bonus - Advanced Features
 
-Used for providing additional, nice-to-have information or features.
+### Purpose
+
+Use bonus notes for advanced techniques, optional features, power-user tips, or extra value content that goes beyond the basics.
+
+### When to Use
+
+- Sharing advanced techniques
+- Describing optional features
+- Providing expert-level tips
+- Offering additional value
+- Going beyond basic usage
+- Showcasing hidden features
+
+### Example
 
 > [!bonus]
-> Here's an advanced technique that can further enhance your implementation.
+> Advanced users can create custom note styles by disabling default injection and creating their own CSS classes that match your design system. See the [CSS Customization guide](/docs/customization/styling) for details.
+
+### Best Practices
+
+✅ **Do:**
+- Provide genuine additional value
+- Target intermediate/advanced users
+- Link to detailed documentation
+- Make it optional and supplementary
+- Explain the benefits
+
+❌ **Don't:**
+- Include essential information (use Note/Important)
+- Make it too complex without explanation
+- Use for basic tips (use Tip)
+- Forget to link to detailed guides
+
+### Markdown Syntax
 
-**Markdown Syntax**:
 ```markdown
 > [!bonus]
 > Here's an advanced technique that can further enhance your implementation.
 ```
 
-## Multiple Paragraphs
+### Real-World Examples
 
-Notes can contain multiple paragraphs and other markdown elements like lists and code blocks.
+> [!bonus]
+> You can use custom class prefixes to run multiple instances of the plugin with different styles on the same page:
+> ```javascript
+> .use(remarkNotes, { classPrefix: 'sidebar' })
+> .use(remarkNotes, { classPrefix: 'main' })
+> ```
 
-> [!note]
-> This note has multiple paragraphs.
+---
+
+## Advanced Usage
+
+### Multiple Paragraphs
+
+All note types support multiple paragraphs, lists, code blocks, and other markdown elements:
+
+> [!tip]
+> When structuring complex notes, follow these guidelines:
 >
-> You can include:
-> - Lists
-> - And other markdown elements
+> 1. Start with the key message
+> 2. Provide supporting details
+> 3. Include examples when helpful
 >
-> ```js
-> // Even code blocks
-> console.log('Hello world');
+> ```javascript
+> // Example code
+> unified()
+>   .use(remarkNotes)
+>   .process(content);
 > ```
+>
+> This keeps your notes organized and scannable.
 
-**Markdown Syntax**:
+**Syntax:**
 ```markdown
-> [!note]
-> This note has multiple paragraphs.
+> [!tip]
+> First paragraph.
 >
-> You can include:
-> - Lists
-> - And other markdown elements
+> Second paragraph with a list:
+> - Item 1
+> - Item 2
 >
 > ```js
-> // Even code blocks
-> console.log('Hello world');
+> // Code block
 > ```
-```
\ No newline at end of file
+```
+
+### Nested Elements
+
+You can include various markdown elements:
+
+> [!note]
+> **Supported markdown elements:**
+>
+> - **Bold** and *italic* text
+> - [Links](https://example.com)
+> - `inline code`
+> - Lists (ordered and unordered)
+> - Code blocks
+> - Images (use sparingly)
+> 
+> Complex formatting works seamlessly!
+
+### Combining Note Types
+
+Use different types strategically in your documentation:
+
+> [!note]
+> The `classPrefix` option prepends a custom string to all CSS classes.
+
+> [!tip]
+> Use a prefix that matches your project's naming convention, like `docs-` or `blog-`.
+
+> [!important]
+> The default CSS uses attribute selectors, so it works with any prefix automatically.
+
+> [!bonus]
+> Advanced CSS users can target specific prefixes for granular control over different sections.
+
+---
+
+## Choosing the Right Type
+
+### Decision Tree
+
+```
+Is it critical information that could cause errors?
+├─ YES → Use [!important]
+└─ NO ↓
+
+Is it practical advice or a best practice?
+├─ YES → Use [!tip]
+└─ NO ↓
+
+Is it a quotation or testimonial?
+├─ YES → Use [!quote]
+└─ NO ↓
+
+Is it advanced/optional information?
+├─ YES → Use [!bonus]
+└─ NO → Use [!note]
+```
+
+### Common Mistakes
+
+**❌ Wrong:**
+```markdown
+> [!note]
+> WARNING: This will delete all your data!
+```
+
+**✅ Right:**
+```markdown
+> [!important]
+> This operation permanently deletes all data. Create a backup before proceeding.
+```
+
+---
+
+**❌ Wrong:**
+```markdown
+> [!important]
+> You might want to use TypeScript for better development experience.
+```
+
+**✅ Right:**
+```markdown
+> [!tip]
+> Use TypeScript for better development experience with autocomplete and type safety.
+```
+
+---
+
+## Accessibility Considerations
+
+All note types are designed with accessibility in mind:
+
+- **Semantic HTML:** Uses `<blockquote>` elements
+- **Color Independence:** Information isn't conveyed by color alone
+- **Screen Readers:** Proper heading hierarchy and ARIA labels
+- **Keyboard Navigation:** Fully keyboard accessible
+- **Contrast Ratios:** WCAG AA compliant color combinations
+
+> [!note]
+> The icons are decorative (aria-hidden) and the note type is provided as text, ensuring screen reader users get the same information as sighted users.
+
+---
+
+## Next Steps
+
+- [CSS Customization](/docs/customization/styling) - Customize note appearance
+- [Framework Integration](/docs/guides/frameworks) - Use with your favorite framework
+- [API Reference](/docs/api/overview) - Complete technical documentation
+- [Troubleshooting](/docs/guides/troubleshooting) - Common issues and solutions
\ No newline at end of file
diff --git a/docs/docs/guides/frameworks.md b/docs/docs/guides/frameworks.md
new file mode 100644
index 0000000..d5c2253
--- /dev/null
+++ b/docs/docs/guides/frameworks.md
@@ -0,0 +1,516 @@
+---
+sidebar_position: 1
+---
+
+# Framework Integration
+
+Complete integration guides for using `remark-notes-plugin` with popular frameworks and static site generators.
+
+## Next.js
+
+### Next.js 13+ (App Router with MDX)
+
+For Next.js 13+ using the App Router with `@next/mdx`:
+
+**1. Install dependencies:**
+
+```bash
+npm install remark-notes-plugin @next/mdx @mdx-js/loader @mdx-js/react
+```
+
+**2. Configure `next.config.mjs`:**
+
+```javascript
+import createMDX from '@next/mdx';
+import remarkNotes from 'remark-notes-plugin';
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  pageExtensions: ['js', 'jsx', 'md', 'mdx', 'ts', 'tsx'],
+};
+
+const withMDX = createMDX({
+  options: {
+    remarkPlugins: [remarkNotes],
+    rehypePlugins: [],
+  },
+});
+
+export default withMDX(nextConfig);
+```
+
+**3. Import styles in your root layout (`app/layout.tsx`):**
+
+```typescript
+import 'remark-notes-plugin/styles.css';
+import './globals.css';
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+**4. Create an MDX file (`app/blog/post.mdx`):**
+
+```mdx
+# My Blog Post
+
+> [!tip]
+> This is a helpful tip in Next.js!
+
+Regular content here...
+
+> [!important]
+> Don't forget this important detail.
+```
+
+### Next.js (Pages Router with MDX)
+
+For the traditional Pages Router:
+
+**1. Install dependencies:**
+
+```bash
+npm install remark-notes-plugin @next/mdx @mdx-js/loader
+```
+
+**2. Configure `next.config.js`:**
+
+```javascript
+const withMDX = require('@next/mdx')({
+  extension: /\.mdx?$/,
+  options: {
+    remarkPlugins: [require('remark-notes-plugin')],
+    rehypePlugins: [],
+  },
+});
+
+module.exports = withMDX({
+  pageExtensions: ['js', 'jsx', 'ts', 'tsx', 'md', 'mdx'],
+});
+```
+
+**3. Import styles in `pages/_app.js` or `pages/_app.tsx`:**
+
+```javascript
+import 'remark-notes-plugin/styles.css';
+import '../styles/globals.css';
+
+export default function App({ Component, pageProps }) {
+  return <Component {...pageProps} />;
+}
+```
+
+### Next.js with Custom Markdown Processing
+
+If you're processing markdown programmatically:
+
+```typescript
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkNotes from 'remark-notes-plugin';
+import remarkRehype from 'remark-rehype';
+import rehypeStringify from 'rehype-stringify';
+
+export async function getStaticProps() {
+  const markdown = `
+> [!note]
+> This is processed server-side
+  `;
+
+  const result = await unified()
+    .use(remarkParse)
+    .use(remarkNotes)
+    .use(remarkRehype)
+    .use(rehypeStringify)
+    .process(markdown);
+
+  return {
+    props: {
+      content: result.toString(),
+    },
+  };
+}
+```
+
+> [!tip]
+> For better performance with many pages, disable automatic style injection and import the CSS file manually in your layout.
+
+## Astro
+
+Astro has excellent built-in support for remark plugins.
+
+**1. Install the plugin:**
+
+```bash
+npm install remark-notes-plugin
+```
+
+**2. Configure `astro.config.mjs`:**
+
+```javascript
+import { defineConfig } from 'astro/config';
+import remarkNotes from 'remark-notes-plugin';
+
+export default defineConfig({
+  markdown: {
+    remarkPlugins: [remarkNotes],
+  },
+});
+```
+
+**3. The CSS is automatically injected, but you can also import it manually:**
+
+```astro
+---
+// src/layouts/Layout.astro
+import 'remark-notes-plugin/styles.css';
+---
+
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>My Site</title>
+  </head>
+  <body>
+    <slot />
+  </body>
+</html>
+```
+
+**4. Use in your markdown files:**
+
+```markdown
+---
+title: My Page
+---
+
+# Welcome
+
+> [!note]
+> This is a note in Astro!
+
+> [!tip]
+> Astro makes it super easy to use remark plugins.
+```
+
+### Astro with Custom Class Prefix
+
+```javascript
+import { defineConfig } from 'astro/config';
+import remarkNotes from 'remark-notes-plugin';
+
+export default defineConfig({
+  markdown: {
+    remarkPlugins: [
+      [remarkNotes, { classPrefix: 'astro' }]
+    ],
+  },
+});
+```
+
+## Gatsby
+
+**1. Install dependencies:**
+
+```bash
+npm install remark-notes-plugin gatsby-plugin-mdx
+```
+
+**2. Configure `gatsby-config.js`:**
+
+```javascript
+module.exports = {
+  plugins: [
+    {
+      resolve: 'gatsby-plugin-mdx',
+      options: {
+        extensions: ['.mdx', '.md'],
+        mdxOptions: {
+          remarkPlugins: [require('remark-notes-plugin')],
+        },
+      },
+    },
+  ],
+};
+```
+
+**3. Import styles in `gatsby-browser.js`:**
+
+```javascript
+import 'remark-notes-plugin/styles.css';
+```
+
+**4. Or disable auto-injection and use CSS modules:**
+
+```javascript
+module.exports = {
+  plugins: [
+    {
+      resolve: 'gatsby-plugin-mdx',
+      options: {
+        mdxOptions: {
+          remarkPlugins: [
+            [require('remark-notes-plugin'), { injectStyles: false }]
+          ],
+        },
+      },
+    },
+  ],
+};
+```
+
+## Docusaurus
+
+Docusaurus is what we use for this documentation site!
+
+**1. Install the plugin:**
+
+```bash
+npm install remark-notes-plugin
+```
+
+**2. Configure `docusaurus.config.js`:**
+
+```javascript
+import remarkNotes from 'remark-notes-plugin';
+
+const config = {
+  presets: [
+    [
+      'classic',
+      {
+        docs: {
+          remarkPlugins: [remarkNotes],
+        },
+        blog: {
+          remarkPlugins: [remarkNotes],
+        },
+      },
+    ],
+  ],
+};
+
+export default config;
+```
+
+**3. Import styles in `src/css/custom.css`:**
+
+```css
+@import 'remark-notes-plugin/styles.css';
+
+/* Your custom styles below */
+```
+
+> [!note]
+> Styles are automatically injected by default, but importing them manually gives you more control over the cascade order.
+
+## VitePress
+
+**1. Install dependencies:**
+
+```bash
+npm install remark-notes-plugin
+```
+
+**2. Configure `.vitepress/config.ts`:**
+
+```typescript
+import { defineConfig } from 'vitepress';
+import remarkNotes from 'remark-notes-plugin';
+
+export default defineConfig({
+  markdown: {
+    config: (md) => {
+      md.use(remarkNotes);
+    },
+  },
+});
+```
+
+**3. Import styles in `.vitepress/theme/index.ts`:**
+
+```typescript
+import DefaultTheme from 'vitepress/theme';
+import 'remark-notes-plugin/styles.css';
+import './custom.css';
+
+export default {
+  extends: DefaultTheme,
+};
+```
+
+> [!important]
+> VitePress uses markdown-it by default, not remark. You may need additional configuration or consider using a different approach for VitePress.
+
+## Eleventy (11ty)
+
+**1. Install dependencies:**
+
+```bash
+npm install @11ty/eleventy-plugin-remark remark-notes-plugin
+```
+
+**2. Configure `.eleventy.js`:**
+
+```javascript
+const eleventyRemark = require('@11ty/eleventy-plugin-remark');
+const remarkNotes = require('remark-notes-plugin');
+
+module.exports = function(eleventyConfig) {
+  eleventyConfig.addPlugin(eleventyRemark, {
+    plugins: [remarkNotes],
+  });
+
+  return {
+    dir: {
+      input: 'src',
+      output: 'dist',
+    },
+  };
+};
+```
+
+## Hugo
+
+Hugo doesn't use remark directly, but you can preprocess markdown files:
+
+**1. Create a preprocessing script (`scripts/process-markdown.js`):**
+
+```javascript
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkNotes from 'remark-notes-plugin';
+import remarkStringify from 'remark-stringify';
+import { readFileSync, writeFileSync } from 'fs';
+import { glob } from 'glob';
+
+async function processFile(filepath) {
+  const content = readFileSync(filepath, 'utf-8');
+  
+  const result = await unified()
+    .use(remarkParse)
+    .use(remarkNotes, { injectStyles: false })
+    .use(remarkStringify)
+    .process(content);
+
+  writeFileSync(filepath, result.toString());
+}
+
+const files = glob.sync('content/**/*.md');
+files.forEach(processFile);
+```
+
+**2. Add to your build process in `package.json`:**
+
+```json
+{
+  "scripts": {
+    "prebuild": "node scripts/process-markdown.js",
+    "build": "hugo"
+  }
+}
+```
+
+## Vanilla Unified/Remark
+
+For custom implementations using unified directly:
+
+```typescript
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkNotes from 'remark-notes-plugin';
+import remarkRehype from 'remark-rehype';
+import rehypeStringify from 'rehype-stringify';
+
+async function processMarkdown(markdown: string) {
+  const result = await unified()
+    .use(remarkParse)
+    .use(remarkNotes, {
+      classPrefix: 'custom',
+      injectStyles: false,
+    })
+    .use(remarkRehype, { allowDangerousHtml: true })
+    .use(rehypeStringify, { allowDangerousHtml: true })
+    .process(markdown);
+
+  return result.toString();
+}
+
+// Usage
+const html = await processMarkdown(`
+> [!tip]
+> This is processed with vanilla unified!
+`);
+
+console.log(html);
+```
+
+## Configuration Best Practices
+
+### When to Disable Style Injection
+
+Set `injectStyles: false` when:
+
+1. **Using a build tool** (Vite, Webpack, Rollup) that handles CSS imports
+2. **Server-Side Rendering** with separate CSS extraction
+3. **Custom styling** - you're providing your own styles
+4. **Performance optimization** - better caching with separate CSS files
+
+### When to Use Custom Class Prefix
+
+Use `classPrefix` when:
+
+1. **Avoiding conflicts** with existing CSS classes
+2. **Multiple instances** of the plugin with different styles
+3. **Framework conventions** - matching your project's naming scheme
+4. **Scoped styling** - better encapsulation
+
+## Troubleshooting
+
+### Styles Not Appearing
+
+**Problem:** Notes appear unstyled.
+
+**Solutions:**
+1. Ensure styles are imported: `import 'remark-notes-plugin/styles.css'`
+2. Check if `injectStyles` is set to `false` and you forgot to import CSS
+3. Verify CSS load order in your build tool
+
+### Build Errors with MDX
+
+**Problem:** Build fails when processing MDX files.
+
+**Solutions:**
+1. Ensure you're using compatible versions of MDX and remark
+2. Check for syntax errors in your markdown notes
+3. Try setting `injectStyles: false` for SSR environments
+
+### TypeScript Errors
+
+**Problem:** TypeScript can't find module types.
+
+**Solution:**
+```typescript
+// If types aren't recognized, add to your tsconfig.json:
+{
+  "compilerOptions": {
+    "moduleResolution": "node",
+    "esModuleInterop": true
+  }
+}
+```
+
+## Next Steps
+
+- [API Reference](/docs/api/overview) - Complete API documentation
+- [CSS Customization](/docs/customization/styling) - Customize note styles
+- [Troubleshooting](/docs/guides/troubleshooting) - Common issues and solutions
diff --git a/docs/docs/guides/troubleshooting.md b/docs/docs/guides/troubleshooting.md
new file mode 100644
index 0000000..9d13fe7
--- /dev/null
+++ b/docs/docs/guides/troubleshooting.md
@@ -0,0 +1,564 @@
+---
+sidebar_position: 2
+---
+
+# Troubleshooting
+
+Common issues and solutions when using `remark-notes-plugin`.
+
+## Installation Issues
+
+### Module Not Found
+
+**Problem:**
+```
+Error: Cannot find module 'remark-notes-plugin'
+```
+
+**Solutions:**
+
+1. Verify the package is installed:
+   ```bash
+   npm list remark-notes-plugin
+   ```
+
+2. Reinstall the package:
+   ```bash
+   npm install remark-notes-plugin
+   ```
+
+3. Clear your package manager cache:
+   ```bash
+   npm cache clean --force
+   # or
+   yarn cache clean
+   # or
+   pnpm store prune
+   ```
+
+### Type Definitions Not Found
+
+**Problem:**
+```
+Could not find a declaration file for module 'remark-notes-plugin'
+```
+
+**Solution:**
+
+The package includes TypeScript definitions. Ensure your `tsconfig.json` has:
+
+```json
+{
+  "compilerOptions": {
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "skipLibCheck": false
+  }
+}
+```
+
+## Style Issues
+
+### Styles Not Appearing
+
+**Problem:** Notes appear as plain blockquotes without styling.
+
+**Common Causes:**
+
+1. **Missing CSS import** when `injectStyles: false`:
+   ```javascript
+   // Add this to your app:
+   import 'remark-notes-plugin/styles.css';
+   ```
+
+2. **CSS not loaded** in build output:
+   ```javascript
+   // Ensure your bundler handles CSS imports
+   // For Vite, Webpack, this should work automatically
+   ```
+
+3. **CSP (Content Security Policy)** blocking inline styles:
+   ```javascript
+   // Use manual import instead:
+   unified().use(remarkNotes, { injectStyles: false });
+   import 'remark-notes-plugin/styles.css';
+   ```
+
+4. **CSS load order** - styles being overridden:
+   ```css
+   /* Increase specificity */
+   blockquote[class*="remark-note"] {
+     /* Your styles */
+   } !important; /* Last resort */
+   ```
+
+### Styles Conflict with Existing CSS
+
+**Problem:** Note styles clash with your site's CSS.
+
+**Solutions:**
+
+1. **Use a custom class prefix:**
+   ```javascript
+   unified().use(remarkNotes, { classPrefix: 'my-docs' });
+   ```
+
+2. **Scope your overrides:**
+   ```css
+   .documentation-content [class*="remark-note"] {
+     /* Your custom styles */
+   }
+   ```
+
+3. **Disable default styles completely:**
+   ```javascript
+   unified().use(remarkNotes, { injectStyles: false });
+   // Provide your own CSS
+   ```
+
+### Dark Mode Not Working
+
+**Problem:** Notes don't change appearance in dark mode.
+
+**Solution:**
+
+Ensure your theme uses the standard `[data-theme='dark']` selector:
+
+```css
+/* Add dark mode overrides */
+[data-theme='dark'] blockquote[class*="remark-note"] {
+  background-color: #1a202c;
+  border-color: #4a5568;
+  color: #e2e8f0;
+}
+```
+
+For other theme selectors:
+
+```css
+.dark blockquote[class*="remark-note"],
+html.dark blockquote[class*="remark-note"] {
+  /* Dark mode styles */
+}
+```
+
+## Build Issues
+
+### SSR/SSG Errors
+
+**Problem:**
+```
+ReferenceError: document is not defined
+TypeError: fs.readFileSync is not a function
+```
+
+**Solution:**
+
+The plugin is designed for SSR. If you see these errors:
+
+1. **Ensure you're using the correct import:**
+   ```javascript
+   // Server-side (Node.js)
+   import remarkNotes from 'remark-notes-plugin';
+   
+   // NOT the browser build
+   ```
+
+2. **For Vite/Webpack, configure externals:**
+   ```javascript
+   // vite.config.js
+   export default {
+     ssr: {
+       noExternal: ['remark-notes-plugin']
+     }
+   }
+   ```
+
+### Next.js Build Errors
+
+**Problem:** Build fails with MDX or remark errors.
+
+**Solutions:**
+
+1. **Next.js 13+ App Router:**
+   ```javascript
+   // next.config.mjs
+   import createMDX from '@next/mdx';
+   import remarkNotes from 'remark-notes-plugin';
+   
+   const withMDX = createMDX({
+     options: {
+       remarkPlugins: [remarkNotes],
+     },
+   });
+   
+   export default withMDX({
+     pageExtensions: ['js', 'jsx', 'md', 'mdx', 'ts', 'tsx'],
+   });
+   ```
+
+2. **Next.js Pages Router:**
+   ```javascript
+   // next.config.js
+   const withMDX = require('@next/mdx')({
+     options: {
+       remarkPlugins: [require('remark-notes-plugin')],
+     },
+   });
+   
+   module.exports = withMDX({
+     pageExtensions: ['js', 'jsx', 'md', 'mdx', 'ts', 'tsx'],
+   });
+   ```
+
+3. **Disable style injection for better SSR:**
+   ```javascript
+   remarkPlugins: [
+     [remarkNotes, { injectStyles: false }]
+   ]
+   ```
+
+### Astro Build Errors
+
+**Problem:** Build fails or styles missing.
+
+**Solution:**
+
+```javascript
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import remarkNotes from 'remark-notes-plugin';
+
+export default defineConfig({
+  markdown: {
+    remarkPlugins: [remarkNotes],
+  },
+});
+```
+
+Import styles in your layout:
+
+```astro
+---
+// src/layouts/Layout.astro
+import 'remark-notes-plugin/styles.css';
+---
+```
+
+## Runtime Issues
+
+### Notes Not Being Transformed
+
+**Problem:** Blockquotes remain as plain blockquotes.
+
+**Checklist:**
+
+1. **Verify syntax is correct:**
+   ```markdown
+   > [!note]
+   > Text here
+   
+   // NOT:
+   > [note]  ❌
+   > !note   ❌
+   [!note]  ❌
+   ```
+
+2. **Check note type is valid:**
+   ```markdown
+   Valid: note, tip, important, quote, bonus
+   
+   Invalid: warning, info, danger, caution
+   ```
+
+3. **Ensure plugin is in pipeline:**
+   ```javascript
+   unified()
+     .use(remarkParse)
+     .use(remarkNotes)  // Must be AFTER parse
+     .use(remarkRehype)
+     .process(content);
+   ```
+
+4. **Check MDX processing:**
+   ```javascript
+   // For MDX, may need specific configuration
+   remarkPlugins: [remarkNotes]
+   ```
+
+### Invalid Note Types Silently Ignored
+
+**Problem:** Unknown note types don't produce notes.
+
+**Expected Behavior:** This is intentional! Invalid types gracefully degrade to regular blockquotes.
+
+**Valid types:** `note`, `tip`, `important`, `quote`, `bonus`
+
+**To add custom types:** You'll need to modify the source code or create a custom plugin variant.
+
+## Performance Issues
+
+### Slow Build Times
+
+**Problem:** Build takes significantly longer with the plugin.
+
+**Optimizations:**
+
+1. **Disable style injection:**
+   ```javascript
+   unified().use(remarkNotes, { injectStyles: false });
+   // Import CSS once in your layout instead
+   ```
+
+2. **Cache markdown processing:**
+   ```javascript
+   // Use your framework's caching mechanisms
+   // For example, Next.js automatic MDX caching
+   ```
+
+3. **Limit plugin usage:**
+   ```javascript
+   // Only apply to specific content
+   if (isDocumentation) {
+     remarkPlugins.push(remarkNotes);
+   }
+   ```
+
+### Large Bundle Size
+
+**Problem:** Plugin increases bundle size.
+
+**Solution:**
+
+The plugin is very lightweight (~10KB total):
+- Plugin code: ~8KB
+- CSS: ~2KB
+
+If size is critical:
+
+1. Use tree-shaking (automatic with ES modules)
+2. Disable style injection and use minimal custom CSS
+3. Consider if you really need all note types
+
+## MDX-Specific Issues
+
+### MDX Components Not Working Inside Notes
+
+**Problem:**
+```markdown
+> [!note]
+> <MyComponent /> doesn't render
+```
+
+**Solution:**
+
+MDX components work inside notes. Ensure:
+
+1. **Component is properly imported:**
+   ```mdx
+   import MyComponent from './MyComponent';
+   
+   > [!note]
+   > <MyComponent />
+   ```
+
+2. **Syntax is valid MDX:**
+   ```mdx
+   > [!note]
+   > Regular text
+   >
+   > <MyComponent />
+   ```
+
+### Code Blocks in Notes
+
+**Problem:** Code blocks inside notes not rendering correctly.
+
+**Solution:**
+
+Ensure proper markdown syntax:
+
+```markdown
+> [!tip]
+> Here's how to use it:
+>
+> ```javascript
+> const x = 1;
+> ```
+```
+
+Note the empty line before the code block!
+
+## Framework-Specific Issues
+
+### Gatsby: GraphQL Queries Failing
+
+**Problem:** GraphQL can't query MDX with notes.
+
+**Solution:**
+
+```javascript
+// gatsby-config.js
+{
+  resolve: 'gatsby-plugin-mdx',
+  options: {
+    mdxOptions: {
+      remarkPlugins: [require('remark-notes-plugin')],
+    },
+  },
+}
+```
+
+### Docusaurus: Admonitions Conflicting
+
+**Problem:** Docusaurus admonitions and remark-notes conflict.
+
+**Solution:**
+
+They use different syntaxes and shouldn't conflict:
+
+```markdown
+<!-- Docusaurus admonition -->
+:::note
+This is a Docusaurus admonition
+:::
+
+<!-- remark-notes-plugin -->
+> [!note]
+> This is a remark note
+```
+
+Both can coexist. Choose based on preference.
+
+### VitePress: Plugin Not Working
+
+**Problem:** VitePress uses markdown-it, not remark.
+
+**Solution:**
+
+VitePress requires additional configuration as it doesn't use remark by default. Consider:
+
+1. Using VitePress's built-in custom containers instead
+2. Using a markdown-it plugin for similar functionality
+3. Pre-processing markdown files before VitePress build
+
+## Browser Compatibility
+
+### IE11 Support
+
+**Problem:** Notes don't work in Internet Explorer 11.
+
+**Solution:**
+
+IE11 is not supported. The plugin uses modern CSS features:
+- CSS Grid
+- CSS Custom Properties
+- Flexbox
+
+For legacy browser support:
+- Add polyfills
+- Transpile CSS with PostCSS and Autoprefixer
+- Use a CSS-in-JS solution
+
+### Mobile Safari Issues
+
+**Problem:** Rendering issues on iOS Safari.
+
+**Solution:**
+
+The plugin is mobile-optimized. If you encounter issues:
+
+1. **Check your viewport meta tag:**
+   ```html
+   <meta name="viewport" content="width=device-width, initial-scale=1">
+   ```
+
+2. **Test responsive breakpoints:**
+   ```css
+   @media (max-width: 768px) {
+     [class*="remark-note"] {
+       /* Mobile-specific overrides */
+     }
+   }
+   ```
+
+## Getting Help
+
+If your issue isn't covered here:
+
+### 1. Check Existing Issues
+
+Search [GitHub Issues](https://github.com/rishichawda/remark-notes-plugin/issues) for similar problems.
+
+### 2. Create a Minimal Reproduction
+
+Use [StackBlitz](https://stackblitz.com/) or [CodeSandbox](https://codesandbox.io/) to create a minimal example.
+
+### 3. Open an Issue
+
+Include:
+- Node.js version (`node --version`)
+- Package manager version
+- Framework and version
+- Plugin configuration
+- Error messages
+- Minimal reproduction
+
+### 4. Check the Documentation
+
+- [API Reference](/docs/api/overview) - Complete API docs
+- [Framework Integration](/docs/guides/frameworks) - Framework-specific guides
+- [CSS Customization](/docs/customization/styling) - Styling help
+
+## FAQ
+
+### Can I use custom note types?
+
+Not directly. The plugin supports five types: `note`, `tip`, `important`, `quote`, `bonus`. To add custom types, you'd need to fork and modify the source.
+
+### Does it work with rehype plugins?
+
+Yes! Use it in your remark pipeline before converting to rehype:
+
+```javascript
+unified()
+  .use(remarkParse)
+  .use(remarkNotes)
+  .use(remarkRehype)
+  .use(rehypePluginHere)
+  .use(rehypeStringify);
+```
+
+### Can I disable specific note types?
+
+Not built-in, but you can override their styles to hide them:
+
+```css
+[class*="remark-note-bonus"] {
+  display: none;
+}
+```
+
+### Is it compatible with GitHub Flavored Markdown?
+
+Yes! It uses the same `[!type]` syntax as GitHub Alerts, making it compatible.
+
+### Can I change the icons?
+
+Yes, by overriding the CSS and providing your own SVGs or icon fonts:
+
+```css
+[class*="remark-note-icon"] {
+  /* Hide default icon */
+  visibility: hidden;
+}
+
+[class*="remark-note-icon"]::before {
+  visibility: visible;
+  content: '🔔'; /* Your custom icon */
+}
+```
+
+---
+
+Still stuck? [Open an issue](https://github.com/rishichawda/remark-notes-plugin/issues) on GitHub!
diff --git a/docs/docs/intro.md b/docs/docs/intro.md
index 734800c..fbd4c14 100644
--- a/docs/docs/intro.md
+++ b/docs/docs/intro.md
@@ -4,64 +4,237 @@ sidebar_position: 1
 
 # Introduction
 
-**remark-notes-plugin** is a plugin for [remark](https://github.com/remarkjs/remark) that transforms markdown blockquotes into beautifully styled note elements.
+Transform your markdown documentation from plain text to polished content with beautifully styled note callouts.
 
 ![npm](https://img.shields.io/npm/v/remark-notes-plugin)
 ![npm](https://img.shields.io/npm/dt/remark-notes-plugin)
 ![GitHub](https://img.shields.io/github/license/rishichawda/remark-notes-plugin)
 
-## Overview
+## What is remark-notes-plugin?
 
-This plugin enhances your markdown content by converting standard blockquotes into visually distinct note elements, making your documentation more engaging and readable. It supports five different note types:
+**remark-notes-plugin** is a powerful [remark](https://github.com/remarkjs/remark) plugin that automatically converts GitHub-flavored alert syntax into beautifully styled note components. Write simple markdown, get professional-looking callouts.
 
-- **Note**: Standard informational notes
-- **Tip**: Helpful suggestions and advice
-- **Important**: Critical information that requires attention
-- **Quote**: Styled quote blocks
-- **Bonus**: Additional information or features
+```markdown
+> [!tip]
+> Pro tip: This plugin makes your docs look amazing!
+```
+
+Becomes a beautiful, styled tip callout with an icon, custom colors, and professional typography.
+
+## Why Use This Plugin?
+
+### 📝 Familiar Syntax
+
+Uses the same `[!type]` syntax as GitHub Alerts - no new syntax to learn. If you write markdown on GitHub, you already know how to use this plugin.
+
+### 🎨 Professional Design
+
+Five carefully designed note types with:
+
+- Custom icons for each type
+- Thoughtful color palettes
+- Smooth animations and hover effects
+- Full dark mode support
+
+### ⚡ Zero Configuration
+
+Works out of the box with sensible defaults:
+
+- Automatic style injection
+- Responsive design
+- Accessibility built-in
+- No setup required
+
+### 🔧 Fully Customizable
+
+When you need more control:
+
+- Custom CSS class prefixes
+- Manual style import
+- Complete style override capability
+- Framework-specific optimizations
+
+### 🚀 Framework Agnostic
 
-## Features
+Seamlessly integrates with:
 
-- Simple integration with any remark-based markdown pipeline
-- Five distinct note types with different styling
-- Automatic style injection (configurable)
-- Custom CSS class prefixes for better control
-- Easy to use with popular frameworks like Astro, Gatsby, Next.js, and more
-- Fully customizable through CSS
-- Lightweight with minimal dependencies
-- MDX compatible
+- Astro
+- Next.js (App Router & Pages Router)
+- Gatsby
+- Docusaurus
+- Any remark-based system
 
-## Quick Example
+## Quick Start
 
-**Markdown Input**:
+Get up and running in under 2 minutes:
+
+**1. Install**
+
+```bash
+npm install remark-notes-plugin
+```
+
+**2. Configure**
+
+```javascript
+import remarkNotes from 'remark-notes-plugin';
+
+// Add to your remark pipeline
+unified()
+  .use(remarkParse)
+  .use(remarkNotes)  // 👈 That's it!
+  .use(remarkRehype)
+  .use(rehypeStringify);
+```
+
+**3. Write**
 
 ```markdown
 > [!note]
-> This is a note.
+> Now you can write beautiful notes in your markdown!
+```
+
+**Done!** Your notes are now beautifully styled.
+
+## Five Note Types
+
+Each type serves a specific purpose and has its own distinct visual style:
+
+### 📘 Note
+
+For general information, definitions, and helpful context.
+
+> [!note]
+> This is a standard note with a blue theme. Perfect for providing additional context or explaining concepts.
+
+### 💡 Tip
+
+For best practices, helpful suggestions, and pro tips.
 
 > [!tip]
-> This is a tip.
+> Share expert advice and shortcuts that help readers work more efficiently.
+
+### ⚠️ Important
+
+For critical information that demands attention.
 
 > [!important]
-> This is important information.
+> Highlight warnings, requirements, and information that readers must not miss.
+
+### 💬 Quote
+
+For testimonials, quotations, and highlighted text.
 
 > [!quote]
-> This is a quote.
+> "The best way to predict the future is to invent it." — Alan Kay
+
+### ⭐ Bonus
+
+For advanced techniques, optional features, and extra value.
 
 > [!bonus]
-> This is a bonus tip.
+> Go beyond the basics with advanced tips and additional features.
+
+## Features at a Glance
+
+- ✅ **Simple Integration** - Drop into any remark pipeline in seconds
+- ✅ **GitHub-Compatible** - Same syntax as GitHub Alerts
+- ✅ **TypeScript Support** - Full type definitions included
+- ✅ **MDX Compatible** - Works seamlessly with MDX files
+- ✅ **Accessible** - WCAG compliant with proper semantic HTML
+- ✅ **Responsive** - Mobile-optimized out of the box
+- ✅ **Customizable** - Override styles with CSS
+
+## Real-World Use Cases
+
+### Documentation Sites
+
+Make your technical documentation more engaging and scannable:
+
+```markdown
+## Installation
+
+> [!important]
+> Requires Node.js 14 or higher
+
+> [!tip]
+> Use pnpm for faster installs: `pnpm add package-name`
+```
+
+### Blog Posts
+
+Add visual interest and highlight key points:
+
+```markdown
+> [!quote]
+> "This plugin transformed our documentation from boring to beautiful!"
+> — Happy User
+
+> [!bonus]
+> Want to take it further? Check out our advanced customization guide.
 ```
 
-**HTML Output**:
+### Tutorial Content
+
+Structure learning content with clear visual cues:
 
-Beautifully styled note elements that stand out in your content, each with its own distinct appearance based on the note type.
+```markdown
+> [!note]
+> Before starting, make sure you understand JavaScript basics.
 
-<div class="remark-note note"><div class="remark-note-header"><span class="remark-note-icon" data-type="note"><svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg"><g stroke-linecap="round" stroke-linejoin="round" stroke-width="0.048"></g><g><path d="M8 2V5" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" stroke-miterlimit="10"></path><path d="M16 2V5" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" stroke-miterlimit="10"></path><path d="M21 8.5V17C21 20 19.5 22 16 22H8C4.5 22 3 20 3 17V8.5C3 5.5 4.5 3.5 8 3.5H16C19.5 3.5 21 5.5 21 8.5Z" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" stroke-miterlimit="10"></path><path d="M8 11H16" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" stroke-miterlimit="10"></path><path d="M8 16H12" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" stroke-miterlimit="10"></path></g></svg></span><span class="remark-note-title">note</span></div><div class="remark-note-content"><p>This is a note.</p></div></div>
+> [!tip]
+> Follow along by cloning the example repository.
 
-<div class="remark-note tip"><div class="remark-note-header"><span class="remark-note-icon" data-type="tip"><svg viewBox="-0.5 0 25 25" fill="none" xmlns="http://www.w3.org/2000/svg"><g stroke-linecap="round" stroke-linejoin="round"></g><g><path d="M19.0006 9.03002C19.0007 8.10058 18.8158 7.18037 18.4565 6.32317C18.0972 5.46598 17.5709 4.68895 16.9081 4.03734C16.2453 3.38574 15.4594 2.87265 14.5962 2.52801C13.7331 2.18336 12.8099 2.01409 11.8806 2.03002C10.0966 2.08307 8.39798 2.80604 7.12302 4.05504C5.84807 5.30405 5.0903 6.98746 5.00059 8.77001C4.95795 9.9595 5.21931 11.1402 5.75999 12.2006C6.30067 13.2609 7.10281 14.1659 8.09058 14.83C8.36897 15.011 8.59791 15.2584 8.75678 15.5499C8.91565 15.8415 8.99945 16.168 9.00059 16.5V18.03H15.0006V16.5C15.0006 16.1689 15.0829 15.843 15.24 15.5515C15.3971 15.26 15.6241 15.0121 15.9006 14.83C16.8528 14.1911 17.6336 13.328 18.1741 12.3167C18.7147 11.3054 18.9985 10.1767 19.0006 9.03002Z" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"></path><path d="M15 21.04C14.1345 21.6891 13.0819 22.04 12 22.04C10.9181 22.04 9.86548 21.6891 9 21.04" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"></path><path d="M11.9901 5.64001L10.3301 8.41998C10.2549 8.54184 10.2138 8.68167 10.2111 8.82483C10.2084 8.96799 10.2441 9.10925 10.3146 9.23389C10.3851 9.35852 10.4877 9.46195 10.6118 9.53339C10.7359 9.60482 10.8769 9.64165 11.0201 9.64001H13.0201C13.1617 9.63947 13.301 9.67657 13.4237 9.7475C13.5463 9.81843 13.6479 9.92063 13.7181 10.0437C13.7883 10.1668 13.8245 10.3063 13.8231 10.4479C13.8217 10.5896 13.7827 10.7283 13.7101 10.85L12.0301 13.64" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"></path></g></svg></span><span class="remark-note-title">tip</span></div><div class="remark-note-content"><p>This is a tip.</p></div></div>
+> [!important]
+> Save your work before running this command!
+```
 
-<div class="remark-note important"><div class="remark-note-header"><span class="remark-note-icon" data-type="important"><svg viewBox="0 0 18 18" fill="currentColor" xmlns="http://www.w3.org/2000/svg"><g stroke-width="0"></g><g stroke-linecap="round" stroke-linejoin="round"></g><g><path d="M9,14a1.5,1.5,0,1,1,1.5068-1.5A1.5035,1.5035,0,0,1,9,14Z" fill="currentColor"></path><path d="M9,2A7,7,0,1,1,2,9,7.0079,7.0079,0,0,1,9,2M9,0a9,9,0,1,0,9,9A9,9,0,0,0,9,0Z" fill="currentColor"></path><path d="M10,4H8a1,1,0,0,0-.97,1.2425l1,4a1,1,0,0,0,1.94,0l1-4A1,1,0,0,0,10,4Zm0,2h0Z" fill="currentColor"></path></g></svg></span><span class="remark-note-title">important</span></div><div class="remark-note-content">  <p>This is important information.</p></div></div>
+## Browser Support
+
+Works in all modern browsers:
+
+- Chrome/Edge 90+
+- Firefox 88+
+- Safari 14+
+- Mobile browsers (iOS Safari, Chrome Mobile)
+
+## Next Steps
+
+Ready to enhance your markdown? Here's where to go:
+
+<div style={{display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(250px, 1fr))', gap: '1rem', margin: '2rem 0'}}>
+  <div style={{padding: '1.5rem', border: '1px solid #e2e8f0', borderRadius: '8px'}}>
+    <h3 style={{marginTop: 0}}>📦 Installation</h3>
+    <p>Get started in less than 2 minutes</p>
+    <a href="/docs/getting-started/installation">Install Now →</a>
+  </div>
+  
+  <div style={{padding: '1.5rem', border: '1px solid #e2e8f0', borderRadius: '8px'}}>
+    <h3 style={{marginTop: 0}}>📖 Usage Guide</h3>
+    <p>Learn how to use the plugin</p>
+    <a href="/docs/getting-started/usage">View Guide →</a>
+  </div>
+  
+  <div style={{padding: '1.5rem', border: '1px solid #e2e8f0', borderRadius: '8px'}}>
+    <h3 style={{marginTop: 0}}>🎨 Customization</h3>
+    <p>Make it match your design system</p>
+    <a href="/docs/customization/styling">Customize →</a>
+  </div>
+  
+  <div style={{padding: '1.5rem', border: '1px solid #e2e8f0', borderRadius: '8px'}}>
+    <h3 style={{marginTop: 0}}>🔌 Frameworks</h3>
+    <p>Integration guides for popular tools</p>
+    <a href="/docs/guides/frameworks">See Integrations →</a>
+  </div>
+</div>
+
+## Questions?
+
+- **Need help?** Check our [troubleshooting guide](/docs/guides/troubleshooting)
+- **Want the full API?** See the [API reference](/docs/api/overview)
+- **Found a bug?** [Open an issue](https://github.com/rishichawda/remark-notes-plugin/issues)
+- **Want to contribute?** [View the repo](https://github.com/rishichawda/remark-notes-plugin)
 
-<div class="quote remark-note"><div class="remark-note-header"><span class="remark-note-icon" data-type="quote"><svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg"><g stroke-linecap="round" stroke-linejoin="round"></g><g><path d="M14 15V14C14 13.0681 14 12.6022 14.1522 12.2346C14.3552 11.7446 14.7446 11.3552 15.2346 11.1522C15.6022 11 16.0681 11 17 11H17.5C18.9045 11 19.6067 11 20.1111 11.3371C20.3295 11.483 20.517 11.6705 20.6629 11.8889C21 12.3933 21 13.0955 21 14.5V15.3431C21 16.1606 21 16.5694 20.8478 16.9369C20.6955 17.3045 20.4065 17.5935 19.8284 18.1716L19.2396 18.7604C18.7822 19.2178 18 18.8938 18 18.2469V17.8787C18 17.3934 17.6066 17 17.1213 17H16C14.8954 17 14 16.1046 14 15Z" stroke-linejoin="round" stroke-width="1.5"></path><path d="M3 9V8C3 7.06812 3 6.60218 3.15224 6.23463C3.35523 5.74458 3.74458 5.35523 4.23463 5.15224C4.60218 5 5.06812 5 6 5H6.5C7.90446 5 8.60669 5 9.11114 5.33706C9.32952 5.48298 9.51702 5.67048 9.66294 5.88886C10 6.39331 10 7.09554 10 8.5V9.34315C10 10.1606 10 10.5694 9.84776 10.9369C9.69552 11.3045 9.40649 11.5935 8.82843 12.1716L8.23965 12.7604C7.78219 13.2178 7 12.8938 7 12.2469V11.8787C7 11.3934 6.6066 11 6.12132 11H5C3.89543 11 3 10.1046 3 9Z" stroke-linejoin="round" stroke-width="1.5"></path></g></svg></span><span class="remark-note-title">quote</span></div><div class="remark-note-content"><p>This is a quote.</p></div></div>
+---
 
-<div class="remark-note bonus"><div class="remark-note-header"><span class="remark-note-icon" data-type="bonus"><svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg"><g stroke-linecap="round" stroke-linejoin="round"></g><g><path d="M9.23163 8.61762C7.26389 9.06284 6.28001 9.28545 6.04594 10.0382C5.81186 10.7909 6.4826 11.5753 7.82408 13.1439L8.17113 13.5498C8.55234 13.9955 8.74294 14.2184 8.82869 14.4942C8.91444 14.7699 8.88562 15.0673 8.82799 15.662L8.77552 16.2035C8.5727 18.2965 8.4713 19.343 9.08412 19.8082C9.69694 20.2734 10.6181 19.8492 12.4605 19.0009L12.9372 18.7815C13.4607 18.5404 13.7225 18.4199 14 18.4199C14.2775 18.4199 14.5393 18.5404 15.0628 18.7815L15.5395 19.0009C17.3819 19.8492 18.3031 20.2734 18.9159 19.8082C19.5287 19.343 19.4273 18.2965 19.2245 16.2035M20.1759 13.1439C21.5174 11.5753 22.1881 10.7909 21.9541 10.0382C21.72 9.28545 20.7361 9.06284 18.7684 8.61762L18.2593 8.50244C17.7001 8.37592 17.4205 8.31266 17.196 8.14225C16.9716 7.97183 16.8276 7.71355 16.5396 7.19699L16.2775 6.7267C15.2641 4.9089 14.7575 4 14 4C13.2425 4 12.7359 4.9089 11.7225 6.7267" stroke-width="1.5" stroke-linecap="round"></path><path d="M2.08887 16C3.20445 15.121 4.68639 14.7971 6.08887 15.1257" stroke-width="1.5" stroke-linecap="round"></path><path d="M2.08887 10.5C3.08887 10 3.37862 10.0605 4.08887 10" stroke-width="1.5" stroke-linecap="round"></path><path d="M2 5.60867L2.20816 5.48676C4.41383 4.19506 6.75032 3.84687 8.95304 4.48161L9.16092 4.54152" stroke-width="1.5" stroke-linecap="round"></path></g></svg></span><span class="remark-note-title">bonus</span></div><div class="remark-note-content"><p>This is a bonus tip.</p></div></div>
\ No newline at end of file
+Built with ❤️ for the markdown community. [Star us on GitHub](https://github.com/rishichawda/remark-notes-plugin) ⭐
diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts
index 2be0b81..ad9fdc2 100644
--- a/docs/docusaurus.config.ts
+++ b/docs/docusaurus.config.ts
@@ -7,7 +7,7 @@ import remarkNotes from 'remark-notes-plugin';
 
 const config: Config = {
   title: 'Remark Notes Plugin',
-  tagline: 'Transform markdown quotes into beautiful note elements',
+  tagline: 'Transform markdown blockquotes into beautiful, professional note components',
   favicon: 'img/favicon.ico',
 
   // Set the production url of your site here
@@ -44,11 +44,22 @@ const config: Config = {
             'https://github.com/rishichawda/remark-notes-plugin/tree/main/docs',
           // Add remark plugin to process notes
           remarkPlugins: [remarkNotes],
+          showLastUpdateTime: true,
+          showLastUpdateAuthor: true,
         },
         blog: false, // We don't need a blog for this project
         theme: {
           customCss: './src/css/custom.css',
         },
+        sitemap: {
+          changefreq: 'weekly',
+          priority: 0.5,
+        },
+        // Google Analytics (optional - uncomment and add your tracking ID)
+        // gtag: {
+        //   trackingID: 'G-XXXXXXXXXX',
+        //   anonymizeIP: true,
+        // },
       } satisfies Preset.Options,
     ],
   ],
@@ -56,6 +67,23 @@ const config: Config = {
   themeConfig: {
     // Replace with your project's social card
     image: 'img/remark-notes-social-card.jpg',
+    
+    // Announcement bar
+    announcementBar: {
+      id: 'support_us',
+      content: '⭐ If you like remark-notes-plugin, give it a star on <a target="_blank" rel="noopener noreferrer" href="https://github.com/rishichawda/remark-notes-plugin">GitHub</a>!',
+      backgroundColor: '#667eea',
+      textColor: '#ffffff',
+      isCloseable: true,
+    },
+    
+    metadata: [
+      {name: 'keywords', content: 'remark, markdown, notes, callouts, documentation, plugin, mdx, astro, next.js'},
+      {name: 'description', content: 'A powerful remark plugin that transforms markdown blockquotes into beautiful, professional note components. Perfect for documentation, blogs, and technical writing.'},
+      {name: 'author', content: 'rishichawda'},
+      {name: 'og:type', content: 'website'},
+      {name: 'twitter:card', content: 'summary_large_image'},
+    ],
     navbar: {
       title: 'Remark Notes Plugin',
       logo: {
@@ -69,36 +97,94 @@ const config: Config = {
           position: 'left',
           label: 'Documentation',
         },
+        {
+          type: 'dropdown',
+          label: 'Quick Links',
+          position: 'left',
+          items: [
+            {
+              label: 'Getting Started',
+              to: '/docs/getting-started/installation',
+            },
+            {
+              label: 'API Reference',
+              to: '/docs/api/overview',
+            },
+            {
+              label: 'Framework Integration',
+              to: '/docs/guides/frameworks',
+            },
+            {
+              label: 'Customization',
+              to: '/docs/customization/styling',
+            },
+          ],
+        },
+        {
+          href: 'https://www.npmjs.com/package/remark-notes-plugin',
+          label: 'npm',
+          position: 'right',
+        },
         {
           href: 'https://github.com/rishichawda/remark-notes-plugin',
           label: 'GitHub',
           position: 'right',
         },
       ],
+      hideOnScroll: true,
     },
     footer: {
       style: 'dark',
       links: [
         {
-          title: 'Docs',
+          title: 'Documentation',
           items: [
             {
-              label: 'Getting Started',
+              label: 'Introduction',
               to: '/docs/intro',
             },
+            {
+              label: 'Getting Started',
+              to: '/docs/getting-started/installation',
+            },
+            {
+              label: 'API Reference',
+              to: '/docs/api/overview',
+            },
           ],
         },
         {
-          title: 'More',
+          title: 'Resources',
+          items: [
+            {
+              label: 'Framework Integration',
+              to: '/docs/guides/frameworks',
+            },
+            {
+              label: 'Customization',
+              to: '/docs/customization/styling',
+            },
+            {
+              label: 'Troubleshooting',
+              to: '/docs/guides/troubleshooting',
+            },
+          ],
+        },
+        {
+          title: 'Community',
           items: [
             {
               label: 'GitHub',
               href: 'https://github.com/rishichawda/remark-notes-plugin',
             },
             {
-              label: 'npm',
+              label: 'npm Package',
               href: 'https://www.npmjs.com/package/remark-notes-plugin',
             },
+            {
+              label: 'Issues',
+              href: 'https://github.com/rishichawda/remark-notes-plugin/issues',
+            },
           ],
         },
       ],
@@ -107,8 +193,30 @@ const config: Config = {
     prism: {
       theme: prismThemes.github,
       darkTheme: prismThemes.dracula,
-      additionalLanguages: ['bash', 'diff', 'json', 'markdown'],
+      additionalLanguages: ['bash', 'diff', 'json', 'markdown', 'typescript', 'jsx', 'tsx'],
+    },
+    colorMode: {
+      defaultMode: 'light',
+      disableSwitch: false,
+      respectPrefersColorScheme: true,
+    },
+    docs: {
+      sidebar: {
+        hideable: true,
+        autoCollapseCategories: true,
+      },
+    },
+    tableOfContents: {
+      minHeadingLevel: 2,
+      maxHeadingLevel: 4,
     },
+    
+    // Algolia search (optional - configure when ready)
+    // algolia: {
+    //   appId: 'YOUR_APP_ID',
+    //   apiKey: 'YOUR_SEARCH_API_KEY',
+    //   indexName: 'remark-notes-plugin',
+    // },
   } satisfies Preset.ThemeConfig,
 };
 
diff --git a/docs/sidebars.ts b/docs/sidebars.ts
index 3620dfc..d6b8670 100644
--- a/docs/sidebars.ts
+++ b/docs/sidebars.ts
@@ -14,10 +14,14 @@ import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
  */
 const sidebars: SidebarsConfig = {
   tutorialSidebar: [
-    'intro',
+    {
+      type: 'doc',
+      id: 'intro',
+      label: '👋 Introduction',
+    },
     {
       type: 'category',
-      label: 'Getting Started',
+      label: '🚀 Getting Started',
       collapsed: false,
       items: [
         'getting-started/installation',
@@ -27,13 +31,38 @@ const sidebars: SidebarsConfig = {
     },
     {
       type: 'category',
-      label: 'Examples',
+      label: '📚 Guides',
+      collapsed: false,
+      items: [
+        'guides/frameworks',
+        'guides/troubleshooting',
+      ],
+    },
+    {
+      type: 'category',
+      label: '🎨 Customization',
+      collapsed: false,
+      items: [
+        'customization/styling',
+      ],
+    },
+    {
+      type: 'category',
+      label: '💡 Examples',
       collapsed: false,
       items: [
         'examples/note-types',
         'examples/customization',
       ],
     },
+    {
+      type: 'category',
+      label: '📖 API Reference',
+      collapsed: false,
+      items: [
+        'api/overview',
+      ],
+    },
   ],
 };
 
diff --git a/docs/src/components/HomepageFeatures/index.tsx b/docs/src/components/HomepageFeatures/index.tsx
index b819de8..c7357d9 100644
--- a/docs/src/components/HomepageFeatures/index.tsx
+++ b/docs/src/components/HomepageFeatures/index.tsx
@@ -5,38 +5,98 @@ import styles from './styles.module.css';
 
 type FeatureItem = {
   title: string;
-  icon: string;
+  icon: ReactNode;
   description: ReactNode;
 };
 
 const FeatureList: FeatureItem[] = [
   {
     title: 'Simple Integration',
-    icon: '🔌',
+    icon: (
+      <svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+        <path d="M13 2L3 14h8l-1 8 10-12h-8l1-8z" fill="currentColor"/>
+      </svg>
+    ),
+    description: (
+      <>
+        Drop into any remark-based pipeline. Works seamlessly with Astro, Next.js, 
+        Gatsby, Docusaurus, and other static site generators.
+      </>
+    ),
+  },
+  {
+    title: 'Five Note Types',
+    icon: (
+      <svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+        <rect x="3" y="3" width="7" height="7" rx="1" fill="currentColor" opacity="0.9"/>
+        <rect x="14" y="3" width="7" height="7" rx="1" fill="currentColor" opacity="0.7"/>
+        <rect x="3" y="14" width="7" height="7" rx="1" fill="currentColor" opacity="0.8"/>
+        <rect x="14" y="14" width="7" height="7" rx="1" fill="currentColor" opacity="0.6"/>
+        <circle cx="7" cy="7" r="2" fill="white" opacity="0.3"/>
+      </svg>
+    ),
     description: (
       <>
-        Easy to integrate with any remark-based markdown processing pipeline,
-        including Astro, Gatsby, and other static site generators.
+        Note, Tip, Important, Quote, and Bonus - each with distinct styling 
+        and semantic meaning for better content organization.
       </>
     ),
   },
   {
-    title: 'Multiple Note Types',
-    icon: '🎨',
+    title: 'Zero Configuration',
+    icon: (
+      <svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+        <circle cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="2"/>
+        <path d="M8 12l2 2 4-4" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"/>
+      </svg>
+    ),
     description: (
       <>
-        Supports 5 different note types - Note, Tip, Important, Quote, and Bonus - each with
-        distinct styling for better content organization.
+        Works out of the box with automatic style injection. Customize with 
+        optional configurations for advanced use cases.
       </>
     ),
   },
   {
-    title: 'Elegant Design',
-    icon: '✨',
+    title: 'Fully Customizable',
+    icon: (
+      <svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+        <path d="M12 2L14.5 9.5L22 12L14.5 14.5L12 22L9.5 14.5L2 12L9.5 9.5L12 2Z" fill="currentColor"/>
+      </svg>
+    ),
     description: (
       <>
-        Transform plain blockquotes into beautifully styled note elements that enhance
-        your content's readability and visual appeal.
+        Override default styles, add custom class prefixes, and control style 
+        injection for perfect integration with your design system.
+      </>
+    ),
+  },
+  {
+    title: 'TypeScript Ready',
+    icon: (
+      <svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+        <rect x="2" y="3" width="20" height="18" rx="2" stroke="currentColor" strokeWidth="2"/>
+        <path d="M8 8L8 16M12 10v6M16 12v4" stroke="currentColor" strokeWidth="2" strokeLinecap="round"/>
+      </svg>
+    ),
+    description: (
+      <>
+        Full TypeScript support with exported types for options and note types. 
+        Enjoy autocomplete and type safety in your editor.
+      </>
+    ),
+  },
+  {
+    title: 'MDX Compatible',
+    icon: (
+      <svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+        <path d="M4 4h7l-7 16h7M20 4h-7l7 16h-7" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"/>
+      </svg>
+    ),
+    description: (
+      <>
+        Seamlessly works with MDX files. Transform your markdown notes without 
+        worrying about compatibility issues.
       </>
     ),
   },
@@ -45,12 +105,12 @@ const FeatureList: FeatureItem[] = [
 function Feature({title, icon, description}: FeatureItem) {
   return (
     <div className={clsx('col col--4')}>
-      <div className="text--center">
+      <div className={styles.featureCard}>
         <div className={styles.featureIcon}>{icon}</div>
-      </div>
-      <div className="text--center padding-horiz--md">
-        <Heading as="h3">{title}</Heading>
-        <p>{description}</p>
+        <div className={styles.featureContent}>
+          <Heading as="h3" className={styles.featureTitle}>{title}</Heading>
+          <p className={styles.featureDescription}>{description}</p>
+        </div>
       </div>
     </div>
   );
@@ -60,7 +120,15 @@ export default function HomepageFeatures(): ReactNode {
   return (
     <section className={styles.features}>
       <div className="container">
-        <div className="row">
+        <div className={styles.featuresHeader}>
+          <Heading as="h2" className={styles.featuresTitle}>
+            Why Choose Remark Notes?
+          </Heading>
+          <p className={styles.featuresSubtitle}>
+            Everything you need to create beautiful documentation
+          </p>
+        </div>
+        <div className="row" style={{gap: '20px 0'}}>
           {FeatureList.map((props, idx) => (
             <Feature key={idx} {...props} />
           ))}
diff --git a/docs/src/components/HomepageFeatures/styles.module.css b/docs/src/components/HomepageFeatures/styles.module.css
index 2d0f0ac..fe9201a 100644
--- a/docs/src/components/HomepageFeatures/styles.module.css
+++ b/docs/src/components/HomepageFeatures/styles.module.css
@@ -1,11 +1,145 @@
 .features {
+  padding: 5rem 0;
+  background: white;
+}
+
+[data-theme='dark'] .features {
+  background: #1a202c;
+}
+
+.featuresHeader {
+  text-align: center;
+  margin-bottom: 4rem;
+}
+
+.featuresTitle {
+  font-size: 2.5rem;
+  font-weight: 800;
+  margin-bottom: 1rem;
+  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+  -webkit-background-clip: text;
+  -webkit-text-fill-color: transparent;
+  background-clip: text;
+}
+
+[data-theme='dark'] .featuresTitle {
+  background: linear-gradient(135deg, #818cf8 0%, #a78bfa 100%);
+  -webkit-background-clip: text;
+  -webkit-text-fill-color: transparent;
+  background-clip: text;
+}
+
+.featuresSubtitle {
+  font-size: 1.2rem;
+  color: #64748b;
+}
+
+[data-theme='dark'] .featuresSubtitle {
+  color: #94a3b8;
+}
+
+.featureCard {
+  height: 100%;
+  padding: 2rem;
+  background: linear-gradient(135deg, #f8fafc 0%, #ffffff 100%);
+  border-radius: 16px;
+  border: 1px solid #e2e8f0;
+  transition: all 0.3s ease;
+  margin-bottom: 2rem;
+}
+
+.featureCard:hover {
+  transform: translateY(-4px);
+  box-shadow: 0 12px 24px rgba(102, 126, 234, 0.15);
+  border-color: #667eea;
+}
+
+[data-theme='dark'] .featureCard {
+  background: linear-gradient(135deg, #2d3748 0%, #1a202c 100%);
+  border-color: #4a5568;
+}
+
+[data-theme='dark'] .featureCard:hover {
+  box-shadow: 0 12px 24px rgba(129, 140, 248, 0.2);
+  border-color: #818cf8;
+}
+
+.featureIcon {
+  width: 64px;
+  height: 64px;
+  margin: 0 auto 1.5rem;
   display: flex;
   align-items: center;
-  padding: 2rem 0;
-  width: 100%;
+  justify-content: center;
+  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+  color: white;
+  border-radius: 12px;
+  font-size: 2rem;
+  box-shadow: 0 4px 12px rgba(102, 126, 234, 0.3);
 }
 
-.featureIcon {
-  font-size: 3rem;
-  margin-bottom: 1rem;
+[data-theme='dark'] .featureIcon {
+  background: linear-gradient(135deg, #4c51bf 0%, #553c9a 100%);
+}
+
+.featureIcon svg {
+  width: 32px;
+  height: 32px;
+}
+
+.featureContent {
+  text-align: center;
+}
+
+.featureTitle {
+  font-size: 1.5rem;
+  font-weight: 700;
+  margin-bottom: 0.75rem;
+  color: #1e293b;
+}
+
+[data-theme='dark'] .featureTitle {
+  color: #f1f5f9;
+}
+
+.featureDescription {
+  font-size: 1rem;
+  line-height: 1.6;
+  color: #64748b;
+  margin: 0;
 }
+
+[data-theme='dark'] .featureDescription {
+  color: #94a3b8;
+}
+
+@media (max-width: 996px) {
+  .features {
+    padding: 3rem 0;
+  }
+
+  .featuresHeader {
+    margin-bottom: 2.5rem;
+  }
+
+  .featuresTitle {
+    font-size: 2rem;
+  }
+}
+
+@media (max-width: 768px) {
+  .featureCard {
+    padding: 1.5rem;
+  }
+
+  .featureIcon {
+    width: 56px;
+    height: 56px;
+  }
+
+  .featureIcon svg {
+    width: 28px;
+    height: 28px;
+  }
+}
+
diff --git a/docs/src/css/custom.css b/docs/src/css/custom.css
index 8181c56..03d9296 100644
--- a/docs/src/css/custom.css
+++ b/docs/src/css/custom.css
@@ -9,94 +9,293 @@
 
 /* You can override the default Infima variables here. */
 :root {
-  --ifm-color-primary: #25c2a0;
-  --ifm-color-primary-dark: #21af90;
-  --ifm-color-primary-darker: #1fa588;
-  --ifm-color-primary-darkest: #1a8870;
-  --ifm-color-primary-light: #29d5b0;
-  --ifm-color-primary-lighter: #32d8b4;
-  --ifm-color-primary-lightest: #4fddbf;
+  --ifm-color-primary: #667eea;
+  --ifm-color-primary-dark: #4c5fd6;
+  --ifm-color-primary-darker: #4353cf;
+  --ifm-color-primary-darkest: #3543a9;
+  --ifm-color-primary-light: #808dfa;
+  --ifm-color-primary-lighter: #949fff;
+  --ifm-color-primary-lightest: #b8c2ff;
+  --ifm-code-font-size: 95%;
+  --ifm-font-family-base: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+  --ifm-heading-font-weight: 700;
   --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1);
-
-  /* Note type colors */
-  --note-color: #4285f4;
-  --tip-color: #0f9d58;
-  --important-color: #db4437;
-  --quote-color: #9c27b0;
-  --bonus-color: #ff9800;
+  
+  /* Custom color palette */
+  --color-note: #318CE7;
+  --color-tip: #7ccf00;
+  --color-important: #EF9B0F;
+  --color-quote: #8C92AC;
+  --color-bonus: #9966CC;
+  
+  /* Spacing */
+  --ifm-leading: 1.6;
+  --ifm-spacing-horizontal: 1.5rem;
+  --ifm-spacing-vertical: 1.5rem;
 }
 
 /* For readability concerns, you should choose a lighter palette in dark mode. */
 [data-theme='dark'] {
-  --ifm-color-primary: #25c2a0;
-  --ifm-color-primary-dark: #21af90;
-  --ifm-color-primary-darker: #1fa588;
-  --ifm-color-primary-darkest: #1a8870;
-  --ifm-color-primary-light: #29d5b0;
-  --ifm-color-primary-lighter: #32d8b4;
-  --ifm-color-primary-lightest: #4fddbf;
-  --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
-
-  /* Note type colors - slightly brighter for dark mode */
-  --note-color: #669df6;
-  --tip-color: #34a853;
-  --important-color: #ea4335;
-  --quote-color: #b455c9;
-  --bonus-color: #ffa726;
-}
-
-/* Styles for remark-notes-plugin notes */
-/* .remark-note {
+  --ifm-color-primary: #818cf8;
+  --ifm-color-primary-dark: #6571f6;
+  --ifm-color-primary-darker: #5663f5;
+  --ifm-color-primary-darkest: #2f40f0;
+  --ifm-color-primary-light: #9da7fa;
+  --ifm-color-primary-lighter: #acb5fb;
+  --ifm-color-primary-lightest: #d8dcfd;
+  --docusaurus-highlighted-code-line-bg: rgba(129, 140, 248, 0.1);
+  --ifm-background-color: #1a202c;
+  --ifm-background-surface-color: #2d3748;
+  
+  /* Dark mode note colors - slightly brighter */
+  --color-note: #60a5fa;
+  --color-tip: #86e62b;
+  --color-important: #fbbf24;
+  --color-quote: #a5b4c9;
+  --color-bonus: #a78bfa;
+}
+
+/* Enhanced typography */
+html {
+  font-size: 16px;
+  scroll-behavior: smooth;
+}
+
+body {
+  font-family: var(--ifm-font-family-base);
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+h1, h2, h3, h4, h5, h6 {
+  font-weight: var(--ifm-heading-font-weight);
+  letter-spacing: -0.01em;
+}
+
+/* Code blocks improvements */
+code {
+  background-color: rgba(102, 126, 234, 0.1);
+  border-radius: 4px;
+  padding: 0.15rem 0.3rem;
+  font-size: 0.9em;
+}
+
+[data-theme='dark'] code {
+  background-color: rgba(129, 140, 248, 0.15);
+}
+
+pre code {
+  background-color: transparent;
+  padding: 0;
+}
+
+/* Improved code block styling */
+.theme-code-block {
+  border-radius: 12px;
+  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
   margin: 1.5rem 0;
-  padding: 1rem;
-  border-radius: 0.5rem;
-  border-left: 0.25rem solid var(--note-color);
-  background-color: var(--ifm-color-emphasis-100);
-  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.05);
-} */
+}
 
-/* .remark-note-title {
+/* Navbar enhancements */
+.navbar {
+  backdrop-filter: blur(10px);
+  background-color: rgba(255, 255, 255, 0.95);
+  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.05);
+}
+
+[data-theme='dark'] .navbar {
+  background-color: rgba(26, 32, 44, 0.95);
+  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.2);
+}
+
+.navbar__title {
+  font-weight: 700;
+  font-size: 1.1rem;
+}
+
+/* Sidebar improvements */
+.theme-doc-sidebar-container {
+  border-right: 1px solid var(--ifm-toc-border-color);
+}
+
+.menu__link {
+  border-radius: 8px;
+  transition: all 0.2s ease;
+}
+
+.menu__link:hover {
+  background-color: rgba(102, 126, 234, 0.1);
+}
+
+[data-theme='dark'] .menu__link:hover {
+  background-color: rgba(129, 140, 248, 0.15);
+}
+
+.menu__link--active {
+  background-color: rgba(102, 126, 234, 0.15);
   font-weight: 600;
-  margin-bottom: 0.5rem;
-  color: var(--note-color);
-} */
+}
 
-/* Styles for different note types */
-/* .remark-note {
-  border-left-color: var(--note-color);
+[data-theme='dark'] .menu__link--active {
+  background-color: rgba(129, 140, 248, 0.2);
 }
 
-.remark-note-tip {
-  border-left-color: var(--tip-color);
+/* Footer improvements */
+.footer {
+  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+  color: white;
 }
 
-.remark-note-tip .remark-note-title {
-  color: var(--tip-color);
+[data-theme='dark'] .footer {
+  background: linear-gradient(135deg, #4c51bf 0%, #553c9a 100%);
+}
+
+.footer__title {
+  color: white;
+  font-weight: 700;
+}
+
+.footer__link-item {
+  color: rgba(255, 255, 255, 0.9);
+  transition: color 0.2s ease;
+}
+
+.footer__link-item:hover {
+  color: white;
+  text-decoration: underline;
+}
+
+.footer__copyright {
+  color: rgba(255, 255, 255, 0.8);
+}
+
+/* Table of Contents improvements */
+.table-of-contents {
+  font-size: 0.9rem;
+}
+
+.table-of-contents__link {
+  color: var(--ifm-color-emphasis-700);
+  transition: all 0.2s ease;
+}
+
+.table-of-contents__link:hover {
+  color: var(--ifm-color-primary);
+  text-decoration: none;
+}
+
+.table-of-contents__link--active {
+  color: var(--ifm-color-primary);
+  font-weight: 600;
+}
+
+/* Pagination improvements */
+.pagination-nav__link {
+  border-radius: 12px;
+  border: 1px solid var(--ifm-color-emphasis-300);
+  transition: all 0.3s ease;
+}
+
+.pagination-nav__link:hover {
+  border-color: var(--ifm-color-primary);
+  box-shadow: 0 4px 12px rgba(102, 126, 234, 0.15);
+  transform: translateY(-2px);
+}
+
+/* Admonition enhancements (keep for other admonitions) */
+.admonition {
+  border-radius: 8px;
+  border-left-width: 4px;
+  margin: 1.5rem 0;
+}
+
+/* Improved link styles */
+.markdown a {
+  color: var(--ifm-color-primary);
+  text-decoration: none;
+  border-bottom: 1px solid transparent;
+  transition: border-bottom-color 0.2s ease;
+}
+
+.markdown a:hover {
+  border-bottom-color: var(--ifm-color-primary);
+}
+
+/* Smooth animations */
+* {
+  transition-property: background-color, border-color, color, fill, stroke;
+  transition-duration: 0.2s;
+  transition-timing-function: ease-in-out;
+}
+
+*:where(:not(:active):not(:focus)) {
+  transition-property: background-color, border-color, color, fill, stroke;
+}
+
+/* Better spacing for content */
+.markdown > * {
+  margin-bottom: 1.5rem;
+}
+
+.markdown h2 {
+  margin-top: 3rem;
+  margin-bottom: 1rem;
+}
+
+.markdown h3 {
+  margin-top: 2rem;
+  margin-bottom: 0.75rem;
+}
+
+/* Improved blockquote (for non-note blockquotes) */
+.markdown blockquote:not([class*="remark-note"]) {
+  border-left: 4px solid var(--ifm-color-primary);
+  padding-left: 1rem;
+  color: var(--ifm-color-emphasis-700);
+  font-style: italic;
+}
+
+/* Enhanced buttons */
+.button {
+  border-radius: 8px;
+  font-weight: 600;
+  transition: all 0.3s ease;
 }
 
-.remark-note-important {
-  border-left-color: var(--important-color);
+.button:hover {
+  transform: translateY(-2px);
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
 }
 
-.remark-note-important .remark-note-title {
-  color: var(--important-color);
+/* Search improvements */
+.navbar__search-input {
+  border-radius: 8px;
+  border: 1px solid var(--ifm-color-emphasis-300);
 }
 
-.remark-note-quote {
-  border-left-color: var(--quote-color);
+.navbar__search-input:focus {
+  border-color: var(--ifm-color-primary);
+  box-shadow: 0 0 0 3px rgba(102, 126, 234, 0.1);
 }
 
-.remark-note-quote .remark-note-title {
-  color: var(--quote-color);
+/* Responsive improvements */
+@media (max-width: 996px) {
+  :root {
+    --ifm-spacing-horizontal: 1rem;
+    --ifm-spacing-vertical: 1rem;
+  }
+  
+  html {
+    font-size: 15px;
+  }
 }
 
-.remark-note-bonus {
-  border-left-color: var(--bonus-color);
+@media (max-width: 768px) {
+  html {
+    font-size: 14px;
+  }
 }
 
-.remark-note-bonus .remark-note-title {
-  color: var(--bonus-color);
-} */
 
 /* Dark mode styles */
 [data-theme='dark'] .remark-note {
diff --git a/docs/src/pages/index.module.css b/docs/src/pages/index.module.css
index 4003ed0..1516f63 100644
--- a/docs/src/pages/index.module.css
+++ b/docs/src/pages/index.module.css
@@ -3,37 +3,278 @@
  * and scoped locally.
  */
 
+/* Hero Section */
 .heroBanner {
-  padding: 4rem 0;
+  padding: 6rem 0 4rem;
   text-align: center;
   position: relative;
   overflow: hidden;
+  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
 }
 
-@media screen and (max-width: 996px) {
-  .heroBanner {
-    padding: 2rem;
+[data-theme='dark'] .heroBanner {
+  background: linear-gradient(135deg, #4c51bf 0%, #553c9a 100%);
+}
+
+.heroContent {
+  position: relative;
+  z-index: 1;
+}
+
+.logoContainer {
+  display: inline-block;
+  margin-bottom: 1.5rem;
+  animation: float 3s ease-in-out infinite;
+}
+
+@keyframes float {
+  0%, 100% {
+    transform: translateY(0);
+  }
+  50% {
+    transform: translateY(-10px);
   }
 }
 
+.heroLogo {
+  width: 120px;
+  height: 120px;
+  filter: drop-shadow(0 4px 12px rgba(0, 0, 0, 0.2));
+}
+
+.heroTitle {
+  font-size: 3.5rem;
+  font-weight: 800;
+  color: white;
+  margin-bottom: 1rem;
+  letter-spacing: -0.02em;
+  line-height: 1.2;
+}
+
+.heroSubtitle {
+  font-size: 1.5rem;
+  color: rgba(255, 255, 255, 0.95);
+  margin-bottom: 1rem;
+  font-weight: 500;
+}
+
+.heroDescription {
+  font-size: 1.1rem;
+  color: rgba(255, 255, 255, 0.85);
+  max-width: 700px;
+  margin: 0 auto 2.5rem;
+  line-height: 1.6;
+}
+
 .buttons {
   display: flex;
   align-items: center;
   justify-content: center;
+  gap: 1rem;
+  flex-wrap: wrap;
+  margin-bottom: 2rem;
 }
 
-.logoContainer {
+.buttonPrimary {
+  background: white;
+  color: #667eea;
+  border: none;
+  font-weight: 600;
+  transition: all 0.3s ease;
+  box-shadow: 0 4px 14px rgba(0, 0, 0, 0.15);
+}
+
+.buttonPrimary:hover {
+  background: #f7fafc;
+  color: #667eea;
+  transform: translateY(-2px);
+  box-shadow: 0 6px 20px rgba(0, 0, 0, 0.2);
+}
+
+.buttonSecondary {
+  background: transparent;
+  color: white;
+  border: 2px solid white;
+  font-weight: 600;
+  transition: all 0.3s ease;
   display: flex;
+  align-items: center;
   justify-content: center;
-  margin-bottom: 2rem;
 }
 
-.heroLogo {
-  width: 200px;
-  height: 200px;
-  transition: transform 0.3s ease;
+.buttonSecondary:hover {
+  background: white;
+  color: #667eea;
+  border-color: white;
+  transform: translateY(-2px);
+}
+
+.quickStart {
+  margin-top: 2rem;
+}
+
+.installCommand {
+  display: inline-block;
+  background: rgba(0, 0, 0, 0.2);
+  color: white;
+  padding: 0.75rem 1.5rem;
+  border-radius: 8px;
+  font-family: 'Monaco', 'Menlo', 'Ubuntu Mono', monospace;
+  font-size: 1rem;
+  border: 1px solid rgba(255, 255, 255, 0.3);
+  backdrop-filter: blur(10px);
+}
+
+/* Live Demo Section */
+.demoSection {
+  padding: 5rem 0;
+  background: linear-gradient(to bottom, #f7fafc 0%, #ffffff 100%);
+}
+
+[data-theme='dark'] .demoSection {
+  background: linear-gradient(to bottom, #1a202c 0%, #2d3748 100%);
+}
+
+.sectionTitle {
+  font-size: 2.5rem;
+  font-weight: 800;
+  text-align: center;
+  margin-bottom: 0.75rem;
+  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+  -webkit-background-clip: text;
+  -webkit-text-fill-color: transparent;
+  background-clip: text;
+}
+
+[data-theme='dark'] .sectionTitle {
+  background: linear-gradient(135deg, #818cf8 0%, #a78bfa 100%);
+  -webkit-background-clip: text;
+  -webkit-text-fill-color: transparent;
+  background-clip: text;
+}
+
+.sectionSubtitle {
+  text-align: center;
+  font-size: 1.2rem;
+  color: #64748b;
+  margin-bottom: 3rem;
+}
+
+[data-theme='dark'] .sectionSubtitle {
+  color: #94a3b8;
 }
 
-.heroLogo:hover {
-  transform: scale(1.05);
+.demoGrid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 2rem;
+  max-width: 1400px;
+  margin: 0 auto;
 }
+
+@media (max-width: 996px) {
+  .demoGrid {
+    grid-template-columns: 1fr;
+  }
+}
+
+.demoColumn {
+  display: flex;
+  flex-direction: column;
+}
+
+.demoHeading {
+  font-size: 1.25rem;
+  font-weight: 700;
+  margin-bottom: 1rem;
+  color: #334155;
+}
+
+[data-theme='dark'] .demoHeading {
+  color: #e2e8f0;
+}
+
+.demoCode {
+  background: #1e293b;
+  color: #e2e8f0;
+  padding: 1.5rem;
+  border-radius: 12px;
+  overflow-x: auto;
+  font-family: 'Monaco', 'Menlo', 'Ubuntu Mono', monospace;
+  font-size: 0.9rem;
+  line-height: 1.6;
+  flex: 1;
+  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
+  border: 1px solid #334155;
+}
+
+.demoNotes {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+  background: white;
+  padding: 1.5rem;
+  border-radius: 12px;
+  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
+  border: 1px solid #e2e8f0;
+}
+
+[data-theme='dark'] .demoNotes {
+  background: #0f172a;
+  border-color: #334155;
+}
+
+/* Responsive Design */
+@media screen and (max-width: 996px) {
+  .heroBanner {
+    padding: 4rem 2rem 3rem;
+  }
+}
+
+@media (max-width: 768px) {
+  .heroBanner {
+    padding: 4rem 1rem 3rem;
+  }
+
+  .heroTitle {
+    font-size: 2.5rem;
+  }
+
+  .heroSubtitle {
+    font-size: 1.2rem;
+  }
+
+  .heroDescription {
+    font-size: 1rem;
+  }
+
+  .heroLogo {
+    width: 80px;
+    height: 80px;
+  }
+
+  .buttons {
+    flex-direction: column;
+    gap: 0.75rem;
+  }
+
+  .sectionTitle {
+    font-size: 2rem;
+  }
+
+  .demoSection {
+    padding: 3rem 0;
+  }
+}
+
+@media (max-width: 480px) {
+  .heroTitle {
+    font-size: 2rem;
+  }
+
+  .installCommand {
+    font-size: 0.85rem;
+    padding: 0.6rem 1rem;
+  }
+}
+
diff --git a/docs/src/pages/index.tsx b/docs/src/pages/index.tsx
index 9b35907..06ce754 100644
--- a/docs/src/pages/index.tsx
+++ b/docs/src/pages/index.tsx
@@ -4,7 +4,7 @@ import Link from '@docusaurus/Link';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import Layout from '@theme/Layout';
 import HomepageFeatures from '@site/src/components/HomepageFeatures';
-import GitHubRepo from '@site/src/components/GitHubRepo';
+// import GitHubRepo from '@site/src/components/GitHubRepo';
 import Heading from '@theme/Heading';
 
 import styles from './index.module.css';
@@ -16,31 +16,164 @@ import Logo from '@site/static/img/logo.svg';
 function HomepageHeader() {
   const {siteConfig} = useDocusaurusContext();
   return (
-    <header className={clsx('hero hero--primary', styles.heroBanner)}>
+    <header className={clsx('hero', styles.heroBanner)}>
       <div className="container">
-        <div className={styles.logoContainer}>
-          <Logo className={styles.heroLogo} role="img" aria-label="Remark Notes Plugin Logo" />
+        <div className={styles.heroContent}>
+          <div className={styles.logoContainer}>
+            <Logo className={styles.heroLogo} role="img" aria-label="Remark Notes Plugin Logo" />
+          </div>
+          <Heading as="h1" className={styles.heroTitle}>
+            {siteConfig.title}
+          </Heading>
+          <p className={styles.heroSubtitle}>{siteConfig.tagline}</p>
+          <p className={styles.heroDescription}>
+            A powerful remark plugin that transforms simple markdown blockquotes into beautiful, 
+            professional note components. Perfect for documentation, blogs, and technical writing.
+          </p>
+          <div className={styles.buttons}>
+            <Link
+              className={clsx('button button--lg', styles.buttonPrimary)}
+              to="/docs/intro">
+              Get Started →
+            </Link>
+            <Link
+              className={clsx('button button--outline button--lg', styles.buttonSecondary)}
+              href="https://github.com/rishichawda/remark-notes-plugin">
+              <svg width="20" height="20" viewBox="0 0 16 16" fill="currentColor" style={{marginRight: '8px'}}>
+                <path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"></path>
+              </svg>
+              GitHub
+            </Link>
+          </div>
+          <div className={styles.quickStart}>
+            <code className={styles.installCommand}>npm install remark-notes-plugin</code>
+          </div>
         </div>
-        <Heading as="h1" className="hero__title">
-          {siteConfig.title}
+      </div>
+    </header>
+  );
+}
+
+function LiveDemo() {
+  return (
+    <section className={styles.demoSection}>
+      <div className="container">
+        <Heading as="h2" className={styles.sectionTitle}>
+          See It In Action
         </Heading>
-        <p className="hero__subtitle">{siteConfig.tagline}</p>
-        <p>Beautiful and customizable note components for your markdown</p>
-        <div className={styles.buttons}>
-          <Link
-            className="button button--secondary button--lg"
-            to="/docs/intro">
-            Get Started
-          </Link>
-          <Link
-            className="button button--outline button--lg button--secondary"
-            href="https://github.com/rishichawda/remark-notes-plugin"
-            style={{ marginLeft: '1rem' }}>
-            GitHub
-          </Link>
+        <p className={styles.sectionSubtitle}>
+          Five beautiful note types to enhance your content
+        </p>
+        <div className={styles.demoGrid}>
+          <div className={styles.demoColumn}>
+            <h3 className={styles.demoHeading}>Markdown Input</h3>
+            <pre className={styles.demoCode}>
+              {`> [!note]
+> Perfect for general information
+> and helpful context.
+
+> [!tip]
+> Share best practices and
+> pro tips with your readers.
+
+> [!important]
+> Highlight critical information
+> that demands attention.
+
+> [!quote]
+> Showcase quotes and
+> testimonials beautifully.
+
+> [!bonus]
+> Add extra value with
+> advanced techniques.`}
+            </pre>
+          </div>
+          <div className={styles.demoColumn}>
+            <h3 className={styles.demoHeading}>Rendered Output</h3>
+            <div className={styles.demoNotes}>
+              <blockquote className="remark-note remark-note-note">
+                <div className="remark-note-header">
+                  <span className="remark-note-icon">
+                    <svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+                      <path d="M8 2V5" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round"/>
+                      <path d="M16 2V5" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round"/>
+                      <path d="M21 8.5V17C21 20 19.5 22 16 22H8C4.5 22 3 20 3 17V8.5C3 5.5 4.5 3.5 8 3.5H16C19.5 3.5 21 5.5 21 8.5Z" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round"/>
+                      <path d="M8 11H16" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round"/>
+                      <path d="M8 16H12" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round"/>
+                    </svg>
+                  </span>
+                  <span className="remark-note-title">note</span>
+                </div>
+                <div className="remark-note-content">
+                  <p>Perfect for general information and helpful context.</p>
+                </div>
+              </blockquote>
+
+              <blockquote className="remark-note remark-note-tip">
+                <div className="remark-note-header">
+                  <span className="remark-note-icon">
+                    <svg viewBox="-0.5 0 25 25" fill="none" xmlns="http://www.w3.org/2000/svg">
+                      <path d="M19.0006 9.03002C19.0007 8.10058 18.8158 7.18037 18.4565 6.32317C18.0972 5.46598 17.5709 4.68895 16.9081 4.03734C16.2453 3.38574 15.4594 2.87265 14.5962 2.52801C13.7331 2.18336 12.8099 2.01409 11.8806 2.03002C10.0966 2.08307 8.39798 2.80604 7.12302 4.05504C5.84807 5.30405 5.0903 6.98746 5.00059 8.77001C4.95795 9.9595 5.21931 11.1402 5.75999 12.2006C6.30067 13.2609 7.10281 14.1659 8.09058 14.83C8.36897 15.011 8.59791 15.2584 8.75678 15.5499C8.91565 15.8415 8.99945 16.168 9.00059 16.5V18.03H15.0006V16.5C15.0006 16.1689 15.0829 15.843 15.24 15.5515C15.3971 15.26 15.6241 15.0121 15.9006 14.83C16.8528 14.1911 17.6336 13.328 18.1741 12.3167C18.7147 11.3054 18.9985 10.1767 19.0006 9.03002Z" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round"/>
+                      <path d="M11.9901 5.64001L10.3301 8.41998C10.2549 8.54184 10.2138 8.68167 10.2111 8.82483C10.2084 8.96799 10.2441 9.10925 10.3146 9.23389C10.3851 9.35852 10.4877 9.46195 10.6118 9.53339C10.7359 9.60482 10.8769 9.64165 11.0201 9.64001H13.0201C13.1617 9.63947 13.301 9.67657 13.4237 9.7475C13.5463 9.81843 13.6479 9.92063 13.7181 10.0437C13.7883 10.1668 13.8245 10.3063 13.8231 10.4479C13.8217 10.5896 13.7827 10.7283 13.7101 10.85L12.0301 13.64" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round"/>
+                    </svg>
+                  </span>
+                  <span className="remark-note-title">tip</span>
+                </div>
+                <div className="remark-note-content">
+                  <p>Share best practices and pro tips with your readers.</p>
+                </div>
+              </blockquote>
+
+              <blockquote className="remark-note remark-note-important">
+                <div className="remark-note-header">
+                  <span className="remark-note-icon">
+                    <svg viewBox="0 0 18 18" fill="currentColor" xmlns="http://www.w3.org/2000/svg">
+                      <path d="M9,14a1.5,1.5,0,1,1,1.5068-1.5A1.5035,1.5035,0,0,1,9,14Z"/>
+                      <path d="M9,2A7,7,0,1,1,2,9,7.0079,7.0079,0,0,1,9,2M9,0a9,9,0,1,0,9,9A9,9,0,0,0,9,0Z"/>
+                      <path d="M10,4H8a1,1,0,0,0-.97,1.2425l1,4a1,1,0,0,0,1.94,0l1-4A1,1,0,0,0,10,4Zm0,2h0Z"/>
+                    </svg>
+                  </span>
+                  <span className="remark-note-title">important</span>
+                </div>
+                <div className="remark-note-content">
+                  <p>Highlight critical information that demands attention.</p>
+                </div>
+              </blockquote>
+
+              <blockquote className="remark-note remark-note-quote">
+                <div className="remark-note-header">
+                  <span className="remark-note-icon">
+                    <svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+                      <path d="M14 15V14C14 13.0681 14 12.6022 14.1522 12.2346C14.3552 11.7446 14.7446 11.3552 15.2346 11.1522C15.6022 11 16.0681 11 17 11H17.5C18.9045 11 19.6067 11 20.1111 11.3371C20.3295 11.483 20.517 11.6705 20.6629 11.8889C21 12.3933 21 13.0955 21 14.5V15.3431C21 16.1606 21 16.5694 20.8478 16.9369C20.6955 17.3045 20.4065 17.5935 19.8284 18.1716L19.2396 18.7604C18.7822 19.2178 18 18.8938 18 18.2469V17.8787C18 17.3934 17.6066 17 17.1213 17H16C14.8954 17 14 16.1046 14 15Z" stroke="currentColor" strokeWidth="1.5" strokeLinejoin="round"/>
+                      <path d="M3 9V8C3 7.06812 3 6.60218 3.15224 6.23463C3.35523 5.74458 3.74458 5.35523 4.23463 5.15224C4.60218 5 5.06812 5 6 5H6.5C7.90446 5 8.60669 5 9.11114 5.33706C9.32952 5.48298 9.51702 5.67048 9.66294 5.88886C10 6.39331 10 7.09554 10 8.5V9.34315C10 10.1606 10 10.5694 9.84776 10.9369C9.69552 11.3045 9.40649 11.5935 8.82843 12.1716L8.23965 12.7604C7.78219 13.2178 7 12.8938 7 12.2469V11.8787C7 11.3934 6.6066 11 6.12132 11H5C3.89543 11 3 10.1046 3 9Z" stroke="currentColor" strokeWidth="1.5" strokeLinejoin="round"/>
+                    </svg>
+                  </span>
+                  <span className="remark-note-title">quote</span>
+                </div>
+                <div className="remark-note-content">
+                  <p>Showcase quotes and testimonials beautifully.</p>
+                </div>
+              </blockquote>
+
+              <blockquote className="remark-note remark-note-bonus">
+                <div className="remark-note-header">
+                  <span className="remark-note-icon">
+                    <svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+                      <path d="M9.23163 8.61762C7.26389 9.06284 6.28001 9.28545 6.04594 10.0382C5.81186 10.7909 6.4826 11.5753 7.82408 13.1439L8.17113 13.5498C8.55234 13.9955 8.74294 14.2184 8.82869 14.4942C8.91444 14.7699 8.88562 15.0673 8.82799 15.662L8.77552 16.2035C8.5727 18.2965 8.4713 19.343 9.08412 19.8082C9.69694 20.2734 10.6181 19.8492 12.4605 19.0009L12.9372 18.7815C13.4607 18.5404 13.7225 18.4199 14 18.4199C14.2775 18.4199 14.5393 18.5404 15.0628 18.7815L15.5395 19.0009C17.3819 19.8492 18.3031 20.2734 18.9159 19.8082C19.5287 19.343 19.4273 18.2965 19.2245 16.2035M20.1759 13.1439C21.5174 11.5753 22.1881 10.7909 21.9541 10.0382C21.72 9.28545 20.7361 9.06284 18.7684 8.61762L18.2593 8.50244C17.7001 8.37592 17.4205 8.31266 17.196 8.14225C16.9716 7.97183 16.8276 7.71355 16.5396 7.19699L16.2775 6.7267C15.2641 4.9089 14.7575 4 14 4C13.2425 4 12.7359 4.9089 11.7225 6.7267" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round"/>
+                    </svg>
+                  </span>
+                  <span className="remark-note-title">bonus</span>
+                </div>
+                <div className="remark-note-content">
+                  <p>Add extra value with advanced techniques.</p>
+                </div>
+              </blockquote>
+            </div>
+          </div>
         </div>
       </div>
-    </header>
+    </section>
   );
 }
 
@@ -49,17 +182,18 @@ export default function Home(): ReactNode {
   return (
     <Layout
       title={siteConfig.title}
-      description="A remark plugin that transforms markdown quotes into styled note elements">
+      description="A powerful remark plugin that transforms markdown blockquotes into beautiful, professional note components">
       <HomepageHeader />
       <main>
-        <div className="container margin-vert--lg">
+        <HomepageFeatures />
+        {/* <LiveDemo /> */}
+        {/* <div className="container margin-vert--lg">
           <div className="row">
             <div className="col col--8 col--offset-2">
               <GitHubRepo owner="rishichawda" repo="remark-notes-plugin" />
             </div>
           </div>
-        </div>
-        <HomepageFeatures />
+        </div> */}
       </main>
     </Layout>
   );