Skip to content

Getting Started

What is MarkdownFlow?

MarkdownFlow (also known as MDFlow or markdown-flow) extends standard Markdown with AI to create personalized, interactive pages. Its tagline is "Write Once, Deliver Personally".

Instead of writing static content for readers, you write prompts for AI agents. These agents transform your instructions into personalized content that adapts to each user's choices, preferences, and context.

Complete Compatibility with Markdown

MarkdownFlow is not a replacement for Markdown — it's a natural extension:

  • ✅ All standard Markdown syntax works unchanged
  • ✅ All Markdown extensions (tables, task lists, footnotes) work normally
  • ✅ Existing Markdown documents work in MDFlow without modification
  • ✅ Your favorite Markdown editors and toolchains continue to work

You can start with any existing Markdown document and gradually add MDFlow features as needed.

Everyday Syntax First

MarkdownFlow adds two everyday syntax elements to standard Markdown, plus variables for advanced shared context:

Remember the Core Principle

All examples below show AI instructions, not direct user content. You write prompts for AI to generate personalized content.

1. Interactive Elements

Buttons and input fields that collect user choices. For a single MarkdownFlow document, you normally do not need variables; the user's response becomes context for the following content.

Ask the user about their experience level.
?[Beginner | Intermediate | Expert]

Generate a learning recommendation based on the experience level the user just selected.

Ask the user about their habits. Can be single or multiple choice.
?[Movies || Sports || Reading || Traveling]

Collect the user's name in a friendly way.
?[...Enter your name here]

Learn more: Interaction Specification

2. Preserved Content

Text that maintains its exact meaning and style during AI processing.

Introduce our company values, making sure to preserve the exact motto:
===Amplifying humanity's eternal values===

Provide installation instructions, preserving the exact command:
===npm install markdown-flow===

Learn more: Preserved Output Specification

3. Variables

Advanced placeholders for shared context. Use variables when a value must be supplied by the platform or shared across different MarkdownFlow documents.

Generate a welcoming message for {{user_name}} that mentions their
current account balance of {{balance}} in a friendly tone.

For interaction controls, add %{{variable}} only when the answer needs to be stored for cross-document use:

?[%{{shared_level}} Beginner | Intermediate | Expert]

Learn more: Variables Specification

How It Works (Simple Version)

A MarkdownFlow Agent processes your document by:

  1. Reading your MDFlow document (AI instructions)
  2. Incorporating reader responses from interaction controls
  3. Calling a Large Language Model with these combined instructions
  4. Generating personalized content unique to each reader

For the complete technical workflow: See Specification

What's Next?

Ready to dive in? Follow this learning path:

  1. Core Concepts - Understand the fundamental principles
  2. Quick Start - Build your first interactive document
  3. Try It Now - Practice with live examples
  4. Next Steps - Explore advanced features and get help

Or jump straight to the action with our 5-minute Quick Start!