There’s no Markdown syntax for centering text, images, headings, or tables. What you can do is drop a bit of HTML into your Markdown file. Which bit of HTML depends on where your Markdown ends up:
- On GitHub (READMEs, issues, pull requests), use the
alignattribute:<p align="center">,<div align="center">, or<h1 align="center">. GitHub stripsstyleattributes, so CSS does nothing there. - Almost everywhere else that renders HTML, such as VS Code’s preview, Obsidian, Jupyter, and most static site generators, CSS works too:
<p style="text-align: center;">. - Pandoc to PDF ignores HTML. Use LaTeX there:
\begin{center}…\end{center}.
If you’re here for a GitHub README, this is the snippet you probably want: a centered logo, title, tagline, and a row of badges.
<div align="center">
<img src="docs/logo.png" alt="My Project logo" width="120">
<h1>My Project</h1>
<p>A one-line description of what it does.</p>
<p>
<a href="https://github.com/you/my-project/actions"><img src="https://img.shields.io/badge/build-passing-brightgreen" alt="Build status"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
</p>
</div>
Replace the paths and links with your own. Here’s roughly what that looks like (I left the badges out of this preview, and the font is my site’s, not GitHub’s):
My Project
A one-line description of what it does.
The rest of this article explains why this works, how to center each kind of element, and what to use on other platforms. Every rendered example on this page is rendered by my WordPress site, so spacing and fonts will look a little different on GitHub. For a complete README template, see my article on README.md files.
Why CSS doesn’t work on GitHub (and align does)
Markdown was designed to let you fall back to HTML for anything it can’t do, and centering is one of those things. The catch is that sites like GitHub don’t trust the HTML you write. Before showing your README, GitHub sanitizes it. Its markup documentation says this step removes script tags, class and id attributes, and inline styles.
So <p style="text-align: center;"> becomes a plain <p> on GitHub, and your text ends up on the left. The old align attribute survives the cleanup, and so do width and height on images. That’s why every centered README you’ve seen uses align="center".
A note on the deprecated align attribute and center tag
Strictly speaking, align is deprecated in HTML (see the <div> element on MDN), and the <center> tag is obsolete. Browsers still support both. My advice:
- On GitHub, use
align="center". It’s the only thing that works, and there’s no sign of GitHub dropping it. Don’t use<center>: GitHub removes the tag. - On your own website or any platform that keeps
style, use CSS. It’s the modern, valid way to do it.
Markdown center text
To center a line or paragraph of text on GitHub, wrap it in a paragraph with the align attribute:
Here's some regular text. <p align="center">A piece of centered text</p> And some more regular text.
On platforms that keep CSS, you can use text-align instead (text-align on MDN):
<p style="text-align: center;">A piece of centered text</p>
Either way, the result looks like this:
Here’s some regular text.
A piece of centered text
And some more regular text.
Using Markdown inside a centered block
Here’s the gotcha that trips up most people. Markdown is not processed inside an HTML block that starts on the same line or the line right after the opening tag. This shows the literal asterisks:
<p align="center"> This is **not** bold on GitHub </p>
The fix is a <div> with a blank line after the opening tag and before the closing tag. The blank lines end the HTML block, so the parser goes back to reading Markdown in between:
<div align="center"> This **is** bold, and [this is a link](https://markdown.land). </div>
This behavior comes straight from the CommonMark rules for HTML blocks, so it works the same on GitHub, GitLab, and most modern Markdown parsers. Use <div> rather than <p> for this trick: Markdown wraps your text in its own <p>, and a paragraph inside a paragraph is invalid HTML.
Two exceptions: Obsidian never renders Markdown inside HTML elements, and Jekyll’s kramdown parser only does it when you add markdown="1" to the tag, like <div align="center" markdown="1">. If you only need bold or links in a single centered line, it’s easier to use the HTML tags <b> and <a href="…"> directly.
Markdown center titles and headers
Headings work the same way. On GitHub:
<h1 align="center">My Project</h1> <h2 align="center">Installation</h2>
And with CSS everywhere else:
<h1 style="text-align: center;">My Project</h1>
Markdown formatting inside the heading isn’t processed, so <h1 align="center">My **Project**</h1> shows the asterisks. Use <h1 align="center">My <em>Project</em></h1> instead.
Some static site generators let you add attributes to a regular Markdown heading. In Hugo you can write ## Installation {.text-center} (attributes on headings are on by default), and in Jekyll you can put {: .text-center} on the line after the heading. Both add a CSS class, so your theme needs a .text-center { text-align: center; } rule for it to do anything.
Markdown center image
Markdown’s image syntax, , has no option for alignment or size. To center an image on GitHub, put an HTML <img> tag inside a centered paragraph:
<p align="center"> <img src="https://markdown.land/wp-content/uploads/2021/06/markdown-512px.png" alt="The Markdown logo" width="150"> </p>
Result:
If you’d rather keep Markdown image syntax, use the <div> with blank lines from the text section:
<div align="center">  </div>
One thing that does not work: putting align="center" on the <img> tag itself. For images, the align attribute only knows left, right, and a few vertical positions. The centering always goes on the wrapper.
Center an image and resize it
Use the width attribute (or height, but usually not both, so the image keeps its proportions). The value is a number of pixels, without px. Browsers also accept a percentage, like width="50%", even though the HTML spec only allows pixel numbers. GitHub keeps both width and height.
On platforms with CSS, you can center the image itself, without a wrapper, by making it a block with automatic side margins:
<img src="https://markdown.land/wp-content/uploads/2021/06/markdown-512px.png" alt="The Markdown logo" style="display: block; margin-left: auto; margin-right: auto; width: 30%;">
Here, width: 30% is relative to the width of the page. You can also use an absolute value like width: 480px. You can learn more about the HTML img tag on MDN. For everything else about images, like paths, captions, GIFs, and videos, see my Markdown images guide.
Some platforms have their own resize syntax: Obsidian supports  and ![[image.png|200]], and GitLab supports {width=200}. Neither works on GitHub.
Center multiple images or badges side by side
Put all the images in the same centered paragraph. Line breaks between the tags become small spaces, so the images sit next to each other in one centered row:
<p align="center"> <img src="screenshot-light.png" alt="App in light mode" width="300"> <img src="screenshot-dark.png" alt="App in dark mode" width="300"> </p>
Badges are just small linked images, so they work the same way. With HTML:
<p align="center"> <a href="https://github.com/you/my-project/actions"><img src="https://img.shields.io/badge/build-passing-brightgreen" alt="Build status"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a> </p>
Or with Markdown badge syntax, using the blank-line trick:
<div align="center"> [](https://github.com/you/my-project/actions) [](LICENSE) </div>
If the images don’t fit next to each other, the browser wraps them onto the next line. Make them narrower with width to keep them on one row.
A centered logo for light and dark mode
GitHub also supports the <picture> element, which lets you show a different logo in dark mode. It goes inside the centered paragraph like any image:
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/logo-dark.png">
<img src="docs/logo-light.png" alt="My Project logo" width="160">
</picture>
</p>
See GitHub Docs on images for details.
Markdown center a table
There’s no Markdown syntax to center a whole Markdown table either. On GitHub, wrap the table in a centered <div>, with blank lines so the table is still parsed as Markdown:
<div align="center"> | Item | Price | # In stock | |--------------|:-----:|-----------:| | Juicy Apples | 1.99 | 739 | | Bananas | 1.89 | 6 | </div>
Result:
| Item | Price | # In stock |
|---|---|---|
| Juicy Apples | 1.99 | 739 |
| Bananas | 1.89 | 6 |
This works because browsers treat the old align="center" on a <div> specially: it centers the block elements inside it, too, not only the text. CSS text-align: center doesn’t do that. It centers the text inside the table cells but leaves the table itself on the left.
Center a table with CSS
If your platform keeps style, wrap the Markdown table in a <div> that’s only as wide as its content and has automatic side margins:
<div style="width: fit-content; margin-left: auto; margin-right: auto;"> | Item | Price | # In stock | |--------------|:-----:|-----------:| | Juicy Apples | 1.99 | 739 | | Bananas | 1.89 | 6 | </div>
If centering seems to do nothing, your table is probably stretched to the full width of the page. Many website themes do that (my WordPress theme does, so I had to add width: auto to the table in the example above). A full-width table can’t be centered because there’s no room left over. GitHub tables are only as wide as their content, so you won’t run into this there.
Create an HTML table
You can also write the table in HTML and center it directly. On GitHub, use <table align="center">. With CSS, use automatic margins:
<table style="margin-left: auto; margin-right: auto;"> <tr><th>Item</th> <th>Price</th> <th># In stock</th></tr> <tr><td>Juicy Apples</td> <td>1.99</td> <td>739</td></tr> <tr><td>Bananas</td> <td>1.89</td> <td>6</td></tr> </table>
It works well, but it defeats the purpose of Markdown a little, since it takes a lot of tags. MDN has a good reference on the HTML table element if you want to go this route.
Center columns of a Markdown table
Centering the contents of a column is different, and for that Markdown does have syntax: put colons on both sides of the dashes in the separator row, like |:-----:|. The Price column in the examples above uses it. See aligning columns in a Markdown table for all the options.
Center a code block
I’d leave code blocks alone. Centered lines of code are hard to read, and on GitHub there’s no clean way to center the box while keeping the code left-aligned. If you wrap a section of your README in <div align="center">, close it before your code blocks.
On your own site, you can center the box and keep the code left-aligned with the same trick as the table:
<div style="width: fit-content; margin-left: auto; margin-right: auto;">
```python
print("Hello, centered box")
```
</div>
The box shrinks to the width of the longest line and moves to the middle, while the code inside stays left-aligned. For everything else about fenced code, see my article on Markdown code blocks.
How to center in Markdown, per platform
Here’s what works where. The general rule: if a platform keeps the style attribute, use CSS. If it only keeps align, use align.
| Platform | What works | Watch out for |
|---|---|---|
| GitHub (READMEs, issues, comments) | align="center" on <p>, <div>, <h1>–<h6>, <table>; width/height on images | style is removed; <center> is removed |
| GitLab | align="center"; image size with {width=200} or the width attribute | style is removed (it only keeps text alignment on table cells) |
| VS Code preview | Both align and style | The preview is more forgiving than GitHub: test on GitHub before you push |
| Obsidian (Reading view) | Both align and style; image size with  | No Markdown inside HTML; blank lines break an HTML block |
| Jekyll / GitHub Pages (kramdown) | HTML with align or style; or {: .text-center} after a block | Markdown inside HTML needs markdown="1" |
| Hugo | Attributes like {.text-center} plus a CSS class in your theme | Raw HTML is left out by default; enable markup.goldmark.renderer.unsafe |
| Pandoc to PDF | Raw LaTeX: \begin{center} … \end{center} | HTML is ignored. Images with alt text and tables are centered by default |
| Jupyter (JupyterLab, Notebook 7) | align, style, and even <center> | Tables in Markdown cells are already centered by default |
Sources: GitLab links to its HTML allowlist from the GitLab Flavored Markdown docs, Obsidian explains its rules on its HTML content help page, and Hugo’s defaults are in its markup configuration docs.
Centering in a PDF with Pandoc
When Pandoc converts Markdown to PDF, it goes through LaTeX and drops all HTML. You can write LaTeX right in your Markdown file instead:
\begin{center}
This line is centered in the PDF.
\end{center}
Pandoc passes the whole environment through as raw LaTeX, so Markdown inside it (like **bold**) isn’t converted. If you need Markdown inside, use raw LaTeX blocks for the opening and closing lines only:
```{=latex}
\begin{center}
```
This **bold** text is centered.
```{=latex}
\end{center}
```
You often don’t need any of this, though. An image that stands alone in a paragraph and has alt text becomes a figure, and Pandoc centers figures in PDF output. Tables are centered by default, too.
More resources
- My Markdown cheat sheet has all the basic syntax on one page.
- Read all about Markdown tables, including column alignment.
- Writing a README? See how to write a good README.md.
- New to Markdown? Start with the Markdown introduction.
FAQ
Can I center text in pure Markdown?
No. Neither CommonMark nor GitHub Flavored Markdown has syntax for centering. You need a bit of HTML, or a dialect-specific extension like kramdown’s {: .text-center} or Hugo’s attributes, which still rely on a CSS class.
Why doesn’t text-align: center work on GitHub?
GitHub removes the style attribute from all HTML in Markdown files, for security. Use the align="center" attribute instead, for example <p align="center">.
How do I center an image and resize it?
On GitHub: <p align="center"><img src="image.png" alt="…" width="200"></p>. The width is in pixels; leave out the height so the image keeps its proportions. Elsewhere you can use CSS: style="display: block; margin: 0 auto; width: 200px;".
Why is my Markdown not rendered inside the centered div?
Add a blank line after <div align="center"> and another before </div>. Without those blank lines, everything is treated as raw HTML and your Markdown shows up literally.
Is align=”center” deprecated? Should I still use it?
It’s deprecated in HTML, but browsers still support it and it’s the only centering method that works on GitHub and GitLab. Use it there. On your own website, use CSS.
How do I center the columns of a table?
Use colons on both sides of the separator row, like |:---:|. That centers the cell contents, not the table itself. See aligning columns.