How to Use SharePoint Markdown Web Part?

In this tutorial, learn how to use the SharePoint Markdown web part to format rich content using Markdown syntax on modern pages quickly. You will see how to add the Markdown web part, configure it, use all supported Markdown features, build a table of contents, and understand its limitations compared to the Text web part.

What is the SharePoint Markdown Web Part?

The Markdown web part lets you add text to a modern SharePoint page and format it with Markdown instead of the standard rich text toolbar. It is available only on modern SharePoint Online pages and is not supported in SharePoint Server 2019.

The Markdown web part is useful when:

• You prefer keyboard‑driven authoring instead of clicking formatting icons.
• You want to paste content from a Markdown editor or developer documentation.
• You need a simple table of contents built from a list of links.

Key features and limitations

When you add the Markdown web part to a page, it shows a two‑column editor by default, with a dark theme and live preview on the right. You can switch between dark and light themes and choose to hide the preview if you only want to focus on the Markdown source.

Important limitations:

• HTML tags inside the Markdown web part are rendered as plain text and are not executed or styled as HTML.
• Advanced formatting (custom fonts, colors, or complex layouts) is better handled with the Text web part or custom SPFx solutions.

Markdown vs Text web part

Both web parts can be used to add text, but they are optimized for different authoring styles.

Check out Display Weather in SharePoint using Weather Web Part

How to Add the Markdown Web Part in SharePoint

Follow these steps to add the Markdown web part to a modern SharePoint Online page.

1. Open the modern SharePoint page where you want to add Markdown content, then select Edit in the top‑right corner.
2. Choose or add a section layout, then select the + icon in the section where the Markdown web part should appear.
3. In the web part picker, search for Markdown and select the Markdown web part.
4. The web part will display a left panel for Markdown input and a right panel showing the rendered preview in dark mode.
5. Use the web part toolbar or property pane to change the theme (dark or light) and toggle preview visibility.

After adding and configuring content, select Republish to make your changes visible to page visitors.

Check out SharePoint Online Document Library Web Part

Configure the SharePoint Markdown Web Part

Once the Markdown web part is on the page, you can configure it from the web part toolbar and property pane. Use the Edit web part icon to open the properties on the right side of the page.

You can:

• Switch between dark and light theme to match the page design.
• Show or hide the live preview pane if you prefer a single‑column editor.
• Copy/paste Markdown content from an external editor if you already maintain documentation in Markdown.

Selecting Republish or Save as draft will store the Markdown source and the rendered output for readers.

Markdown headers (H1–H6)

Use the hash symbol # to create headings in the Markdown web part. You can add one or more heading levels from h1 to h6 as shown below.

Examples:

• # Heading 1
• ## Heading 2
• ### Heading 3
• #### Heading 4

Type the Markdown in the left column and confirm that the rendered headings appear in the preview on the right. Headings are essential if you want to build a manual table of contents using links to specific sections.

Emphasis: bold, italic, strikethrough

The Markdown web part supports standard emphasis syntax to highlight important text.
You can also use keyboard shortcuts like Ctrl+B and Ctrl+I while editing.

Common emphasis options:

• Bold: **Text** or __Text__
• Italic: *Text* or _Text_
• Strikethrough: ~~Text~~

Enter the emphasis syntax in the left column and verify that the expected styling appears in the right preview pane. Use emphasis sparingly to keep content readable and accessible.

Paragraphs and blockquotes

Paragraphs are created simply by writing text on separate lines with a blank line between them. To display quoted or highlighted text, use the Blockquote syntax.

Blockquote example:

• > This is an important note for readers.

The quote will appear indented and styled differently in the preview, making it stand out from normal paragraphs. Blockquotes are ideal for warnings, best‑practice notes, or external quotations.

Code snippets

The Markdown web part can highlight inline code and code blocks, which is very useful for technical articles. Use backticks to indicate code: single backticks for inline code and triple backticks for multi‑line code blocks.

Examples:

• Inline: Use the `Get-Item` cmdlet in PowerShell
• Code block:

undefined

Write-Host “Hello SharePoint”

undefined

After adding code, select Republish so that visitors can see the formatted snippet.

Links

Links in the Markdown web part follow the standard Markdown pattern of text in square brackets and URL in parentheses.
When users select the link, they are redirected to the specified URL.

Syntax:

