FAQ: Markdown Questions Answered
Markdown is simple in its basics but full of edge cases, platform differences, and non-obvious behaviors. Whether you are brand new to Markdown or have been using it for years and still run into head-scratching issues, this FAQ covers the questions that come up most often. Each answer is practical, specific, and actionable. Questions cover syntax, compatibility, tools, file handling, GitHub-specific behavior, and troubleshooting — the complete picture of what you actually need to know to work with Markdown confidently.
Markdown Basics: What It Is and How It Works
What is Markdown? Markdown is a plain text formatting syntax created by John Gruber in 2004. You write text with lightweight formatting markers — asterisks for bold, pound signs for headings, hyphens for lists — and a Markdown parser converts that text into HTML. It is designed so that the raw Markdown is still readable as plain text without conversion. Who uses Markdown? Markdown is used by software developers (GitHub READMEs, documentation), technical writers (developer portals, API docs), bloggers (Ghost, Dev.to, Jekyll blogs), data scientists (Jupyter notebooks), project managers (Notion, Linear, Jira), and note-takers (Obsidian, Logseq, Bear, Typora). Is Markdown a programming language? No. Markdown is a markup language — a set of conventions for annotating text. It describes how text should be formatted but does not perform computation. HTML is also a markup language. Markdown can be thought of as a shorthand for HTML. Is there an official Markdown standard? The CommonMark specification (commonmark.org) is the most widely adopted standard. It was published by a group of developers who wanted to resolve the ambiguities in the original Markdown specification. GitHub Flavored Markdown (GFM) extends CommonMark with tables, task lists, and strikethrough. What is a Markdown parser? A Markdown parser is software that reads Markdown text and produces HTML output. Different parsers exist for different programming languages: marked (JavaScript), Python-Markdown (Python), Goldmark (Go), pulldown-cmark (Rust). Most parsers support CommonMark with various extensions.
Syntax Questions and Troubleshooting
Why is my Markdown not rendering as formatted text? The most common reason is that you are viewing the raw file rather than a rendered preview. Make sure you are using a Markdown viewer, not just opening the file in a browser (which displays raw text) or a plain text editor. Use WikiPlus Markdown Preview or open the file in VS Code with the built-in preview (Ctrl+Shift+V). Why is my heading not rendering? The most common cause is a missing space between the # and the heading text. `#Heading` does not render as a heading in CommonMark; `# Heading` does. Also check that there is no content on the same line after the heading text. Why is my list rendering as plain text? List items need a blank line before the first item if they follow a paragraph of text. In the middle of a document, `paragraph text\n- item` often does not render as a list. Add a blank line: `paragraph text\n\n- item`. Why is my code block showing as plain text? For fenced code blocks, both the opening and closing ``` must be on their own lines. Also check that the opening fence has exactly three backticks — some writers accidentally use two, which does not trigger a code block. How do I show a literal backtick in inline code? Wrap the inline code with double backticks: `` `literal backtick` ``. There must be a space between the outer backtick pairs and the inner content. Why is my bold text not working inside a URL? Markdown parsing inside URLs is intentionally disabled in most parsers. `[**bold** text](url)` renders the asterisks as literal characters inside the link text, not bold. Write the link text without Markdown emphasis: `[bold text](url)` and style it with CSS if needed.
Compatibility and Platform Questions
Does Markdown render the same everywhere? No. Different platforms use different Markdown parsers with different extension support. A document that renders perfectly on GitHub may have broken tables on a platform that does not support GFM, or missing footnotes on a platform without footnote support. CommonMark provides a baseline that most parsers agree on, but extensions vary. Testing in the target environment is always the final check. Does Obsidian use standard Markdown? Obsidian uses a Markdown dialect that is mostly CommonMark-compatible with its own extensions: `[[wikilinks]]` for internal links, `![[embeds]]` for embedded notes, callout blocks with `> [!note]` syntax, and properties (frontmatter). Obsidian Markdown documents are portable as Markdown files but the proprietary extensions will not render correctly outside Obsidian. Can I use Markdown in Confluence? Confluence supports Markdown via the Markdown macro. Go to Insert > Other macros, search for Markdown, and paste your Markdown inside the macro. It renders as formatted Confluence content. Note: pasting Markdown directly into a Confluence page without the macro will display it as raw text. Can I use Markdown in Slack or Discord? Slack and Discord both support a subset of Markdown-like formatting. Bold, italic, code, and code blocks work. Full Markdown tables, task lists, and most other features do not. These platforms have their own formatting conventions that overlap with Markdown but are not Markdown-compliant.
Tools, Editors, and File Format Questions
What file extension should Markdown files use? The standard extensions are .md and .markdown. The .md extension is more common and universally recognized. GitHub renders both .md and .markdown files. Some tools also use .txt for Markdown content, though this is less conventional. What is the best Markdown editor? For developers: VS Code with Markdown All in One extension, or Neovim with markdown-preview.nvim. For writers: Typora (WYSIWYG), iA Writer, or Ulysses. For cross-platform notes: Obsidian. Browser-based: WikiPlus Markdown Preview for quick checks, HackMD or StackEdit for online editing with export. How do I open a .md file on Windows? Windows does not have a built-in Markdown viewer. Options: install VS Code and open the file (Ctrl+Shift+V for preview), use a browser extension that renders .md files, open the file in Notepad to see raw text, or paste the content into WikiPlus Markdown Preview. How do I open a .md file on Mac? MacOS can open .md files in TextEdit (raw text view). For rendered Markdown: open in VS Code, use the Marked 2 app (paid, excellent rendering), use the free MacDown editor, or drag the file content into WikiPlus Markdown Preview in your browser. Can Markdown files contain images from my computer? Yes, using relative file paths: ``. The image renders in local editors that support relative paths (VS Code, Typora). For web publication, the image must be hosted somewhere — a CDN, your static site's image folder, or an image hosting service — and the Markdown must reference its public URL.
Frequently Asked Questions
- Is Markdown the same as reStructuredText?
- No, they are different markup languages. reStructuredText (rST) is used primarily in the Python ecosystem via Sphinx documentation generator. Markdown is more widely adopted across general development. rST has a more rigid and consistent syntax with fewer ambiguities, but a steeper learning curve. They are not interchangeable. Pandoc can convert between them: `pandoc input.md -f markdown -t rst -o output.rst`.
- What is the difference between .md and .mdx files?
- MDX (.mdx) files are Markdown extended with JSX — React components can be embedded directly inside the Markdown content. A .md file is plain Markdown that converts to static HTML. An .mdx file is processed by a JavaScript build tool and converts to a React component tree. MDX is used by Next.js, Docusaurus, Astro, and other React-based documentation and blogging frameworks. Standard Markdown previewers show the text content of .mdx files but do not render embedded JSX components.
- How do I add a table of contents to a long Markdown document?
- Manually: list your headings as links using GitHub's auto-generated anchor IDs (lowercase, spaces to hyphens, punctuation removed). For example `## My Section` generates anchor `#my-section`. Automatically: VS Code's Markdown All in One extension can insert and update a table of contents. Markmap.js and other tools generate visual mindmaps from headings. Static site generators like Docusaurus generate TOCs automatically from heading structure.