DEV Community

Markdown Basics 🤓

Below are some examples of commonly used markdown syntax. If you want to dive deeper, check out this cheat sheet.

Bold & Italic

Italics: *asterisks* or _underscores_

Bold: **double asterisks** or __double underscores__

Links

I'm an inline link: [I'm an inline link](put-link-here)

Inline Images

example image, with sloan ![Image description](put-link-to-image-here)

Headers

Add a header to your post with this syntax:

      
#One '#' for a h1 header
##Two '#'s for a h2 header
...
######Six '#'s for a h6 header

One '#' for a h1 header

Two '#'s for a h2 header

Six '#'s for a h6 header

We support native Liquid tags in our editor, but have created our own custom tags as well. A list of supported custom embeds appears below. To create a custom embed, use the complete URL:
{% embed https://... %}

Universal URL Embeds

For most supported platforms, you can simply use the {% embed URL %} syntax. The platforms natively supported are:

  • Asciinema
  • Bandcamp
  • Blogcast
  • Bluesky
  • Bolt.new
  • Cloud Run
  • CodePen
  • CodeSandbox
  • DotNetFiddle
  • GitHub (Gist, Issue, Repo)
  • Glitch
  • Hugging Face Space
  • Instagram
  • JSFiddle
  • JSitor
  • Kotlin
  • LiveCodes
  • Loom
  • Lovable
  • Medium
  • Mux
  • Next Tech
  • Reddit
  • Replit
  • Slideshare
  • SoundCloud
  • Speaker Deck
  • Spotify
  • StackBlitz
  • Stackery
  • Stack Exchange / Stack Overflow
  • Twitch
  • Twitter (Tweet or Timeline)
  • Vimeo
  • Warp Terminal
  • Wikipedia
  • YouTube

Example: {% embed https://www.youtube.com/watch?v=12345 %}

DEV Community Specific Embeds

You can also use explicit tags to embed internal content across the platform:

  • Article Link: {% link URL %} (Renders a card for the article)
  • User Profile: {% user username %}
  • Tag Profile: {% tag tagname %}
  • Comment: {% comment comment_id_code %} (or use a comment URL)
  • Podcast Episode: {% podcast URL %}
  • Organization: {% organization orgname %}

Agent Session

Embed a curated coding agent session (from Claude Code, Codex, Gemini CLI, Aider, etc.):

{% agent_session ID %}

Embed a named slice (created in the curation tool) to narrate different parts throughout your post:

{% agent_session ID planning %}

Or embed a specific range of messages by index:

{% agent_session ID 0..10 %}

Upload and curate a session to get the ID.

Card

You can create a standalone highlight card to emphasize important content. The content inside the card can use Markdown.

{% card %}
This is some **important** content inside a card!
{% endcard %}

Call To Action (CTA)

Provide a link that a user will be redirected to when clicked. The description will contain the label/description for the call to action button.

{% cta link %}
description
{% endcta %}

Details / Spoiler / Collapsible

You can embed an interactive HTML element to hide content behind a summary. This is great for hiding text (i.e. answers to questions) behind a click.

  {% details summary %} content {% enddetails %}
  {% spoiler summary %} content {% endspoiler %}
  {% collapsible summary %} content {% endcollapsible %}

KaTex

Place your mathematical expression within a KaTeX liquid block, as follows:

{% katex %}
c = \pm\sqrt{a^2 + b^2}
{% endkatex %}

To render KaTeX inline add the "inline" option:

{% katex inline %} c = \pm\sqrt{a^2 + b^2} {% endkatex %}

Feed

Embed an article feed by organization, tag, or multiple tags:

{% feed org=org-slug %}
{% feed tag=ruby %}
{% feed tags=ruby,javascript limit=10 sort=reactions %}

Options: limit (1-30), sort (recent/reactions/comments/score), min_reactions, min_comments, since (e.g. 30d or 2025-01-01).

Layout (Row & Col)

Create responsive grid layouts:

{% row %}
{% col background=default %}Column 1{% endcol %}
{% col span=2 background=subtle %}Wide column{% endcol %}
{% endrow %}

span sets column width (1-4, default 1). background accepts default or subtle.

Features

Display a grid of feature cards:

{% features %}
{% feature title="Fast" icon="lightning" %}Optimized for speed.{% endfeature %}
{% feature title="Secure" icon="🔒" %}Built with security in mind.{% endfeature %}
{% feature title="Simple" %}No icon needed.{% endfeature %}
{% endfeatures %}

title is required. icon is optional and accepts either an emoji or one of the supported icon names below.

Supported icons: analytics, badge, book, boost, calendar, checkmark, code, cog, comment, connect, discover, email, fire, heart, image, lightning, location, lock, organization, pencil, people, raised-hands, search, sparkle-heart, sparkles, team, verified, video-camera, wallet.

Quote

Display a testimonial or quote:

{% quote author="Jane Doe" role="CTO" rating=5 %}Great product!{% endquote %}

Options: author (required), role, image, rating (1-5), source, link.

Group several testimonials into responsive columns:

{% quotes %}
{% quote author="Jane Doe" rating=5 %}Great product!{% endquote %}
{% quote author="John Smith" %}Easy to recommend.{% endquote %}
{% endquotes %}

Offer

Create a call-to-action box with a button:

{% offer link="https://example.com" button="Sign Up" %}Join us today!{% endoffer %}

link is optional (button is hidden without it). button defaults to "Learn More".

Slides

Create an image/video carousel or gallery:

{% slides mode="carousel" %}
{% slide image="https://example.com/photo.jpg" alt="Description" %}
{% slide video="https://youtube.com/watch?v=abc123" %}
{% endslides %}

Each slide needs at least one of: image, video, or link. Optional: title, alt.

mode="carousel" presents cards in a swipeable, scroll-snapping strip with optional desktop controls.

Parsing Liquid Tags as a Code Example

To parse Liquid tags as code, simply wrap it with a single backtick or triple backticks.

`{% mytag %}{{ site.SOMETHING }}{% endmytag %}`

One specific edge case is with using the raw tag. To properly escape it, use this format:

`{% raw %}{{site.SOMETHING }} {% ``endraw`` %}`

Here's the Markdown cheatsheet again for reference.

Happy posting! 📝