What makes Markdown portable?

Portability comes from using widely supported Markdown features and avoiding non-universal extensions or embedded HTML. Keep to the core syntax and test in your target parsers.

How do I handle URLs with parentheses or spaces?

Encode or wrap URLs properly. Use angle brackets or percent-encoding like %28 and %29 to preserve links in text and link syntax.

Do I need YAML frontmatter?

Only if your workflow requires it. YAML frontmatter uses --- fences and should appear at the file start; some parsers render it as text if misused.

Markdown

Verified

@ivangdavila

npx machina-cli add skill @ivangdavila/markdown --openclaw

Files (1)

SKILL.md

2.0 KB

Whitespace Traps

Blank line required before lists, code blocks, and blockquotes—without it, many parsers continue the previous paragraph
Nested lists need 4 spaces (not 2) for GitHub/CommonMark; 2 spaces breaks nesting in strict parsers
Two trailing spaces for <br> break—invisible and often stripped by editors; prefer blank line or <br> tag
Lines with only spaces still break paragraphs—trim trailing whitespace

Links & Images

Parentheses in URLs break [text](url)—use %28 %29 or angle brackets: [text](<url with (parens)>)
Spaces in URLs need %20 or angle bracket syntax
Reference-style links [text][ref] fail silently if [ref]: url is missing—verify all refs exist
Images without alt text: always provide ![alt](url) even if empty ![]() for accessibility tools

Code

Triple backticks inside fenced blocks—use 4+ backticks for outer fence or indent method
Inline backticks containing backtick—wrap with double backticks and pad: `` `code` ``
Language hint after fence affects syntax highlighting—omit only when truly plain text

Tables

Alignment colons go in separator row: :--- left, :---: center, ---: right
Pipe | in cell content needs backslash escape: \|
No blank line before table—some parsers fail
Empty cells need at least one space or break rendering

Escaping

Characters needing escape in text: \*, \_, \[, \], \#, \>, \``, \`
Escape not needed inside code spans/blocks
Ampersand only needs escape as & when it could form an HTML entity

Portability

HTML tags work in GitHub but stripped in many renderers—prefer pure Markdown
Extended syntax (footnotes, task lists, emoji shortcodes) not universal—check target parser
YAML frontmatter needs --- fences and only at file start; some parsers render it as text

Source

git clone https://clawhub.ai/ivangdavila/markdownView on GitHub

Overview

This skill guides you to generate clean, portable Markdown that renders consistently across parsers. It covers whitespace management, links and images, code fences, tables, escaping, and portability pitfalls to avoid parser-specific issues.

How This Skill Works

Markdown content is analyzed and adjusted to follow universal rules. It enforces whitespace before lists and blocks, uses proper code fences, escapes special characters, and validates links and images for portability. It also flags non-portable constructs like HTML or extended syntax that may not be supported by all parsers and recommends plain Markdown alternatives.

When to Use It

Publishing READMEs that render consistently on GitHub, GitLab, and other parsers
Authoring docs with nested lists and tables to ensure correct indentation and alignment
Embedding links and images without breaking due to parentheses, spaces, or missing references
Creating tutorials or blog posts that avoid non-universal extensions and HTML
Preparing code samples with safe backticks and proper language hints for syntax highlighting

Quick Start

Step 1: Scan for whitespace traps (blank lines before lists, before code blocks, etc.)
Step 2: Normalize links, images, code fences, and escaping for portability
Step 3: Validate rendering across target parsers and adjust as needed

Best Practices

Place a blank line before lists, code blocks, and blockquotes to avoid merging paragraphs
Indent nested lists with four spaces to ensure correct nesting in strict parsers
Avoid trailing spaces; prefer blank lines or explicit <br> tags when line breaks are needed
Escape problematic characters in text (*, _, [, ], #, >, `) and handle code spans/blocks cleanly
Favor pure Markdown over HTML and verify support for extensions like footnotes or emoji in your target parser

Example Use Cases

A GitHub README with nested bullets and fenced code blocks using language hints
A docs page containing a table with alignment and escaped pipes
A post with URLs containing parentheses and spaces rendered correctly
An image block with alt text and portable URL handling
A tutorial that relies on pure Markdown without HTML tags across parsers

Frequently Asked Questions

Add this skill to your agents