0
# Template Processing
1

2
Pug template engine integration for markup preprocessing and global style handling for CSS scope management.
3

4
## Capabilities
5

6
### Pug Processing
7

8
Pug template engine integration for preprocessing markup blocks with full Pug language support.
9

10
```typescript { .api }
11
/**
12
 * Creates Pug preprocessor for markup blocks
13
 * @param options - Pug configuration options
14
 * @returns PreprocessorGroup with markup preprocessing
15
 */
16
function pug(options?: Options.Pug): PreprocessorGroup;
17

18
namespace Options {
19
  interface Pug {
20
    /** Tag name for markup sections */
21
    markupTagName?: string;
22
    
23
    /** Content to prepend to every file */
24
    prependData?: string;
25
    
26
    /** Remove common leading whitespace (automatically enabled) */
27
    stripIndent?: boolean;
28
    
29
    // Additional Pug options (subset of pug.Options)
30
    // Excludes: 'filename', 'doctype', 'compileDebug' (handled internally)
31
  }
32
}
33
```
34

35
**Usage Examples:**
36

37
```typescript
38
import { pug } from "svelte-preprocess";
39

40
// Basic Pug support
41
const preprocess = {
42
  markup: pug()
43
};
44

45
// Pug with custom configuration
46
const preprocess = {
47
  markup: pug({
48
    markupTagName: 'template',
49
    
50
    // Pug-specific options
51
    pretty: process.env.NODE_ENV === 'development',
52
    filters: {
53
      'markdown': require('marked')
54
    }
55
  })
56
};
57

58
// Pug with global mixins
59
const preprocess = {
60
  markup: pug({
61
    prependData: `
62
      mixin button(text, type='button')
63
        button(type=type)= text
64
      
65
      mixin icon(name)
66
        svg.icon(class=\`icon-\${name}\`)
67
          use(href=\`#icon-\${name}\`)
68
    `
69
  })
70
};
71
```
72

73
### Global Style Processing
74

75
Handles CSS with `global` attributes, transforming selectors to global scope.
76

77
```typescript { .api }
78
/**
79
 * Creates global style preprocessor for handling global CSS
80
 * @returns PreprocessorGroup with style preprocessing for global styles
81
 */
82
function globalStyle(): PreprocessorGroup;
83

84
namespace Options {
85
  interface GlobalStyle {
86
    /** Enable source map generation */
87
    sourceMap: boolean;
88
  }
89
}
90
```
91

92
**Usage Examples:**
93

94
```typescript
95
import { globalStyle } from "svelte-preprocess";
96

97
// Basic global style support
98
const preprocess = {
99
  style: globalStyle()
100
};
101
```
102

103
The global style processor is typically used automatically within the auto preprocessor when PostCSS is available:
104

105
```svelte
106
<!-- Global styles are automatically processed -->
107
<style global>
108
  body {
109
    margin: 0;
110
    font-family: system-ui;
111
  }
112
  
113
  .global-utility {
114
    display: flex;
115
    align-items: center;
116
  }
117
</style>
118

119
<!-- Scoped styles (normal Svelte behavior) -->
120
<style>
121
  .component-style {
122
    color: blue;
123
  }
124
</style>
125
```
126

127
## Integration with Auto Preprocessor
128

129
Template processors integrate seamlessly with the auto preprocessor:
130

131
```typescript
132
import { sveltePreprocess } from "svelte-preprocess";
133

134
const preprocess = sveltePreprocess({
135
  // Pug markup processing
136
  pug: {
137
    markupTagName: 'template',
138
    prependData: `
139
      mixin component-wrapper(class='')
140
        div.component(class=class)
141
          block
142
    `
143
  },
144
  
145
  // Global style processing (automatic when PostCSS available)
146
  globalStyle: true,
147
  
148
  // Works with other preprocessors
149
  scss: true,
150
  postcss: {
151
    plugins: [require('autoprefixer')]
152
  }
153
});
154
```
155

156
The auto preprocessor detects template languages based on:
157
- `<template lang="pug">` or custom `markupTagName`
158
- Automatic global style handling for `<style global>`
159

160
## Pug Language Features
161

162
### Basic Pug Syntax
163

164
```pug
165
<!-- Input Pug -->
166
div.container
167
  h1.title Welcome to Svelte
168
  p.description 
169
    | This is a Pug template with 
170
    strong dynamic content
171
    | .
172
  
173
  ul.list
174
    each item in items
175
      li.item= item.name
176

177
<!-- Compiles to HTML -->
178
<div class="container">
179
  <h1 class="title">Welcome to Svelte</h1>
180
  <p class="description">
181
    This is a Pug template with 
182
    <strong>dynamic content</strong>.
183
  </p>
184
  
185
  <ul class="list">
