md2wechat-skill

The Professional API mode is designed for stable output, team collaboration, and Agent automation. Unlike the free mode, it provides:

• Direct WeChat HTML: Returns final HTML instead of just prompts.
• Advanced Themes: Access to 48 professional themes.
• Layout Parsing: Parses 53 recommended :::module syntax names.
• Automation: Suitable for managing multiple accounts and matrix publishing.

To use these features, you must apply for API service via the '极客杰尼' WeChat official account.

The md2wechat tool supports converting Markdown content into WeChat-compatible HTML with the following features:

• Markdown to HTML conversion: Standard Markdown syntax is transformed for WeChat.
• Automatic image uploading: Handles both local and remote images.
• Theming: Supports multiple beautiful themes.
• Draft creation: One-click creation of WeChat drafts.

The project is designed to transform Markdown into stable, verifiable, and automatable WeChat Official Account content. The core workflow follows this sequence:

cmd (CLI entry) $\rightarrow$ inspect (validation/metadata) $\rightarrow$ converter/publish (orchestration) $\rightarrow$ asset pipeline (image processing) $\rightarrow$ draft/wechat adapters (platform delivery).

Key architectural components:

• inspect: The single source of truth for metadata, readiness, and semantic checks.
• preview: A view layer that reuses inspect results and calls the converter to generate HTML, but does not perform side effects like uploading.
• convert: The primary command for transformation, metadata extraction, and executing side effects (uploading/draft creation) based on flags.
• AssetPipeline: Handles image uploading, generation, downloading, and HTML backfilling.

Advanced Layout Modules are visual card components used to enhance WeChat Official Account articles. They are written in Markdown using the :::module_name syntax and are rendered into structured HTML via the md2wechat API.

Note: These modules are exclusive to API mode. The convert command uses API mode by default. Access to the API requires consultation with the author.

The 4-Purpose Principle

To maintain readability and avoid clutter, follow the principle of using minimal modules, targeting one module per purpose:

• attention: Capture interest (e.g., hero, cards, verdict).
• readability: Improve mobile reading experience (e.g., toc, steps, part).
• memorability: Help readers remember key points or brands (e.g., verdict, manifesto, author-card).
• conversion: Drive actions like follows or purchases (e.g., cta, faq, checklist).

It is important to understand the difference between the two configuration types in md2wechat:

When reporting an issue on GitHub, include the following diagnostic data to help maintainers resolve the problem quickly:

1. Version Information: Run md2wechat version --json and go version.
2. Configuration Summary: Run md2wechat config show --format json.
3. Error Logs: Provide the failed command and its full error output (e.g., md2wechat convert article.md 2>&1).
4. System Info: Run uname -a on macOS/Linux or systeminfo on Windows.

# Example of gathering diagnostic data
md2wechat version --json
go version
md2wechat config show --format json
md2wechat convert article.md 2>&1

Initialize the default configuration file by running md2wechat config init. The configuration is stored at ~/.config/md2wechat/config.yaml.

To create WeChat drafts, you must configure the following keys:

• wechat.appid
• wechat.secret
• api.md2wechat_key

You can also switch the API domain by modifying api.md2wechat_base_url in the config file. Supported domains include https://www.md2wechat.cn and https://md2wechat.app.

Create WeChat image posts (newspic/image messages) using either local files or Markdown content.

• From Files: Specify a title and a list of images.
• From Markdown: Use the --from-markdown flag. This supports both local image paths and remote image URLs (remote images are automatically downloaded, uploaded to WeChat, and then used to create the post).

The Brand Profile is a Markdown file used by Agents (not the CLI) to understand brand context, tone, and style preferences. It is stored at ~/.config/md2wechat/brand.md.

Setup

Use the following commands to manage the profile:

• md2wechat brand init: Initializes a new Brand Profile (idempotent; won't overwrite if it exists).
• md2wechat brand show: Displays the current profile.
• md2wechat brand show --json: Displays the profile in JSON format, including the raw Markdown content in the data.content field.

Usage for Developers/Agents

Agents should read the content of brand.md and use it as context for content generation. If the file is missing, the Agent should fall back to default styles. If the file exists but is unreadable, the Agent should notify the user and use default styles.

After installation, use the following commands to initialize your configuration and validate it. Using the --json flag is recommended for machine-readable output.

md2wechat version --json
md2wechat config init --json
md2wechat config validate --json