Skip to main content
This lesson shows how to apply common Markdown (and MDX) formatting to a README. It walks through practical examples you can paste directly into your README source to improve readability on GitHub and other Markdown renderers.
A few MDX-specific tips for editing READMEs rendered as MDX:
  • Wrap snippets that include curly braces or angle-bracket placeholders in backticks, for example: `{{workflow.name}}` or `https://localhost:<PORT>`.
  • Avoid placing raw JSON or object literals inline; use fenced code blocks to ensure correct rendering and parsing.
When adding examples with placeholders (e.g., <PORT>, <name>) or template variables (e.g., {{inputs.param}}), always wrap them in backticks to prevent the MDX parser from interpreting them as JSX or template syntax.

​
Quick reference

Use this short reference for common Markdown elements and how to use them in README files.

​
Hiding lines with HTML comments

Use HTML-style comments in the README to keep content visible only in the source but hidden when rendered on GitHub:
These are useful for leaving notes, TODOs, or editing reminders inside your README file.

​
Headings

Create headings with the hash (#) character. More hashes produce smaller headings:
Headings structure content for both readers and search engines—use them to improve readability and SEO by including concise, descriptive phrases.

​
Blockquotes

Use the greater-than symbol (>) to make quoted blocks:
Blockquotes are great for highlighting notes, quotes, or important callouts inside regular text.

​
Emphasis and inline code

Use emphasis and inline code to call out terms, filenames, or commands:
  • Italic: *italic* or _italic_
  • Bold: **bold** or __bold__
  • Inline code: use backticks `like this`
Example:
Tip: prefer inline code for short commands, filenames, or placeholders.

​
Horizontal rule / divider

Separate sections with a horizontal rule. Any of these work:
Horizontal rules visually break longer README files into logical parts.

​
Lists

Use unordered (bulleted) or ordered (numbered) lists for steps, features, or itemized details. Unordered:
Ordered:
Lists improve scanability and accessibility of README content.

​
Task lists (checkboxes)

GitHub-Flavored Markdown supports task lists to show progress or checklist items:
Task lists render as interactive checkboxes on GitHub and are useful for contributing guides or project roadmaps.

​
Tables

Create tables with pipes (|) and separate the header row with dashes (-). Example:
Tables are ideal for comparing tools, listing features, or showing compatibility. Keep table rows concise for best readability. Create hyperlinks using square brackets for text and parentheses for the URL. Combine links with inline code formatting when you want to highlight technologies:
These appear as clickable items in the rendered README.
Once you add these elements to your README and commit the changes (for example, committing directly to the main branch), GitHub will render headings, blockquotes, lists, task checkboxes, tables, and links—making your profile or project README easier to scan and more informative. Use these references for advanced MDX/Markdown features and best practices.

Watch Video