0
# markdown-it-container
1

2
markdown-it-container is a plugin for the markdown-it parser that enables creation of block-level custom containers using a fenced syntax similar to code blocks. It allows you to define custom container types (like warnings, notes, or spoilers) with configurable validation, rendering, and marker characters.
3

4
## Package Information
5

6
- **Package Name**: markdown-it-container
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install markdown-it-container`
10

11
## Core Imports
12

13
```javascript
14
import container from "markdown-it-container";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const container = require("markdown-it-container");
21
```
22

23
## Basic Usage
24

25
```javascript
26
import markdownit from "markdown-it";
27
import container from "markdown-it-container";
28

29
// Simple container with default rendering
30
const md = markdownit().use(container, "warning");
31

32
const result = md.render(`
33
::: warning
34
*Here be dragons*
35
:::
36
`);
37
// Output: <div class="warning"><p><em>Here be dragons</em></p></div>
38

39
// Custom container with custom renderer
40
const mdCustom = markdownit().use(container, "spoiler", {
41
  render: function (tokens, idx) {
42
    if (tokens[idx].nesting === 1) {
43
      // opening tag
44
      return '<details><summary>Click to reveal</summary>\n';
45
    } else {
46
      // closing tag
47
      return '</details>\n';
48
    }
49
  }
50
});
51
```
52

53
## Capabilities
54

55
### Container Plugin
56

57
The main plugin function that registers a custom container with markdown-it.
58

59
```javascript { .api }
60
/**
61
 * Registers a custom container with markdown-it parser
62
 * @param md - The markdown-it parser instance
63
 * @param name - Container name (used as CSS class and validation)
64
 * @param options - Configuration options for the container
65
 */
66
export default function container(md: MarkdownIt, name: string, options?: ContainerOptions): void;
67

68
interface ContainerOptions {
69
  /** Custom validation function for container parameters */
70
  validate?: (params: string, markup: string) => boolean;
71
  /** Custom renderer for opening/closing tokens */
72
  render?: (tokens: Token[], idx: number, options: any, env: any, renderer: any) => string;
73
  /** Character(s) to use as delimiter (default: ':') */
74
  marker?: string;
75
}
76
```
77

78
**Parameters:**
79

80
- `md` (MarkdownIt): The markdown-it parser instance to register the container with
81
- `name` (string): Container name - used as CSS class in default rendering and for validation
82
- `options` (ContainerOptions, optional): Configuration options
83

84
**Options Properties:**
85

86
- `validate` (function, optional): Function to validate container parameters
87
  - Parameters: `params` (string) - text after opening marker, `markup` (string) - full opening marker  
88
  - Returns: `true` if valid, `false/falsy` to skip processing
89
  - Default: Validates that the first word in params exactly matches the container name
90
  - Example: For container name "warning", `::: warning message` is valid, but `::: warn message` is not
91
- `render` (function, optional): Custom renderer for opening/closing tokens
92
  - Parameters: 
93
    - `tokens` (Token[]) - Array of all tokens
94
    - `idx` (number) - Index of current token being rendered
95
    - `options` (any) - Markdown-it options
96
    - `env` (any) - Environment object
97
    - `renderer` (any) - The markdown-it renderer instance
98
  - Returns: HTML string for the token
99
  - Default: Creates `<div>` with container name as CSS class using `renderer.renderToken()`
100
- `marker` (string, optional): Character(s) used as delimiter (default: ':')
101

102
**Usage Examples:**
103

104
```javascript
105
// Basic container with default div rendering
106
md.use(container, "note");
107
// ::: note
108
// content
109
// :::
110
// → <div class="note"><p>content</p></div>
111

112
// Container with custom marker
113
md.use(container, "custom", {
114
  marker: ">"
115
});
116
// >>> custom
117
// content  
118
// >>>
119
// → <div class="custom"><p>content</p></div>
120

121
// Container with custom validation
122
md.use(container, "alert", {
123
  validate: function(params) {
124
    return params.trim().match(/^alert\s+(info|warning|error)$/);
125
  }
126
});
127
// Only accepts: ::: alert info, ::: alert warning, ::: alert error
128

129
// Container with custom rendering
130
md.use(container, "details", {
131
  validate: function(params) {
132
    return params.trim().match(/^details\s+(.*)$/);
133
  },
134
  render: function(tokens, idx) {
135
    if (tokens[idx].nesting === 1) {
136
      return '<details><summary>Click to reveal</summary>\n';
137
    } else {
138
      return '</details>\n';
139
    }
140
  }
141
});
142
```
143

144
## Markdown Syntax
145

146
The plugin enables the following markdown syntax:
147

148
```
149
::: container_name [optional parameters]
150
Content goes here (parsed as markdown)
151
:::
152
```
153

154
**Syntax Rules:**
155

156
- **Minimum markers**: Exactly 3 or more marker characters are required (e.g., `:::`, `::::`, `:::::`)
157
- **Container name**: Must match exactly (case-sensitive) with registered name
158
- **Indentation**: Opening marker can be indented up to 3 spaces (4+ spaces creates code block)
159
- **Closing marker**: Must have equal or greater length than opening marker
160
- **Content parsing**: Content inside containers is parsed as regular markdown
161
- **Nesting**: Containers can be nested within each other using different marker lengths
162
- **Auto-closing**: Containers auto-close at document end if not explicitly closed
163

164
**Examples:**
165

166
```markdown
167
<!-- Basic container -->
168
::: warning
169
This is a warning message
170
:::
171

172
<!-- Container with parameters -->
173
::: alert info Important Notice
174
Check the documentation for details
175
:::
176

177
<!-- Nested containers -->
178
::::: outer
179
:::: inner  
180
Content here
181
::::
182
:::::
183

184
<!-- Longer closing marker -->
185
::: container
186
Content
187
::::::::::
188
```
189

190
## Types
191

192
```javascript { .api }
193
interface MarkdownIt {
194
  use(plugin: Function, ...args: any[]): MarkdownIt;
195
  render(src: string, env?: any): string;
196
  block: {
197
    ruler: {
198
      before(beforeName: string, ruleName: string, rule: Function, options?: any): void;
199
    };
200
    tokenize(state: any, start: number, end: number): void;
201
  };
202
  renderer: {
203
    rules: Record<string, Function>;
204
  };
205
  utils: {
206
    escapeHtml(str: string): string;
207
  };
208
}
209

210
interface Token {
211
  /** Token type (e.g., 'container_name_open', 'container_name_close') */
212
  type: string;
213
  /** Nesting level: 1 for opening, -1 for closing, 0 for self-closing */
214
  nesting: number;
215
  /** Content after container name (parameters/arguments) */
216
  info: string;
217
  /** The marker string used to open/close (e.g., '::::', ':::::') */
218
  markup: string;
219
  /** Whether this is a block-level token */
220
  block: boolean;
221
  /** Source line mapping [start_line, end_line] */
222
  map: [number, number] | null;
223
  /** Add or join CSS class to token attributes */
224
  attrJoin(name: string, value: string): void;
225
}
226
```