How to Center Text in Markdown: The Complete 2026 Guide

You can't center text in markdown using markdown alone. The CommonMark specification defines no alignment syntax, and the GitHub Flavored Markdown spec only adds alignment for table columns. Every other case — centered headings, centered images, centered paragraphs — requires HTML, and that HTML survives or dies depending on the platform rendering your file.

This guide gives you the exact snippet for each case, the compatibility table for twelve platforms, and the workarounds for the two that strip everything (npm and Reddit).

New to markdown formatting? Caleb Curry's crash course is a quick primer on the syntax and where raw HTML (like centering) fits in:

The short answer: markdown can't center text on its own#

If you came here looking for ::: center or <<>> or some clever asterisk trick, stop searching. It doesn't exist.

The only alignment the markdown spec acknowledges is table column alignment:

| Left | Center | Right |
| :--- | :----: | ----: |
| a    | b      | c     |

For everything else, you drop into HTML. The HTML attribute that works almost everywhere is the deprecated align="center" on a block element. Yes, it's deprecated. MDN documents that align is obsolete but still widely supported. The reason it's still the practical answer in 2026 is that the modern alternative — style="text-align: center" — gets stripped by most platform sanitizers for security reasons.

How to center text in markdown (the HTML way)#

There are three snippets you'll actually use. They look similar; the differences matter.

Option 1: <div align="center"> — the safest bet#

Some left-aligned text above.
 
<div align="center">
 
This paragraph is centered.
 
</div>
 
Some left-aligned text below.

The blank lines around the <div> and inside it are not optional. Without them, many parsers treat the inside as a literal HTML block and skip markdown parsing entirely. With them, you can write markdown inside the div — including links, bold, lists, even images.

Option 2: <p align="center"> — for a single paragraph#

<p align="center">
  This single paragraph is centered, and you don't need extra blank lines.
</p>

This is more compact but you cannot put block-level markdown (headings, lists, blockquotes) inside a <p> tag — that's invalid HTML and most parsers will close the paragraph for you, with unpredictable results.

Option 3: style="text-align: center" — usually doesn't work#

<div style="text-align: center">This rarely renders centered.</div>

This is the technically-correct modern approach and the one that almost never works on the platforms you care about. GitHub, GitLab, and npm all run HTML sanitizers that strip inline style attributes by default. The open-source pipeline GitHub uses to sanitize rendered markdown explicitly removes the style attribute. Use this only when you control the rendering pipeline.

How to center images and headings#

Centering text is the easy part. Most people actually want to center a logo, a header image, or a heading at the top of a README.

Center an image#

<div align="center">
 
![Project logo](./assets/logo.png)
 
</div>

Or with an <img> tag if you need to control the size:

<div align="center">
  <img src="./assets/logo.png" alt="Project logo" width="200" />
</div>

Both render the same way on GitHub. The <img> form is better when you need a width attribute, since the markdown image syntax has no way to set dimensions. There's more nuance to embedding images in a GitHub README the right way, especially around relative paths and dark-mode variants.

Center a heading#

Headings are tricky because you can't put a markdown # heading inside a <p align="center">. Use <h1>/<h2> directly:

<h1 align="center">My Project</h1>
<p align="center">A short tagline that explains what it does.</p>

This is the de-facto README pattern on GitHub. You lose the markdown heading anchor that some renderers auto-generate, but for the top of a README that doesn't matter.

Center a whole block — logo, heading, badges, and tagline#

<div align="center">
 
<img src="./logo.png" alt="Logo" width="120" />
 
# My Project
 
A one-line description.
 
