Markdown FAQ

This FAQ is useful for:

• Beginners learning Markdown for the first time
• Developers writing GitHub documentation
• Technical writers
• Students taking notes in Markdown
• Anyone switching from Word or Google Docs

This guide includes questions about:

What is Markdown?#

Markdown is a lightweight markup language used to format plain text. Instead of using HTML tags, you write simple characters such as #, *, and - to create headings, lists, links, and other formatting.

Because Markdown is easy to read and write, it's widely used for documentation, GitHub repositories, blogs, note-taking, and static websites.

Who created Markdown?#

Markdown was created by John Gruber in 2004 with help from Aaron Swartz. The goal was to make writing for the web easier by keeping documents readable as plain text while allowing them to be converted into HTML.

Why was Markdown created?#

Before Markdown, writing HTML by hand could be slow and difficult for simple documents.

Markdown was designed to let people focus on writing instead of HTML tags. You write plain text first, then convert it into HTML when needed.

Is Markdown free?#

Yes.

Markdown is an open format that anyone can use. Most Markdown editors, libraries, and converters are also free, although some desktop applications offer paid features.

Is Markdown a programming language?#

No.

Markdown is a markup language, not a programming language. It formats text but cannot execute code, perform calculations, or build applications.

Where is Markdown used?#

Markdown is commonly used for:

• GitHub README files
• Software documentation
• Developer wikis
• Knowledge bases
• Personal notes
• Technical blogs
• Static websites

Which file extension does Markdown use?#

The standard file extension is .md.

Some applications also support .markdown, but .md is the most widely used format and works across nearly all Markdown editors and platforms.

Do I need a special Markdown editor?#

No.

You can write Markdown in any plain text editor. However, a dedicated Markdown editor makes writing easier by providing live preview, syntax highlighting, and export options.

If you're writing online, our Markdown Editor lets you write and preview Markdown in the same window.

How do I create headings in Markdown?#

