MarkdownFlow Agent

You are working with MarkdownFlow, a Markdown format extension that enables AI-powered, personalized, and interactive documents. The tagline is "Write Once, Deliver Personally" (一次创作,千人千面).

Core Principle

**CRITICAL**: MarkdownFlow documents are written **for AI agents, not for human readers**. This is the fundamental paradigm:

Repository Structure

This is the main documentation and landing page repository. Key locations:

Separate implementation repos exist under ai-shifu organization (frontend: markdown-flow-ui, remark-flow, markdown-it-flow; backend: markdown-flow-agent-py, markdown-flow-agent-go).

MarkdownFlow Syntax

Core extensions:

1. **Variables**: `{{variable_name}}` - Dynamic placeholders

2. **User Input**: `?[%{{variable}}Option1|Option2]` - Interactive buttons storing choices

3. **Preserved Content**: `===content===` - Content AI should not interpret

Working with Documentation

Development Commands

```bash

Install MkDocs dependencies

pip install mkdocs-material pymdown-extensions

Run MkDocs locally

cd docs

mkdocs serve

Build documentation

mkdocs build --site-dir site --clean

Pre-commit hooks

pip install pre-commit

pre-commit install

pre-commit run --all-files

```

Documentation Guidelines

1. Main entry: `docs/docs/en/index.md`

2. Use formal, official tone

3. **ALL examples must follow core principle**: Show AI instructions, not user content

4. Navigation defined in `docs/mkdocs.yml`

5. Enforce paradigm: "You write prompts for AI, not content for humans"

Linting Rules

Critical Content Consistency Rule

**HOMEPAGE SYNC REQUIREMENT**:

The homepage has TWO content sources that MUST be synchronized:

1. **`home/translations.js`** - Single source of truth (dynamic content)

2. **`home/index.html`** - Static HTML (English)

3. **`home/zh/index.html`** - Static HTML (Chinese)

4. **README files** - Must match translations.js

Update Process (MANDATORY ORDER)

1. Update `home/translations.js` first (both English and Chinese)

2. Update `home/index.html` to match English from translations.js

3. Update `home/zh/index.html` to match Chinese from translations.js

4. Update README files to match translations.js

5. **Never update only one file**

Areas Requiring Sync

Translation Glossary (Chinese)

Use standardized translations for consistency:

Core Terms

Syntax Elements

Technical Components

Documentation Sections

Deployment

Site auto-deploys to GitHub Pages on push to main via `.github/workflows/deploy-gh-pages.yml`:

1. Copies static homepage from `home/` to `_site/`

2. Builds MkDocs docs to `_site/docs/`

3. Deploys to GitHub Pages

Important Files

Task Execution Steps

1. **Understand the core principle**: All examples and docs should demonstrate "writing for AI"

2. **Check content consistency**: Verify homepage sync before editing

3. **Follow translation glossary**: Use standardized Chinese terms

4. **Maintain linting standards**: Run pre-commit before committing

5. **Test documentation locally**: Use `mkdocs serve` to preview changes

6. **Respect repository structure**: Don't modify implementation repos from this repo