How to Create an MD File (and Check That It Renders)

Creating a .md file takes about ten seconds: make a text file, give it the .md extension, write Markdown in it. The part that actually goes wrong is everything after that — Windows silently saving notes.md.txt, a table that looked fine in the editor collapsing into pipes, a Mermaid diagram that never draws. A Markdown file is only finished when something renders it correctly.

Markdown source typed into mdview.io before it is rendered into a formatted document

Create an MD File on Windows, macOS, or Linux

There is no special program involved. A .md file is plain text.

Windows — open Notepad, write your content, then File → Save as, set Save as type to All Files, and name the file notes.md. Leaving the type set to Text Documents appends .txt and produces notes.md.txt, which is the single most common failure here. If File Explorer hides extensions, enable File name extensions in the View tab so you can see what you actually saved.
macOS — TextEdit defaults to rich text, which will not do. Switch with Format → Make Plain Text, then save as notes.md. Confirm "Use .md" when prompted rather than letting it append .txt.
Linux — any editor works, or create it from the shell in one line.

printf '# Project Notes\n\nFirst paragraph.\n' > notes.md

The extension is a convention, not a format marker. Nothing inside the file declares it as Markdown; tools decide how to treat it based on the name.

What to Put Inside

Markdown is a small syntax. Headings use leading hash marks, lists use dashes, and emphasis uses asterisks. The pieces worth knowing from the start are the ones that break most often:

Element	Syntax	Common mistake
Heading	`# Title`	No space after the hash
Table	Pipe-delimited rows plus a separator row	Missing the `---` separator line
Link	`[text](https://example.com)`	Unescaped parentheses inside the URL
Code block	A fence line, the code, a closing fence	Fence not at the start of a line
Math	$...$ or ````math-display
[Formula]

| Diagram | A fenced block tagged `mermaid` | Missing the language tag |

For links specifically, see [Markdown link syntax](/s/markdown-link-syntax-urls-images-anchors); for math, [previewing LaTeX with KaTeX](/s/markdown-math-preview-latex-katex).

## Create an MD File Online

If you only need the file to hand to someone, you can skip the local editor entirely. Open [mdview.io](https://mdview.io), type or paste your content, and you have a live rendered document as you write — headings, tables, syntax-highlighted code, KaTeX math, and Mermaid diagrams. From there you can save the `.md` file, export it to PDF, or publish it as a share link with its own URL.

This is usually the faster route when the file's real destination is another person rather than a repository.

## Adding a Diagram

A diagram lives inside the file as text, in a fenced block tagged `mermaid`:

```mermaid
flowchart LR
  A[Write .md file] --> B[Render it]
  B --> C{Looks right?}
  C -- No --> D[Fix the syntax]
  D --> B
  C -- Yes --> E[Share or export]
```

That is the whole mechanism. The diagram travels with the document in plain text, and any renderer with Mermaid support draws it. A viewer without Mermaid support prints the source instead, which is why the file can look correct in one tool and broken in another.

## Verify Before You Send It

A `.md` file has no validator and no compile step, so mistakes stay invisible until someone else opens it. Render the file once before it leaves your machine and check four things: tables have their separator row and the columns line up, code blocks open and close, math uses delimiters your renderer accepts, and every diagram actually draws.

If something does not render, the cause is almost always in the source rather than the viewer — a missing separator row, a fence that starts mid-line, or a Mermaid version difference. [Markdown checker: test formatting before you share](/s/markdown-checker-render-test) walks through the checks; [why AI-generated Markdown often breaks](/s/why-ai-markdown-breaks) covers the same failures when the file came out of ChatGPT or Claude rather than your keyboard.

## Naming and README Files

`README.md` is an ordinary `.md` file with a conventional name — repository hosts look for it and render it on the project page. Nothing about the file itself is different, so everything above applies. If you are writing one, preview it before pushing: see [how to preview a README before publishing to GitHub](/s/how-to-preview-a-readme-file-before-publishing-to-github).

Creating the file is trivial. Knowing it renders the way you intended is the part worth a tool — mdview.io shows the finished document, diagrams and all, so you find the broken table before your reader does.