QUICKSTART.md

Quick Start Guide - Manifest-Driven Content Generator

Get started with the manifest-driven content generator in 5 minutes.

What It Does

Extracts content from markdown files based on patterns and inserts it into templates.

Example: Extract all objectives from all modules and put them in a website document.

Installation

cd tools/content-generator
npm install

Basic Usage

Step 1: Verify Your Setup

The example configuration is already set up for you:

node manifest-generator.js --validate

You should see:

✓ Validation passed
  Documents: 1
  Extractions: 2
  Warnings: 0

Step 2: Generate Content

node manifest-generator.js

This creates output/website.md with extracted objectives and topics from the guide template.

Step 3: Check the Output

cat output/website.md

You'll see objectives and topics extracted from the source guide and inserted into the template.

How It Works

1. The Manifest (manifest.yml)

Defines what to extract and where to put it:

primary_source: "../merge-markdown/merged/guide/Guide Template.md"

documents:
  output/website.md:
    template: website.md
    extractions:
      objectives:
        pattern: "#### Objectives"  # Find this heading
        scope: bullets               # Collect bullets until next heading
      topics:
        pattern: "## "               # Find any H2 heading
        scope: self_plain            # Collect just the heading text

2. The Template (website.md)

Contains placeholders where content will be inserted:

## Objectives

//Generated by content-generator
//objectives

## Topics

//Generated by content-generator
//topics

3. The Magic ✨

The generator:

1. Finds all instances of "#### Objectives" in the source
2. Collects all bullets from each until the next heading
3. Combines them into one list
4. Replaces //objectives placeholder with the list

Same process for topics!

Common Patterns

Extract Module Titles

modules:
  pattern: "# Module"
  scope: self_plain

Extract Prerequisites

prerequisites:
  pattern: "## Prerequisites"
  scope: bullets

Extract Introduction Text

intro:
  pattern: "## Introduction"
  scope: text

Extract Code Examples

code:
  pattern: "## Example"
  scope: code

Scope Types Cheat Sheet

Scope	What It Collects	Example Use
self	Just the matched line	Headings with formatting
self_plain	Matched line, no formatting	Clean heading text
bullets	All bullets until next heading	Objectives, prerequisites
text	Paragraph text	Descriptions, intros
code	Code blocks	Examples
all	Everything	Complete sections

Add _plain to any scope to strip markdown formatting.

Next Steps

1. Read the full docs: MANIFEST_README.md
2. Explore scope types: SCOPE_TYPES.md
3. Understand validation: VALIDATION.md
4. Modify manifest.yml to extract different content
5. Create your own templates for different output formats

Troubleshooting

Problem: No content extracted

Solution:

• Check that pattern matches lines in source (case-sensitive!)
• Verify scope type is correct (bullets for lists, text for paragraphs)

Problem: Content not inserted in template

Solution:

• Ensure placeholder key matches extraction key exactly
• Use proper two-line format: //Generated by content-generator then //key

Problem: Wrong content extracted

Solution:

• Make pattern more specific (e.g., "## Activity" instead of "## ")
• Collection stops at ANY heading - this might include sub-sections

Examples Directory

See the output/ directory for generated examples:

• website.md - Course metadata with objectives and topics
• (Add more as you create them)

Tips

1. Test with --validate before generating to catch errors
2. Start simple - one extraction, one template
3. Pattern specificity - more specific patterns = more control
4. Use primary_source for documents that share the same source
5. Check the output - verify extracted content is what you expect

Getting Help

• Validation errors? Check VALIDATION.md
• Scope confusion? See SCOPE_TYPES.md
• Complex setup? Read MANIFEST_README.md

What's Next?

Try creating a new document:

1. Create a template file with placeholders
2. Add it to manifest.yml under documents:
3. Define your extractions
4. Run node manifest-generator.js --validate
5. Run node manifest-generator.js
6. Check your output!

Happy generating! 🎉