• [Link text](https://contoso.sharepoint.com/sites/Example)

Example:

• [SPGuides](https://spguides.com/)

Add your link in the left column and confirm the clickable link in the preview.
You can combine links with bullet lists to create a simple navigation or resources section.

Images

You can display images in the Markdown web part using similar syntax to links, prefixed with an exclamation mark.
Use alt text inside square brackets and the image URL inside parentheses, with no spaces.

Syntax:

• ![Alt text](https://pnp.github.io/images/hero-parker-p-800.png)

Ensure that:

• The image is accessible from the page (for example, from a SharePoint library or a public URL).
• Alt text is meaningful to support accessibility and screen readers.

Once added, the image will appear in the preview and on the published page.

Lists: bulleted and numbered

The Markdown web part supports both unordered (bulleted) and ordered (numbered) lists.
Lists are a core feature for breaking information into scannable chunks.

Bulleted list examples:

• - Item one
• * Item two

Numbered list example:

• 1. First step
• 2. Second step

You can mix text, links, and simple inline formatting within list items. After adding your list, verify that it renders correctly in the right preview pane.

You can see an example in the screenshot below:

Tables

Tables are fully supported in the Markdown web part, and columns are separated with the pipe (|) character. The Markdown properties pane often shows an example table that you can copy and adapt.

Simple table example:

• | Column 1 | Column 2 |
• | -------- | -------- |
• | Value A | Value B |

You can rename column headers, add new rows, or extend the table with more columns as needed. Tables created this way are ideal for small datasets, feature matrices, or quick comparisons.

Here is an example and the screenshot:

Building a table of contents (TOC)

You can build a manual table of contents on a modern page using the Markdown web part and header links from Text web parts. This approach works well when your page has multiple sections with headings.

Steps to create a TOC:

1. Add one or more Text web parts to the page and create headings (Heading 1, Heading 2, etc.) and content under each heading.
2. Publish or republish the page so SharePoint generates anchor links for each heading.
3. Hover over each heading; when the link icon appears, right‑click it and choose Copy link.
4. Add or open the Markdown web part where you want the table of contents.
5. Build a bulleted list of links, for example:
   • - [Introduction](PASTE-INTRO-LINK-HERE)
   • - [Getting started](PASTE-GETTING-STARTED-LINK-HERE)

When a user selects a link in the TOC, they are taken directly to the corresponding heading in the page. You can repeat this for all major sections to create a page‑level navigation experience.

HTML support and security

The Markdown web part is intentionally restrictive with HTML to keep modern pages secure and consistent. If you type HTML tags such as <sup> or <ul><li>, they will be rendered as text instead of being interpreted by the browser.

This means:

• You cannot rely on HTML tags or scripts within the Markdown web part for custom formatting.
• For advanced scenarios like custom HTML, scripts, or third‑party widgets, you need alternatives such as SPFx web parts or the (limited) Embed web part, where allowed.

Here is a screenshot for your reference:

When to use Markdown vs Other Options

Use the Markdown web part when you:

• Maintain documentation or snippets in Markdown and want to reuse them in SharePoint.
• Need simple, fast formatting with headings, lists, links, images, and tables.
• Want to build a lightweight table of contents from page heading links.

Use the Text web part when you:

• Need more visual control, including font styles, highlighting, and inline formatting.
• Are building communication pages where non‑technical authors will maintain the content.

For highly customized layouts, branding, or interactive experiences, consider SPFx web parts or custom solutions deployed to your tenant app catalog.

Conclusion

The Markdown web part lets you create clean, structured content on modern SharePoint pages using familiar Markdown syntax. It works best for technical documentation, quick tables, and table‑of‑contents style navigation, especially when you already write in Markdown or want a keyboard‑first editing experience.

By combining Markdown with other modern web parts such as Text, Image, and custom SPFx solutions, you can design pages that are both easy to maintain and pleasant for users to read.

You may also like the following tutorias:

• SharePoint Online Text Web Part
• SharePoint Online Button Web Part

Bijay Kumar

After working for more than 18 years in Microsoft technologies like SharePoint, Microsoft 365, and Power Platform (Power Apps, Power Automate, and Power BI), I thought will share my SharePoint expertise knowledge with the world. Our audiences are from the United States, Canada, the United Kingdom, Australia, New Zealand, etc. For my expertise knowledge and SharePoint tutorials, Microsoft has been awarded a Microsoft SharePoint MVP (12 times). I have also worked in companies like HP, TCS, KPIT, etc.