Headings are created with the # symbol. The number of # characters determines the heading level.

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Use only one H1 (#) for the page title, then organize the rest of your content with H2 and H3 headings.

If you want to learn more, see the Markdown Headings guide.

How do I make text bold or italic?#

Wrap text with asterisks (*) or underscores (_).

**Bold text**

*Italic text*

***Bold and italic***

Most Markdown editors support both styles.

How do I create lists?#

Use -, *, or + for unordered lists, and numbers for ordered lists.

- Apple
- Orange
- Banana

1. First step
2. Second step
3. Third step

Nested lists can be created by indenting the child items.

How do I create links?#

Use square brackets for the link text and parentheses for the URL.

[MDConvertHub](https://mdconverthub.com)

For internal documentation, descriptive link text is usually better than phrases like "click here."

Learn more in the Markdown Links guide.

How do I add images?#

Images use the same syntax as links, with an exclamation mark at the beginning.

![Markdown Logo](images/logo.png)

Always include descriptive alt text to improve accessibility.

If the image doesn't appear, check that the file path is correct.

See the Markdown Images guide for more examples.

How do I create tables?#

Most modern Markdown editors support GitHub Flavored Markdown tables.

| Name | Role |
| --- | --- |
| Alex | Developer |
| Sarah | Designer |

Tables are useful for comparing data, documenting APIs, and organizing information.

Need help creating tables? Try the Markdown Table Generator.

How do I write inline code?#

Wrap the text with a single backtick.

`npm install`

Example:

npm install

Inline code is commonly used for commands, filenames, variables, and function names.

How do I create code blocks?#

Use three backticks before and after the code block. Adding the language name enables syntax highlighting.

```javascript
function greet() {
  console.log("Hello, world!");
}
```

Most Markdown editors support syntax highlighting for popular programming languages.

Read the Markdown Code Blocks guide to learn more.

What is GitHub Flavored Markdown (GFM)?#

GitHub Flavored Markdown (GFM) is GitHub's version of standard Markdown. It includes extra features that aren't available in the original Markdown specification.

Some of the most commonly used additions are:

• Tables
• Task lists
• Strikethrough
• Automatic URL linking
• Fenced code blocks

If you're writing README files or GitHub documentation, you'll most likely be using GitHub Flavored Markdown.

What is a README file?#

A README is the main document for a project or repository. It explains what the project does, how to install it, and how to use it.

A typical README includes sections like:

• Project overview
• Features
• Installation
• Usage
• Configuration
• License
• Contributing

If you don't want to write one from scratch, try the README Generator.

Does GitHub support all Markdown features?#

No.

GitHub supports most common Markdown syntax, but some features depend on the Markdown processor you're using.

For example, GitHub supports:

• Headings
• Lists
• Tables
• Task lists
• Code blocks
• Images
• Blockquotes

Some HTML elements and advanced extensions may not work or may be filtered for security reasons.

Can I use HTML in GitHub Markdown?#

Yes, but only certain HTML elements are allowed.

Simple tags like these usually work:

<div>
<span>
<details>
<summary>
<br>

GitHub removes scripts and other potentially unsafe HTML.

If you're unsure whether something is supported, check the Markdown HTML guide.

How do I create task lists?#

Task lists are created with checkboxes.

- [ ] Write documentation
- [x] Finish README
- [ ] Publish project

Unchecked boxes use a space, while completed tasks use x.

Task lists are commonly used in GitHub issues, pull requests, and project documentation.

Can I create tables on GitHub?#

Yes.

GitHub supports Markdown tables using GitHub Flavored Markdown.

| Feature | Supported |
| --- | --- |
| Tables | Yes |
| Task Lists | Yes |
| Code Blocks | Yes |

Tables are useful for comparing features, listing commands, or documenting APIs.

Does GitHub support syntax highlighting?#

Yes.

Specify the language immediately after the opening backticks.

```python
def hello():
    print("Hello")
```

GitHub automatically highlights many popular programming languages, making code easier to read.

Can I preview Markdown before publishing?#

Yes.

Most Markdown editors provide a live preview while you write.

If you're using MDConvertHub, open the Markdown Editor to write, preview, and copy your Markdown before publishing it to GitHub or another platform.

Can I use HTML inside Markdown?#

Yes.

Most Markdown parsers allow you to include HTML when standard Markdown syntax isn't enough.

For example:

<div class="note">
  This content uses HTML inside a Markdown document.
</div>

This is useful for layouts or elements that Markdown doesn't support. However, some platforms remove certain HTML tags for security reasons.

Learn more in the Markdown vs HTML guide.

When should I use HTML instead of Markdown?#

Markdown is designed for writing content, while HTML offers much more control over page structure and presentation.

Choose Markdown when you want:

• Clean, readable documents
• Fast writing
• Simple formatting
• Portable files

Choose HTML when you need:

• Forms
• Navigation menus
• Audio or video
• Interactive components
• Responsive layouts
• Embedded content
• Custom attributes
• Advanced accessibility features

If your project needs complex layouts or interactive features, HTML is usually the better choice. For documentation, README files, notes, and articles, Markdown is often the simpler option.

Does Markdown support tables?#

Yes, but support depends on the Markdown flavor.

GitHub Flavored Markdown (GFM) supports tables using pipe (|) syntax.

| Name | Role |
| --- | --- |
| Alex | Developer |
| Sarah | Designer |

If creating tables manually feels slow, try the Markdown Table Generator.

Can Markdown display mathematical equations?#

Yes, if your editor or documentation platform supports LaTeX.

Inline equation:

$E = mc^2$

Block equation:

$$
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
$$

Not every Markdown editor supports math rendering, so check your platform's documentation first.

Read the Markdown Math guide for more examples.

Does Markdown support diagrams?#

Some Markdown tools support diagrams through Mermaid.

Example:

```mermaid
graph TD
    A[Start] --> B[Write Markdown]
    B --> C[Preview]
    C --> D[Publish]
```

Mermaid is commonly used for flowcharts, sequence diagrams, and system architecture documentation.

See Mermaid Diagrams for platform compatibility.

Can I create footnotes?#

Many Markdown processors support footnotes, although they're not part of the original Markdown specification.

Example:

Markdown supports footnotes in many editors.[^1]

[^1]: This is a footnote.

Footnotes are useful for references, citations, and additional information without interrupting the main content.

Does Markdown support task lists?#

Yes, in GitHub Flavored Markdown and many modern editors.

- [x] Write documentation
- [x] Review changes
- [ ] Publish website

Task lists work well for project planning, meeting notes, and personal checklists.

Can I mix Markdown and HTML?#

Yes.

Many developers combine Markdown for most of the document and HTML only where extra formatting is required.

Keeping most of your content in Markdown makes documents easier to read, edit, and maintain, while HTML can handle cases that Markdown doesn't support.

Why is my Markdown showing as plain text?#

This usually happens because the Markdown file isn't being processed by a Markdown parser.

Make sure that:

• The file has a .md extension.
• Your editor or website supports Markdown rendering.
• You're opening the preview instead of the raw file.

If you're testing Markdown online, use the Markdown Editor to see the rendered output.

Why aren't my headings working?#

A heading must start with one or more # characters followed by a space.

Correct:

## Installation

Incorrect:

##Installation

Also avoid placing text directly above a heading without a blank line when your Markdown processor requires one.

Why is my image not showing?#

Most broken images are caused by an incorrect file path.

Check that:

• The image file exists.
• The filename is spelled correctly.
• Uppercase and lowercase letters match.
• The relative path points to the correct folder.

Example:

![Project Screenshot](images/screenshot.png)

Why isn't my link working?#

Verify that the link uses the correct Markdown syntax.

[MDConvertHub](https://mdconverthub.com)

For internal links, make sure the destination page or file actually exists.

Why isn't my table rendering correctly?#

Tables are supported in GitHub Flavored Markdown and most modern Markdown editors, but not every Markdown parser.

Also check that:

• Every row contains the same number of columns.
• The separator row uses hyphens (---).
• Pipes (|) are placed correctly.

Example:

| Name | Role |
| --- | --- |
| Alex | Developer |

If you don't want to format tables manually, use the Markdown Table Generator.

Why isn't my code highlighting working?#

Syntax highlighting only works if you specify the language after the opening backticks.

Example:

```javascript
console.log("Hello");
```

If you leave out the language name, the code will still render, but without highlighting.

Why doesn't my Markdown look the same everywhere?#

Different applications use different Markdown parsers.

For example, GitHub, Obsidian, GitLab, and various documentation tools may support different features such as:

• Tables
• Task lists
• Footnotes
• Mermaid diagrams
• Mathematical equations

If you're sharing Markdown across multiple platforms, stick to standard syntax whenever possible.

Why isn't my HTML rendering?#

Many Markdown applications allow HTML, but some remove certain tags for security reasons.

Simple HTML elements usually work, while scripts, iframes, and embedded content may be blocked.

If HTML is important for your project, check what your Markdown editor or publishing platform supports.

How can I check if my Markdown is correct?#

The easiest way is to preview it before publishing.

A live preview lets you catch formatting problems such as broken headings, lists, links, images, and tables before sharing your document.

Using a Markdown editor with live preview can save a lot of time when working on larger documents.

Markdown is simple to learn, but it's normal to have questions when you're getting started.

Whether you're creating documentation, writing a README, taking notes, or publishing technical content, understanding the basics makes writing much easier.

As you become more familiar with Markdown, you can explore additional features such as tables, task lists, diagrams, mathematical equations, and HTML integration. Most importantly, choose a Markdown editor that lets you preview your work before publishing.

💡 Tip: If you're unsure whether a feature is supported, test it in the Markdown Editor before publishing.