186
    {#each items as item}
187
      <li class="item">{item.name}</li>
188
    {/each}
189
  </ul>
190
</div>
191
```
192

193
### Svelte Integration
194

195
Pug templates maintain full Svelte functionality:
196

197
```pug
198
<!-- Svelte directives work in Pug -->
199
script.
200
  export let count = 0;
201
  
202
  function increment() {
203
    count += 1;
204
  }
205

206
div.counter
207
  h2 Count: #{count}
208
  button(on:click="{increment}") Increment
209
  
210
  // Conditional rendering
211
  if count > 5
212
    p.warning High count detected!
213
  
214
  // Each blocks
215
  ul
216
    each item, i in items
217
      li(class:active="{i === activeIndex}")= item
218

219
style(lang="scss").
220
  .counter {
221
    padding: 1rem;
222
    border: 1px solid #ccc;
223
    
224
    .warning {
225
      color: red;
226
      font-weight: bold;
227
    }
228
  }
229
```
230

231
### Advanced Pug Features
232

233
```typescript
234
const preprocess = {
235
  markup: pug({
236
    // Custom filters
237
    filters: {
238
      'markdown': (text) => require('marked')(text),
239
      'highlight': (text, options) => require('highlight.js').highlight(text, options).value
240
    },
241
    
242
    // Global variables
243
    globals: ['_', 'moment'],
244
    
245
    // Custom functions
246
    prependData: `
247
      //- Utility mixins
248
      mixin responsive-image(src, alt)
249
        picture
250
          source(media="(max-width: 768px)" srcset=\`\${src}-mobile.jpg\`)
251
          img(src=src alt=alt loading="lazy")
252
      
253
      //- SVG icon helper  
254
      mixin icon(name, size='24')
255
        svg(width=size height=size)
256
          use(href=\`#icon-\${name}\`)
257
    `
258
  })
259
};
260
```
261

262
## Global Style Handling
263

264
### Automatic Processing
265

266
Global styles are automatically processed when using the auto preprocessor:
267

268
```typescript
269
const preprocess = sveltePreprocess({
270
  // Global styles processed automatically if PostCSS available
271
  postcss: true, // Enables global style processing
272
  
273
  scss: true // Global SCSS styles also supported
274
});
275
```
276

277
### Manual Configuration
278

279
```typescript
280
// Explicit global style configuration
281
const preprocess = sveltePreprocess({
282
  globalStyle: {
283
    sourceMap: true
284
  },
285
  
286
  postcss: {
287
    plugins: [require('autoprefixer')]
288
  }
289
});
290
```
291

292
### Selector Transformation
293

294
The global style processor transforms CSS selectors:
295

296
```scss
297
/* Input: style with global attribute */
298
<style global lang="scss">
299
  .button {
300
    padding: 0.5rem 1rem;
301
    
302
    &:hover {
303
      background: #f0f0f0;
304
    }
305
    
306
    .icon {
307
      margin-right: 0.5rem;
308
    }
309
  }
310
</style>
311

312
/* Output: Transformed to global selectors */
313
:global(.button) {
314
  padding: 0.5rem 1rem;
315
}
316

317
:global(.button:hover) {
318
  background: #f0f0f0;
319
}
320

321
:global(.button .icon) {
322
  margin-right: 0.5rem;
323
}
324
```
325

326
## Development Patterns
327

328
### Component Libraries
329

330
```pug
331
<!-- Component template with Pug -->
332
mixin card(title, variant='default')
333
  article.card(class=`card--${variant}`)
334
    header.card__header
335
      h3.card__title= title
336
      if block('actions')
337
        .card__actions
338
          block actions
339
    
340
    .card__content
341
      block content
342

343
<!-- Usage -->
344
+card('My Card', 'primary')
345
  block content
346
    p This is the card content
347
  
348
  block actions
349
    button.btn Edit
350
    button.btn Delete
351
```
352

353
### Global Utilities
354

355
```scss
356
/* Global utility styles */
357
<style global lang="scss">
358
  // Layout utilities
359
  .flex { display: flex; }
360
  .flex-col { flex-direction: column; }
361
  .items-center { align-items: center; }
362
  .justify-between { justify-content: space-between; }
363
  
364
  // Spacing utilities
365
  @for $i from 1 through 12 {
366
    .p-#{$i} { padding: #{$i * 0.25}rem; }
367
    .m-#{$i} { margin: #{$i * 0.25}rem; }
368
  }
369
  
370
  // Responsive utilities
371
  @media (max-width: 768px) {
372
    .hidden-mobile { display: none; }
373
  }
374
</style>
375
```
376

377
### Theming with Global Variables
378

379
```pug
380
<!-- Template with theme classes -->
381
div.app(class="{theme}")
382
  header.header
383
    h1.title= title
384
  
385
  main.content
386
    block content
387

388
style(global lang="scss").
389
  .app {
390
    --primary: #007acc;
391
    --background: #ffffff;
392
    --text: #333333;
393
    
394
    &.dark {
395
      --primary: #66b3ff;
396
      --background: #1a1a1a;
397
      --text: #ffffff;
398
    }
399
  }
400
  
401
  .header {
402
    background: var(--background);
403
    color: var(--text);
404
  }
405
```
406

407
## Error Handling
408

409
### Pug Compilation Errors
410

411
```typescript
412
const preprocess = {
413
  markup: pug({
414
    // Enhanced error reporting
415
    compileDebug: process.env.NODE_ENV === 'development',
416
    
417
    // Pretty error output
418
    pretty: process.env.NODE_ENV === 'development'
419
  })
420
};
421
```
422

423
### Global Style Warnings
424

425
The global style processor will warn when PostCSS is not available:
426

427
```typescript
428
// This will show a warning if PostCSS is not installed
429
const preprocess = sveltePreprocess({
430
  globalStyle: true // Requires PostCSS for proper functioning
431
});
432
```
433

434
## Types
435

436
```typescript { .api }
437
interface PugOptions {
438
  /** Tag name for markup sections */
439
  markupTagName?: string;
440
  
441
  /** Content to prepend to source */
442
  prependData?: string;
443
  
444
  /** Remove leading whitespace (automatically enabled) */
445
  stripIndent?: boolean;
446
  
447
  // Additional Pug compiler options (subset of pug.Options)
448
  /** Pretty-print output */
449
  pretty?: boolean;
450
  
451
  /** Custom filters */
452
  filters?: Record<string, Function>;
453
  
454
  /** Global variables */
455
  globals?: string[];
456
  
457
  /** Additional Pug options (excluding filename, doctype, compileDebug) */
458
  [key: string]: any;
459
}
460

461
interface GlobalStyleOptions {
462
  /** Enable source map generation */
463
  sourceMap: boolean;
464
}
465
```