[![npm version](https://badge.fury.io/js/myproject.svg)](https://npmjs.com/package/myproject)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
</div>

The blank lines inside the div let markdown parse normally — so the # becomes a real <h1> and the badge syntax becomes real images. This pattern is the answer to centering a heading in markdown for 95% of READMEs.

Platform compatibility: what actually renders where#

Here's the part nobody puts in one place. Which platforms render <div align="center">, which strip it, and which only support a subset.

The pattern: anything based on a permissive renderer (MDX, Obsidian, static-site generators) accepts everything. Anything that runs your content through a sanitizer (GitHub, GitLab, Bitbucket) accepts the align attribute and strips inline styles. Anything that strips HTML entirely (npm, Reddit, Discord) gives you nothing.

The npm and Reddit problem (and what to do instead)#

The npm registry and Reddit both ship your markdown through aggressive sanitizers. The align attribute is stripped. Inline styles are stripped. Most tags beyond a small whitelist are stripped entirely.

For npm specifically, this is the most common surprise: a README that looks gorgeous on GitHub renders as a left-aligned wall of text on the npm package page. The npm renderer is strict for security reasons that are reasonable, but it makes consistent presentation impossible.

The workarounds:

1. Bake centering into your images. If you want a centered logo on npm, export the logo at the target width of the README (around 700px) with the actual logo centered inside transparent padding. The image itself is left-aligned, but the visible content inside looks centered.

2. Use ASCII spacing for text. Crude, but it works on Reddit and npm:

                    Centered-ish heading

This relies on monospaced fonts in code blocks. Outside a code block it falls apart because proportional fonts ignore extra spaces.

3. Accept left alignment and design around it. This is the answer most maintainers eventually land on. Use badges, bold headings, and structure to create visual hierarchy instead of relying on alignment.

4. Maintain a separate README for npm. Some projects use the files field in package.json to ship a stripped-down README.npm.md. It's effort, but if presentation matters for adoption, it's the only way to get both surfaces right.

Centering in MDX: the modern way#

MDX is different. It accepts real JSX, so you can use real CSS instead of fighting deprecated HTML attributes.

The simplest approach with Tailwind:

<div className="text-center">
 
# A centered heading
 
A centered paragraph below it.
 
</div>

Or with inline style, which actually works in MDX because there's no sanitizer in your way:

<div style={{ textAlign: "center" }}>
  Centered text without the `align` attribute.
</div>

If you're using a documentation platform, the cleanest answer is usually a component:

For a full inventory of what's available, see the full MDX component reference. And if you'd rather not write JSX by hand at all, writing docs in a visual MDX editor instead of fighting raw syntax handles all of this through a Notion-style interface.

Common mistakes that break centering#

Five gotchas that turn working snippets into broken ones.

1. No blank line between the opening tag and the content#

<div align="center">
**This bold won't render.**
</div>

The parser treats the contents as a raw HTML block and skips markdown processing. Add blank lines:

<div align="center">
 
**This bold renders correctly.**
 
</div>

This is the same blank-line rule that governs horizontal rules and the blank-line rules around block HTML — markdown is strict about block-level boundaries.

2. Using the wrong attribute name#

<div align=center>     <!-- works but unquoted, fragile -->
<div align="centre">   <!-- British spelling, doesn't work -->
<div alignment="center"> <!-- not a real attribute -->

The only attribute that works is align. The only value that centers is center. Quote it.

3. Prettier or your editor reformatting your HTML#

Prettier loves to collapse this:

<div align="center">
 
# Heading
 
</div>

Into this:

<div align="center"># Heading</div>

Which then renders as literal text. Add <!-- prettier-ignore --> above the block, or configure Prettier to leave markdown HTML alone.

4. Indenting your HTML block by four spaces#

If your <div> is indented four spaces (often because it's inside a list or a blockquote), most parsers treat it as a code block. Pull it back to column zero, or learn indenting content correctly so HTML blocks don't get parsed as code if you genuinely need it nested.

5. Nesting block elements inside inline ones#

<p align="center">
  <h2>This is invalid HTML</h2>
</p>

A <p> cannot contain a <h2>. Browsers will silently close the <p> before the <h2> starts, and your alignment evaporates. Use <div> whenever you put a heading or list inside.

When to stop fighting and use a real component#

If you're writing a README, you're stuck with HTML hacks. That's the format. But if you're writing actual documentation — a docs site, a product help center, an internal wiki — centering is a UI concern, not a content concern, and the answer isn't <div align="center">. The answer is a component.

A "Hero" component centers your hero. A "Logo" component centers your logo. A "Callout" component handles its own styling. You stop thinking about alignment entirely because the component owns it. This is also the case for why blockquotes and callouts often beat raw HTML formatting — once you have proper components, you stop reaching for the lower-level primitive.

Dokly takes this further by handling the whole MDX layer for you. Centered headings, callouts, step-by-step walkthroughs, and tabs are all components with sensible defaults, and the visual editor means you never type a <div align="center"> again. If your docs are still living in raw markdown with HTML hacks, the migration takes minutes.

Frequently Asked Questions#

Can you center text in pure markdown without HTML?#

No. The CommonMark and GitHub Flavored Markdown specs don't include alignment syntax for text or images. The only built-in alignment is for table column contents using colons in the divider row. For anything else, you have to drop into HTML, and that HTML may or may not render depending on the platform.

Does GitHub markdown support centered text?#

Yes, GitHub renders <div align="center"> and <p align="center"> in README and issue files. It does strip inline style attributes through its HTML sanitizer, so style="text-align: center" will not work. Stick with the align attribute on a div or p tag — it's deprecated in HTML5 but GitHub still honors it.

How do I center an image in markdown?#

Wrap the standard markdown image syntax (or an <img> tag) inside a <div align="center"> block, with a blank line before and after the div. On platforms that strip HTML you cannot center images at all — your only option is to pre-crop the image with padding baked in.

Why doesn't text-align: center work in my markdown file?#

Most markdown renderers run an HTML sanitizer that strips inline style attributes for security reasons. GitHub, GitLab, and npm all do this. The deprecated align attribute usually survives the sanitizer, which is why it remains the practical answer in 2026 even though it's technically obsolete HTML.

How do I center text in MDX?#

MDX accepts real JSX, so you can use a Tailwind class like <div className="text-center">, a styled component, or a documentation platform's built-in components. This is the cleanest path because you get real CSS instead of fighting with deprecated HTML attributes.

Will centered text work on npm package pages?#

Usually not. The npm registry strips most HTML from README files, including align attributes and style attributes on common tags. If your README needs to look good on npm, design it to read fine left-aligned and only center things that gracefully degrade, like images that look fine either way.

If you're tired of working around markdown sanitizers and just want docs that look right by default, try Dokly free — the visual MDX editor handles centering, callouts, and the rest as components, so you never write another <div align="center">.