md-scaffold

name	md-scaffold
description	Scaffold properly structured Markdown files from templates for clean first-pass conversion
tier	extended
inheritance	inheritable
applyTo	**/*scaffold*,**/*template*,**/*.md
muscle	.github/muscles/md-scaffold.cjs

Markdown Scaffolder

Start right, convert clean — templates that work with every converter

Generate properly structured Markdown files from battle-tested templates. Each template includes correct frontmatter, extended syntax examples, converter directives, and navigation sentinels so documents convert cleanly on first pass.

---

When to Use

• Starting a new document that will be converted to Word, PDF, or email
• Need a consistent structure for reports, tutorials, or reference guides
• Want converter-ready Markdown with correct frontmatter from the start
• Creating Gamma-ready slide decks from Markdown
• Ensuring consistent document structure across a team
• Setting up documentation for a new project

---

Available Templates

Template	Purpose	Includes
report	Formal report with TOC	Executive summary, sections, appendix, tables
tutorial	Step-by-step guide	Prerequisites, learning objectives, exercises
reference	CLI/API reference	Commands, parameters, examples
slides	Gamma-ready presentation	H2 slide breaks, speaker notes format
email	Newsletter/governance email	YAML frontmatter for RFC 5322 headers

---

Usage

# Create a report
node .github/muscles/md-scaffold.cjs report "Quarterly Review"

# Create a tutorial with custom output path
node .github/muscles/md-scaffold.cjs --output docs/guide.md tutorial "Getting Started"

# List available templates
node .github/muscles/md-scaffold.cjs --list

# Create slides for a presentation
node .github/muscles/md-scaffold.cjs slides "Sprint Demo"

# Create email template
node .github/muscles/md-scaffold.cjs email "Weekly Update"

---

Options Reference

Option	Description
--output PATH	Custom output path (default: title-slugified.md)
--list	List all available templates
--author NAME	Set author in frontmatter
--force	Overwrite existing file

---

Template Design Principles

1. Converter-ready: Every template produces Markdown that passes markdown-lint.cjs on first run
2. Navigation sentinels: <!-- nav:start --> / <!-- nav:end --> markers for nav-inject.cjs
3. Frontmatter included: Correct YAML frontmatter for the target converter
4. Extended syntax: Callouts, kbd shortcuts, highlights, and other extended Markdown features
5. Minimal editing: Fill in content, delete unused sections — ready to convert

---

Template Details

Report Template

---
title: "{{title}}"
author: "{{author}}"
date: "{{date}}"
style: professional
toc: true
---

Includes:

• Executive Summary
• Background
• Analysis with tables
• Recommendations
• Appendix
• Nav sentinels

Tutorial Template

---
title: "{{title}}"
author: "{{author}}"
date: "{{date}}"
difficulty: intermediate
time: "30 minutes"
---

Includes:

• Learning Objectives
• Prerequisites
• Step-by-step sections
• Exercises
• Summary
• Next Steps

Reference Template

---
title: "{{title}}"
version: "1.0.0"
date: "{{date}}"
---

Includes:

• Synopsis
• Commands table
• Options table
• Examples
• Exit codes
• See Also

Slides Template

---
title: "{{title}}"
author: "{{author}}"
date: "{{date}}"
format: gamma
---

Includes:

• H2 slide breaks
• Speaker notes format <!-- notes: -->
• Image placeholders
• Bullet point structure

Email Template

---
to: [e-mail]
from: [e-mail]
subject: "{{title}}"
cc: 
reply-to: 
---

Includes:

• Greeting
• Body sections
• Call to action
• Signature

---

Workflow Integration

New Project Documentation

# Scaffold initial docs
node .github/muscles/md-scaffold.cjs report "Project Charter"
node .github/muscles/md-scaffold.cjs reference "CLI Reference"
node .github/muscles/md-scaffold.cjs tutorial "Getting Started"

Convert to Distribution Format

# Scaffold → Edit → Convert
node .github/muscles/md-scaffold.cjs report "Q4 Review"
# ... edit quarterly-review.md ...
node .github/muscles/md-to-word.cjs quarterly-review.md --style professional

---

Troubleshooting

Problem	Cause	Solution
File already exists	Default won't overwrite	Use --force or --output
Template not found	Typo in template name	Use --list to see options
Frontmatter invalid	Manual editing broke YAML	Re-scaffold or fix YAML syntax

---

Requirements

• Node.js 18+

---

Muscle Script

.github/muscles/md-scaffold.cjs (v1.0.0)

---

Related Skills

• md-to-word — Convert scaffolded docs to Word
• md-to-html — Convert scaffolded docs to HTML
• md-to-eml — Convert email templates to .eml
• lint-clean-markdown — Validate scaffolded output
• nav-inject — Inject navigation using sentinels
• gamma-presentation — Alternative for Gamma slides

---

Skill version: 2.0.0 | Last updated: 2026-04-14 | Category: document-conversion