0
# markdown-loader
1

2
A webpack loader for processing Markdown files into HTML using the marked library. This loader enables seamless integration of Markdown content into webpack builds by transforming .md files into HTML strings that can be imported as modules.
3

4
## Package Information
5

6
- **Package Name**: markdown-loader
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install markdown-loader`
10

11
## Core Imports
12

13
The loader is used in webpack configuration rather than direct imports:
14

15
```javascript
16
// webpack.config.js
17
export default {
18
  module: {
19
    rules: [
20
      {
21
        test: /\.md$/,
22
        use: [
23
          { loader: "html-loader" },
24
          { loader: "markdown-loader" }
25
        ]
26
      }
27
    ]
28
  }
29
};
30
```
31

32
## Basic Usage
33

34
```javascript
35
// webpack.config.js
36
export default {
37
  module: {
38
    rules: [
39
      {
40
        test: /\.md$/,
41
        use: [
42
          {
43
            loader: "html-loader",
44
          },
45
          {
46
            loader: "markdown-loader",
47
            options: {
48
              // Pass options to marked library
49
              // See https://marked.js.org/using_advanced#options
50
            },
51
          },
52
        ],
53
      },
54
    ],
55
  },
56
};
57
```
58

59
Then import Markdown files in your JavaScript:
60

61
```javascript
62
import readmeContent from './README.md';
63
// readmeContent contains the HTML string
64
console.log(readmeContent);
65
```
66

67
## Architecture
68

69
markdown-loader uses a hybrid module structure for webpack compatibility:
70

71
- **CommonJS Entry** (`src/main.cjs`): Required by webpack's loader system, serves as a trampoline
72
- **ES Module Core** (`src/loader.js`): Contains the actual loader implementation
73
- **Marked Integration**: Uses the marked library for Markdown parsing with configurable options
74

75
The loader follows webpack's loader interface, receiving raw markdown content and returning HTML.
76

77
## Capabilities
78

79
### Webpack Loader Function
80

81
The core loader functionality that transforms Markdown to HTML.
82

83
```javascript { .api }
84
/**
85
 * Webpack loader function that converts markdown content to HTML
86
 * @param {string} markdown - Raw markdown content from file
87
 * @returns {string} HTML string generated by marked library
88
 */
89
function markdownLoader(markdown);
90
```
91

92
This function:
93
- Receives markdown content as a string parameter
94
- Uses `this.getOptions()` to retrieve webpack loader options
95
- Passes options directly to `marked.parse()` for customization
96
- Returns HTML string that can be processed by subsequent loaders
97

98
### CommonJS Trampoline
99

100
The entry point required for webpack loader compatibility.
101

102
```javascript { .api }
103
/**
104
 * CommonJS trampoline function for webpack loader compatibility
105
 * @param {...any} args - Arguments passed from webpack loader system
106
 * @returns {Promise<string>} Promise resolving to HTML string
107
 */
108
async function trampolin(...args);
109
```
110

111
This async function:
112
- Dynamically imports the ES module loader
113
- Calls the actual loader with proper `this` context
114
- Returns the result from the ES module loader
115

116
## Configuration Options
117

118
All options are passed directly to the marked library. Common options include:
119

120
```javascript { .api }
121
interface MarkedOptions {
122
  /** Custom renderer for overriding HTML output */
123
  renderer?: Renderer;
124
  /** Function for syntax highlighting code blocks */
125
  highlight?: (code: string, lang: string) => string;
126
  /** Enable GitHub Flavored Markdown extensions */
127
  gfm?: boolean;
128
  /** Allow HTML tags in markdown */
129
  sanitize?: boolean;
130
  /** Other marked library options */
131
  [key: string]: any;
132
}
133
```
134

135
**Usage Examples:**
136

137
```javascript
138
// With custom syntax highlighting
139
{
140
  loader: "markdown-loader",
141
  options: {
142
    highlight: (code, lang) => {
143
      return require('highlight.js').highlight(code, { language: lang }).value;
144
    }
145
  }
146
}
147

148
// With custom renderer
149
import { Renderer } from 'marked';
150

151
class CustomRenderer extends Renderer {
152
  heading(text, level) {
153
    return `<h${level} class="custom-heading">${text}</h${level}>`;
154
  }
155
}
156

157
{
158
  loader: "markdown-loader", 
159
  options: {
160
    renderer: new CustomRenderer()
161
  }
162
}
163
```
164

165
## Integration Patterns
166

167
### With html-loader Chain
168

169
The recommended usage pattern combines markdown-loader with html-loader:
170

171
```javascript
172
{
173
  test: /\.md$/,
174
  use: [
175
    { loader: "html-loader" },    // Processes HTML output
176
    { loader: "markdown-loader" }  // Converts MD to HTML
177
  ]
178
}
179
```
180

181
### Direct Module Import
182

183
After configuration, Markdown files can be imported as modules:
184

185
```javascript
186
// Import processed markdown as HTML string
187
import content from './documentation.md';
188
document.getElementById('content').innerHTML = content;
189
```
190

191
## Runtime Requirements
192

193
- **Node.js**: >= 12.22.9
194
- **webpack**: >= 5.0.0 (peer dependency)
195
- **marked**: ^4.0.12 (bundled dependency)
196

197
## Error Handling
198

199
The loader inherits error handling from the marked library. Common issues:
200

201
- **Invalid Markdown**: Marked will attempt to parse malformed markdown gracefully
202
- **Option Conflicts**: Invalid marked options will throw during parsing
203
- **File Access**: Standard webpack file loading errors apply
204

205
The loader does not implement custom error handling beyond webpack's standard loader error propagation.