implement configuration options

add `injectStyles` and `classPrefix` options to provide more control over styles

Signed-off-by: rishichawda <[email protected]>

Author: rishichawda

index.ts

@@ -4,13 +4,22 @@ import type { Blockquote, Paragraph, Text } from 'mdast'
 import { styles } from './lib/styles.js'
 import { createNoteStructure } from './lib/node-structure.js'
 import { VALID_NOTE_TYPES, ValidNoteType } from './lib/icons-hast.js'
+import type { RemarkNotesOptions } from './lib/types/options.js'
+
+// Export types for public API
+export type { RemarkNotesOptions } from './lib/types/options.js'
+export type { ValidNoteType } from './lib/icons-hast.js'
+
+export default function remarkNotes(options: RemarkNotesOptions = {}) {
+  // Extract options with defaults
+  const classPrefix = options.classPrefix ?? ''
+  const injectStyles = options.injectStyles ?? true
 
-export default function remarkNotes() {
   let hasInjectedStyles = false
 
   return (tree: Node) => {
-    // Inject styles at the beginning of the document (only once)
-    if (!hasInjectedStyles) {
+    // Inject styles at the beginning of the document (only once) if enabled
+    if (injectStyles && !hasInjectedStyles) {
       const root = tree as Parent
       if (root.children) {
         root.children.unshift({
@@ -24,46 +33,46 @@ export default function remarkNotes() {
     visit(tree, 'blockquote', (node: Blockquote, index, parent) => {
       // Validate we have parent and index for proper node replacement
       if (!parent || index === null || index === undefined) return
-      
+
       const firstParagraph = node.children[0]
       if (!firstParagraph || firstParagraph.type !== 'paragraph') return
-      
+
       const firstChild = firstParagraph.children[0]
       if (!firstChild || firstChild.type !== 'text') return
-      
+
       const textNode = firstChild as Text
-      
+
       // Match [!type] pattern
       const match = textNode.value.match(/^\[!(\w+)\]/)
       if (!match) return
-      
+
       const noteType = match[1].toLowerCase() as ValidNoteType
-      
+
       // Only transform if it's a recognized note type
       if (!VALID_NOTE_TYPES.includes(noteType)) return
-      
+
       // Clone children to preserve original markdown structure
       const children = [...node.children]
-      
+
       // Process the first paragraph to remove the note marker
       if (children.length > 0 && children[0].type === 'paragraph') {
         const firstPara = children[0] as Paragraph
         const firstTextNode = firstPara.children[0] as Text
-        
+
         if (firstTextNode && firstTextNode.type === 'text') {
           // Remove the [!type] marker and any trailing whitespace
           firstTextNode.value = firstTextNode.value.replace(/^\[!\w+\]\s*/, '')
-          
+
           // If the text node is now empty and it's the only child, remove the paragraph
           if (firstTextNode.value === '' && firstPara.children.length === 1) {
             children.shift()
           }
         }
       }
-      
+
       // Create the note structure using proper mdast nodes (with hast-converted SVG icons)
-      const noteContainer = createNoteStructure(noteType, children);
-      
+      const noteContainer = createNoteStructure(noteType, children, classPrefix);
+
       // Replace the blockquote with the container
       (parent as Parent).children[index] = noteContainer;
     })

lib/node-structure.ts

@@ -21,35 +21,41 @@ import { ICON_HAST_MAP, ValidNoteType } from './icons-hast.js'
  * 
  * @param noteType - The type of note (note, tip, important, etc.)
  * @param children - The content nodes (markdown) to include in the note
+ * @param classPrefix - The prefix for all CSS class names (default: 'remark-note')
  * @returns A mdast node that will be transformed to the note HTML structure
  */
 export function createNoteStructure(
   noteType: ValidNoteType,
-  children: Node[]
+  children: Node[],
+  classPrefix: string = ''
 ): any {
+  // Build class names: prefix is prepended to standard 'remark-note' names
+  // Default: 'remark-note-icon', With prefix 'my': 'my-remark-note-icon'
+  const baseClass = classPrefix ? `${classPrefix}-remark-note` : 'remark-note'
+  const makeClass = (suffix: string) => classPrefix ? `${classPrefix}-remark-note-${suffix}` : `remark-note-${suffix}`
   // Get the hast representation of the icon
   const iconHast = ICON_HAST_MAP[noteType]
-  
+
   // Create icon span with embedded hast node
   // Using data.hast tells remark-rehype to use this hast node directly
   const iconNode: any = {
     type: 'paragraph',
     data: {
       hName: 'span',
       hProperties: {
-        className: ['remark-note-icon']
+        className: [makeClass('icon')]
       },
       hChildren: [iconHast]  // Embed hast node directly
     },
   }
-  
+
   // Create title span
   const titleNode: any = {
     type: 'paragraph',
     data: {
       hName: 'span',
       hProperties: {
-        className: ['remark-note-title']
+        className: [makeClass('title')]
       }
     },
     children: [
@@ -59,43 +65,43 @@ export function createNoteStructure(
       }
     ]
   }
-  
+
   // Create header div
   const headerNode: any = {
     type: 'paragraph',
     data: {
       hName: 'div',
       hProperties: {
-        className: ['remark-note-header']
+        className: [makeClass('header')]
       }
     },
     children: [iconNode, titleNode]
   }
-  
+
   // Create content wrapper div
   const contentNode: any = {
     type: 'paragraph',
     data: {
       hName: 'div',
       hProperties: {
-        className: ['remark-note-content']
+        className: [makeClass('content')]
       }
     },
     children: children
   }
-  
+
   // Build the structure: wrap everything in a blockquote container with data hints
   // Using blockquote for semantic HTML since the source is a blockquote
   const noteContainer: any = {
     type: 'paragraph', // Use a standard mdast type
     data: {
       hName: 'blockquote',  // Transform to blockquote for semantic HTML
       hProperties: {
-        className: ['remark-note', noteType]
+        className: [baseClass, makeClass(noteType)]
       }
     },
     children: [headerNode, contentNode]
   }
-  
+
   return noteContainer
 }

lib/types/options.ts

@@ -0,0 +1,95 @@
+/**
+ * Configuration options for the remark-notes plugin
+ * 
+ * @module lib/types/options
+ */
+
+/**
+ * Options for configuring the remark-notes plugin behavior
+ * 
+ * @example
+ * ```typescript
+ * import remarkNotes from 'remark-notes-plugin'
+ * 
+ * // Using default options
+ * unified().use(remarkNotes)
+ * 
+ * // With custom class prefix
+ * unified().use(remarkNotes, { classPrefix: 'my-callout' })
+ * 
+ * // Disable automatic style injection
+ * unified().use(remarkNotes, { injectStyles: false })
+ * 
+ * // Both options
+ * unified().use(remarkNotes, { 
+ *   classPrefix: 'custom-note',
+ *   injectStyles: false 
+ * })
+ * ```
+ */
+export interface RemarkNotesOptions {
+    /**
+     * Custom prefix for all generated CSS class names
+     * 
+     * This prefix is **prepended** to the standard 'remark-note' class names.
+     * 
+     * **Default (no prefix):**
+     * - Container: `remark-note` and `remark-note-{noteType}`
+     * - Elements: `remark-note-header`, `remark-note-icon`, etc.
+     * 
+     * **With prefix (e.g., 'my'):**
+     * - Container: `my-remark-note` and `my-remark-note-{noteType}`
+     * - Elements: `my-remark-note-header`, `my-remark-note-icon`, etc.
+     * 
+     * @default '' (empty string - no prefix)
+     * 
+     * @example
+     * ```typescript
+     * // No prefix (default)
+     * { classPrefix: '' }
+     * // Generates: class="remark-note remark-note-tip"
+     * 
+     * // Custom prefix
+     * { classPrefix: 'my' }
+     * // Generates: class="my-remark-note my-remark-note-tip"
+     * ```
+     * 
+     * @remarks
+     * The shipped CSS uses attribute selectors (e.g., `[class*="remark-note-icon"]`)
+     * and will work with any prefix automatically.
+     */
+    classPrefix?: string
+
+    /**
+     * Controls whether the plugin automatically injects styles into the document
+     * 
+     * When `true` (default), the plugin injects a `<style>` tag containing the note styles
+     * directly into the AST. This is convenient for most use cases.
+     * 
+     * When `false`, styles are not injected and you must manually import the CSS file:
+     * `import 'remark-notes-plugin/styles.css'`
+     * 
+     * Set to `false` when:
+     * - 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
+     * 
+     * @default true
+     * 
+     * @example
+     * ```typescript
+     * // Automatic style injection (default)
+     * { injectStyles: true }
+     * 
+     * // Manual CSS import
+     * { injectStyles: false }
+     * // Then in your code:
+     * // import 'remark-notes-plugin/styles.css'
+     * ```
+     * 
+     * @remarks
+     * The CSS file is available at the package export: `remark-notes-plugin/styles.css`
+     */
+    injectStyles?: boolean
+}