` page breaks or `` colours. ## Can I convert a Markdown table to PDF with Pandoc? Yes, if you prefer the command line and have a LaTeX engine installed, which Pandoc uses by default to make PDFs: ```bash pandoc table.md -o table.pdf pandoc table.md -o table.pdf -V geometry:landscape ``` The second command sets a landscape page through the LaTeX `geometry` variable. One Pandoc behaviour is worth knowing for tables: according to the [Pandoc manual](https://pandoc.org/MANUAL.html#tables), if any line of a pipe table is longer than the column width, the table takes the full text width and wraps cell contents, and the relative column widths come from the number of dashes in the separator row. So `|---|-|` makes the first column three quarters of the width. If your columns come out at odd widths in Pandoc, adjust the dashes. The browser converter ignores dash counts and sizes columns from their content. ## How do I make the table if my data is in a spreadsheet? Export the sheet as CSV and paste it into the [CSV to markdown converter](/csv-to-markdown), which writes the pipe table for you. For a small table typed by hand, the [markdown table generator](/markdown-table-generator) gives you a grid to fill in and copies the markdown. Either way, paste the result into the PDF converter and follow the steps above. Building the table in markdown first, rather than printing the spreadsheet, gives you a clean bordered table without gridlines, hidden columns or cut-off cells. ## What can the browser converter not do with tables? It cannot merge cells: markdown tables have no colspan or rowspan, so a header that spans two columns has to be restructured as two separate headers or written as a heading above the table. It does not accept custom CSS, so you cannot change the border colour, font or cell padding. It does not render LaTeX-style math such as `$x^2$` inside cells; that prints as typed. It also has no manual page breaks, so you cannot force a table to start on a new page, although a heading directly above a table is kept with what follows it where the browser can manage it. If you need any of these, use a tool with stylesheet support such as Pandoc with a LaTeX template, or convert to Word with the [markdown to Word converter](/markdown-to-word) and adjust the table there. ## Is the PDF table selectable and searchable? Yes. The PDF is generated from text, not a screenshot, so you can select a cell, copy it and search the document with Ctrl+F or Cmd+F. Copying a whole table out of a PDF, however, usually gives you the cell values separated by spaces or line breaks rather than a table, because PDF files store positioned text, not rows and columns. Keep the markdown source if you will need the table again, and treat the PDF as the printed copy. ## How do I keep Mermaid diagrams and code blocks when converting Markdown to PDF? URL: https://docs-md.com/markdown-to-pdf/markdown-to-pdf-mermaid-code Updated: 2026-10-17 Use a converter that renders `mermaid` code fences as diagrams and highlights other fences by language, then save as PDF. A browser-based converter does both, printing diagrams as vector graphics and code as real text. Command-line tools such as Pandoc do not draw Mermaid on their own, so pre-render the diagrams to images first. Both features depend on the same thing in your source: a fenced code block with the right language tag on the opening fence. A diagram must start with ` ```mermaid `; a code sample should start with its language, such as ` ```python ` or ` ```bash `. Without the tag, a converter has no way to know that the block is a diagram or which highlighting rules to use, and you get plain monospaced text. The [code block guide](/guides/markdown-code-block) covers fences, tags and indentation. ````markdown ```mermaid flowchart LR Draft --> Review --> Publish ``` ```python def publish(doc): return render(doc) ``` ```` ## How do I convert Markdown with Mermaid diagrams to PDF in the browser? Open the [markdown to PDF converter](/markdown-to-pdf), paste your markdown or click **Open .md file**, and look at the preview. Each `mermaid` fence is drawn as a diagram, and each tagged code block is syntax-highlighted. Wait until every diagram has appeared in the preview (they render a moment after the text), then click **Download PDF** and choose **Save as PDF** in the print dialog. Everything happens in your browser; the document is not uploaded. Diagrams are inserted as SVG, so they stay sharp at any zoom level in the PDF and their labels remain text. Flowcharts, sequence diagrams, class diagrams, Gantt charts and the other types that the Mermaid library supports all go through the same path. ## What happens if a Mermaid diagram has a syntax error? The converter shows the diagram's source as a plain code block instead of a picture, both in the preview and in the PDF. That is your signal to fix the syntax: a missing arrow, an unclosed bracket or a keyword the diagram type does not accept are the usual causes. Check the preview before printing, because a broken diagram printed as code is easy to miss in a long document. The error is not reported line by line, so for a stubborn diagram, cut it down to two nodes and add lines back until it breaks. ## How are code blocks printed? Code blocks print in a monospaced font on a light background with a thin border, and the PDF text stays selectable, so a reader can copy a command out of it. Keywords, strings and comments keep their highlight colours. The converter also asks the browser not to split a code block across two pages, so short and medium blocks move to the next page whole; a block longer than a page has to split, and does. Two things to watch: - **Long lines are cut off, not wrapped.** A line wider than the page runs past the right margin and is clipped in the PDF. Wrap lines in the source (about 80 characters fits portrait A4 or Letter comfortably), use a backslash continuation in shell commands, or switch the print dialog to landscape. - **Untagged blocks get no colour.** Add the language to the fence. Indented code blocks (four spaces, no fence) cannot carry a tag at all, so convert them to fences; the [markdown formatter](/markdown-formatter) can help tidy a file before you do. ## Can Pandoc keep Mermaid diagrams? Not on its own; Pandoc treats a `mermaid` fence as an ordinary code block and prints its source. The common fix is to pre-render diagrams with the official Mermaid CLI, which, per its [README](https://github.com/mermaid-js/mermaid-cli), can read a markdown file, render every Mermaid block to an image and write a new markdown file that refers to the images: ```bash npx -p @mermaid-js/mermaid-cli mmdc -i report.md -o report-rendered.md -e png pandoc report-rendered.md -o report.pdf ``` The `-e` option sets the image format (`svg`, `png` or `pdf`). The default is SVG; PNG is the safer choice when the PDF is produced through LaTeX, at the cost of a raster image. The Mermaid CLI renders through a headless Chromium browser, so the first run can be slow while it installs. Pandoc highlights code blocks by default, and its `--syntax-highlighting` option (`--highlight-style` in older versions) picks a colour style or turns highlighting off, as described in the [Pandoc manual](https://pandoc.org/MANUAL.html). ## Do Mermaid diagrams work when exporting from VS Code? The VS Code preview renders Mermaid, and the Markdown PDF extension can include diagrams in its export, loading the Mermaid library from a CDN by default, so the export needs internet access. The full comparison of routes is in the guide to [exporting Markdown to PDF from VS Code](/markdown-to-pdf/vs-code-markdown-to-pdf). ## Will the diagram look the same as on GitHub? Close, but not identical. GitHub renders `mermaid` fences in markdown files, issues and pull requests, and so do many editors, but each uses its own Mermaid version and theme. This converter uses a neutral grey theme, which prints well in black and white. Layout can differ slightly between Mermaid versions: node positions and line routing are computed each time, not stored in your source. If exact appearance matters, export the diagram once to SVG or PNG and embed that image instead of the fence; then every renderer shows the same picture. ## What can this converter not do with diagrams and code? It cannot render PlantUML, Graphviz `dot` or other diagram languages; only Mermaid fences become pictures, and the rest print as code. Images referenced by a relative path such as `./diagram.png` do not load, because a web page cannot read files from your disk, so use an absolute `https://` URL. It does not render math written as `$...$`. It has no line numbers for code blocks and no way to choose the highlight theme or the font. Interactive features of Mermaid, such as clickable nodes, are switched off and could not work on paper anyway. To check how a file renders before converting it, the [markdown viewer](/markdown-viewer) shows the same rendering in a full page. ## Is a PDF the right format for diagrams and code? For handing in, printing or archiving, yes. For code that people will copy and run, a PDF is a poor carrier: copying from a PDF can lose indentation or join lines, which breaks Python and YAML. Keep the markdown source alongside the PDF, or share a link to the rendered document so readers copy from the original text. ## How do I export Markdown to PDF from VS Code? URL: https://docs-md.com/markdown-to-pdf/vs-code-markdown-to-pdf Updated: 2026-10-17 VS Code can preview markdown but has no built-in PDF export, so you need one extra step. Install an extension such as Markdown PDF and run its Export (pdf) command, paste the file into a browser converter and save as PDF, or run Pandoc from the integrated terminal. Which one fits depends on whether you can install things. The built-in preview is still useful as a check before you export. According to the [VS Code Markdown documentation](https://code.visualstudio.com/docs/languages/markdown), you toggle the preview with Ctrl+Shift+V (Cmd+Shift+V on macOS) and open it side by side with Ctrl+K V (Cmd+K V), and the preview renders Mermaid diagrams in `mermaid` code fences and math with KaTeX. That documentation describes no PDF or print command, which is why every route below goes through something else. ## How do I export with the Markdown PDF extension? Markdown PDF (extension ID `yzane.markdown-pdf`) is the most widely used option. The steps, from its [README](https://github.com/yzane/vscode-markdown-pdf): 1. Open the Extensions view (Ctrl+Shift+X, or Cmd+Shift+X on macOS), search for **Markdown PDF** and install it. 2. Open your `.md` file. 3. Press F1 or Ctrl+Shift+P to open the Command Palette, type `export`, and choose `markdown-pdf: Export (pdf)`. You can also right-click inside the editor and pick the same command. 4. Wait for the notification. The extension renders the file with a Chromium browser and writes the PDF. It needs a Chromium-based browser to print. It uses an installed Chrome, Edge or Chromium if it finds one, and otherwise downloads one on first use, so the first export can take a while and needs a network connection. Settings worth knowing go in `settings.json`: ```json { "markdown-pdf.format": "A4", "markdown-pdf.orientation": "landscape", "markdown-pdf.outputDirectory": "output", "markdown-pdf.convertOnSave": true } ``` `format` accepts paper sizes such as Letter, Legal, A3 and A4 (A4 is the default), `orientation` is `portrait` or `landscape`, `outputDirectory` chooses where the PDF goes, and `convertOnSave` re-exports every time you save (the README says to restart VS Code after turning it on). For a page break, the extension documents `

` on its own line; the [page break guide](/guides/markdown-page-break) compares that with other tools. ## How do I export without installing an extension? Use a browser converter. Open the file in VS Code, select all with Ctrl+A (Cmd+A), copy, and paste it into the [markdown to PDF converter](/markdown-to-pdf), or click **Open .md file** there and pick the file directly. Check the preview, click **Download PDF**, and choose **Save as PDF** in the print dialog. The conversion runs in your browser and the text is not uploaded, which matters on a locked-down work laptop where installing extensions needs approval. This route keeps headings, tables, task lists, syntax-highlighted code blocks and Mermaid diagrams. It has limits that the extension does not share, because the converter only sees the text you paste, not your project folder: - **Relative images do not load.** `![diagram](./img/flow.png)` points at a file on your disk, which a web page cannot read. Use an absolute `https://` image URL, or export with the extension instead. - **Relative links become plain text.** A link to `../docs/setup.md` has nowhere to go in a PDF made on a web page, so it prints as its link text. - **Raw HTML is shown as text.** A `

` page break or a `
` prints literally. - **No math.** `$E = mc^2$` prints as typed, even though the VS Code preview renders it. ## How do I export Markdown to PDF from the VS Code terminal? Open the integrated terminal (View > Terminal) and run Pandoc, if it is installed: ```bash pandoc notes.md -o notes.pdf ``` The [Pandoc manual](https://pandoc.org/MANUAL.html#creating-a-pdf) explains that Pandoc makes PDFs through LaTeX by default, so you also need a LaTeX engine installed. If you do not have one, Pandoc can use other engines through the `--pdf-engine` option. Pandoc is the best choice for long documents with citations, numbered sections or a custom template, and the worst choice if you just want the file to look like the VS Code preview, because its LaTeX output has its own typography. ## Why does my PDF look different from the VS Code preview? Because the preview and the PDF are produced by different renderers. The VS Code preview uses VS Code's own markdown engine and your editor theme; the extension uses its own renderer and stylesheet; a browser converter uses the site's styles; Pandoc goes through LaTeX. Fonts, code colours and spacing will differ between them. If you need a specific look, the extension accepts your own CSS files through its `markdown-pdf.styles` setting. The preview is reliable for structure (is the table a table, is the list nested) but not for page layout, since it shows no pages at all. ## Do Mermaid diagrams survive the export? In all three routes they can, but each needs something. The Markdown PDF extension renders `mermaid` fences by loading the Mermaid library from a URL, which by default is a public CDN, so the export needs internet access for diagrams to appear. The browser converter renders them in the page and prints them as vector graphics. Pandoc has no Mermaid support of its own and prints the fence as a code block unless you pre-render the diagrams. The guide to [keeping Mermaid and code blocks in a PDF](/markdown-to-pdf/markdown-to-pdf-mermaid-code) covers each case. ## Which method should I use? Use the extension if you export often, need local images, or want export on save. Use the browser converter for a one-off export, on a machine where you cannot install extensions, or when you want to see exactly what will print before printing it. Use Pandoc for long, structured documents or when the export runs in a script. If the goal is only to let someone read the file, a PDF may be unnecessary: a shared link to a rendered page, or the [markdown viewer](/markdown-viewer), shows the same content without the page-layout work. ## Can VS Code print Markdown directly? Not from the built-in preview; the official documentation lists no print command for it. The Markdown PDF extension can also export HTML, PNG and JPEG with the same Export commands. Whichever route you take, check the first exported PDF for long code lines and wide tables, which are the two things most likely to run off the page; the [table to PDF guide](/markdown-to-pdf/markdown-table-to-pdf) covers fixes for the second. --- # PDF to markdown converter URL: https://docs-md.com/pdf-to-markdown Category: Convert Updated: 2026-08-29 Drop a PDF, get editable markdown — headings, lists, and paragraphs inferred from the layout. Nothing is uploaded. ## How do I convert PDF tables to Markdown tables? URL: https://docs-md.com/pdf-to-markdown/pdf-tables-to-markdown Updated: 2026-10-17 Use a tool that detects table structure, such as Tabula, Camelot or pdfplumber, to pull the table out as rows and columns, export it as CSV, and turn the CSV into a markdown pipe table. For a small table, retyping it into a table generator is often quicker. Then check every cell against the PDF. The reason this needs its own step is that a PDF does not store tables. It stores characters at positions on a page, plus lines and rectangles that happen to be drawn around them. A table on screen is something your eyes assemble from alignment; software has to guess the same thing from coordinates. General text extractors read across the page line by line and lose the columns, while table extractors look for ruling lines or aligned gaps and rebuild the grid. ## What does the PDF to Markdown converter do with tables? The [PDF to markdown converter](/pdf-to-markdown) on this site extracts text, headings, lists and paragraphs in your browser, but it does not rebuild tables. Each row of a table comes out as one line with the cell values separated by spaces, and consecutive rows are joined into a paragraph. That is fine for a document that happens to contain a small table you can rebuild by hand. It is not a table extractor, so for data tables use one of the methods below, and use the converter for the surrounding text. A common workflow for a report is to do both: convert the whole PDF for the prose, extract the tables separately, and paste the finished markdown tables back into the converted text where they belong. ## How do I convert a small table quickly? Open the [markdown table generator](/markdown-table-generator), add rows and columns with the **+ Row** and **+ Column** buttons, and type the values into the grid; it also accepts pasted comma- or tab-separated text. It writes the pipe syntax for you. For up to a few dozen cells this is usually faster than installing anything, and you check each value as you type it. The [markdown table guide](/guides/markdown-table) covers the syntax if you prefer to write it directly: ```markdown | Plan | Seats | Price | | ----- | ----: | ----: | | Basic | 5 | $10 | | Team | 25 | $40 | ``` ## How do I extract larger tables without code? [Tabula](https://github.com/tabulapdf/tabula) is a free desktop application for exactly this job. You open a PDF, drag a box around a table, and export the selection as CSV. It needs Java installed. Its README says it works only on text-based PDFs, with a simple test: if you can click and drag to select text in the table in a PDF viewer, Tabula should work. The same README notes that the original authors are not actively updating the desktop application, though the underlying `tabula-java` library still gets releases. Once you have a CSV file, paste it into the [CSV to markdown converter](/csv-to-markdown) to get the pipe table. Check the header row: extractors sometimes split a two-line header into two rows, which you will want to merge into one. ## How do I extract PDF tables with Python? Two well-documented libraries work on text-based PDFs. [Camelot](https://github.com/camelot-dev/camelot) can write markdown directly: ```python import camelot tables = camelot.read_pdf("report.pdf", pages="1-3") tables[0].to_markdown("table.md") ``` `read_pdf` reads only page 1 unless you pass `pages`. Its default method, `lattice`, uses the ruling lines between cells; for tables separated only by whitespace, its README recommends `flavor="network"` or `flavor="stream"`, and `flavor="auto"` picks per page. Each table also exposes `tables[0].df`, a pandas DataFrame, if you want to clean it before writing. [pdfplumber](https://github.com/jsvine/pdfplumber) gives you the rows as lists, which pandas can turn into markdown (the `to_markdown` method needs the `tabulate` package installed): ```python import pdfplumber import pandas as pd with pdfplumber.open("report.pdf") as pdf: rows = pdf.pages[0].extract_table() df = pd.DataFrame(rows[1:], columns=rows[0]) print(df.to_markdown(index=False)) ``` By default pdfplumber, like Camelot's lattice mode, finds cells from the page's drawn lines; its `table_settings` argument lets you switch strategies for borderless tables. Its documentation is explicit that it works best on machine-generated PDFs and does not do OCR. ## What about tables in scanned PDFs? A scanned table is a picture, so there is no text for these tools to align. The scan needs OCR first, and table structure from OCR output is less reliable than from a digital PDF. Camelot's README describes an optional machine-learning mode with OCR for scanned and image-only pages. Otherwise, run OCR on the file as described in [converting a scanned PDF to markdown](/pdf-to-markdown/scanned-pdf-to-markdown), then try an extractor on the result, and plan to check numbers by hand. ## What gets lost when a PDF table becomes a Markdown table? Markdown tables are simple, so some PDF tables cannot be represented exactly: - **Merged cells.** There is no colspan or rowspan. A header spanning two columns must be repeated or split into two headers, and a cell spanning rows must be repeated on each row or left blank. - **Multi-line cells.** Each row must sit on one line of markdown. Line breaks inside a cell are lost, or need `
` in renderers that allow HTML. - **Nested headers and subtotals.** Grouped column headers and bold subtotal rows become ordinary rows; mark them with bold text if the meaning depends on them. - **Formatting and footnotes.** Colours, shading and superscript footnote markers usually disappear; add footnotes as a list under the table. ## How do I check the extracted table? Compare row and column counts with the PDF first, since a merged or dropped row shifts everything below it. Then check the cells most likely to break: numbers with thousands separators or negative values in brackets, cells that wrapped onto two lines in the PDF, empty cells, and the last row before a page break. If a table continues across pages, extract each page's part and join them, removing the repeated header. For tables headed to a language model, a correct small table is worth more than a large one with shifted columns, so cut columns you do not need; the guide to [preparing PDFs for ChatGPT, Claude or RAG](/pdf-to-markdown/pdf-to-markdown-for-llm) covers the rest of that clean-up. ## Can I copy a table from a PDF viewer and paste it? You can try, but the result is usually text with spaces or line breaks between cells rather than columns, because the viewer copies characters in reading order. It sometimes works for a simple table with one word per cell, if you paste into a spreadsheet and split the text into columns there. For anything bigger, a table extractor saves time, and once the data is in a spreadsheet you can save it as CSV and convert it in one step. ## How do I convert a PDF to Markdown for ChatGPT, Claude or a RAG pipeline? URL: https://docs-md.com/pdf-to-markdown/pdf-to-markdown-for-llm Updated: 2026-10-17 Extract the PDF's text into markdown, check it, remove page furniture such as running headers and page numbers, then paste or upload the `.md` file. For a RAG pipeline, split it on its headings. This works for PDFs with a text layer; scans need OCR first, and charts or complex tables are better sent as the PDF itself. Markdown suits language models because it is plain text that still carries structure. A heading marked with `##` tells the model, and your chunking code, where a section starts; a `-` list stays a list. You also get to see and edit exactly what the model will read, which you cannot do with a PDF that the service parses for you. ## Why convert to Markdown instead of uploading the PDF? Three reasons: control, cost and reuse. Both major APIs read PDFs by looking at the text and a picture of every page. Anthropic's [PDF support documentation](https://platform.claude.com/docs/en/build-with-claude/pdf-support) says each page is converted into an image and its text is extracted and provided alongside it, and that image tokens are charged in addition to text tokens. OpenAI's [file input guide](https://platform.openai.com/docs/guides/pdf-files) likewise says PDF parsing puts both extracted text and page images into context, which can increase token usage. Markdown sends only the text, so a long text-heavy document costs less to process and leaves more of the context window for your question. Control matters as much. In markdown you can delete the cover page, the table of contents, the legal boilerplate and every repetition of the running header before the model sees any of it. And a markdown file can be versioned, diffed, searched and reused across tools, which a one-off upload cannot. ## When should I send the PDF itself? When the meaning is in the layout or the pictures. Charts, diagrams, photos, signatures, forms with checkboxes and pages where position matters (an invoice, a floor plan) lose information as text. Complex tables are also safer as a PDF unless you rebuild them as markdown tables first. Scanned documents with no text layer cannot be converted by text extraction at all. In those cases the page images the APIs create are exactly what you want, and the extra cost buys real information. ## How do I convert the PDF in the browser? 1. Open the [PDF to markdown converter](/pdf-to-markdown) and drop the PDF on it, or click **Choose PDF**. The file is read in your browser and is not uploaded. 2. Read the result in the editor on the left against the preview on the right. Larger text has become headings (`#`, `##`, `###`), bullet characters have become list items, wrapped lines have been joined into paragraphs, and words hyphenated across line ends have been rejoined. 3. Clean up in the editor (see below). 4. Click **Copy markdown** to paste into a chat, or **Download .md** to upload the file or feed it to a script. If the converter reports that no text was found, the PDF is a scan; see [whether a scanned PDF can be converted](/pdf-to-markdown/scanned-pdf-to-markdown). ## What should I clean up before giving it to a model? Remove the things that repeat on every page and carry no meaning: running headers, footers, page numbers, and "Confidential" stamps. They come through as stray lines between paragraphs and can confuse both the model and a chunker. Then check: - **Heading levels.** Headings are guessed from font size, so a large pull quote may have become a heading and a small bold heading may have stayed a paragraph. Fix them, because the headings are what your chunks will be built on. The [headings guide](/guides/markdown-headings) covers the levels. - **Paragraphs split at page breaks.** Each page is processed on its own, so a paragraph that runs from one page to the next comes out as two. Join them where it matters. - **Multi-column pages.** Two-column layouts, common in papers and newsletters, can come out with lines from both columns interleaved. Check these pages first. - **Tables.** The converter does not rebuild tables; their cells come out as runs of text. Rebuild the important ones as markdown tables, following the [PDF tables guide](/pdf-to-markdown/pdf-tables-to-markdown). To see how long the result is before you paste it, the [word counter](/markdown-word-counter) gives word and character counts. ## How do I chunk the Markdown for a RAG pipeline? Split on headings rather than on a fixed number of characters, so that each chunk is one coherent section. A common pattern is to split at `##` and, if a section is still too long for your embedding model, again at `###`, then by paragraph. Keep the heading path with each chunk, for example "Annual report > Risks > Currency", either at the top of the chunk text or in its metadata, so a chunk retrieved on its own still says what it is about. Store the source file name and page or section with every chunk so answers can cite where they came from. Whatever sizes you choose, test retrieval on real questions; good chunking is checked, not assumed. ## How do I convert many PDFs automatically? The browser converter handles one file at a time and has no API, so for a pipeline use a library. Two open-source options with markdown output: Microsoft's [MarkItDown](https://github.com/microsoft/markitdown) runs as `markitdown file.pdf -o file.md` after `pip install 'markitdown[all]'`, and [PyMuPDF4LLM](https://pypi.org/project/pymupdf4llm/) provides `pymupdf4llm.to_markdown("file.pdf")` in Python, with options for tables and OCR. PyMuPDF4LLM is licensed under the AGPL, with a commercial licence also offered, which matters if you ship it inside a closed product. Whichever you use, spot-check the output the same way you would check a manual conversion. ## Does the converter keep links, images or bold text? No. It reads the characters on each page and their sizes, so it keeps text, headings, lists and paragraphs, but not hyperlinks, images, bold or italic, footnote markers as footnotes, or colours. For most question-answering use that loss is acceptable, because the words carry the meaning. If a document depends on its figures, describe them in a sentence where they appeared, or send the relevant pages as a PDF alongside the markdown. ## Is it safe to convert confidential PDFs this way? The conversion step is: the PDF is processed in your browser and the file is not sent to a server. What happens next is up to you. Pasting the markdown into a chat service sends it to that service under its terms, the same as uploading the PDF would. Removing names, account numbers and other personal data from the markdown before you send it is easier than redacting a PDF, which is one more reason to convert first. ## Can a scanned PDF be converted to Markdown? URL: https://docs-md.com/pdf-to-markdown/scanned-pdf-to-markdown Updated: 2026-10-17 Yes, but only after optical character recognition (OCR) turns the page images into text. A scanned PDF is a set of photographs of pages with no text inside, so a text-based converter finds nothing to extract. Run OCR first, which adds an invisible text layer, then convert that PDF to markdown and proofread it. The distinction is between how a PDF was made, not how it looks. A PDF exported from Word, Google Docs, LaTeX or a design tool contains the actual characters with their fonts and positions; a converter can read them directly. A PDF made by a scanner, a phone scanning app or a fax contains one image per page. To a computer it is no different from a photo of a page, and getting words out of it means recognising the shapes of letters, which is what OCR does. ## How do I know if my PDF is scanned? Open it in any PDF viewer and try to select a sentence with the cursor. If you can highlight individual words, there is a text layer. If the cursor draws a box over the whole page, or nothing happens, the page is an image. A second check is search: press Ctrl+F (Cmd+F on macOS) and look for a word you can see on the page; no match means no text. On the command line, the Poppler utility `pdffonts` lists the fonts a PDF uses, and a purely scanned file lists none: ```bash pdffonts scan.pdf ``` Some PDFs are mixed: typed pages with a few scanned pages inserted, such as a signed form. Check a page of each kind. ## What does the PDF to Markdown converter do with a scan? The [PDF to markdown converter](/pdf-to-markdown) reads only the text layer, in your browser, and does not perform OCR. That is a deliberate trade: OCR engines are large and slow, and keeping the tool to text extraction means the file never leaves your computer and conversion takes seconds. When a PDF has no text at all, it says so, with a message that the file is probably a scan and needs OCR. With a mixed PDF, there is no error. The typed pages convert and the scanned pages contribute nothing, so the markdown can look complete while missing pages. Compare the page count shown above the result with the content, or OCR the whole file first so every page has text. ## How do I add a text layer with OCR? [OCRmyPDF](https://github.com/ocrmypdf/OCRmyPDF) is a free command-line tool that adds a searchable text layer to a scanned PDF using the Tesseract OCR engine, while the scanned page images stay visible as before. Its README lists installs such as `brew install ocrmypdf` on macOS and `apt install ocrmypdf` on Debian and Ubuntu. Then: ```bash ocrmypdf -l eng scan.pdf scan-ocr.pdf ``` `-l` sets the language, and several can be combined, for example `-l eng+fra`; other languages need their Tesseract language packs installed. The README also shows `--rotate-pages` to fix pages scanned sideways and `--deskew` to straighten crooked ones, both of which help recognition. For a mixed PDF where some pages already have text, the documentation describes a skip mode that leaves those pages alone: `--mode skip` in version 17 and later, `--skip-text` in earlier versions. Once you have `scan-ocr.pdf`, drop it into the converter. Headings, paragraphs and lists are inferred from the OCR text the same way as from any other PDF. ## Are there other ways to OCR a PDF? Several, depending on what you have: - **Desktop PDF software.** Many PDF editors include an OCR or "recognise text" command that saves a searchable copy; feed that copy to the converter. - **Python libraries.** [PyMuPDF4LLM](https://pypi.org/project/pymupdf4llm/) converts PDFs to markdown and documents OCR options such as `force_ocr=True` and `ocr_language="eng+fra"`. Microsoft's MarkItDown has an OCR plugin that sends page images to a vision-capable language model. - **An AI model directly.** Claude and OpenAI's models accept PDFs and look at an image of each page, so you can upload a scan and ask for markdown. Treat the result as a draft: models can silently skip or rephrase text, which is harder to spot than an OCR typo. ## How accurate is OCR? It depends mostly on the scan. Clean, straight, high-resolution pages of printed text in a common font come out with few errors; faint photocopies, skewed phone photos, small print, unusual fonts and handwriting come out much worse. The Tesseract documentation on [improving quality](https://tesseract-ocr.github.io/tessdoc/ImproveQuality.html) says it works best on images of at least 300 DPI, so if you are scanning the paper yourself, scan at 300 DPI or higher rather than trying to fix a low-resolution file later. Typical errors to look for when proofreading: `0` and `O`, `1`, `l` and `I`, `rn` read as `m`, missing or extra spaces, broken words at line ends, and stray characters from stamps, staples or punch holes. Numbers deserve the most care, because a wrong digit looks perfectly plausible. ## What about tables and multi-column pages in scans? OCR recognises characters, not structure. Table cells come out as text in reading order and columns of a two-column page can be interleaved, the same problems that text-based PDFs have, plus recognition errors on top. Rebuild important tables by hand or with a table-extraction tool; the [PDF tables guide](/pdf-to-markdown/pdf-tables-to-markdown) covers the options. For newspapers and academic papers with complex layouts, expect to reorder paragraphs. ## How do I clean up the Markdown after OCR? Read it against the original, page by page, for anything you will rely on. Then tidy the structure: fix heading levels, delete running headers and page numbers that came through as text, and rejoin paragraphs split at page breaks. The [markdown formatter](/markdown-formatter) normalises spacing and list markers, and the [markdown linter](/markdown-lint) points out structural problems such as skipped heading levels. If the markdown is going to a language model, the guide to [preparing PDFs for ChatGPT, Claude or RAG](/pdf-to-markdown/pdf-to-markdown-for-llm) covers the remaining steps. ## Can handwriting be converted to Markdown? Not reliably with standard OCR. Engines such as Tesseract are built for printed text, and handwritten notes usually come out as fragments. Vision-capable AI models do better on clear handwriting, but they guess at unclear words without marking them, so check every line. For a few pages, typing them out may be faster than correcting the output. --- # Markdown to Word converter URL: https://docs-md.com/markdown-to-word Category: Convert Updated: 2026-08-29 Markdown to a .doc that opens in Word — or paste from Word and get clean markdown back. Both directions, in-browser. ## Can Microsoft Word open a .md file? URL: https://docs-md.com/markdown-to-word/can-word-open-md-file Updated: 2026-10-17 Not as Markdown. Desktop Word can open a `.md` file only as plain text, so you see the raw `#`, `**` and `|` characters instead of headings, bold and tables. Word for the web does not open it at all. To get a formatted Word document, convert the Markdown to `.docx` (or a Word-readable `.doc`) first. That answer surprises people because a `.md` file looks so close to a document. It is one, structurally: headings, lists, emphasis, tables. But the structure is written as punctuation in plain text, and turning that punctuation into formatting is the job of a Markdown parser. Word ships without one. ## Which file formats does Word actually support? Microsoft's [file format reference for Word](https://learn.microsoft.com/en-us/office/compatibility/office-file-format-reference) lists .doc, .docm, .docx, .dot, .dotm, .dotx, .htm and .html, .mht, .odt, .pdf, .rtf, .txt, .wps, .xml and .xps. Markdown is not on the list. The browser version is narrower still: according to Microsoft's page on [differences between Word for the web and the desktop app](https://support.microsoft.com/en-us/office/differences-between-using-a-document-in-the-browser-and-in-word-90fac46c-2b8e-4fa1-b997-4e55ce4ed754), Word for the web opens .docx, .dotx, .docm, .dotm, .doc, .dot and, from a SharePoint library, .odt, and it "can't open documents in other file formats". So there are two different situations: | Where | Opens a .md file? | What you see | |---|---|---| | Word for Windows or Mac | Yes, as plain text | The Markdown source, symbols and all | | Word for the web | No | Nothing; the format is not supported | | Word with a Markdown add-in | Yes, converted | Formatted headings, lists, tables | ## How do I open a .md file in desktop Word anyway? In File > Open, change the file-type filter from Word documents to All Files, then pick the `.md` file. Word reads it as text. If accented letters or non-Latin characters come out garbled, Word guessed the wrong encoding; Microsoft's [text encoding page](https://support.microsoft.com/en-us/office/choose-text-encoding-when-you-open-and-save-files-60d59c21-88b5-4006-831c-d536d42fd861) explains how to choose one on open. Markdown files are almost always UTF-8. This is useful when you only want to proofread the words or run Word's spelling and grammar check over the text. It is not useful for sharing a formatted document: the reader sees `## Results` and `**important**` rather than a heading and bold text. If you edit and save the file from Word, keep the encoding as UTF-8 and watch Word's AutoCorrect as you type: it can turn straight quotes into curly ones and double hyphens into dashes, which breaks code samples and some Markdown syntax. ## What is the best way to get a .md file into Word with formatting? Convert it. There are three common routes, and each produces a real Word document with styles. 1. **In the browser.** Paste the Markdown into the [Markdown to Word converter](/markdown-to-word) and click Download .doc. Headings, lists, tables, links, blockquotes and code blocks come through. The file is HTML in a Word-compatible wrapper; desktop Word opens it, and File > Save As > Word Document (.docx) turns it into a standard `.docx`. Do that before uploading it to Word for the web, which does not accept HTML. 2. **On the command line.** [Pandoc](https://pandoc.org/MANUAL.html) converts directly: `pandoc notes.md -o notes.docx`. Add `-f gfm` for GitHub-flavored files, and `--reference-doc=your-template.docx` to apply your own styles. 3. **Inside Word.** A third-party add-in such as [Writage](https://www.writage.com/docs/introduction/) adds Markdown open and save to Word on Windows and macOS. Check the vendor's license and pricing before you rely on it. Whichever you choose, headings become Word's Heading 1, Heading 2 and so on, so the navigation pane, the table of contents feature and PDF bookmarks work. That only holds if the Markdown uses real headings; lines of bold text stay bold text. The [headings guide](/guides/markdown-headings) covers the syntax. ## Why does my .md file open in Notepad or another app instead of Word? Double-clicking runs whatever app your operating system has associated with the `.md` extension, which is often a text editor or a code editor. That is the right default: Markdown is designed to be read and edited as plain text. Changing the association to Word only changes which program shows you the raw text; it does not make Word render it. If you just want to read a Markdown file with formatting, open it in a [Markdown viewer](/markdown-viewer) instead, which renders headings, tables and code without converting anything. ## Can Word save a document as a .md file? Not natively. Word's save formats include .docx, .rtf, .txt, .htm and PDF, not Markdown. Saving as .txt keeps the words and drops every bit of formatting, so you lose the structure you would want in Markdown. To go from Word to Markdown, copy the content and paste it into the Word to Markdown side of the [Markdown to Word converter](/markdown-to-word), which reads the formatted clipboard and writes `#` headings, `**bold**`, lists and pipe tables. Pandoc also reads `.docx`: `pandoc report.docx -t gfm -o report.md`. ## Do tables and images survive the conversion to Word? Tables do, when you use a converter: each pipe table becomes a real Word table, as explained in [turning a Markdown table into a Word table](/markdown-to-word/markdown-table-to-word-table). Images depend on where they live. An image referenced by a relative path such as `./img/chart.png` only resolves if the converter can see that folder. Pandoc, run from the folder the paths are relative to, embeds local images in the `.docx`. A browser-based converter cannot read your disk, so the file carries only the image address: local images come through as broken references, and remote ones depend on Word fetching the URL. Check every image after opening and insert any missing ones in Word. ## Is converting better than sending the .md file as it is? It depends on the reader. A developer, a static-site generator or an AI assistant reads the `.md` directly, and converting would only lose the plain-text advantages: clean diffs, version control, and no hidden formatting. A reviewer who works in Word with tracked changes, or a client who expects a document, needs the converted file. If the reader only needs to look at it, a PDF is often simpler than either; the [Markdown to PDF converter](/markdown-to-pdf) produces one with the same headings and tables. ## How do I keep code blocks formatted when converting Markdown to Word? URL: https://docs-md.com/markdown-to-word/keep-code-blocks-in-word Updated: 2026-10-17 Use fenced code blocks in the Markdown and convert with a tool that maps them to a monospaced block style, such as Pandoc or a converter that writes preformatted text. Indentation and line breaks then survive. Pasting code as plain text into Word loses them, because Word's normal paragraph style uses a proportional font and AutoCorrect rewrites quotes. Code is the part of a document that breaks most easily on the way into Word. Prose can reflow freely; code cannot. A changed quote mark, a collapsed indent or a wrapped line can turn a working example into one that fails when a reader copies it. The steps below keep the code exact and readable. ## Why do code blocks lose their formatting in Word? Three separate things go wrong, and they have different fixes. - **The font.** Word's body text is proportional, so columns of code stop lining up. Code needs a monospaced font. - **Whitespace.** Leading spaces, tabs and blank lines inside a block matter in code, especially in Python and YAML. Plain paragraphs in Word do not protect them. - **AutoCorrect.** Word's [AutoFormat As You Type](https://support.microsoft.com/en-us/word/autoformat-as-you-type) options replace straight quotes with curly ones and can apply formatting to text wrapped in asterisks or underscores. Inside code, that silently changes the characters. A converter fixes the first two by writing each code block as a dedicated preformatted block. The third only happens when someone types in Word, so it matters when you edit the code after conversion. ## How do I convert Markdown code blocks to Word in the browser? Paste the document into the [Markdown to Word converter](/markdown-to-word) and download the `.doc`. Each fenced code block becomes a preformatted block set in Consolas (falling back to Courier New) at 10 pt, on a light grey background with a thin border, and inline code in sentences gets the same monospaced font. Spaces, indentation and blank lines inside the block are kept as written. Open the file in desktop Word and use File > Save As > Word Document (.docx) to make it a standard Word file. The limit is color. The browser converter does not apply syntax highlighting, so keywords and strings come out in one color. For many documents (runbooks, procedures, handover notes) that is fine and easier to print. If you need colored code, use Pandoc. ## How do I keep syntax highlighting with Pandoc? Pandoc highlights code in `.docx` output by default, using its internal highlighter and the `pygments` style, as described under `--syntax-highlighting` in the [Pandoc manual](https://pandoc.org/MANUAL.html#option--syntax-highlighting). It needs to know the language, so write the tag after the opening fence: ````markdown ```python def total(items): return sum(i.price for i in items) ``` ```` Then convert: ```bash pandoc guide.md -o guide.docx ``` To pick a different color scheme, pass a style name. The manual lists `pygments`, `kate`, `monochrome`, `breezeDark`, `espresso`, `zenburn`, `haddock` and `tango`, and `pandoc --list-highlight-styles` prints the list for your installed version: ```bash pandoc guide.md --syntax-highlighting=tango -o guide.docx pandoc guide.md --syntax-highlighting=none -o guide.docx ``` If your pandoc rejects `--syntax-highlighting`, it is an older release: use `--highlight-style=tango` instead, which the current manual lists as the deprecated spelling of the same option. Dark styles such as `breezeDark` and `zenburn` assume a dark background, so check that the result is legible on a white page before you send it. ## How do I change the font or size of code in the Word file? With Pandoc, change the styles in a reference document rather than fixing each block by hand. Pandoc writes code blocks with the paragraph style `Source Code` and inline code with the character style `Verbatim Char`; both are in the list of styles the [reference-doc option](https://pandoc.org/MANUAL.html#option--reference-doc) uses. Create the reference file once, edit those two styles in Word (font, size, shading, spacing), save it, and pass it on every conversion: ```bash pandoc -o custom-reference.docx --print-default-data-file reference.docx pandoc guide.md --reference-doc=custom-reference.docx -o guide.docx ``` With the browser converter's output, select one code block in Word, set the font and shading you want, then use Styles > Create a Style so you can apply the same look to the other blocks in one click each. ## What do I do about long lines in code blocks? Word has no horizontal scrolling, so a line wider than the page wraps onto the next line. The wrapped part is not a new line in the code, but a reader cannot tell. Your options, in order of preference: 1. Shorten the lines in the source. Most languages allow breaking a long call or command across lines (a trailing backslash in shell, open brackets in Python and JavaScript). 2. Reduce the code font size by a point in the code style. Do it in the style, not block by block. 3. Put the section in landscape orientation in Word for very wide output such as logs or tables printed by a tool. If the document is going to be read rather than edited, a PDF is often the better target: the [Markdown to PDF converter](/markdown-to-pdf) keeps the same monospaced blocks with fixed page layout. ## How do I stop Word changing quotes inside code? Turn off the smart quotes option before you edit any code in Word. Microsoft's [smart quotes page](https://support.microsoft.com/en-us/office/smart-quotes-in-word-702fc92e-b723-4e3d-b2cc-71dedaf2f343) gives the path: File > Options > Proofing > AutoCorrect Options > AutoFormat As You Type, then clear "Straight quotes" with "smart quotes". The setting only affects text as you type, so code that came in through conversion keeps its straight quotes until someone edits it. Spelling and grammar marks are the other annoyance: Word underlines variable names and keywords. Select the code (or modify the code style) and choose [Do not check spelling or grammar](https://support.microsoft.com/en-us/word/set-up-or-change-the-languages-used-to-check-spelling-and-grammar) in the proofing language settings, so the red lines go away without switching proofing off for the whole document. ## What happens to inline code, tables of commands and diagrams? Inline code in a sentence keeps its monospaced font with both converters. Code inside a table cell has to be inline code in Markdown in the first place, because a GitHub Flavored Markdown cell cannot hold a fenced block; the [code block guide](/guides/markdown-code-block) and [Markdown table to Word table](/markdown-to-word/markdown-table-to-word-table) cover both sides of that. Diagram fences such as `mermaid` are not drawn by either converter: they arrive in Word as code, showing the diagram source. Render the diagram to an image first and reference the image in the Markdown if the reader needs to see it. ## How do I check the code survived? Copy one block back out of the Word file and compare it with the original, or run it. A diff tool shows any changed character: curly quotes, a non-breaking space, a dash where a hyphen was. For documents where readers will copy commands, do this check on every block, not only the first one. ## How do I turn a Markdown table into a Word table? URL: https://docs-md.com/markdown-to-word/markdown-table-to-word-table Updated: 2026-10-17 Convert the Markdown to a Word document with a converter that understands pipe tables, and each table arrives as a real Word table with rows, columns and borders. Pasting the raw text into Word gives you lines full of `|` characters instead; Word's Convert Text to Table can repair that, but only after some cleanup. A Markdown table is plain text: pipes mark the columns, a row of hyphens separates the header, and each line is one row. Word does not read that syntax. It needs the table structure spelled out, either as HTML table markup or as Word's own table XML inside a `.docx`. Every method below is a way of producing one of those two things. Pick the one that fits how often you do this and how much control you need over the result. ## What is the quickest way to get a Word table from Markdown? Use the [Markdown to Word converter](/markdown-to-word) on this site: paste the whole document, click Download .doc, and open the file in Word. The converter renders the Markdown to HTML with the GitHub Flavored Markdown table rules, so every pipe table becomes an HTML ``, and Word opens that as a native table you can resize, restyle and sort. What you get, concretely: - The header row is a real header row, and each cell sits in its own Word cell. - Cells have a thin grey border and a little padding, so the table is readable before you apply a style. - Bold, italic, links and inline code inside cells keep their formatting. - The conversion runs in your browser; the document is not uploaded anywhere. Two honest limits. First, the download is a `.doc` file that contains HTML, which desktop Word opens directly, sometimes after a compatibility prompt. Use File > Save As and choose Word Document (.docx) to turn it into a normal Word file. Microsoft's own list of [formats Word for the web opens](https://support.microsoft.com/en-us/office/differences-between-using-a-document-in-the-browser-and-in-word-90fac46c-2b8e-4fa1-b997-4e55ce4ed754) excludes HTML, so do that save in desktop Word before you upload the file to the browser version or SharePoint. Second, the table gets the converter's simple bordered look rather than one of Word's table styles; apply a style from the Table Design tab once the file is open. ## How do I convert a Markdown table to Word with Pandoc? Pandoc writes `.docx` directly and is the better choice when you convert often or need a house style. Install it, then run: ```bash pandoc report.md -o report.docx ``` Pandoc's Markdown reader handles pipe tables by default. If your file is GitHub-flavored, say so explicitly with `-f gfm`: ```bash pandoc report.md -f gfm -o report.docx ``` Every pipe table becomes a Word table with the style named `Table`. To change how all tables look (borders, shading, fonts), make a reference document once and pass it on every run. The [Pandoc manual](https://pandoc.org/MANUAL.html#option--reference-doc) gives the steps: ```bash pandoc -o custom-reference.docx --print-default-data-file reference.docx # open custom-reference.docx in Word, edit the "Table" style, save pandoc report.md --reference-doc=custom-reference.docx -o report.docx ``` Column widths follow a rule worth knowing. According to the [pipe_tables section](https://pandoc.org/MANUAL.html#extension-pipe_tables) of the manual, if any line of the table is longer than the column width setting, the table takes the full text width and the relative column widths come from the number of hyphens in the delimiter row. So `|---|-|` gives the first column three quarters of the width. If every line is shorter, cells are sized to their content. When a table comes out with a cramped first column, adjust the hyphens rather than fighting the widths in Word afterwards. ## Can I fix a Markdown table that I already pasted into Word? Yes, with Word's built-in Convert Text to Table. Microsoft documents it in [Convert text to a table or a table to text](https://support.microsoft.com/en-us/word/convert-text-to-a-table-or-a-table-to-text): separator characters mark the columns and paragraph marks mark the rows. Steps for a pasted pipe table: 1. Delete the delimiter line (the one made of hyphens and colons). It would otherwise become a row of dashes. 2. Select the remaining table lines. 3. Choose Insert > Table > Convert Text to Table. 4. Under Separate text at, choose Other and type `|`. 5. Click OK, then delete the empty first and last columns that the outer pipes create. The result is a real table, but expect cleanup: the spaces around each cell value stay in the cells, an escaped pipe (`\|`) inside a cell is split into two cells, and any Markdown inside cells (`**bold**`, backticks, links) stays as literal characters. Microsoft also notes that when your text contains commas you should use tabs as the separator, and the same reasoning applies to pipes. A cleaner variant: paste the table into the [CSV to Markdown converter](/csv-to-markdown), switch it to Markdown to CSV, choose Tab as the output delimiter, and paste the tab-separated result into Word. Convert Text to Table with Tabs then needs no column deletion and no space trimming. ## Why does my table show pipes instead of columns in Word? Because Word received the Markdown source, not a converted document. This happens when you paste from a text editor, open a `.md` file directly, or copy from a viewer that copies the raw text. Word has no Markdown reader; Microsoft's [file format reference](https://learn.microsoft.com/en-us/office/compatibility/office-file-format-reference) for Word lists formats such as .docx, .doc, .rtf, .odt, .htm and .txt, and no Markdown format. Convert first with one of the methods above; renaming the file to `.docx` does not help, because the content is still plain text. ## Which method keeps formatting inside cells? Both converters keep inline formatting, because they parse the Markdown before building the table. Bold, italic, inline code, links and line breaks written as `
` come through as formatting in the Word cell. Word's Convert Text to Table does not parse anything, so the asterisks and backticks stay as text. If the cells hold more than short inline content, remember the source format's limits first: a GitHub Flavored Markdown cell cannot hold a list, a paragraph break or a code block, as the [GFM specification](https://github.github.com/gfm/#tables-extension-) states that block-level elements cannot be inserted in a table. The [table syntax guide](/guides/markdown-table) and [line breaks in table cells](/guides/markdown-table-line-break) cover the workarounds. ## What about merged cells, captions and very wide tables? Markdown pipe tables have no merged cells, so nothing to convert; merge the cells in Word after conversion using Layout > Merge Cells. Captions are not part of GFM; Pandoc's own Markdown accepts a caption paragraph starting with `Table:` or just `:` directly before or after the table (the [table_captions extension](https://pandoc.org/MANUAL.html#extension-table_captions)), and the reference document has a Table Caption style for it. For tables wider than the page, convert first, then either set the table to AutoFit to window in Word or switch that section to landscape. If the same wide table is going to a PDF instead, the [Markdown to PDF converter](/markdown-to-pdf) handles the layout in one step. ## What should I check after converting? Open the result and look at four things: - **Header row.** Select the first row and choose Table Layout > [Repeat Header Rows](https://support.microsoft.com/en-us/word/repeat-table-header-on-subsequent-pages) so a long table repeats its header on every page. - **Number alignment.** Right-align numeric columns if the converter did not. - **Escaped characters.** A `\|` in the source should appear as a single `|` inside one cell. - **Widths.** Long cells can squeeze short ones; drag the column borders or use AutoFit to contents. If you are still building the table, the [Markdown table generator](/markdown-table-generator) produces padded, correctly escaped pipe tables that convert without surprises. --- # CSV to markdown table converter URL: https://docs-md.com/csv-to-markdown Category: Convert Updated: 2026-09-03 Paste CSV, TSV, or a spreadsheet range and get an aligned markdown table — or paste a markdown table and get CSV back. ## How do I convert CSV to Markdown from the command line? URL: https://docs-md.com/csv-to-markdown/csv-to-markdown-command-line Updated: 2026-10-17 Run `pandoc -f csv -t gfm data.csv` to print a GitHub-flavored markdown table, or `mlr --icsv --omd cat data.csv` if you use Miller. Both read quoted fields correctly and escape pipe characters. Add `-o table.md` to pandoc, or redirect with `>`, to write the result to a file instead of the terminal. Those two are the safest choices. csvkit's `csvlook` and Python's pandas also print markdown-style tables, but both change your data in ways that are easy to miss. Every command below was run on 2026-10-17 against the same test file with the versions named, and the differences are described from that run rather than from memory. The test file has a comma inside a quoted field and a literal pipe: ```csv name,price,note Widget,9.99,"Small, blue" Gadget,24.50,"Has a | pipe" ``` ## pandoc pandoc lists CSV and TSV among its input formats in the [pandoc manual](https://pandoc.org/MANUAL.html), and `gfm` (GitHub-Flavored Markdown) among its outputs. Tested with pandoc 3.12.1: ```bash pandoc -f csv -t gfm data.csv pandoc -f csv -t gfm data.csv -o table.md cat data.csv | pandoc -f csv -t gfm pandoc -f tsv -t gfm data.tsv ``` Output: ```markdown | name | price | note | |--------|-------|---------------| | Widget | 9.99 | Small, blue | | Gadget | 24.50 | Has a \| pipe | ``` The columns are padded, the pipe is escaped as `\|`, and `24.50` stays `24.50`. pandoc treats the first row as the header. Install it from the [pandoc releases page](https://github.com/jgm/pandoc/releases) or your package manager. One behavior to know: when a cell contains a line break, pandoc cannot express the table as a pipe table, so it writes a raw HTML `

` instead, with `
` inside the cell. That still renders on GitHub, but it is no longer a markdown table you can edit comfortably. If you want a pipe table, replace the line breaks first; the [line break in a table cell guide](/guides/markdown-table-line-break) explains the options. ## Miller [Miller](https://miller.readthedocs.io/en/latest/file-formats/) (`mlr`) supports markdown as an output format, and as of Miller 6.11.0 as an input format too. Tested with Miller 6.22.0: ```bash mlr --icsv --omd cat data.csv mlr --c2m cat data.csv mlr --itsv --omd cat data.tsv mlr --icsv --ifs ';' --omd cat data.csv ``` `--c2m` is shorthand for CSV in, markdown out. Output: ```markdown | name | price | note | | --- | --- | --- | | Widget | 9.99 | Small, blue | | Gadget | 24.50 | Has a \| pipe | ``` Miller does not pad the columns, which makes the source harder to read but renders identically. Its strength is that `cat` can be any Miller verb, so you can filter, sort or pick columns in the same command, for example `mlr --c2m sort -f name then cut -f name,price data.csv`. The weakness: a cell with a line break is written into the table as-is, which splits the row across two lines and breaks the table. Replace line breaks before converting if your data has them. ## csvkit (csvlook) The [csvlook documentation](https://csvkit.readthedocs.io/en/latest/scripts/csvlook.html) describes its output as a "Markdown-compatible, fixed-width format". Tested with csvkit 2.2.0: ```bash csvlook data.csv csvlook -I data.csv csvlook -d ';' -I data.csv ``` Two problems showed up in testing. First, csvlook does not escape pipes, so `Has a | pipe` became an extra column when rendered. Second, it infers column types by default: a value of `007` came out as `7`, and with `-d ';'` the value `1,5` came out as `15`. The `-I` (`--no-inference`) flag turns inference off and keeps values as written. Use csvlook for reading a CSV in the terminal; if you publish its output, add `-I` and check for pipes by hand. ## Python with pandas pandas has `DataFrame.to_markdown()`, which, as its [documentation](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.to_markdown.html) says, requires the `tabulate` package. Tested with pandas 3.0.6 and tabulate 0.10.0: ```bash pip install pandas==3.0.6 tabulate==0.10.0 python -c "import pandas as pd; print(pd.read_csv('data.csv', dtype=str).to_markdown(index=False))" ``` `index=False` drops the row-number column that pandas adds otherwise. `dtype=str` matters: without it, pandas parses `24.50` as a number and prints `24.5`, and `007` as `7`. Like csvlook, this output did not escape the pipe, and a cell with a line break split the row. pandas is the right choice when the data needs cleaning in Python anyway; for a straight conversion it is the heaviest option. ## Which tool should I use? pandoc for a one-off conversion or a build script, because it escapes pipes, keeps values unchanged and pads columns. Miller when you also want to filter, sort or select columns in the same step. pandas when the conversion sits inside a Python data pipeline. csvlook for looking at data in a terminal rather than for producing published markdown. | Tool | Version tested | Escapes `\|` | Keeps `007` and `24.50` | Cell with a line break | |---|---|---|---|---| | pandoc | 3.12.1 | yes | yes | writes an HTML table | | Miller | 6.22.0 | yes | yes | breaks the table | | csvlook | csvkit 2.2.0 | no | only with `-I` | shows `↵` | | pandas + tabulate | 3.0.6 + 0.10.0 | no | only with `dtype=str` | breaks the table | ## How do I convert every CSV file in a folder? Use a shell loop. With pandoc, this writes `report.md` next to `report.csv` for each file in the current folder: ```bash for f in *.csv; do pandoc -f csv -t gfm "$f" -o "${f%.csv}.md"; done ``` The quotes around `$f` keep file names with spaces intact, and `${f%.csv}` strips the extension before adding `.md`. ## How do I set column alignment from the command line? None of these commands sets alignment for you; pandoc and Miller write plain `---` separators, which render left-aligned. Edit the separator row afterwards: `---:` aligns a column right and `:---:` centers it, as the [markdown table guide](/guides/markdown-table) shows. If you would rather click than edit, paste the CSV into the [CSV to markdown converter](/csv-to-markdown), which has per-column alignment and runs in the browser. ## How do I keep a generated table in sync with the CSV? Treat the markdown as a build output. Keep the CSV as the source of truth, put the conversion command in a script or a `Makefile` target, and run it whenever the data changes: ```make docs/prices.md: data/prices.csv pandoc -f csv -t gfm data/prices.csv -o docs/prices.md ``` If both files are committed, a continuous-integration job can run the same command and then `git diff --exit-code docs/prices.md`, which fails the build when someone edited the CSV without regenerating the table. That catches the most common drift: a table in the docs that no longer matches the data it claims to show. Pinning the converter version in the job keeps the output stable, because padding and escaping can change between releases. ## What about CSV files with a semicolon or tab delimiter? For tab-separated files use pandoc's `-f tsv` or Miller's `--itsv`. For semicolons, which spreadsheet software writes in some locales, Miller takes `--ifs ';'` and csvlook takes `-d ';'`. pandoc's CSV reader expects commas, so convert the delimiter first or use Miller. ## Can I do this without installing anything? Yes, if you do not need it in a script. The [CSV to markdown converter](/csv-to-markdown) accepts pasted CSV or TSV, detects the delimiter, escapes pipes, turns in-cell line breaks into `
` tags, and works offline once the page has loaded. For data that starts as JSON rather than CSV, the [JSON to markdown table converter](/json-to-markdown-table) does the same job. ## How do I convert an Excel sheet to a Markdown table? URL: https://docs-md.com/csv-to-markdown/excel-to-markdown-table Updated: 2026-10-17 Select the cells in Excel, copy them, and paste them into a CSV to Markdown converter. The copied cells arrive as tab-separated text, which the converter turns into a pipe table with the first row as the header. For a whole sheet, save it as CSV first. Formatting and formulas do not carry over; values do. Markdown has no spreadsheet format of its own, so every route goes through plain text: either the text Excel puts on the clipboard when you copy, or a CSV file. The converter's job is to split that text into cells, escape anything that would break a pipe table, and lay out the header and delimiter rows. ## What is the fastest way to turn Excel cells into a Markdown table? Copy and paste: 1. In Excel, select the range, including the header row. Select only the cells you need; empty rows and columns at the edges become empty table rows and columns. 2. Copy it (Ctrl+C, or Cmd+C on a Mac). 3. Paste into the input of the [CSV to Markdown converter](/csv-to-markdown). The delimiter is set to auto-detect, and a pasted spreadsheet range is detected as tab-separated. 4. Check the options: First row is header (on by default), Pad columns (aligns the pipes in the source), Trim whitespace, and Bold header. 5. Click a column's alignment control to right-align numbers or center a status column, then copy the Markdown. The same copy and paste works from Google Sheets, Numbers and LibreOffice Calc. If you prefer to edit cells after pasting, the [Markdown table generator](/markdown-table-generator) also accepts pasted tab-separated data and gives you a grid to work in. ## How do I convert a whole sheet saved as CSV? Save the sheet as CSV, then open the file in the converter. Microsoft's instructions for [saving a workbook as text or CSV](https://support.microsoft.com/en-us/office/save-a-workbook-to-text-format-txt-or-csv-3e9a9d6c-70da-4255-aa28-fcacf1f081e6) are: File > Save As (or Save a Copy), choose a location, and pick a CSV or text format in the file type list. Two things in that page matter here: - Every CSV and tab-delimited format "saves only the active sheet". A workbook with five sheets needs five saves, one per sheet, each giving one table. - "When you save a workbook in any of the text formats, all formatting will be removed." Colors, fonts, borders and number formats do not reach the CSV. Then use the converter's file button to open the `.csv` (it also accepts `.tsv` and `.txt`), or open the file in a text editor and paste its contents. Values with commas, quotes or line breaks are fine as long as they are quoted the standard way, which [RFC 4180](https://www.rfc-editor.org/rfc/rfc4180) describes: the field is enclosed in double quotes, and a quote inside it is doubled. The converter parses that format, so a quoted address such as `"12 High St, Leeds"` stays in one cell. If accented or non-Latin characters come out garbled, the CSV was saved in an encoding other than UTF-8. Copy and paste avoids the question entirely, because the clipboard carries text rather than a file. ## Can I convert an .xlsx file directly? Not in the browser converter; it reads delimited text, not Excel's file format. On the command line, recent [Pandoc](https://pandoc.org/MANUAL.html) releases list `xlsx` among their input formats, so this is worth trying: ```bash pandoc budget.xlsx -t gfm -o budget.md ``` Run `pandoc --list-input-formats` first; if `xlsx` is not listed, your version predates the reader. Check the output carefully, especially for workbooks with several sheets, merged cells or formulas, and fall back to the CSV route when it does not match what you see in Excel. ## What gets lost when Excel data becomes Markdown? More than people expect, because a Markdown table is only text in a grid: | In Excel | In the Markdown table | |---|---| | Cell values | Kept | | Formulas | Not kept; only a value can appear in a cell | | Number formats, colors, fonts, borders | Removed | | Merged cells | No equivalent; Markdown tables cannot merge cells | | Several sheets | One table per sheet, converted separately | | Charts, images, comments | Not converted | | Line breaks inside a cell | Written as `
` | | A pipe character in a value | Escaped with a backslash so it stays in its cell | Before converting, unmerge merged cells and fill in the repeated values, delete helper columns, and check that dates and numbers display the way you want them to read. The [Markdown table guide](/guides/markdown-table) explains why merged cells and multi-line cells have no Markdown syntax and what the HTML fallback looks like. ## How big a sheet can I turn into a Markdown table? There is no fixed limit in the syntax, but readability sets one. A Markdown table works well up to roughly the width of a page in columns and a few dozen rows; beyond that, the source becomes hard to edit and the rendered table needs horizontal scrolling on GitHub. For larger data, keep the CSV as the source file in the repository, link to it, and put a short summary table in the Markdown. GitHub also [renders `.csv` and `.tsv` files](https://docs.github.com/en/repositories/working-with-files/using-files/working-with-non-code-files#rendering-csv-and-tsv-data) as tables when you open them in the repository view, which is often enough on its own. ## Why do my columns come out shifted? Usually because of a delimiter mismatch. Auto-detect picks between comma, tab, semicolon and pipe from the first lines; if it guesses wrong (for example on a semicolon-separated file whose values contain commas), set the delimiter by hand. If one row has fewer cells than the header, the converter pads it with empty cells; check the source for a missing value or an unquoted comma in that row. When you paste a range, make sure the selection is a clean rectangle without hidden columns you did not intend to include. ## Can I go back from a Markdown table to Excel? Yes. Switch the converter to Markdown → CSV, paste the table, and download the result or copy it as tab-separated text to paste straight into a sheet. Escaped pipes become plain pipes and fields that need quoting are quoted. That round trip is also the easiest way to [sort a Markdown table](/markdown-table-generator/sort-markdown-table) or bulk-edit it. If the table's next stop is a Word document rather than a spreadsheet, see [turning a Markdown table into a Word table](/markdown-to-word/markdown-table-to-word-table). ## How do I convert a Google Sheet to a Markdown table? URL: https://docs-md.com/csv-to-markdown/google-sheets-to-markdown Updated: 2026-10-17 Select the cells in Google Sheets, copy them, and paste into a CSV-to-markdown converter. Sheets puts the selection on the clipboard as tab-separated text, which a converter turns into a pipe table with a header row. For a whole sheet, use File, Download, Comma-separated values, and convert the downloaded file instead. Google Sheets has no "export as Markdown" option. Google Docs gained one in 2024, but the spreadsheet download menu still offers formats such as Excel, OpenDocument, PDF, web page, CSV and TSV, so every route goes through one of those plain formats first. Below are three routes, from the quickest to the most repeatable, followed by the problems that usually show up in the output. ## Method 1: copy and paste a range This is the fastest way for a table you will paste into a README, an issue or a chat message once. 1. In Google Sheets, select the range you want, including the row of column titles. 2. Press Ctrl+C (Cmd+C on a Mac). 3. Open the [CSV to markdown converter](/csv-to-markdown) and paste into the input box. 4. Leave "First row is header" ticked if your selection included the titles. If it did not, untick it and the converter writes generic headers that you can rename. 5. Click a column chip to set left, center or right alignment if you need it, then copy the markdown. For a three-column selection the result looks like this: ```markdown | Region | Q1 | Q2 | | ------ | ------ | ------ | | North | 12,400 | 13,050 | | South | 9,870 | 10,210 | ``` The converter detects the tab delimiter on its own, so there is nothing to configure. Everything happens in your browser; the cells are not uploaded anywhere. If you want to tidy the result by hand afterwards, the [markdown table guide](/guides/markdown-table) covers the syntax, alignment colons and what renders where. ## Method 2: download the sheet as CSV Use this when the table is large, or when you want a file you can keep next to the markdown. 1. Open the spreadsheet and click the tab of the sheet you want. 2. Go to **File**, then **Download**, then **Comma-separated values (.csv)**. Google's help page on [downloading a copy of a file](https://support.google.com/docs/answer/49114) describes the same menu. 3. Open the downloaded file in a text editor, copy everything, and paste it into the converter. You can also convert it on the command line, which the [command-line guide](/csv-to-markdown/csv-to-markdown-command-line) covers with pandoc and Miller. The CSV download contains one sheet: the one that was active when you downloaded. A spreadsheet with five tabs needs five downloads. CSV keeps quoting for cells that contain commas, quotes or line breaks, which is why it is safer than copy and paste for messy text columns: a cell holding `Smith, John` stays one cell. ## Method 3: fetch it automatically If the table changes and you regenerate the markdown often, skip the manual download. Two documented options exist. **Publish to web as CSV.** In the sheet, choose **File**, **Share**, **Publish to web**, pick the sheet and the CSV format, and publish. Google's [publishing help page](https://support.google.com/docs/answer/183965) explains the dialog and how to stop publishing later. You get a URL that always returns the current data, which you can pipe into a converter: ```bash curl -sL "PASTE-THE-PUBLISHED-CSV-URL" | pandoc -f csv -t gfm ``` Be careful: a published sheet is readable by anyone who has the link, and your organization's admin may have turned publishing off. Do not publish anything private. **The Drive API.** A script with access to the file can call the Drive API's export method with the `text/csv` MIME type. Google's [table of export formats](https://developers.google.com/workspace/drive/api/guides/ref-export-formats) notes that CSV and TSV exports through the API contain the first sheet only, so put the table you need on the first tab or use the Sheets API to read a specific range instead. ## Why do my numbers look different in the markdown? What you copy is the text the sheet displays, so formatting decides the output. A cell formatted as currency may arrive as `$1,250.00` rather than `1250`, and a percentage as `12%`. If you want raw numbers, change the column format to plain number before copying, or add a helper column. Formulas never come through as formulas; you get their current results. ## What happens to merged cells? Markdown tables have no colspan or rowspan, so a merged cell cannot survive. When you copy or export, the value usually lands in the first cell of the merged area and the others come out empty. Unmerge the cells in Sheets and decide what each cell should say before converting, or switch to an HTML table if the merge really matters. The [table guide](/guides/markdown-table) explains the limits of the syntax. ## How do I keep line breaks inside a cell? A markdown table row has to sit on one source line, so a cell with a line break (Alt+Enter or Ctrl+Enter in Sheets) cannot be written as-is. The converter replaces each line break inside a cell with a `
` tag, which GitHub and most renderers display as a new line. The [line break in a table cell guide](/guides/markdown-table-line-break) lists the alternatives and which renderers accept them. ## What if a cell contains a pipe character? A literal `|` would split the cell in two. The converter escapes it as `\|`, which GitHub displays as a plain pipe. If you build the table by hand, the [escape characters guide](/guides/markdown-escape-characters) shows the same fix, and its caveat about pipes inside inline code. ## Can I convert the markdown table back into Google Sheets? Yes. Switch the converter to the markdown-to-CSV direction, paste the table, and copy the CSV. Pasting CSV text into Sheets puts it all in column A; use **Data**, **Split text to columns** to break it on commas, or save it as a `.csv` file and import it with **File**, **Import**. Alignment and bold formatting in the markdown are not carried over, because CSV has no place for them. ## Does the same method work for Excel? Yes. Excel also puts a copied range on the clipboard as tab-separated text, so the paste route is identical. Saving as CSV from Excel has one trap: in regions that use a comma as the decimal separator, Excel can write semicolons between fields instead of commas. The converter's delimiter detection handles that, but command-line tools need to be told, for example with Miller's `--ifs ';'` option. ## Which method should I use? Copy and paste for a one-off table under a few hundred rows. Download as CSV when the sheet has commas or line breaks in text cells, or when you want to keep the source file. Publish or use the API only when you regenerate the same table often and the data is safe to expose to the script or the link. In every case, check the first few rows of the output against the sheet: headers, number formatting and empty cells are where problems show up. --- # JSON to markdown table converter URL: https://docs-md.com/json-to-markdown-table Category: Convert Updated: 2026-10-15 Paste a JSON array or object and get a markdown table — nested keys flattened to dot paths, pipes escaped, columns reorderable — or turn a table back into JSON. --- # Markdown to Slack converter URL: https://docs-md.com/markdown-to-slack Category: Convert Updated: 2026-10-15 Turn standard markdown into Slack mrkdwn — *bold*, _italic_, links, headings as bold lines, tables as code grids — with a list of what was approximated. --- # Markdown to Discord converter URL: https://docs-md.com/markdown-to-discord Category: Convert Updated: 2026-10-15 Turn standard markdown into Discord markdown — headings to ###, masked links, code blocks with languages, tables as code grids — with every approximation listed. --- # Markdown to Jira converter URL: https://docs-md.com/markdown-to-jira Category: Convert Updated: 2026-10-15 Turn standard markdown into Jira wiki markup — h1. headings, *bold*, {code:lang} blocks, ||header|| tables, [text|url] links, ** nested lists — ready for issue fields. --- # Markdown to plain text converter URL: https://docs-md.com/markdown-to-plain-text Category: Convert Updated: 2026-10-15 Strip every markdown marker and keep the words, lists, code and paragraph structure — links optionally kept as "text (url)". For email, SMS, and form fields. --- # Markdown table generator URL: https://docs-md.com/markdown-table-generator Category: Generate Updated: 2026-09-01 Build tables in a visual grid — set column alignment, paste CSV/TSV from a spreadsheet, and copy clean padded markdown. ## Can a Markdown table cell contain a list or an image? URL: https://docs-md.com/markdown-table-generator/markdown-table-cell-lists-images Updated: 2026-10-17 An image, yes. A real list, no. In GitHub Flavored Markdown a table cell holds inline content only, and an image is inline, so `![alt](url)` works in a cell. A list is a block element, so `- item` stays literal text. Fake a list with `•` and `
`, or use HTML or a different layout. The rule behind both answers is short. A pipe table is one line per row, and each cell is the text between two pipes on that line. The [GFM specification](https://github.github.com/gfm/#tables-extension-) says the cells contain text "in which inlines are parsed" and that "block-level elements cannot be inserted in a table". Inline means anything that can sit inside a sentence: emphasis, links, inline code, images, line breaks written as HTML. Block means anything that needs lines of its own: paragraphs, lists, fenced code, quotes, headings. ## Which content can go in a Markdown table cell? Here is the practical split for GitHub, GitLab and most renderers that follow GFM: | Content | In a pipe-table cell? | How | |---|---|---| | Bold, italic, strikethrough | Yes | `**bold**`, `*italic*`, `~~old~~` | | Links | Yes | `[docs](https://example.com)` | | Inline code | Yes | `` `npm test` `` (escape any pipe inside with a backslash) | | Images | Yes | `![logo](logo.png)` | | Line breaks | Yes, as HTML | `first
second` | | Bulleted or numbered list | No, as Markdown | Fake it with `•` and `
`, or use HTML | | Fenced code block | No | Inline code, or put the block under the table | | Several paragraphs | No | `

` gives the look, not the structure | The details of line breaks, bullet workarounds and code in cells are in [line breaks in a Markdown table cell](/guides/markdown-table-line-break). The rest of this page is about choosing between those workarounds and keeping images readable. ## How do I put an image in a table cell? Type the normal image syntax into the cell: ```markdown | Status | Meaning | |---|---| | ![passing](img/passing.svg) | All checks green | | ![failing](img/failing.svg) | At least one check failed | ``` Images in cells follow the same rules as images anywhere else, which the [image syntax guide](/guides/markdown-image) covers in full. Three points matter more inside a table: - **Size.** Markdown image syntax has no width, and a large image stretches the column. On GitHub, use an HTML tag with a width instead: ` Settings screen

`. Keep the tag on the same line as the rest of the row. - **Alt text.** In a table, the alt text often stands in for a whole cell when the image does not load or a screen reader reads the row. Write what the image means, not what file it is. - **Pipes in URLs.** A literal `|` in an image URL ends the cell. Percent-encode it as `%7C`. ## What is the most reliable way to fake a list in a cell? Use a bullet character and `
` between items: `• Fast
• Free
• Offline`. It is plain text plus one HTML tag, so it renders wherever `
` is allowed and degrades to a single readable line where it is not. Writing `- item` with `
` looks similar in the source, but the hyphens show as hyphens and some editors escape them. For a numbered list, type the numbers: `1. Install
2. Configure`. This is the right choice when a few cells need two to four short items. The source stays readable, the table still works in a plain text editor, and the [table generator](/markdown-table-generator) handles it: type the items into a cell with `
` between them and the generated Markdown keeps them on one line, with any pipes escaped for you. ## When should I use an HTML table instead? When the cells need real structure: proper `

` code block, or merged cells. GitHub and GitLab render HTML tables, and inside `

` you can use list tags. The costs are a much longer source, Markdown syntax that GitHub does not parse inside the HTML, and a table that disappears in renderers that strip HTML. The [Markdown table guide](/guides/markdown-table) shows where HTML tables render and where they do not. If you write for Pandoc rather than GitHub, there is a third option. Pandoc's [grid tables](https://pandoc.org/MANUAL.html#extension-grid_tables) draw the borders with `+`, `-` and `|`, and their cells "may contain arbitrary block elements (multiple paragraphs, code blocks, lists, etc.)": ```markdown +-----------+--------------------+ | Plan | Includes | +===========+====================+ | Basic | - 1 project | | | - Email support | +-----------+--------------------+ ``` GitHub does not render grid tables, so use them only for documents that Pandoc converts, such as Word or PDF output. ## Should the content be a table at all? Often not. If most cells need a list, the data is usually a list of items with details, and a table squeezes it. Two alternatives read better: - **Headings with lists under them.** One heading per row of the would-be table, then the list. Long content gets room, and every item can link to its own anchor. - **A narrow table plus details below.** Keep the table to short comparable values (name, status, version) and move the long text into sections under it. A good test: if you need `
` in more than a third of the cells, change the layout. Tables work best when every cell is a short value a reader compares across rows. ## Can I put a checkbox or task list in a table cell? Not as an interactive task list. GitHub's `- [ ]` syntax is a list item, so it has the same problem as any other list: inside a pipe-table cell it stays literal text and nothing becomes clickable. For a status column, use characters that read correctly as text, such as `☐` and `☑`, or words like Done and Open, which also sort and search better. If the checkboxes need to be ticked on GitHub, put the task list under the table, one item per row, and reference it from the table. ## Do images and lists in cells survive conversion to Word or PDF? Images do, when the converter can reach the file. Inline formatting and `
` line breaks also come through with converters that parse the Markdown first. HTML tables convert as tables in tools that render HTML, and Pandoc grid tables become Word tables with real lists in the cells. Faked lists stay faked: the `•` characters convert as text. For the full Word workflow see [turning a Markdown table into a Word table](/markdown-to-word/markdown-table-to-word-table). ## Why does my list in a table cell show as dashes? Because the list marker is not parsed inside a pipe-table cell, so `- item` is the literal text "- item". Nothing is broken; the syntax does not apply there. Replace the hyphens with `•` and join the items with `
`, or move the list out of the table. ## Should I give an LLM a Markdown table or CSV? URL: https://docs-md.com/markdown-table-generator/markdown-table-vs-csv-for-llm Updated: 2026-10-17 For small tables that a person will also read, a Markdown table is a sound default: every cell boundary is marked and the table renders in chat interfaces. For larger data, CSV is more compact and usually the better choice. Either way, test on your own data, because no format is right for every model and task. Both formats carry the same information: rows, columns and a header. The differences are in how many tokens they cost, how they handle awkward values such as commas and line breaks, and how readable they are to the person checking the prompt and the answer. None of these differences is large for a ten-row table. They start to matter when the table is hundreds of rows long or when the values are messy. ## How many more tokens does a Markdown table use than CSV? It depends on the data and the tokenizer, but Markdown always adds characters: pipes between and around cells, spaces, and a delimiter row. As one measured example, here is the same seven-row, four-column table in three forms, counted with OpenAI's [tiktoken](https://github.com/openai/tiktoken) library and its `o200k_base` encoding: | Format | Characters | Tokens (o200k_base) | |---|---|---| | CSV | 139 | 61 | | Markdown table, compact (`\| a \| b \|`) | 235 | 96 | | Markdown table, padded to align columns | 311 | 120 | The table was: ```text Region,Quarter,Revenue,Units North,Q1,12400,310 North,Q2,13150,322 South,Q1,9800,255 South,Q2,10275,268 West,Q1,15020,401 West,Q2,14790,389 ``` Treat the ratio as an illustration, not a constant. Other models use other tokenizers, longer text values dilute the overhead of the pipes, and short numeric values like these show it at its largest. The useful conclusion is narrower: padding spaces cost tokens and add nothing for a model, so if you send Markdown, send it compact. Count with your own provider's tokenizer before you decide on cost grounds. ## When is a Markdown table the better choice? When the table is small to medium, and a person will read the prompt or the answer. A few reasons: - **Explicit boundaries.** Every cell is enclosed in pipes, including empty ones, so `| North | | 310 |` shows clearly that the middle value is missing. - **Rendering.** Chat interfaces that render Markdown show the table as a table, which makes it easy to check that the model saw what you meant to send. - **Matching output.** If you want a table back, giving one in the same format shows the shape you expect. - **Mixed documents.** A table inside a Markdown document (a spec, a README, meeting notes) can stay as it is, with headings and prose around it. The [Markdown table generator](/markdown-table-generator) builds a correctly escaped table in compact or padded form, and the [CSV to Markdown converter](/csv-to-markdown) turns existing CSV into one, with a Pad columns option you can switch off to save tokens. ## When is CSV the better choice? When the table is large, when cost or context length is the constraint, or when the data already exists as CSV and converting it adds a step where things can go wrong. CSV has a published convention for awkward values: [RFC 4180](https://www.rfc-editor.org/rfc/rfc4180) says fields containing commas, double quotes or line breaks are enclosed in double quotes, and a double quote inside such a field is doubled. A cell with a comma or a multi-line address is therefore unambiguous in well-formed CSV. Markdown tables have no equivalent for line breaks. A cell must stay on one line, so line breaks become `
` and every pipe inside a value must be escaped as `\|`. That is fine for a handful of cells and fragile for messy text exports. If your values contain many commas, a tab-separated file avoids most quoting. ## What goes wrong with either format? The same handful of problems show up in prompts regardless of format: - **Unlabelled columns.** A header like `q2_adj_v3` means nothing to a model. Rename columns to plain words, and add units: `Revenue (USD)`. - **Inconsistent values.** Dates in two formats, numbers with and without thousands separators, `N/A` next to empty cells. Clean them before sending; the model will otherwise guess. - **Broken rows.** An unescaped pipe in Markdown or an unquoted comma in CSV shifts every following value one column to the right. Check the row count and column count after conversion. - **Too many columns.** Very wide rows make it hard to keep a value attached to its header at the far end of a long row. Drop columns the task does not need. ## When should I use neither? When the data is large enough that the model does not need to read every row, or when the answer requires exact arithmetic. Pasting thousands of rows into a prompt to ask for a total or an average asks the model to do in its head what a few lines of code do exactly. If your setup offers file upload with code execution or a database tool, give it the file and ask for the computation. Paste a table only when the model needs to read and reason over the rows themselves: compare a few options, spot an outlier, write a summary. For nested or record-like data, a third shape is often clearer than either: one JSON object per row, or `key: value` lines per record. Each value then carries its own label, at the cost of repeating the keys. The [JSON to Markdown table converter](/json-to-markdown-table) goes the other way when you need a table for a person. ## Does sorting or ordering the rows matter? It can help. If the question is about the largest values or a date range, sort the rows by that column first so the relevant rows are together, and say in the prompt how the table is ordered. See [how to sort a Markdown table](/markdown-table-generator/sort-markdown-table) for ways to do it without retyping. ## What should the prompt say around the table? Say what the table is, where it came from, what each row represents, and any column whose meaning is not obvious. Put the instruction before or after the table rather than in the middle, and state the output format you want. Those few sentences usually matter more than the choice between pipes and commas. The [Markdown table guide](/guides/markdown-table) covers the syntax rules if you write the table by hand. ## How do I sort a Markdown table? URL: https://docs-md.com/markdown-table-generator/sort-markdown-table Updated: 2026-10-17 Markdown has no sort feature: rows appear in the order they are written. To sort, reorder the lines. The simplest way is a round trip: convert the table to CSV, sort it in a spreadsheet, and convert it back. On the command line, `sort` with `|` as the field separator works, as long as you keep the header out of it. A pipe table is just lines of text. The renderer does not reorder anything, and GitHub Flavored Markdown has no attribute for a sort column or a default order. Sorting is something you do to the source before you commit or publish it. The methods below go from the most forgiving (any data, any platform) to the fastest (one command, clean data only). ## How do I sort a Markdown table with a spreadsheet? This works for any table and handles text, numbers and dates the way a spreadsheet does. 1. Paste the table into the [CSV to Markdown converter](/csv-to-markdown) and switch the direction to Markdown → CSV. Choose Tab as the output delimiter; it pastes most cleanly into a spreadsheet. 2. Copy the output and paste it into Excel, Google Sheets, Numbers or LibreOffice Calc. Escaped pipes (`\|`) come out as plain `|` characters, and the header lands in the first row. 3. Select the data, use the spreadsheet's sort command with "data has header row" turned on, and pick the column and direction. 4. Copy the sorted range, including the header, and paste it back into the CSV to Markdown converter in the normal direction. It detects the tab separator and rebuilds the table. Column alignment is not carried through CSV, so set it again in the converter (click a column's alignment control) if your table had right-aligned numbers. This round trip is also the moment to fix anything else: rename a header, delete a column, or correct a value. If your data started in a spreadsheet, see [converting an Excel sheet to a Markdown table](/csv-to-markdown/excel-to-markdown-table). ## How do I sort a Markdown table on the command line? Keep the first two lines (header and delimiter row) as they are and sort the rest with pipes as the field separator. The [GNU sort manual](https://www.gnu.org/software/coreutils/manual/html_node/sort-invocation.html) documents `-t` for the separator and `-k` for the key: ```bash (head -n 2 table.md; tail -n +3 table.md | sort -t '|' -k 2,2) > sorted.md ``` The field numbers are one higher than you might expect. A row like `| axios | 105000 |` starts with a pipe, so field 1 is the empty text before it, field 2 is the first column, field 3 the second, and so on. Common variations: ```bash # second column, numeric, largest first (head -n 2 table.md; tail -n +3 table.md | sort -t '|' -k 3,3 -n -r) # third column, ignoring upper and lower case (head -n 2 table.md; tail -n +3 table.md | sort -t '|' -k 4,4 -f) ``` `-n` compares numbers by value instead of character by character, so `9800` comes before `10275`. `-r` reverses the order and `-f` treats `b` and `B` as equal. If the order of letters looks wrong, it is the locale: the manual notes that sort follows your `LC_COLLATE` setting, and suggests setting `LC_ALL=C` for plain byte order, for example `LC_ALL=C sort -t '|' -k 2,2`. ## When does the command-line method break? When a cell contains an escaped pipe. `sort` does not know Markdown, so `\|` inside a cell counts as a field separator, the rest of that row shifts one field to the right, and the row is sorted on the wrong value. It also breaks on tables that span several sections or have blank lines, and on numbers with currency symbols, units or a leading `+`, which the manual says `-n` does not recognise (thousands separators depend on the locale's `LC_NUMERIC` setting). For any of those, use the spreadsheet round trip, which parses the table properly. The table itself is never damaged by a wrong sort; only the order is. Still, write to a new file (`> sorted.md`) and compare before you replace the original. ## How do I sort by two columns? In a spreadsheet, add a second level in the sort dialog: for example Language first, then Stars within each language. On the command line, give `sort` more than one key. The manual says it compares the keys in the order they appear on the command line, so the second key only decides between rows that tie on the first: ```bash (head -n 2 table.md; tail -n +3 table.md | sort -t '|' -k 4,4 -k 3,3nr) ``` Here the letters after a key (`n` for numeric, `r` for reverse) apply to that key alone, so the table is sorted by the third column alphabetically and, within each group, by the second column from largest to smallest. ## Can the Markdown table generator sort rows? No. The [Markdown table generator](/markdown-table-generator) builds and edits tables: cells, alignment, adding and removing rows and columns, and pasting CSV or TSV data. It does not sort or reorder rows. To sort a table you are building there, sort the data before pasting it in with Paste CSV / TSV, or finish the table, then sort it with one of the methods above. The generator's paste splits on tabs or commas without reading quotes, so for data with commas inside values, paste tab-separated text. ## Should I sort in a text editor? Many code editors have a command to sort selected lines alphabetically, and that works for a quick sort on the first column: select the data rows only (not the header or the delimiter row) and run it. It compares whole lines as text, so it effectively sorts by the first column and cannot sort numbers by value. For any other column, or for numbers, use a spreadsheet or `sort -k`. ## How do I keep a table sorted as it grows? Pick a rule and write it down where contributors will see it, for example in a comment above the table: ``. HTML comments are not rendered, so the note stays in the source only; the [comment guide](/guides/markdown-comment) covers the syntax. Alphabetical order by the first column is the easiest rule to keep, because new rows can be inserted by eye without any tool. For tables generated from data, such as a list of releases or benchmark results, sort in the script that writes the table rather than by hand. ## What order should a table be in? The order a reader needs. Alphabetical suits reference lists that people scan for a name. Descending by a metric suits rankings and comparisons. Chronological suits changelogs and timelines; decide once whether newest goes first. If you hand the table to an AI assistant, say in the prompt how it is sorted, as covered in [Markdown table or CSV for an LLM](/markdown-table-generator/markdown-table-vs-csv-for-llm). The [Markdown table guide](/guides/markdown-table) covers the rest of the syntax. --- # GitHub README and docs viewer URL: https://docs-md.com/github-readme-viewer Category: Edit & share Updated: 2026-10-13 Paste a repository URL and read its README and docs folder as a clean, linked site — relative links and images resolved, no cloning. ## How do I format a README.md? URL: https://docs-md.com/github-readme-viewer/how-to-format-readme-md Updated: 2026-10-17 Format a README.md with GitHub Flavored Markdown: `#` headings for sections, a blank line between paragraphs, fenced code blocks with a language name for commands, `-` for lists, pipes for tables, and relative paths for images and links to other files. GitHub renders the file on the repository's front page, so check the rendered result before you commit. This page is about the formatting itself. What a README should contain (sections, order, length) is covered in [What is a README file?](/readme-generator/what-is-a-readme-file). Here, the question is how to write each part so it renders the way you expect on GitHub, which runs its own variant of markdown and its own cleanup step on the result. ## What markdown syntax does a README use? Ordinary markdown plus the GitHub Flavored Markdown (GFM) extensions: tables, task lists, strikethrough and autolinks. These are the elements almost every README uses: | Element | Syntax | Notes | |---|---|---| | Title | `# Project name` | One H1 at the top | | Section | `## Installation` | H2 for sections, H3 for subsections | | Bold, italic | `**bold**`, `_italic_` | | | Inline code | `` `npm install` `` | For names, flags, file paths | | Code block | three backticks plus a language | See the next section | | Bulleted list | `- item` | Indent two spaces to nest | | Numbered list | `1. step` | Good for setup steps | | Link | `[docs](docs/setup.md)` | Relative paths for repo files | | Image | `![alt text](docs/screenshot.png)` | Alt text is required in practice | | Table | `\| a \| b \|` rows with a `\|---\|---\|` divider | GFM extension | | Task list | `- [ ] todo`, `- [x] done` | GFM extension | Use headings in order without skipping levels, because GitHub builds the file's outline menu and the anchor for every section link from them. The [headings guide](/guides/markdown-headings) covers the syntax and common mistakes. ## How should I format code and commands in a README? Put every command and code sample in a fenced code block with a language name after the opening backticks, so GitHub applies syntax highlighting: ````markdown ```bash npm install my-package ``` ```js import { convert } from 'my-package'; console.log(convert('# Hello')); ``` ```` Keep one command per line and leave out the shell prompt (`$`), so readers can copy the block and run it. Use inline backticks for short names in a sentence, such as `--verbose` or `config.json`. The [code block guide](/guides/markdown-code-block) lists the language names and how to show backticks inside a block. ## Why does my README put two lines on one line? Because a single line break inside a paragraph is ignored in `.md` files. GitHub's docs point out that issues and comments show a line break where you press Enter, but a README does not ([GitHub Docs, line breaks](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#line-breaks)). To force a break inside a paragraph, end the line with two spaces, a backslash (`\`), or `
`. To start a new paragraph, leave a blank line. The backslash is the easiest to see when you read the source, so it is the safest choice; the [new line guide](/guides/markdown-new-line) compares all three. ## How do I add images, badges and links to other files? Use paths relative to the README for anything inside the repository. GitHub's docs say it rewrites relative links and image paths "based on whatever branch you're currently on, so that the link or path always works", that paths starting with `/` resolve from the repository root, and that `./` and `../` work as usual ([GitHub Docs, relative links](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes#relative-links-and-image-paths-in-markdown-files)). ```markdown ![Screenshot of the dashboard](docs/images/dashboard.png) See the [contribution guide](CONTRIBUTING.md) before opening a pull request. ``` Badges are images wrapped in links and usually sit in one line under the title. Keep the link text of any link on a single line; GitHub notes that link text split across lines does not work. Resizing, captions and dark-mode variants need HTML, which the [image guide](/guides/markdown-image) explains. If an image does not appear after you push, the [README images guide](/github-readme-viewer/readme-images-not-showing) goes through the causes. ## How do I add notes and warnings to a README? Use GitHub's alert syntax, a blockquote whose first line is a type in brackets: ```markdown > [!WARNING] > Version 2 changes the config file format. Read the migration notes first. ``` GitHub supports five types: `NOTE`, `TIP`, `IMPORTANT`, `WARNING` and `CAUTION`. Its docs advise using alerts only when they are crucial and limiting them to one or two per article, and say alerts cannot be nested inside other elements. Other sites that display your README may show an alert as a plain quote with `[!WARNING]` in it; the [alerts guide](/guides/markdown-alerts) covers where they render and a portable alternative. ## What HTML can I use in a README on GitHub? A limited set. GitHub converts the markdown and then sanitizes the HTML, "aggressively removing things that could harm you", including `script` tags, inline styles, and `class` or `id` attributes ([github/markup](https://github.com/github/markup#readme)). In practice that leaves layout to a few tags and attributes. When we sent a test file to GitHub's markdown rendering API on 2026-10-17, these survived: `align="center"` on a `

`, `width` on an ``, `

` and `

`, ``, `_{` and `` with a dark-mode ``. A `style` attribute was removed, a `` tag was dropped (its text kept), and an `id` was rewritten with a `user-content-` prefix. So `` is the usual way to center a logo, colored text cannot be done with HTML, and collapsible sections work with ` `. To hide a note from the rendered page, use an HTML comment, ``. The [collapsible section guide](/guides/markdown-collapsible-section) shows the blank lines `` needs for markdown inside it to render. ## Is there a size limit for a README on GitHub? Yes. GitHub's docs say that when a README is viewed on GitHub, "any content beyond 500 KiB will be truncated". Very few READMEs come close, but generated ones (API references, long changelogs, embedded tables of data) can. Move long material to a `docs/` folder and link to it. GitHub also recognizes a README in the `.github` or `docs` folder, and picks `.github` first, then the root, then `docs` if there is more than one. ## How do I check the formatting before I commit? Preview it. GitHub's file editor has a **Preview** tab, editors such as VS Code have a side-by-side preview, and once the file is pushed to a public repository you can read it in the [GitHub README viewer](/github-readme-viewer), which shows the README with the repository's other docs and resolves its relative links and images. Each method has gaps compared with GitHub's own rendering; the [README preview guide](/github-readme-viewer/preview-readme-before-push) compares them. ## How do I preview a README before pushing to GitHub? URL: https://docs-md.com/github-readme-viewer/preview-readme-before-push Updated: 2026-10-17 Open the README in your editor's markdown preview for quick checks, paste it into the Preview tab of GitHub's file editor to see GitHub's own rendering without committing, or push it to a separate branch and read it there before merging. Only the branch method shows images and relative links exactly as they will appear on the repository page. The reason there is no single perfect answer is that GitHub renders a README with its own pipeline: GitHub Flavored Markdown, then a sanitizing step, then GitHub-specific features such as alerts and rewritten relative links. Any preview outside GitHub reproduces some of that, not all of it. The useful question is which differences matter for your file. The table summarizes the trade-offs before the details. | Method | Uses GitHub's renderer | Unpushed images show | Needs a push | |---|---|---|---| | VS Code preview | No (CommonMark, markdown-it) | Yes, from disk | No | | GitHub editor Preview tab | Yes | No | No | | A separate branch | Yes | Yes, once pushed | Yes, not to main | | GitHub markdown API | Yes, with gaps | No | No | ## How do I preview a README in VS Code? Open the file and press Ctrl+Shift+V (Cmd+Shift+V on macOS) to switch to the preview, or Ctrl+K V (Cmd+K V) to open it beside the source, where it updates as you type ([VS Code docs, Markdown preview](https://code.visualstudio.com/docs/languages/markdown#_markdown-preview)). Images load from your disk, so screenshots you have not committed yet appear, and scrolling stays in sync between the two panes. Know the gap. The VS Code docs state that it targets the CommonMark specification using the markdown-it library, not GitHub Flavored Markdown. In practice, check GitHub-only features such as [alerts](/guides/markdown-alerts) on GitHub itself. The preview also blocks scripts and, under its default "Strict" security setting, images served over plain `http`. Other editors and IDEs have similar previews with similar limits. ## How do I use GitHub's Preview tab without committing? Open any markdown file in the repository on GitHub, click the pencil icon to edit it, paste your new README text into the editor, and click **Preview** above the content ([GitHub Docs, editing files](https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files)). This is GitHub's own renderer, so headings, tables, task lists, alerts and allowed HTML look as they will on the repository page. When you are done, cancel the edit instead of clicking **Commit changes**, and nothing is saved. Two limits. Images and files that exist only on your computer are missing, because GitHub cannot see them yet. And pasting into a browser editor is fine for checking the text but easy to get wrong for a long file, so treat it as a check, not the place you edit. Pressing `.` on a repository page opens github.dev, a web version of VS Code, but its markdown preview is VS Code's, with the same gap described above. ## Why push the README to a branch first? Because a branch is the only preview that is exactly what readers will see. Create a branch, commit the README and its images, push, and open the branch on GitHub. GitHub's docs say relative links and image paths are rewritten "based on whatever branch you're currently on, so that the link or path always works", so images in the branch resolve to the branch's files ([GitHub Docs, About READMEs](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes#relative-links-and-image-paths-in-markdown-files)). ```bash git switch -c readme-update git add README.md docs/images/ git commit -m "Rewrite README" git push -u origin readme-update ``` If you open a pull request from the branch, GitHub can show the change as a rendered "rich diff" of the markdown, with added and removed text highlighted, which makes review easier ([GitHub Docs, prose diffs](https://docs.github.com/en/repositories/working-with-files/using-files/working-with-non-code-files#rendering-differences-in-prose-documents)). For a public repository you can also read the branch in the [GitHub README viewer](/github-readme-viewer) at an address like `docs-md.com/gh/owner/repo?ref=readme-update`, which shows the README together with the other markdown files in the repo and its `docs/` folder. The viewer does not read private repositories. Merge when it looks right. ## Can I render a README with GitHub's API? Yes. GitHub's REST API has a `POST /markdown` endpoint that returns the HTML for any markdown you send ([GitHub Docs, Markdown API](https://docs.github.com/en/rest/markdown/markdown)). It works without a token for public use, within the unauthenticated limit of 60 requests per hour: ```bash jq -Rs '{text: ., mode: "markdown"}' README.md \ | curl -s -X POST https://api.github.com/markdown -d @- > preview.html ``` Open `preview.html` in a browser to see the output, unstyled. In our tests on 2026-10-17 the endpoint did not match a repository README exactly. In `markdown` mode it left task lists and alerts as plain text. In `gfm` mode it rendered them but treated every single line break as a break, the way GitHub comments do, which READMEs do not. Relative image paths came back unchanged, so repository images do not load. The API is useful for scripts and checks in CI, less so as a visual preview. ## Which preview should I use for a quick check? For most edits, the editor preview while you write, then one look at the branch or the Preview tab before you merge. If you only need to confirm the syntax of a single file, paste it into the [markdown viewer](/markdown-viewer), which renders GitHub Flavored Markdown in the browser without uploading anything. When you drop a local file in, only that file is read, so its relative images will not load; check those on GitHub. ## What usually looks different after the README is pushed? The same handful of things, so check them first in any preview: - **Line breaks.** A single newline does not break a line in a README; use a blank line, a trailing backslash or ` `. - **Images.** Paths are case-sensitive on GitHub and relative to the README's folder; see [why README images are not showing](/github-readme-viewer/readme-images-not-showing). - **HTML.** GitHub strips `style` attributes and scripts, so styled HTML that looked fine locally can lose its styling. - **Alerts and task lists.** Non-GitHub previews may show them as plain quotes or bracketed text. - **Mermaid and math.** VS Code's preview renders both, and GitHub documents support for [Mermaid diagrams](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams) and math in markdown files, but the two use separate renderers, so look at diagrams on GitHub too. The [README formatting guide](/github-readme-viewer/how-to-format-readme-md) covers the syntax for each of these. ## Does the README preview show the same thing on npm or PyPI? No. GitHub's preview shows GitHub's rendering, and package registries render the README with their own rules. Relative image paths are the usual casualty, because they are rewritten by GitHub but not necessarily by other sites. If the README will also be shown on a registry, use full image URLs that point at the raw file, as the [image guide](/guides/markdown-image) explains, and check the package page after publishing. ## Why are my README images not showing on GitHub? URL: https://docs-md.com/github-readme-viewer/readme-images-not-showing Updated: 2026-10-17 Usually the image is not on GitHub at the path the README gives: it was never committed or pushed, the letter case differs, or the relative path starts from the wrong folder. Less often, an external host blocks GitHub's image proxy. Open the image path on GitHub directly; a 404 there means a path problem. The syntax itself is rarely the issue, since `![alt text](path/to/image.png)` is hard to get wrong; the [image guide](/guides/markdown-image) covers it, along with resizing and dark-mode variants. This page is the GitHub-specific checklist, roughly in order of how often each cause turns out to be the answer. ## Is the image file actually in the repository? Check this first, because it is the most common cause. An image that shows in your local preview is being read from your disk. GitHub can only show files that were committed and pushed to the branch you are looking at. Run these from the repository root: ```bash git ls-files docs/images/ # tracked files in that folder git status --short docs/images/ # untracked or changed files git check-ignore -v docs/images/screenshot.png # is a .gitignore rule hiding it? ``` If `git ls-files` does not list the image, it was never committed. If `git check-ignore` prints a line, a `.gitignore` pattern (often a broad one like `*.png` or `docs/`) is excluding the file, and it names the rule. Commit the file, push, and reload the README. Also make sure you are viewing the branch you pushed to; the repository page shows the default branch. ## Could the letter case of the file name be wrong? Yes, and it is the cause that is hardest to spot, because the image works on your computer. Paths on GitHub are case-sensitive: in our check, a raw file URL ending in `README.md` returned 200 and the same URL ending in `readme.md` returned 404. Common file systems on macOS and Windows are not case-sensitive, a fact Git's own documentation notes when it lists APFS, HFS+, FAT and NTFS ([git-config, core.ignoreCase](https://git-scm.com/docs/git-config#Documentation/git-config.txt-coreignoreCase)). So `![Logo](images/Logo.png)` finds `images/logo.png` locally and fails on GitHub. Compare the path in the README with the output of `git ls-files`, letter by letter, including folder names. Renaming only the case of a file needs `git mv` (for example `git mv images/Logo.png images/logo.png`) so that Git records the change on a case-insensitive disk. ## Is the relative path starting from the right folder? A relative image path is resolved from the folder of the markdown file, not from the repository root. GitHub's docs describe the rules: paths are "relative to the current file", links starting with `/` are relative to the repository root, and `./` and `../` work as usual ([GitHub Docs, relative links and image paths](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes#relative-links-and-image-paths-in-markdown-files)). | README location | Image location | Path that works | |---|---|---| | `README.md` | `docs/img/a.png` | `docs/img/a.png` or `/docs/img/a.png` | | `docs/README.md` | `docs/img/a.png` | `img/a.png` | | `docs/README.md` | `assets/a.png` | `../assets/a.png` or `/assets/a.png` | | `.github/README.md` | `assets/a.png` | `../assets/a.png` or `/assets/a.png` | The last row catches people out: GitHub shows a README from the `.github` folder on the repository's front page, but relative paths still start from `.github/`. A path starting with `/` avoids the question, at the cost of not working in some other renderers. ## Does the file name contain spaces or special characters? A space ends the image destination, so `![Diagram](docs/my diagram.png)` is not read as an image at all and shows up as text. Either rename the file (the simplest fix), write the space as `%20`, or wrap the path in angle brackets, which CommonMark allows for destinations that contain spaces ([CommonMark spec, link destination](https://spec.commonmark.org/0.31.2/#link-destination)): ```markdown ![Diagram](docs/my%20diagram.png) ![Diagram]() ``` Parentheses, `#` and `?` in file names cause similar trouble because they have meaning in a URL. Lower-case names with hyphens avoid all of it. ## Why does an image from another website not load? GitHub does not load external images directly in your reader's browser. It sends them through an image proxy called Camo, which fetches the image and serves it from a `githubusercontent.com` address ([GitHub Docs, About anonymized URLs](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/about-anonymized-urls)). That causes three kinds of failure: 1. **The host requires a login or is on a private network.** GitHub's docs say such an image "can't be viewed by GitHub" and advise moving it to a publicly available service. 2. **The server sends an unexpected content type.** Check with `curl -I https://example.com/image.png` and look at `Content-Type`; Camo only proxies the image types on its list. 3. **The image changed but GitHub shows the old one.** Camo caches images. The docs suggest serving them with `Cache-Control: no-cache` and describe how to purge one cached URL with `curl -X PURGE` as a last resort. Hosts that refuse requests from other sites (hotlink protection) or delete files after a while also break images over time. Storing images in the repository and using relative paths avoids these problems entirely. ## Why do the images show on GitHub but not on npm or another site? Because GitHub rewrites relative image paths for its own pages, and other sites that display your README may not. GitHub's docs say it transforms relative paths "based on whatever branch you're currently on"; a package registry or documentation site reading the same file has no such rule, so `docs/img/a.png` points nowhere. If the README is published elsewhere, use full URLs to the raw file, as the [image guide](/guides/markdown-image) shows. Images stored in a private repository fail there as well, since outside readers have no access to them; even on GitHub, its docs note that relative links to images in a private repository work only for viewers with at least read access. ## How can I check every image link at once? For a public repository, open it in the [GitHub README viewer](/github-readme-viewer), which renders the README with the repository's relative images resolved; any image that is broken there is very likely broken on GitHub too, and the viewer links back to the file on GitHub. To list broken links and images in a markdown file, run it through the [markdown link checker](/markdown-link-checker). Before you push, the [README preview guide](/github-readme-viewer/preview-readme-before-push) explains which previews show unpushed images and which do not. ## Can a long README hide images? Yes, at the very end. GitHub's docs say that when a README is viewed on GitHub, "any content beyond 500 KiB will be truncated", so images referenced after that point are not shown. Only very long READMEs reach that size; if yours does, move reference material into a `docs/` folder and link to it. --- # README generator URL: https://docs-md.com/readme-generator Category: Generate Updated: 2026-09-01 Fill in a form, get a professional README.md with live badges, install and usage sections, and a live preview. ## How do I open a README.md file? URL: https://docs-md.com/readme-generator/how-to-open-readme-md Updated: 2026-10-17 Open it with any text editor, because a README.md is plain text: Notepad on Windows, TextEdit on macOS, or any editor on Linux. You will see the markdown symbols as typed. To see it formatted, with real headings, lists and links, open it in a markdown viewer, in VS Code's preview, or on the project's GitHub page. The `.md` extension means markdown, a way of writing formatting with ordinary characters: `#` before a heading, `*` around emphasis, `-` at the start of a list item. It was designed to read well even unformatted, so the raw file is usable. Nothing in it is executable or needs a special program, and opening it in a text editor is safe. The question is only whether you want to see the symbols or the formatted result. If you are not sure what the file is for, [what a README file is](/readme-generator/what-is-a-readme-file) explains the convention. ## How do I open a README.md file on Windows? Right-click the file, choose **Open with**, and pick **Notepad**. If Windows asks how you want to open the file, choose Notepad and, if you like, tick the option to always use it for `.md` files. Any code editor you already have, such as VS Code or Notepad++, also works. Double-clicking may do nothing useful if no program is associated with `.md`, which is why the right-click route is more reliable the first time. ## How do I open a README.md file on a Mac? Control-click the file, choose **Open With**, and pick **TextEdit**. TextEdit shows the raw markdown. If it opens the file in rich-text mode or the characters look wrong, it is still the same text; nothing is lost. For a formatted view, use one of the viewers below. ## How do I open a README.md file on Linux or in a terminal? Any editor opens it (gedit, Kate, nano, vim). On Linux and macOS, these print the raw text or page through it in a terminal: ```bash cat README.md less README.md ``` On Windows, `type README.md` does the same in Command Prompt and `Get-Content README.md` in PowerShell. For a formatted view inside the terminal, [Glow](https://github.com/charmbracelet/glow) renders markdown with styled headings, lists and code. Its README lists installs such as `brew install glow` and `winget install charmbracelet.glow`, and then: ```bash glow README.md ``` ## How do I see a README.md formatted instead of as raw text? You have four options, from no installation to most control: 1. **In your browser.** Open the [markdown viewer](/markdown-viewer), click **Open .md file** (or drop the file on the panel, or paste its text), and it renders the file with headings, tables, code highlighting and Mermaid diagrams. You can also paste a raw or GitHub file URL to load it. 2. **On GitHub or GitLab.** If the README belongs to a repository, the project's front page already shows it formatted. GitHub's [README documentation](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes) says it looks for the file in the `.github` folder, the root and the `docs` folder, in that order, and also adds an outline menu built from the headings. To read a repository's README and its docs folder as formatted pages, paste the repository URL into the [GitHub README viewer](/github-readme-viewer). 3. **In VS Code.** Open the file and press Ctrl+Shift+V (Cmd+Shift+V on macOS) to switch to the preview, or Ctrl+K V (Cmd+K V) to open the preview beside the text, per the [VS Code documentation](https://code.visualstudio.com/docs/languages/markdown). 4. **As an HTML file.** With Pandoc installed, convert it and open the result in any browser: ```bash pandoc -s README.md -o README.html ``` ## Why does my README look different in different places? Because "markdown" covers several dialects. GitHub uses GitHub Flavored Markdown, which adds tables, task lists, strikethrough and alerts; a basic viewer may show those as plain text. Relative links and images such as `![logo](docs/logo.png)` only work where the viewer can see the rest of the repository, so they break when you open a single downloaded file in a browser tool. HTML inside the file is shown, stripped or escaped depending on the viewer. If something looks broken in one place, check it on the code host where the project lives, since that is what the author tested against. ## Can I edit a README.md file? Yes, in the same text editor you opened it with. Save it as plain text with the `.md` extension, not as `.rtf` or `.docx`; TextEdit in particular may try to save rich text, so use **Format > Make Plain Text** first if it offers. Keep the markdown symbols intact, and preview the result before you commit it. If you are writing one from scratch, the [README generator](/readme-generator) fills in a standard layout from a form, shows a live preview and downloads a ready `README.md`; [headings](/guides/markdown-headings) and the other syntax guides cover the formatting by hand. ## What if the file is called README without .md, or README.rst? `README` with no extension and `README.txt` are plain text; open them exactly the same way. `README.rst` is reStructuredText, a different markup language common in older Python projects: it is also readable as plain text, and GitHub renders it formatted, but markdown viewers will not interpret its syntax. `README.adoc` is AsciiDoc, which likewise reads fine raw. On the command line, Pandoc can convert reStructuredText to HTML in the same way as markdown. ## Is it safe to open a README.md file? Yes. A markdown file is text and cannot run anything when you open it, in a text editor or in a viewer. The care needed is with what it tells you to do. A README often contains install commands and links, and those are only as trustworthy as the project. Before pasting a command such as `curl ... | sh` from the README of a project you do not know, read what it downloads and where from. Links in a rendered README can point anywhere, exactly like links on a web page, so check the address before you follow one that asks for a login. ## Why won't my README.md open on my phone? Phones often have no app associated with `.md` files. The simplest fix is to open the repository page in your phone's browser, where the README is shown formatted. If you have only the file, a text-editor app opens it as plain text, or you can open the browser-based markdown viewer and choose the file from your device. Large READMEs with wide tables are easier to read in landscape. ## What is a README file? URL: https://docs-md.com/readme-generator/what-is-a-readme-file Updated: 2026-10-17 A README file is a plain-text introduction to a project, kept in its top folder. It tells a newcomer what the project is, why it exists, how to install and run it, and where to find help. Today it is usually `README.md`, written in markdown, and code hosts like GitHub show it on the project's front page. The name is literal: it is the file you are meant to read first. The convention is decades older than GitHub. Software distributed on tapes, floppy disks and FTP servers shipped with a file called `README` so that whoever unpacked the archive had an obvious starting point, and the GNU coding standards still ask every package to include one with a general overview. What changed is where people read it. A README used to be opened in a terminal after downloading; now it is the landing page of a repository, a package page on npm or PyPI, and often the first thing an AI coding assistant reads when it is pointed at a codebase. ## What does a README file do? A README answers the questions a stranger has in the first minute: what is this, is it for me, and how do I start? Everything else in a project (the source, the tests, the full documentation) assumes the reader already decided to engage. The README is where that decision is made. In practice it does four jobs: - **Orientation.** One or two sentences that say what the project does and for whom. If a reader cannot tell from the opening whether this solves their problem, the rest of the file does not get read. - **Getting started.** The shortest path from nothing to a working result: requirements, the install command, and one example of real use. - **Navigation.** Links to the places the README does not cover in depth, such as full documentation, the changelog, the issue tracker and the contribution guide. - **Terms.** The license, and for many projects the support status (maintained, experimental, archived) so nobody builds on something that is abandoned. A README is not a manual. Its job is to get someone to the second step, not to answer every question they will ever have. ## What should a README contain? There is no required structure, but most good READMEs share the same skeleton, in roughly this order: 1. **Project name and a one-line description.** Plain language, no slogans. 2. **Badges (optional).** Build status, latest version, license. Useful when they are live; noise when they are not. 3. **What it does and why.** A short paragraph, sometimes a screenshot or a diagram. 4. **Installation.** Exact commands in a code block, plus prerequisites such as the runtime version. 5. **Usage.** The smallest example that does something real, with its output if that helps. 6. **Configuration.** Only the options most people need; link to the rest. 7. **Contributing.** How to report a bug, run the tests and open a pull request, or a link to `CONTRIBUTING.md`. 8. **License.** The license name and a link to the `LICENSE` file. Commands and example code belong in fenced code blocks with a language tag so they get syntax highlighting; the [code block guide](/guides/markdown-code-block) covers the syntax. Long READMEs benefit from a table of contents near the top, which the [markdown TOC generator](/markdown-toc-generator) can build from your headings. Which sections matter depends on the project. A library needs an installation command and an API example. An application needs a screenshot and a download link. A dataset needs its source, its schema and its license more than any install step. A course or a notes repository may need nothing more than what it is and how it is organised. If you would rather fill in a form than start from a blank file, the [README generator](/readme-generator) produces this skeleton with a live preview, and the [README templates](/readme-templates) page has copyable starting points for libraries, apps, CLIs and data projects. ## Where does a README file go? Put it in the root folder of the project, next to the code it describes. That is where people look and where tools look. GitHub also recognises a README in a `.github` or `docs` folder and shows it on the repository's front page, and a README inside any subfolder is displayed when someone browses into that folder, which is a handy way to explain what a directory is for. Package registries read the same file. npm includes the README in the published package and displays it on the package page; Python projects usually point their packaging metadata at the README so PyPI shows it as the project description. Writing one good README therefore covers the repository and the package listing at once. ## What format should a README be in? Markdown, in a file named `README.md`, unless your ecosystem has a different habit. Markdown reads cleanly as raw text in a terminal and renders as formatted headings, lists, tables and links on every major code host. Other formats you will meet: | File | Format | Where it is common | |---|---|---| | `README.md` | Markdown | GitHub, GitLab, npm, most new projects | | `README.rst` | reStructuredText | Older Python projects, Sphinx-based docs | | `README.txt` or `README` | Plain text | Older Unix software, archives, some C projects | | `README.adoc` | AsciiDoc | Some Java and documentation-heavy projects | The uppercase name is a convention, not a rule. One commonly cited reason for it is that in a plain ASCII sort, capital letters come before lowercase ones, so `README` floats to the top of a directory listing on systems that sort that way. Code hosts match the name case-insensitively, but `README.md` is what everyone expects to see. Use [headings](/guides/markdown-headings) to structure it, because many renderers turn them into anchor links and an outline. ## How do you open a README.md file? A `.md` file is plain text, so any text editor opens it: Notepad, TextEdit, VS Code, vim. You will see the markdown symbols (`#` for headings, `*` for emphasis) rather than formatting, which is still readable by design. To see it rendered, open the repository on GitHub or GitLab, use the preview in an editor such as VS Code (the preview command opens it side by side), or paste a repository URL into the [GitHub README viewer](/github-readme-viewer) to read its README and docs folder as formatted pages. ## Is a README the same as documentation? It is the front door of the documentation, not the whole house. Small projects can fit everything they need in the README. Once a project has many options, several audiences or a long API, the README should stay short and link out to a documentation site or a `docs/` folder. A useful test: if a section is something only an existing user would look up, it probably belongs in the full docs rather than the README. Other conventional files take some load off it as well. `CONTRIBUTING.md` holds the contribution process, `CHANGELOG.md` the release history, `LICENSE` the legal text, `CODE_OF_CONDUCT.md` the community rules and `SECURITY.md` how to report vulnerabilities. GitHub links several of these automatically from the repository page, so the README only needs a line pointing to each. ## How long should a README be? As long as it takes to get a new reader to a first working result, and no longer. For a small library that might be a screen and a half. Signs a README has grown too long: the install command is far below the fold, sections repeat what the full docs say, or the changelog lives inside it. Signs it is too short: no example of real use, no install instructions, or no indication of what the project actually does. Keep it current, because an outdated README with commands that no longer work does more harm than a brief one. ## What should a README contain? URL: https://docs-md.com/readme-generator/what-should-a-readme-contain Updated: 2026-10-17 A README should contain the project's name and a one-line description, what it does and who it is for, how to install it, a short usage example, how to get help or contribute, and the license. Those six parts answer a newcomer's first questions. Everything else, such as badges, screenshots and configuration, is optional and depends on the project. GitHub's own [documentation on READMEs](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes) puts it as five questions: what the project does, why it is useful, how users can get started, where they can get help, and who maintains and contributes to it. The same page adds that a README should hold only what people need to start using and contributing, with longer documentation kept elsewhere. If you are new to the file itself, start with [what a README file is](/readme-generator/what-is-a-readme-file); this page goes section by section. ## What is the minimum a README needs? A title, one sentence saying what the project does, an install command and one example of use. A reader who gets those four things can decide whether the project fits and try it within a minute. A license line is the fifth item for anything public, because without a license other people have no clear permission to use the code. Everything beyond that is there to save the reader time, not to fill space. ```markdown # csvtrim Removes empty rows and trailing spaces from CSV files. ## Install pip install csvtrim ## Usage csvtrim input.csv -o clean.csv ## License MIT ``` ## What goes in each section? Here is what good looks like in each common section, in the order most READMEs use: - **Title and one-liner.** The project name as the only H1, then a plain sentence: "Removes empty rows and trailing spaces from CSV files." Not "a blazing-fast next-generation data tool." Say what it does, not how you feel about it. - **Badges.** Optional. Build status, latest version and license are the useful ones, because they answer real questions (does it build, is it current, can I use it). The [badge generator](/markdown-badge-generator) writes the markdown for shields.io badges. Remove badges that point at services you no longer use. - **Description.** Two to four sentences: the problem, who has it, and how this project handles it. A screenshot or a short animated capture belongs here for anything with a user interface. - **Installation.** Prerequisites first (runtime version, system packages), then the exact command in a fenced code block that can be copied as it is. If there are several ways to install, give the most common one first. - **Usage.** The smallest example that does something real, ideally with its output. Use realistic names, not `foo` and `bar`, so the example also shows what the project is for. - **Configuration.** Only the options most people change, in a short table of name, default and meaning. Link to the full list. - **Documentation and help.** Where the full docs live, where to ask questions, and where to report bugs. - **Contributing.** How to set up a development copy, run the tests and open a pull request, or a link to `CONTRIBUTING.md`. - **License.** The license name and a link to the `LICENSE` file. ## How does a README change by project type? The core stays the same, but the weight shifts: | Project type | Put first | Usually needs | Usually skip | |---|---|---|---| | Library | Install command, API example | Supported versions, link to API docs | Screenshots | | Command-line tool | Install, one command with output | Common flags, exit codes if scripted | Long API reference | | Web or desktop app | Screenshot, download or live link | System requirements, how to build from source | Package badges | | Dataset | Source, schema, size | License and citation, how it was collected | Install steps | | Internal service | Owner, how to run locally | Environment variables, deploy process, on-call contact | Marketing description | A team's internal repository needs different answers from an open-source one: who owns it, how to run it, and what breaks if it goes down matter more than badges. ## What should a README leave out? Leave out anything that has a better home. The full API reference belongs in documentation, release history in `CHANGELOG.md`, the contribution process in `CONTRIBUTING.md`, and vulnerability reporting in `SECURITY.md`. Leave out secrets, internal hostnames and real credentials, including in examples. Leave out instructions you have not tested, since a wrong install command costs more trust than a missing one. Also leave out walls of badges, long tables of contributors' avatars and sections that only say "coming soon". On GitHub there is a practical limit too: the README documentation says content beyond 500 KiB is truncated when the file is viewed on the site. Few READMEs come close, but generated tables and embedded data can. ## How long should each section be? Short enough that the install command is visible without much scrolling. The opening (title, one-liner, description) should fit in the first screen. Installation and usage are best at a few lines each. If any section needs subheadings of its own, it is probably documentation and should move to a `docs/` folder or a wiki with a link from the README. Long READMEs are easier to use with a table of contents; GitHub already shows an outline menu built from your headings, and the [TOC generator](/markdown-toc-generator) adds one inside the file for other sites and for raw text readers. ## How do I write a README quickly? Fill in the [README generator](/readme-generator): it has fields for the name, tagline, description, features, install command, a usage example with its language, the license and author, optional badges from an npm package name or GitHub repository, and an optional contributing section. It shows a live preview and lets you copy or download `README.md`. It produces a solid general-purpose skeleton, not a finished file: it has no fields for screenshots, configuration tables or dataset details, so add those by hand. The [README templates](/readme-templates) page has longer starting points for specific project types. ## Is there an official README standard? No. There is no required format or section list; GitHub, GitLab and package registries display whatever the file contains. What exists are conventions: the file name `README.md`, markdown formatting, the section order above, and community files such as `LICENSE` and `CONTRIBUTING.md` that code hosts link to automatically. Some ecosystems add expectations of their own, for example registries that show the README as the package description, so the opening sentence doubles as the package summary. ## How do I know if my README is good enough? Hand it to someone who has never seen the project and watch them. If they can say what it does after the first paragraph and reach a working result using only the README, it is good enough. Any question they have to ask you is a missing sentence. Repeat the test after big changes, and run the install and usage commands yourself before each release so they do not drift out of date. --- # Agent handoff document generator (HANDOFF.md) URL: https://docs-md.com/handoff-generator Category: Generate Updated: 2026-10-15 Fill in goal, state, commands, key files, decisions and next steps; get a complete HANDOFF.md for the next developer or AI coding agent, with a live preview. --- # Table of contents generator URL: https://docs-md.com/markdown-toc-generator Category: Generate Updated: 2026-08-29 Paste a document, get a linked TOC with GitHub-exact anchor slugs — choose depth, insert it under your title. ## How do I add a table of contents to a GitHub README? URL: https://docs-md.com/markdown-toc-generator/github-readme-table-of-contents Updated: 2026-10-17 Add a nested bullet list near the top of the README in which every item links to a heading's anchor, for example `#installation` for the Installation section. GitHub gives every heading an anchor automatically, so you only write the list. GitHub's own generated outline sits in a menu, not in the page. Here is what a finished table of contents looks like in the markdown source, placed under the project title: ```markdown # my-project A command-line tool that converts logs to CSV. ## Table of contents - [Installation](#installation) - [Usage](#usage) - [Options](#options) - [Examples](#examples) - [Contributing](#contributing) - [License](#license) ## Installation ... ``` Each link target is the heading text turned into a slug: lower case, spaces replaced by hyphens, punctuation removed. Indent child items by two spaces (or to line up under the parent's text) so that H3 headings nest under their H2. ## Does GitHub generate a table of contents automatically? Yes, but not inside the file. For any rendered markdown file in a repository, including READMEs, GitHub builds a table of contents from the headings and shows it behind the "Outline" icon in the top corner of the file view ([GitHub Docs, About READMEs](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes#auto-generated-table-of-contents-for-markdown-files)). You do not have to write anything to get it. Its limits are that a reader has to find and open the menu, and it exists only in GitHub's interface, so it does not travel with the file to package registries, documentation sites, or a clone opened in an editor. A written TOC appears wherever the markdown is rendered. ## How do I build the list without typing every anchor? Paste the README into the [markdown TOC generator](/markdown-toc-generator). It reads the headings, creates the anchors with the same slug rules GitHub uses, and gives you a list you can copy or insert under the H1. You can limit the depth (H2 and H3 is usually enough for a README), choose a numbered or bulleted list, and leave the H1 out so the project name does not link to itself. The tool runs in the browser and does not upload the file. If you prefer to write it by hand, GitHub documents the rules it uses to turn a heading into an anchor ([section links](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#section-links)): - Letters are converted to lower case. - Spaces become hyphens; other whitespace and punctuation are removed. - Leading and trailing whitespace is removed. - Markup is removed, so `_italics_` becomes `italics`. - A heading whose anchor matches an earlier one gets `-1`, `-2` and so on appended. So `## What's new in v2?` links as `#whats-new-in-v2`, and a second `## Examples` heading links as `#examples-1`. Non-English letters are kept rather than removed; GitHub's own example turns a heading ending in "Θ!" into an anchor ending in `-θ`. The [anchor link guide](/guides/markdown-anchor-link) covers the edge cases (emoji, dots in version numbers, links into other files) in more detail. ## Where should the table of contents go in a README? Directly after the title and the one- or two-sentence description, before the first real section. Readers decide in the first screen whether the project is for them, so the description should stay above the TOC rather than be pushed down by it. A heading such as `## Table of contents` or `## Contents` above the list makes it easy to find and gives it its own anchor, which you can use for "back to top" links in very long files. Only add one if the README needs it. A file with four short sections scrolls faster than it can be navigated, and the TOC becomes noise. A practical threshold is when the README runs past two or three screens or has more than five or six H2 sections. ## Why do some links in my README table of contents not work? Almost always because the anchor no longer matches the heading. Common causes: 1. **The heading was renamed.** GitHub notes that if you edit a heading, links to it must be updated too, because the anchor changes. 2. **Punctuation was kept in the link.** `#what's-new` does not match; the apostrophe is dropped, so it is `#whats-new`. 3. **Capital letters.** `#Installation` may appear to work in some places but the generated anchor is `#installation`; use lower case. 4. **A duplicate heading.** The second `## Examples` is `#examples-1`, not `#examples`. 5. **The link text spans two lines.** GitHub's docs say link text should be on a single line, or the link breaks. To check every link at once, open the repository in the [GitHub README viewer](/github-readme-viewer) or run the [markdown link checker](/markdown-link-checker) on the file. Regenerating the list from the current headings with the TOC generator is usually faster than hunting for the one stale link. ## Can I hide a heading from the table of contents? In a hand-written or generated list, simply delete that item; nothing links to a heading unless you write the link. GitHub's automatic Outline is different: it lists every heading and cannot be configured from the file. If you need a jump target that is not a heading, GitHub supports a custom HTML anchor such as ``, and its docs note that custom anchors are not included in the document outline. Keep these to a minimum, since a plain [heading](/guides/markdown-headings) is easier to maintain. ## How do I keep the table of contents up to date? The list is plain text, so it does not update itself when headings change. Three habits keep it accurate. Regenerate it whenever you add, remove or rename an H2 or H3 rather than editing single lines. Keep headings short and free of punctuation that matters, so anchors stay stable across edits. And if you edit the README in VS Code, an editor extension can rewrite the TOC on save; the [VS Code TOC guide](/markdown-toc-generator/vs-code-markdown-toc) explains how and what to configure so its anchors match GitHub's. ## Should the TOC be a numbered or bulleted list? Bulleted is the usual choice and the safer one, because adding a section does not renumber the list. A numbered list makes sense when the README is a sequence, such as setup steps that must happen in order. Either way, nesting uses the same indentation rules as any other list; the [nested list guide](/guides/markdown-nested-list) shows how far to indent child items so they render as a sub-list instead of a paragraph. ## How do I make a table of contents in Obsidian? URL: https://docs-md.com/markdown-toc-generator/obsidian-table-of-contents Updated: 2026-10-17 Obsidian has no built-in command that writes a table of contents into a note. For navigation, use the Outline core plugin, which lists the note's headings in a side panel. For a TOC inside the note, write a list of heading links in the form `[[#Heading name]]`, or install a community plugin that generates and updates one for you. Which one you want depends on who the TOC is for. If it is only for you while you work in the note, the Outline panel is enough and needs no upkeep. If the note will be read by others, exported, or published somewhere else, a list written into the note travels with the file. The sections below cover each route and the formats that keep working outside Obsidian. ## How do I use the Outline panel as a table of contents? Outline is a core plugin that "lists the headings in the active note" ([Obsidian Help, Outline](https://obsidian.md/help/plugins/outline)). Click a heading in the panel to jump to that section. You can also drag a heading within the outline to move the whole section, which makes it a quick way to reorder a long note. If you do not see the Outline panel, open **Settings → Core plugins** and make sure Outline is turned on; Obsidian's help notes that some core plugins are disabled by default. The outline updates as you type, and it reflects heading levels as nesting, so a clean heading hierarchy (H2 sections, H3 subsections, no skipped levels) gives you a clean outline. The [headings guide](/guides/markdown-headings) explains the levels and the syntax. The limit is that Outline is part of the app's interface, not of the note. It does not appear in the note's text, in an export, or on another device that opens the file in a different editor. ## How do I write a table of contents inside a note? Write a bulleted list of internal links to the note's own headings. In Obsidian, a link to a heading in the same note is `[[#` followed by the heading text ([Obsidian Help, Internal links](https://obsidian.md/help/links#Link%20to%20a%20heading%20in%20a%20note)): ```markdown ## Contents - [[#Goals]] - [[#Plan]] - [[#Plan#Timeline|Timeline]] - [[#Plan#Budget|Budget]] - [[#Open questions]] ``` You do not need to type the heading names exactly. Type `[[#` and Obsidian shows a list of the headings in the current note; pick one and it completes the link. The help page also documents linking to a subheading by chaining hashes, as in `[[#Plan#Timeline]]`, and changing the visible text with a vertical bar, as in `[[#Plan#Timeline|Timeline]]`, which keeps the list readable. Indent child items under their parent with a tab or spaces, as you would for any [nested list](/guides/markdown-nested-list). Unlike GitHub, Obsidian does not turn headings into slugs. A link to a heading uses the heading's own text. If you rename a heading, Obsidian can update links to it automatically; that behavior is controlled by **Settings → Files and links → Automatically update internal links**, according to the same help page. ## Can I get a table of contents that updates itself in Obsidian? Yes, with a community plugin. Several are listed in Obsidian's community plugin directory; one of them, Automatic Table Of Contents, renders a TOC from a code block and refreshes it when the note changes ([plugin README](https://github.com/johansatge/obsidian-automatic-table-of-contents)): ````markdown ```table-of-contents title: **Contents** minLevel: 2 maxLevel: 3 ``` ```` Options include `style` (`nestedList`, `nestedOrderedList` or `inlineFirstLevel`), `minLevel` and `maxLevel` for heading depth, and `include` and `exclude` patterns. To install any community plugin, open **Settings → Community plugins**, turn off Restricted mode, then browse, install and enable the plugin ([Obsidian Help, Community plugins](https://obsidian.md/help/community-plugins)). Be clear about the trade-off. The plugin's README says the TOC "doesn't generate real Markdown in the document", so it "won't be visible when exporting, or on Obsidian Publish", and links might not work in PDFs. Outside Obsidian the code block is shown as a plain code block. Community plugins are also third-party code, which is why Obsidian keeps them off until you turn off Restricted mode. ## How do I make an Obsidian TOC that also works on GitHub? Use standard markdown links with GitHub-style anchors instead of wikilinks. GitHub does not understand `[[#Heading]]` and will show it as plain text, so a note that will also live in a repository needs links like `[Open questions](#open-questions)`. You can generate that list by pasting the note into the [markdown TOC generator](/markdown-toc-generator), which builds anchors with GitHub's rules. Check the result inside Obsidian as well. Obsidian's documented markdown form for heading links uses the heading text, for example `[Section name](Example.md#Details)`, with spaces written as `%20`, while GitHub uses lower-case slugs with hyphens. A TOC built for one may not navigate in the other, so test the links in both places before relying on them. The [anchor link guide](/guides/markdown-anchor-link) compares how GitHub, Obsidian and other platforms form heading anchors, and the [GitHub README TOC guide](/markdown-toc-generator/github-readme-table-of-contents) covers placement on GitHub. ## Should I switch Obsidian to markdown links instead of wikilinks? Only if the notes need to be read outside Obsidian. Obsidian's help explains that it creates wikilinks by default because they are more compact, and that you can switch by turning off **Use [[Wikilinks]]** under **Settings → Files and links**. After that, typing `[[` still opens the suggestion list, but Obsidian inserts a markdown link instead. That makes new links more portable, but it does not convert links you already wrote, and wikilinks remain easier to type and read. The [Obsidian markdown reference](/obsidian-markdown) lists the other syntax that only Obsidian understands. ## Why is my Obsidian table of contents link not working? The heading text in the link no longer matches the note. Common reasons are a heading that was edited by hand while automatic link updates were off, a typo or different spacing in the link, or a heading that contains characters Obsidian warns against in links, such as `#`, `|`, `^`, `:` or `[[ ]]`. Retyping the link with `[[#` and choosing the heading from the suggestion list is the quickest fix. For TOCs built with GitHub-style slugs, the cause is usually the anchor format, as described above. ## Is a written table of contents worth it for short notes? Usually not. A note with three or four sections is faster to scroll than to navigate, and the Outline panel already covers it with no upkeep. A written list earns its place in long reference notes, notes that other people read, and notes you export or publish, where the Outline panel is not available. ## How do I generate a Markdown table of contents in VS Code? URL: https://docs-md.com/markdown-toc-generator/vs-code-markdown-toc Updated: 2026-10-17 VS Code cannot generate a table of contents on its own: its built-in Markdown support shows an outline of your headings but never writes one into the file. Install the Markdown All in One extension and run "Create Table of Contents" from the Command Palette, or paste the file into a browser TOC generator. The difference matters because the two things look similar. VS Code's Outline view, at the bottom of the Explorer sidebar, shows "the Markdown file's header hierarchy" so you can jump around while editing ([VS Code docs, Markdown](https://code.visualstudio.com/docs/languages/markdown#_document-outline)). That outline lives in the editor. Readers of the rendered file on GitHub or elsewhere never see it. A table of contents is markdown text inside the file: a list of links to each heading's anchor. ## How do I create a TOC with Markdown All in One? Install the extension, open the markdown file, and run its command. Step by step: 1. Open the Extensions view, search for **Markdown All in One** (identifier `yzhang.markdown-all-in-one`) and install it. 2. Put the cursor where the table of contents should go, usually on a blank line under the H1 title. 3. Open the Command Palette (Ctrl+Shift+P on Windows and Linux, Cmd+Shift+P on macOS) and run **Markdown All in One: Create Table of Contents**. The extension inserts a nested list of links. By default it updates that list every time you save the file, so renamed or added headings are picked up without another command; turn this off with the `markdown.extension.toc.updateOnSave` setting. There is also an **Update Table of Contents** command for manual control. These commands and settings are documented in the extension's README ([Markdown All in One](https://github.com/yzhang-gh/vscode-markdown#table-of-contents)). ## Which settings control the generated TOC? All of them are under `markdown.extension.toc` in `settings.json`. The ones most people change: | Setting | Default | What it does | |---|---|---| | `markdown.extension.toc.levels` | `1..6` | Which heading levels are included; `2..3` suits most READMEs | | `markdown.extension.toc.slugifyMode` | `github` | How anchors are built: `github`, `gitlab`, `gitea` or `vscode` | | `markdown.extension.toc.orderedList` | `false` | Numbered list instead of bullets | | `markdown.extension.toc.unorderedList.marker` | `-` | Bullet character: `-`, `*` or `+` | | `markdown.extension.toc.updateOnSave` | `true` | Rewrite the TOC on every save | | `markdown.extension.toc.omittedFromToc` | `{}` | Headings to leave out, per file | ```json { "markdown.extension.toc.levels": "2..3", "markdown.extension.toc.slugifyMode": "github" } ``` Set `slugifyMode` to match where the file will be read. The anchor rules differ slightly between platforms, and a TOC built with the wrong rules has links that work in one place and not in another. The [anchor link guide](/guides/markdown-anchor-link) lists how GitHub, GitLab and others turn headings into anchors. ## How do I leave a heading out of the TOC in VS Code? Add the comment `` at the end of the heading line (or on the line above it), and Markdown All in One skips that heading. You can also narrow the levels with `markdown.extension.toc.levels`, or list headings to skip for a given file in `markdown.extension.toc.omittedFromToc`. If the extension mistakes an ordinary list of links for a table of contents and starts rewriting it, its README says to put `` above that list. Both comments are invisible in the rendered output on GitHub, as explained in the [markdown comment guide](/guides/markdown-comment). ## Can I write a TOC in VS Code without an extension? Yes, by hand with the help of built-in link completions. In a markdown file, type `[Installation](#` and VS Code suggests every heading in the current file; picking one inserts its anchor. Typing `##` inside a link's target suggests headings from all markdown files in the workspace and inserts the full path, such as `docs/setup.md#requirements` (controlled by `markdown.suggest.paths.includeWorkspaceHeaderCompletions`). This works well for a short TOC, but you have to edit it yourself whenever a heading changes. A faster route without installing anything is to copy the file into the [markdown TOC generator](/markdown-toc-generator), choose the depth and list style, and paste the result back. It builds anchors with GitHub's rules and runs in the browser, so nothing is uploaded. The trade-off is that it is a one-off copy: the TOC will not update on save. ## How do I check that the TOC links work? Open the preview and click through them. **Markdown: Open Preview to the Side** (Ctrl+K V, or Cmd+K V on macOS) shows the rendered file next to the source; **Markdown: Open Preview** toggles to it with Ctrl+Shift+V or Cmd+Shift+V. For a check that does not involve clicking, turn on link validation with `"markdown.validate.enabled": true`. VS Code then reports links to headers that do not exist in the current file and in other markdown files. The docs note that it checks local links only, not external URLs. One caveat: the VS Code preview is not GitHub. Its docs say it targets CommonMark using the markdown-it library rather than GitHub Flavored Markdown, so a link that works in the preview can still fail on GitHub if the anchor rules differ. If GitHub is the destination, keep `slugifyMode` on `github` and do a final check there, or in the [GitHub README viewer](/github-readme-viewer) once the file is pushed. ## Why did my TOC links break after renaming a heading? Because the anchor is derived from the heading text, so a new heading means a new anchor. If Markdown All in One updates the TOC on save, the list is fixed for you, but links to that heading elsewhere in the file or in other files are not. VS Code's built-in **Rename Symbol** command helps here: run it on a heading and, according to the VS Code docs, it "updates the header and automatically updates all links to that header" across the workspace. Use it instead of retyping the heading when other files link to the section. ## Does the TOC work the same on GitHub? Yes, if the anchors were built with GitHub's rules, which is the extension's default. GitHub also offers its own generated outline from a menu on every rendered markdown file, so a README there has two kinds of navigation. The [GitHub README TOC guide](/markdown-toc-generator/github-readme-table-of-contents) explains when the written list is still worth having and where to place it. --- # Link, image & code block generator URL: https://docs-md.com/markdown-link-generator Category: Generate Updated: 2026-08-29 Fill in a form, get correct markdown for links (with tooltips and reference style), sized images, and fenced code. --- # Markdown badge generator URL: https://docs-md.com/markdown-badge-generator Category: Generate Updated: 2026-09-03 Design shields.io badges with a live preview — label, message, color, style, logo — and copy them as markdown, HTML, or reStructuredText. --- # Changelog generator URL: https://docs-md.com/changelog-generator Category: Generate Updated: 2026-09-03 Build a CHANGELOG.md in Keep a Changelog format — or paste your git log and let conventional commits sort themselves into Added, Fixed, and Changed. --- # Front matter generator URL: https://docs-md.com/front-matter-generator Category: Generate Updated: 2026-09-03 Generate valid YAML, TOML, or JSON front matter for Jekyll, Hugo, Astro, Docusaurus, or Obsidian — dates, tags, slugs, and custom fields, escaped correctly. --- # Markdown linter URL: https://docs-md.com/markdown-lint Category: Check & compare Updated: 2026-09-03 Find heading, list, spacing, and link problems in a document — every finding explained, most of them fixable with one click. --- # Markdown diff checker URL: https://docs-md.com/markdown-diff Category: Check & compare Updated: 2026-09-03 Compare two versions of a document side by side or as a unified patch, with word-level highlights inside changed lines. --- # Markdown link checker URL: https://docs-md.com/markdown-link-checker Category: Check & compare Updated: 2026-09-03 Extract every link from a document and check it — dead pages, redirects, and broken #anchors — with the line each one is on. --- # Markdown word counter URL: https://docs-md.com/markdown-word-counter Category: Check & compare Updated: 2026-09-03 Word, character, sentence, and paragraph counts that ignore markdown syntax and code — plus reading time and heading, link, and image totals. --- # Markdown viewer URL: https://docs-md.com/markdown-viewer Category: Edit & share Updated: 2026-10-05 Open a .md file — drag it in, paste, or load from a URL — and read it rendered with tables, code highlighting, and mermaid diagrams. Print or share it. ## What is the difference between a markdown reader and a markdown editor? URL: https://docs-md.com/markdown-viewer/md-file-reader-vs-editor Updated: 2026-10-20 A markdown reader, also called a viewer, opens a .md file and shows it formatted so you can read it. A markdown editor is for writing and changing the file, usually with a live preview next to the source. Readers need no setup. Editors add saving, file management and writing aids. Many tools do a bit of both. The two words get mixed up because most editors include a preview and many viewers let you type. The useful question is what you are doing with the file. If someone sent you a README, release notes or a document exported from an AI chat and you want to read it, you need a reader. If you maintain the file, you need an editor. ## What does a markdown reader do? It turns markdown source into a formatted document and gets out of the way. A good reader renders headings, lists, tables, links, images, code blocks with syntax highlighting, and the extensions people actually use, such as task lists, footnotes and Mermaid diagrams. It offers reading comforts: a table of contents or outline, adjustable type size, a print layout. It does not need to save anything. Browser-based readers like the [markdown viewer](/markdown-viewer) open a file you drop in, render it locally, and are done; there is nothing to install or configure. Quick Look extensions on macOS and browser extensions that render `.md` links are readers too. ## What does a markdown editor do? It is where you write. An editor saves the file, manages folders of files, and helps with the writing itself: shortcuts that insert bold or link syntax, auto-continuing lists, spell checking, search across files. Most show a preview, either side by side with the source (VS Code, many code editors) or blended into one view where the symbols disappear as you type (Typora, and Obsidian's live preview mode). Some add structure on top of markdown, such as links between notes, tags or publishing to a website. VS Code's [built-in preview](/markdown-viewer/preview-markdown-in-vs-code) is a common example of the side-by-side approach. ## Do I need an editor just to read a .md file? No. Opening a file in an editor works, but it is more than you need, and editors open the source by default, so you still see `#` and `*` until you switch to the preview. A reader shows the formatted version immediately. If the symbols are what put you off, [why a .md file shows # and * symbols](/markdown-viewer/why-md-file-shows-symbols) explains where they come from. Installing an editor makes sense once you start writing or changing markdown files yourself. ## Can a plain text editor be a markdown editor? Yes. Markdown is plain text, so Notepad, TextEdit, nano or any code editor can create and change a `.md` file. What they lack is the preview and the writing aids. Many people write markdown in a plain editor and check the result in a separate reader, which works well: write in the tool you know, then drop the file into a viewer to make sure the tables and code blocks render the way you expect. Recent versions of Windows 11 Notepad can also show basic markdown formatting, which blurs the line further. ## How do I choose between them? Match the tool to the task. - **Reading a file someone sent you:** a reader. No install, and a browser viewer works on any computer or phone. - **Checking a README before you publish it:** a reader that uses the same rules as the destination. GitHub uses GitHub Flavored Markdown, so render with GFM; the [GitHub README viewer](/github-readme-viewer) also resolves the repository's relative links and images. - **Writing documentation in a code project:** an editor with a side-by-side preview, usually the code editor you already use. - **Keeping notes:** a note-taking editor built on markdown files, such as Obsidian. - **Cleaning up messy markdown:** a formatter, which rewrites spacing and list markers consistently; the [markdown formatter](/markdown-formatter) does this in the browser. ## Do readers and editors render markdown the same way? Not always. Markdown has several flavors. CommonMark is the strict core; GitHub Flavored Markdown adds tables, task lists, strikethrough and autolinks; other tools add footnotes, math, callouts or wiki-style links. An editor may support syntax that a reader does not, or the reverse, so a document can look right in one and partly raw in the other. When the final destination matters, preview with a tool that uses the destination's flavor. The [markdown viewer](/markdown-viewer) renders GitHub Flavored Markdown with footnotes and Mermaid, which matches GitHub, GitLab and most documentation sites. ## Is a markdown reader safer than an editor? Both are safe for ordinary files, because markdown is text and does not run when opened. The difference is about access. A browser reader that works with the File API only sees the one file you give it, which is a reasonable choice for a file from someone you do not know. A desktop editor usually has access to your whole disk and may run extensions. Neither needs network access to render, though images in a document load from wherever their URLs point. ## Can one tool do both? Many do. Editors include previews, and some readers let you edit. The markdown viewer here has an editable source panel, so you can fix a typo and see the result, but it does not save back to your disk; you would copy the corrected text back into your file. That is the practical line between the two: a reader is complete without saving, an editor is not. ## How do I open a .md file on iPhone or Android? URL: https://docs-md.com/markdown-viewer/open-md-file-iphone-android Updated: 2026-10-20 Save the file to your phone, open a browser-based markdown viewer and pick the file there. Neither iOS nor Android renders markdown on its own: the iPhone Files app shows a .md file as plain text, and Android opens it in whatever text app you have, if any. A viewer or a markdown app shows it formatted. A `.md` file is markdown, plain text in which `#` marks a heading, `**` marks bold and `-` starts a list item. On a computer, opening it in a text editor is a reasonable fallback. On a phone, raw markdown is harder to read: long lines of pipes and dashes in a table wrap across the narrow screen, and code blocks lose their alignment. Getting a rendered view is worth the extra step. ## What happens when I tap a .md file on an iPhone? The Files app opens a preview that shows the text, not the formatting. You see the `#` and `*` characters, and tables appear as rows of pipes. The same happens with a `.md` attachment in Mail or a file in a chat app: iOS previews it as text. Nothing is wrong with the file. iOS simply has no markdown renderer built in, so you need a viewer page or an app that understands the format. ## How do I read a .md file formatted on iPhone or iPad? Use a browser viewer through Safari, which can pick files from the Files app. 1. If the file is an attachment in Mail, Messages or another app, open it, tap the share button and choose **Save to Files**. Pick a folder you will find again. 2. Open the [markdown viewer](/markdown-viewer) in Safari. 3. Tap **Open .md file**. iOS shows a file picker; browse to the file and tap it. 4. The document renders with headings, tables, lists, code highlighting and Mermaid diagrams. Tap **Hide source** to give the rendered view the full width of the screen. The file is read by Safari on the phone and is not uploaded. On an iPad you can also drag a file from the Files app in Split View onto the viewer. ## How do I open a .md file on Android? Tapping a `.md` file in a file manager or download notification opens it in an app that has registered for text files, or Android asks you to choose one, or reports that no app can open it. Which of these you see depends on the phone maker and the apps you have installed. To read it formatted, open the [markdown viewer](/markdown-viewer) in Chrome, tap **Open .md file**, and pick the file from the system file picker; downloads are usually in the **Downloads** folder. The rendering is the same as on a desktop, and the file stays on the phone. ## Which markdown apps work on phones? If you read markdown on your phone often, an app saves the save-then-open step. [Obsidian](https://obsidian.md) has free iOS and Android apps that open folders of markdown notes and show them formatted. On Android, [Markor](https://github.com/gsantner/markor) is an open-source markdown editor with a preview mode, available from Google Play and F-Droid. Many other viewers and editors exist in both app stores; check the reviews, the date of the last update, and which permissions the app asks for before you install, because some read every file in your storage. ## How do I read a README from GitHub on my phone? Open the repository on github.com in your browser; GitHub renders `README.md` and other markdown files on the repository page, on mobile as well. The GitHub mobile app does the same for repositories you browse there. If you only have a link to the raw file, the [GitHub README viewer](/github-readme-viewer) loads it from the repository and renders it with relative links and images working, which raw links lose. ## Why does the rendered document look cramped on a phone? Wide content does not fit a phone screen. Tables with many columns, long code lines and large diagrams have to scroll sideways or shrink. In the viewer, turn the phone to landscape, hide the source panel and lower the type size. If the document is yours and is mainly read on phones, keep tables to a few columns and break long code lines; the [markdown table guide](/guides/markdown-table) has tips on keeping tables narrow. ## Can I send someone a .md file to read on their phone? You can, but they will probably see raw text, for the reasons above. If the reader is not technical, send something their phone renders on its own: a PDF, or a link to a rendered web page. The viewer's **Share as link** button publishes the document to a short address that opens as a formatted page in any mobile browser. Treat that link as public to anyone who has it. The [guide to sharing a rendered markdown file](/markdown-viewer/render-markdown-to-pdf-or-link) compares the PDF and link routes. ## Is it safe to open a .md file on my phone? Yes. A markdown file is text and does not run code when it is opened or rendered. Links and images inside it can point to websites, so treat links in a file from a stranger the same way you treat links in a message. The browser viewer does not run scripts from the file, and it does not upload the file; only **Share as link** sends the content to a server, and only when you tap it. ## What about .markdown and .txt files? They work the same way. `.markdown` is a longer extension for the same format, and the viewer also opens `.mdx` and `.txt` files and renders any markdown inside them. If a file chooser greys out a `.md` file, change the filter to all files, or rename a copy to `.txt` in the Files app and open that; the markdown inside renders identically. ## Which option should I pick? For a single file, the browser viewer: nothing to install on either platform, and the rendering matches GitHub. For a folder of notes you read every day, a markdown app such as Obsidian. For a repository README, the GitHub website. On a computer the steps are different; see the guides for [Windows](/markdown-viewer/open-md-file-windows) and [Mac](/markdown-viewer/open-md-file-mac). ## How do I open a .md file on a Mac? URL: https://docs-md.com/markdown-viewer/open-md-file-mac Updated: 2026-10-20 Control-click the file, choose Open With, and pick TextEdit. A .md file is plain text, so it opens, but you see the raw markdown symbols. macOS has no built-in markdown renderer, so to read it formatted use a browser viewer, a Quick Look extension, or an editor with a preview such as VS Code. Markdown writes formatting with ordinary characters: `#` before a heading, `**` around bold text, `-` in front of a list item, pipes for tables. The format was designed to stay readable as plain text, so TextEdit is enough for a short note. For a long README with tables and code, the symbols get in the way, and a rendered view is much easier to read. None of the options below change the file, and none of them need an account. Which one fits depends on whether you only want to read the file once or work with markdown regularly. ## How do I open a .md file in TextEdit? Control-click (or right-click) the file in Finder, choose **Open With**, then **TextEdit**. TextEdit shows the markdown source as typed. If **TextEdit** is not in the list, choose **Other…** and pick it from Applications. If you edit and save the file, keep it as plain text: in TextEdit, **Format**, **Make Plain Text** ensures it does not turn the file into rich text. TextEdit does not interpret markdown, so headings stay as lines starting with `#`. ## Why does Quick Look show raw markdown? Quick Look, the preview you get by selecting a file in Finder and pressing the Space bar, treats a `.md` file as plain text. It shows the content but not the formatting, so you see the `#` and `*` characters. To get a rendered preview in Quick Look you need a third-party Quick Look extension that handles markdown. One open-source option is [QLMarkdown](https://github.com/sbarex/QLMarkdown), a macOS Quick Look extension for markdown files. Its README offers a downloadable release and a Homebrew install: ```bash brew install --cask qlmarkdown ``` After installing, open the app once so macOS registers the extension, then check that it is enabled under the Quick Look section of extensions in System Settings. Older Quick Look plugins in the `.qlgenerator` format are not supported by recent macOS versions, so prefer a project that ships as an app extension and has recent releases. ## How do I read a .md file formatted without installing anything? Use a browser viewer. Open the [markdown viewer](/markdown-viewer) in Safari, Chrome or Firefox, then drag the `.md` file from Finder onto the viewer panel, or click **Open .md file** and choose it. The file is read locally by the browser, not uploaded, and it renders with GitHub's rules: headings, tables, task lists, footnotes, highlighted code and Mermaid diagrams. **Hide source** gives a full-width reading view and the outline lets you jump between headings. Opening the file directly in Safari instead, with **File**, **Open File**, shows plain text, because browsers do not render markdown on their own. ## How do I preview a .md file in VS Code on a Mac? Open the file in Visual Studio Code and press **Cmd+Shift+V** to switch to the rendered preview, or **Cmd+K** then **V** to open the preview beside the source. Both shortcuts are listed in the [VS Code markdown documentation](https://code.visualstudio.com/docs/languages/markdown). The preview updates as you type, scrolls along with the editor and renders Mermaid diagrams and math. If you do not have VS Code, it is a free download, and the [VS Code preview guide](/markdown-viewer/preview-markdown-in-vs-code) covers the rest of its options. ## How do I make .md files always open in one app? Select a `.md` file in Finder and press **Cmd+I** to open **Get Info**. Under **Open with**, choose the app, then click **Change All…** and confirm. Every `.md` file now opens in that app on double-click. Pick a markdown editor or VS Code if you want formatting; TextEdit if you only need the text. A browser is not a good default for local files, because without an extension it shows plain text. You can undo the change the same way by choosing a different app and clicking **Change All…** again. ## Which markdown apps exist for the Mac? Several native editors render markdown, including Typora, Obsidian and iA Writer, along with many smaller ones on the Mac App Store. They differ in price, in which extensions they support (tables, footnotes, math, Mermaid) and in whether they show source and preview side by side or blend them in one view. For reading a file you received, an app is optional; for writing notes every day, one of these is worth trying. Check the developer's current website for pricing and supported macOS versions before you install, because those change. ## Can I read a .md file from the Terminal? Yes, as text: `cat README.md` or `less README.md` prints the source. There are command-line tools that render markdown for the terminal, such as Glow, which you can install with Homebrew, but they are only worth it if you already live in the Terminal. Pandoc can convert a file to HTML that you then open in a browser: ```bash pandoc README.md -s -o README.html && open README.html ``` ## Which option should I pick? For a file someone sent you, the browser viewer: no install, complete rendering, nothing uploaded. If you preview markdown files in Finder all day, install a Quick Look extension. If you edit markdown, use VS Code or a dedicated editor. If the file is a README from a GitHub project, the [GitHub README viewer](/github-readme-viewer) reads it from the repository with its relative links and images working, and [the Windows version of this guide](/markdown-viewer/open-md-file-windows) covers the same steps for a PC. ## How do I open a .md file on Windows? URL: https://docs-md.com/markdown-viewer/open-md-file-windows Updated: 2026-10-20 Right-click the file, choose Open with, and pick Notepad. A .md file is plain text, so it opens in any text editor, but you see the raw markdown symbols. To read it formatted, with headings, lists and tables, open it in a markdown viewer, in VS Code's preview, or in a recent version of Notepad. The `.md` extension stands for markdown, a way of writing formatting with ordinary characters: `#` in front of a heading, `**` around bold text, `-` at the start of a list item. Nothing in the file is executable, so opening it in a text editor is safe. Windows just does not ship a program that is registered to show markdown as a formatted document on every machine, which is why a double-click often asks you to choose an app, or opens the file in something unexpected. ## How do I open a .md file with Notepad? Right-click the file in File Explorer and choose **Open with**, then **Notepad**. On Windows 11 the right-click menu may show **Open with** directly; if it does not, choose **Show more options** first to get the classic menu. If Notepad is not in the short list, pick **Choose another app** and select it there. This always works because markdown is plain text. What you get depends on your Notepad version: older versions show every `#`, `*` and `|` exactly as typed, which is readable for short files and tiring for long ones. ## Can Notepad on Windows 11 show markdown formatted? Recent versions of Notepad on Windows 11 can. Microsoft added lightweight formatting to Notepad in 2025, and it reads markdown files: headings, bold, italic, links and lists can be shown as formatting, with a switch between the formatted view and the raw syntax. Support grew over later updates, and tables arrived in newer builds than the first release. Notepad updates through the Microsoft Store, so if you do not see a formatting toolbar or a formatted view, check the Store for a Notepad update. If your organization manages updates, you may not have it yet, and Windows 10 Notepad does not have it. Even where it works, Notepad covers the basic syntax. Fenced code blocks with syntax highlighting, footnotes, task lists and Mermaid diagrams are outside what it is built to show, so a technical README can still look partly raw. ## How do I see a .md file formatted without installing anything? Use a browser-based viewer. Open the [markdown viewer](/markdown-viewer) in Edge or Chrome, then drag the `.md` file from File Explorer onto the viewer panel, or click **Open .md file** and pick it. The file is read by your browser and not uploaded, and it renders with GitHub's rules: headings, tables, task lists, footnotes, highlighted code and Mermaid diagrams. Click **Hide source** for a full-width reading view and use the outline to jump between sections. This is the quickest route on a work laptop where you cannot install software. ## How do I make .md files always open in the same program? Set a default app for the extension. Right-click any `.md` file, choose **Open with**, then **Choose another app**, select the program and tick **Always use this app to open .md files** before clicking **OK**. You can also do it from **Settings**, **Apps**, **Default apps**: type `.md` in the box that sets a default by file type and pick the app. Good choices are Notepad for quick reading, VS Code if you edit markdown, or a dedicated markdown editor if you installed one. A browser cannot be set as a useful default here, because opening a local `.md` file in Edge or Chrome shows plain text unless an extension is installed. ## How do I open a .md file in VS Code on Windows? Right-click the file and choose **Open with**, then **Visual Studio Code**, or choose **Open with Code** if you ticked that option during installation. The file opens as source. Press **Ctrl+Shift+V** to switch to the rendered preview, or **Ctrl+K** followed by **V** to open the preview beside the source, so you see changes as you type. The [VS Code markdown documentation](https://code.visualstudio.com/docs/languages/markdown) describes both shortcuts. The [guide to previewing markdown in VS Code](/markdown-viewer/preview-markdown-in-vs-code) covers preview locking, scroll sync and why some images do not appear. ## Why does double-clicking a .md file do nothing useful? Windows opens a file with whatever app is registered for its extension, and `.md` often has no registration, or one you did not choose. On a fresh machine Windows asks which app to use. If you installed a developer tool, it may have claimed the extension. Some systems associate `.md` with unrelated software, because the same extension has been used by other file types in the past. Use **Open with** to choose deliberately, and set a default as described above if you open these files often. ## Is a .md file safe to open? Opening it in a text editor or viewer is safe. A `.md` file is text; it does not run code when opened. A rendered markdown document can contain links and images that point to web addresses, so treat links in a file from an unknown sender as you would links in an email. Browser viewers do not run scripts embedded in the file, and VS Code's preview blocks scripts by default as well. ## What about .markdown, .mdx and README files? They open the same way. `.markdown` is a longer spelling of the same format. `.mdx` is markdown with embedded JSX components, used by documentation sites; viewers render the markdown parts and show the components as text or skip them. A `README.md` from a downloaded project is an ordinary markdown file; if it came from GitHub, the [GitHub README viewer](/github-readme-viewer) reads it straight from the repository with its links and images working. For more on the README case specifically, see [how to open a README.md file](/readme-generator/how-to-open-readme-md). ## Which option should I pick? For a one-off file, the browser viewer: nothing to install and the most complete rendering. If you only need to read short notes and your Notepad has formatting, Notepad is fine. If you write markdown regularly, VS Code with its side-by-side preview is the better daily tool. If you need to send the formatted document to someone else, see [how to share a rendered markdown file](/markdown-viewer/render-markdown-to-pdf-or-link). ## How do I preview markdown in VS Code? URL: https://docs-md.com/markdown-viewer/preview-markdown-in-vs-code Updated: 2026-10-20 Open the .md file and press Ctrl+Shift+V (Cmd+Shift+V on a Mac) to switch to the rendered preview. To see source and preview side by side, press Ctrl+K, release, then press V (Cmd+K V on a Mac). The preview is built into VS Code, so no extension is needed, and it updates as you type. Both shortcuts come from the [VS Code Markdown documentation](https://code.visualstudio.com/docs/languages/markdown), which is the reference for everything below. The preview is a separate editor tab, so you can drag it to another group, split it, or put it on a second monitor like any other tab. It renders CommonMark with common extensions, Mermaid diagrams in `mermaid` code fences, and math with KaTeX. ## What are the ways to open the markdown preview? There are four, and they open the same preview. Press **Ctrl+Shift+V** (**Cmd+Shift+V**) to replace the current view with the preview. Press **Ctrl+K V** (**Cmd+K V**) to open it beside the source. Right-click the file's editor tab and choose **Open Preview**. Or open the Command Palette with **Ctrl+Shift+P** (**Cmd+Shift+P**) and run **Markdown: Open Preview** or **Markdown: Open Preview to the Side**. There is also a preview icon in the editor title bar, at the top right of a markdown tab, which opens the side-by-side preview with one click. ## Why does the preview change when I switch files? By default the preview follows the active markdown file: click another `.md` tab and the preview shows that file instead. To pin it to one document, make the preview the active tab and run **Markdown: Toggle Preview Locking** from the Command Palette. A locked preview shows **[Preview]** in its title and stays on its file while you edit others. The documentation notes the command only appears when the preview is the active tab, which is the usual reason people cannot find it. ## How do I keep the editor and preview scrolled together? They already are. VS Code syncs scrolling in both directions, and marks the line your cursor is on with a light gray bar in the preview's left margin. Double-clicking an element in the preview jumps the editor to the matching line. If you prefer to scroll them independently, turn off `markdown.preview.scrollPreviewWithEditor` and `markdown.preview.scrollEditorWithPreview` in Settings. ```json { "markdown.preview.scrollPreviewWithEditor": false, "markdown.preview.scrollEditorWithPreview": false } ``` ## Why are images or content missing from the preview? The preview runs under a security policy. Its default level, **Strict**, disables scripts and only loads content over `https`, so an image with an `http://` URL is blocked. When something is blocked, an alert appears at the top right of the preview; click it, or run **Markdown: Change preview security settings**, to choose **Allow insecure content** (scripts stay off, `http` loads) or **Disable** (no extra restrictions). The setting applies to the whole workspace, and the VS Code documentation recommends staying on Strict unless you trust every markdown file in the workspace. For local images, check that the relative path in the markdown matches the file's location; paths are resolved from the markdown file's folder. ## Can I make .md files open in the preview by default? Yes, through editor associations. Add this to your `settings.json`, and opening a markdown file from the Explorer shows the rendered preview first: ```json { "workbench.editorAssociations": { "*.md": "vscode.markdown.preview.editor" } } ``` Use **View: Reopen Editor With...** from the Command Palette to switch a single file back to the text editor. The same documentation describes a `workbench.diffEditorAssociations` setting that renders markdown diffs from Source Control as a preview, with changes highlighted, which is useful when reviewing a documentation pull request. ## Does the VS Code preview look like GitHub? Close, but not identical. VS Code uses its own stylesheet and its own markdown parser configuration, so spacing, fonts and some extensions differ from what GitHub shows. If you need to know how a README will look on GitHub, render it with GitHub's rules: the [markdown viewer](/markdown-viewer) renders GitHub Flavored Markdown in the browser, and [previewing a README before pushing](/github-readme-viewer/preview-readme-before-push) covers the README case in detail. Inside VS Code, the Markdown Preview GitHub Styling extension by Matt Bierner restyles the preview to resemble GitHub; it changes the look, not the parser. ## How do I change how the preview looks? Point the `markdown.styles` setting at one or more CSS files. The setting accepts `https` URLs or paths relative to the workspace root, and your rules are applied on top of the built-in preview styles: ```json { "markdown.styles": ["preview.css"] } ``` If single line breaks in your source should appear as line breaks in the preview, set `markdown.preview.breaks` to `true`; by default the preview follows CommonMark, where a single newline inside a paragraph is a space. Math rendering can be turned off with `"markdown.math.enabled": false` if dollar signs in your text are being read as formulas. ## Can I export or share the preview? VS Code's preview has no export or share command. To get a PDF, see [exporting markdown to PDF from VS Code](/markdown-to-pdf/vs-code-markdown-to-pdf), which compares an extension, a browser converter and Pandoc. To send a rendered page to someone without VS Code, copy the file's content into the [markdown viewer](/markdown-viewer) and click **Share as link**, which publishes it at a short address that opens in any browser. ## What if I do not have VS Code? You do not need it just to read markdown. A browser viewer renders a file in a few seconds with nothing to install. VS Code makes sense when you also write or edit markdown, because the side-by-side preview shows the effect of every change as you type. The difference between tools for reading and tools for writing is covered in [markdown reader vs editor](/markdown-viewer/md-file-reader-vs-editor). ## How do I share a rendered markdown file with someone who has no markdown app? URL: https://docs-md.com/markdown-viewer/render-markdown-to-pdf-or-link Updated: 2026-10-20 Send it as a PDF or as a link to a rendered web page. A PDF suits a finished document that should look the same everywhere and work offline. A link suits a document you may update, or one with wide tables and diagrams. Both open on any computer or phone without a markdown app. Sending the `.md` file itself is the option to avoid when the reader is not technical. Their computer or phone will most likely show it as plain text, full of `#`, `*` and `|` characters, or ask them which app to use. The two routes below turn the markdown into something every device already knows how to open. ## How do I turn a markdown file into a PDF? Render it and print it to PDF from your browser. In the [markdown viewer](/markdown-viewer), open or drop the `.md` file, check that it renders the way you expect, then click **Print / PDF** and choose **Save as PDF** as the destination in the print dialog. The viewer's controls are hidden and only the rendered document prints. For more control, the [markdown to PDF converter](/markdown-to-pdf) is built for this one job: it keeps code blocks with syntax highlighting, renders tables as real tables, and avoids leaving a heading alone at the bottom of a page. Either way the PDF is produced by the browser's print engine, so the text stays selectable and searchable, and the file is never uploaded. For a cleaner result, set margins to **Default** and turn off **Headers and footers** in the print dialog, so the PDF does not carry the date and page address in its corners. ## How do I share a markdown file as a link? Publish it and send the address. In the viewer, click **Share as link**: the document is published at a short URL that renders as a formatted page, diagrams included, and expires after 30 days. Anyone who opens the link sees the formatted document in their browser, on a computer or a phone, with nothing to install. If you need a different lifetime, use the [main sharing page](/), where you paste the markdown and choose an expiry of 1 day, 7 days, 30 days or never. That page also gives you an edit token, which lets you update the content behind the same URL later, or delete it. ## Should I send a PDF or a link? Pick by what happens after you send it. | Need | PDF | Link | |---|---|---| | Reader opens it offline or archives it | Yes | No | | You will update the document after sending | Send a new file | Same URL, new content (with an edit token) | | Looks identical on every device | Yes, fixed pages | Adapts to the screen | | Wide tables and large diagrams | Can be cut at the page edge | Scroll horizontally | | Attach to an email or upload to a portal | Yes | Paste the URL | | Reader can copy text and code | Yes | Yes | | Stops being available | Never, once sent | When it expires or you delete it | In short, a PDF is a copy and a link is a window. Contracts, reports and anything that has to be filed should be PDFs. Drafts under review, plans that will change and documents mostly read on phones work better as links. ## Who can see a shared markdown link? Anyone who has the URL. The links are unlisted rather than private: they are not protected by a password or tied to the recipient's account, so a forwarded link works for whoever receives it. Do not publish documents with passwords, keys, personal data or anything confidential this way. For sensitive material, send a PDF through a channel you already trust, or use a document system that controls access per person. ## What does each format keep from the markdown? Both keep headings, lists, links, emphasis, tables, block quotes and code blocks with syntax highlighting. Mermaid diagrams render in the viewer and in shared links; in a PDF they appear as they render in the browser before printing, so check the print preview for diagrams cut across a page break. The [guide to keeping Mermaid and code blocks in a PDF](/markdown-to-pdf/markdown-to-pdf-mermaid-code) covers that in detail. Links stay clickable in both. In both, the text stays real text that readers can select and search, not an image of it. ## What if the reader needs to edit the document? Then neither PDF nor link is ideal, because both are for reading. If they use Microsoft Word, convert the markdown to a `.docx` file with the [markdown to Word converter](/markdown-to-word) and send that; headings, lists and tables become native Word formatting they can change. If they are comfortable with markdown, send the `.md` file itself along with a link to a viewer, so they can read it formatted and still edit the source. ## Can I share a README from a GitHub repository? If the repository is public, send the github.com address of the file: GitHub renders markdown for every visitor, with no account needed to read it. If the repository is private, the reader needs access to it, so publish a copy instead: paste the README into the viewer and share it as a link, or print it to PDF. Relative links to other files in the repository will not work in either copy, because those files are not included. ## How do I check the document before sending it? Open the PDF or the link yourself, ideally on a phone as well as a computer. Look for tables that run off the edge, code blocks with very long lines, images that did not load and diagrams that failed to render. Images must use full `https` URLs to appear in a shared link or a PDF made in the browser, because a relative path such as `images/chart.png` only resolves next to the original file. Fix the markdown, render again, and only then send it. If the reader still has trouble, the guide to [opening a .md file on a phone](/markdown-viewer/open-md-file-iphone-android) shows the steps they would need. ## How do I view a markdown file in Chrome? URL: https://docs-md.com/markdown-viewer/view-markdown-in-chrome Updated: 2026-10-20 Chrome has no markdown renderer, so a .md file opened in it shows as plain text. To see it formatted, open an online markdown viewer in Chrome and drop the file onto it, or install a markdown extension and allow it to access file URLs. The viewer needs no install; the extension renders files you open directly. Both routes end in the same place, a formatted document with headings, lists, tables and code, but they work differently. An online viewer is a web page that reads the file you give it. An extension changes how Chrome displays `.md` addresses, so it also works when you open a file from your disk or follow a link to a raw markdown file. The rest of this page covers each route and the permission that trips people up. ## What does Chrome do with a .md file by default? It treats it as text. If you drag a local `.md` file into a Chrome tab, or open it with **Ctrl+O** (**Cmd+O** on a Mac), you usually get the raw source in a plain monospaced page, with every `#`, `*` and `|` visible. Depending on your system and how the file was served, Chrome may download the file instead of showing it. Links to raw files on the web, such as a `raw.githubusercontent.com` address, also display as plain text. None of this is a fault in the file: Chrome only renders HTML, and markdown has to be converted to HTML first. ## How do I view a markdown file in Chrome without installing anything? Use an online viewer. Open the [markdown viewer](/markdown-viewer) in a tab, then drag the `.md` file from your file manager onto the viewer panel, or click **Open .md file** and pick it. The page reads the file with the browser's File API and does not upload it. It renders GitHub Flavored Markdown: tables, task lists, footnotes, highlighted code blocks and Mermaid diagrams. You can also paste markdown text into the editor, or paste a GitHub file URL and click **Load from URL**; that fetch happens in your browser, so it works for hosts that allow cross-origin requests, which GitHub raw files and gists do. This route works in managed Chrome profiles where extensions are blocked. ## How do I render markdown with a Chrome extension? Install a markdown viewer extension from the Chrome Web Store, then open `.md` files or links in Chrome as usual; the extension replaces the plain text with a rendered page. One long-running open-source option is [Markdown Viewer by simov](https://github.com/simov/markdown-viewer), which supports several markdown parsers, themes and syntax highlighting. Before installing any extension, check its permissions, its number of users and when it was last updated, because a viewer extension asks to read the pages it renders. Microsoft Edge can install extensions from the Chrome Web Store, so the same extensions work there. ## Why does the extension not work on local files? Chrome does not let extensions read `file://` addresses unless you allow it per extension. Until you do, a local `.md` file stays as plain text even with the extension installed. To turn it on: 1. Go to `chrome://extensions` in the address bar. 2. Find the markdown extension and click **Details**. 3. Turn on **Allow access to file URLs**. 4. Reload the tab with the `.md` file. The Markdown Viewer project's [setup instructions](https://github.com/simov/markdown-viewer) describe the same switch. It applies to the one extension you enable it for. Only grant it to extensions you trust, because it lets them read local files you open in Chrome. ## Why does an extension not render some markdown links? The extension only acts on addresses it is allowed to run on. Many extensions start with local files and a few known hosts, and ask you to allow other origins one by one. A server can also send a `.md` file with a content type that makes Chrome download it rather than display it, and an extension cannot render a page Chrome never opens. In those cases, download the file and use a viewer, or use **Load from URL** on the viewer page if the host permits cross-origin reads. ## Should I use the online viewer or an extension? Use the online viewer when you read a markdown file now and then, when you cannot install extensions, or on a shared computer. Use an extension when you click through many markdown files or raw links every day and want them to render in place. The viewer has a few things extensions usually lack: **Share as link** to send the rendered page to someone, and **Print / PDF** for a clean printout. For whole repositories, with relative links between files and images that resolve, the [GitHub README viewer](/github-readme-viewer) is the better fit. ## How do I view markdown on a Chromebook? Use the online viewer. Opening a `.md` file from the ChromeOS Files app shows its text, not the formatting. Open the viewer in Chrome and click **Open .md file**; the picker shows your Downloads folder and Google Drive. Extensions behave the same as on other platforms, including the **Allow access to file URLs** switch. ## Can Chrome print a markdown file as a PDF? Not usefully from the raw text tab: you would get a PDF of the source with every symbol. Render it first. In the viewer, click **Print / PDF** and choose **Save as PDF** as the destination in Chrome's print dialog; only the rendered document prints. For page size and margin options, the [markdown to PDF converter](/markdown-to-pdf) is built for it. ## Why does a page say it is markdown but look normal in Chrome? Because the site converted it before sending it. GitHub, GitLab, documentation sites and wikis store pages as markdown and turn them into HTML on their servers, so Chrome receives ordinary HTML and displays it. You only see raw markdown when Chrome gets the `.md` file itself, from your disk or a raw link. If you are not sure why the symbols appear in the first place, [why a .md file shows # and * symbols](/markdown-viewer/why-md-file-shows-symbols) explains it in a few paragraphs. ## Why does my .md file show # and * symbols instead of formatting? URL: https://docs-md.com/markdown-viewer/why-md-file-shows-symbols Updated: 2026-10-20 Because you are looking at the source, not the rendered document. A .md file is plain text in which # marks a heading and * marks emphasis; a program has to read those marks and turn them into formatting. Text editors and phones do not, so they show the symbols. Open the file in a markdown viewer to see the formatting. Markdown works like a recipe rather than a finished dish. The file holds instructions written in ordinary characters, and a renderer follows them to produce a formatted page, usually HTML. When GitHub shows a README with real headings, it has run a renderer on the server. When you open the same file in Notepad or TextEdit, nothing runs, so you see the instructions themselves. ## What do the symbols mean? Each one is a formatting instruction. `#` at the start of a line makes a heading, and more of them make smaller headings (`##`, `###`). Asterisks or underscores around words make emphasis: one pair for italic, two for bold. A `-`, `*` or `1.` at the start of a line begins a list item. Vertical bars `|` separate table columns, `>` starts a quotation, and three backticks open and close a block of code. `[text](https://…)` is a link. The [markdown cheat sheet](/markdown-cheat-sheet) lists the rest on one page, and the [headings guide](/guides/markdown-headings) covers the `#` levels in detail. ## Why is markdown designed so the symbols stay visible? So the file stays readable without any software. John Gruber, who created the format, wrote in the [original syntax documentation](https://daringfireball.net/projects/markdown/syntax) that a markdown document "should be publishable as-is, as plain text, without looking like it's been marked up with tags or formatting instructions." That is why a `.md` file opened in a text editor is usable at all: a `#` line looks like a title and a hyphen list looks like a list. The cost is that the symbols are still there until something renders them. ## How do I make the file show its formatting? Open it in something that renders markdown. The quickest is a browser viewer: open the [markdown viewer](/markdown-viewer), drag the file onto it or click **Open .md file**, and it renders with headings, tables, code highlighting and diagrams, without uploading the file. Other options are VS Code's built-in preview (**Ctrl+Shift+V**, or **Cmd+Shift+V** on a Mac), a markdown editor such as Obsidian or Typora, or, for a file in a GitHub repository, the repository page on github.com. Step-by-step instructions for each platform are in the guides for [Windows](/markdown-viewer/open-md-file-windows), [Mac](/markdown-viewer/open-md-file-mac) and [phones](/markdown-viewer/open-md-file-iphone-android). ## Why do some symbols still show in a markdown viewer? Usually because the markdown is slightly off, and the renderer treats those characters as plain text. Common causes: - **No space after `#`.** CommonMark, the specification most renderers follow, requires a space between the `#` characters and the heading text, so `#Title` stays as text while `# Title` becomes a heading. - **Unclosed emphasis.** `**bold` without the closing `**` shows the asterisks. So does a space just inside the markers, as in `** bold **`. - **A missing blank line.** A list or table directly after a paragraph line sometimes needs a blank line before it to be recognized, depending on the renderer. - **An unclosed code fence.** Three backticks with no matching closing line turn everything after them into a code block, so the rest of the document shows raw. - **Indentation.** A line indented by four spaces is a code block in standard markdown, and shows its symbols literally. Fix the line and render again; the change is immediate in a live preview. ## Why does it show symbols in Word, email or chat? Those programs either do not render markdown or render a different variant. Microsoft Word opens a `.md` file as plain text; [what Word does with a .md file](/markdown-to-word/can-word-open-md-file) explains the conversion route. Email clients send HTML or plain text, so markdown pasted into a message arrives with its symbols. Chat apps support their own subsets: Slack, for example, uses single asterisks for bold, so `**bold**` from a markdown file shows extra asterisks there. The [Slack formatting reference](/slack-markdown) lists what each app accepts. ## How do I show a literal # or * on purpose? Put a backslash in front of it: `\#` and `\*` are displayed as the characters themselves, not read as formatting. This is useful for hashtags at the start of a line or for multiplication signs. Inside inline code (single backticks) or a code block, no escaping is needed, because everything there is shown as typed. The [escape characters guide](/guides/markdown-escape-characters) lists every character that can be escaped. ## Is something wrong with my file? Almost never. Seeing `#` and `*` in a text editor is exactly what a healthy `.md` file looks like. The file is only broken if a markdown renderer also fails to format it, and then the cause is usually one of the syntax slips above, not corruption. If a file shows strange characters such as `Ã©` instead of accented letters, that is a different problem: a text encoding mismatch, which you fix by reopening the file as UTF-8. ## Should I convert the file instead of viewing it? Only if someone else needs to read it in a format they can open. Viewing is enough for reading it yourself. For a colleague without a markdown app, a PDF or a shared link is easier than the raw file; [sharing a rendered markdown file](/markdown-viewer/render-markdown-to-pdf-or-link) compares both. For a Word document, convert to `.docx`. Keep the `.md` file as the source either way, since it is the version that is easy to edit and compare. --- # Markdown formatter (md formatter) URL: https://docs-md.com/markdown-formatter Category: Edit & share Updated: 2026-09-16 Prettify messy markdown: uniform list markers, one emphasis style, aligned tables. Semantic — rendered output never changes. ## How do I align a markdown table so the columns line up? URL: https://docs-md.com/markdown-formatter/fix-markdown-table-alignment Updated: 2026-10-20 Pad each cell with spaces to the width of the widest cell in its column, and make the dashes in the delimiter row the same width. Then every pipe sits in the same position on every line. A formatter does this automatically: paste the table into a markdown formatter or run Prettier, and the source comes back aligned. Alignment in the source is purely for people reading the raw file. Renderers ignore the extra spaces: a table with ragged pipes and the same table with perfect columns produce identical HTML. That is also why aligning a table is safe to automate. A formatter that parses the table and prints it back can only change whitespace, not content. ## What does an aligned markdown table look like? Every row has the same length and the pipes form straight vertical lines. Here is a table as people usually type it, and the same table after one pass through our [Markdown Formatter](/markdown-formatter): ```markdown |Name|Score|Notes| |:---|---:|:-:| |Ada|99|first| |Grace Hopper|7|x| ``` ```markdown | Name | Score | Notes | | :----------- | ----: | :---: | | Ada | 99 | first | | Grace Hopper | 7 | x | ``` Both render as the same three-column table. The second one shows the formatter doing two separate jobs. It pads the cells so the pipes line up, and it pads each cell on the side that matches the column's text alignment, so right-aligned numbers sit flush right in the source too. The delimiter row is stretched to the column width with the colons kept in place. ## How do the colons in the separator row affect alignment? The colons set how text is aligned inside each column when the table is rendered; they do not line up the source. Per the GitHub Flavored Markdown spec, `:---` is left-aligned, `---:` is right-aligned and `:---:` is centred, and a delimiter with no colons leaves alignment to the renderer's default, which is usually left ([GFM spec, Tables](https://github.github.com/gfm/#tables-extension-)). This is the most common confusion behind the question. Someone adds `:---:` hoping the raw file will look tidy, and nothing in the source changes. Two different things are called "alignment": text alignment inside rendered cells, set by colons, and vertical alignment of pipes in the source, set by padding. You usually want both: colons for how readers see the table, padding for how editors see the file. The [markdown table guide](/guides/markdown-table) covers the colon syntax with more examples. ## How do I align a table automatically? Use a tool that parses tables rather than one that counts pipes. Three options, from no setup to fully automatic: 1. **In the browser.** Paste the document into the [Markdown Formatter](/markdown-formatter). Every table in it is reprinted aligned, along with the rest of the file. If you are building a new table rather than fixing one, the [Markdown Table Generator](/markdown-table-generator) produces aligned output from a grid you fill in. 2. **With Prettier.** `npx prettier --write table.md` aligns every table in the file. Prettier keeps tables aligned unless you set `proseWrap` to `never` and the aligned table is wider than `printWidth`; then it prints a compact table instead. See [How do I format markdown files with Prettier?](/markdown-formatter/format-markdown-with-prettier). 3. **In your editor.** In VS Code, the Prettier extension does this on Format Document. Some markdown extensions also offer a table formatting command; check the extension's own documentation for the exact name. Any of these makes an md formatter part of your workflow, so you never align tables by hand again. Doing it by hand is fine for a three-row table and miserable for a twenty-row one, where adding one long cell means re-padding the whole column. ## Why do my columns still look misaligned after formatting? Usually because of characters that are wider or narrower on screen than their count suggests. The common causes: - **CJK characters and emoji.** In a monospaced font, a Chinese, Japanese or Korean character usually takes two columns, and most emoji also display wide. A formatter that counts characters will under-pad these cells. We tested this: our browser formatter counts characters, so a cell containing `東京` comes out two spaces short, while Prettier measures display width and aligns the same table correctly. If your tables contain CJK text, use Prettier for them. - **A proportional font.** Alignment only works in monospaced fonts. If your editor, or a website showing raw markdown, uses a proportional font, no amount of padding will line the pipes up. - **Tabs.** A tab character inside a cell is rendered at a width your editor decides. Replace tabs with spaces. - **Escaped pipes and inline markup.** A cell containing `a \| b` or `[link](https://example.com)` is padded by its source length, which is correct for the source but means the rendered column widths look nothing like the source widths. That is expected. ## Does an aligned table render differently from an unaligned one? No. The outer pipes, the padding and the number of dashes in the delimiter row are all optional in the GFM spec, so these two tables render identically: ```markdown a|b -|- 1|2 | a | b | | - | - | | 1 | 2 | ``` What does matter for rendering is that the header row and the delimiter row have the same number of cells, and that a blank line separates the table from a preceding paragraph, which several renderers need to recognise the table at all. A table that does not render at all is a syntax problem, not an alignment problem; a linter such as [Markdown Lint](/markdown-lint) is the better tool for finding it. ## Should I keep markdown tables aligned in a repository? Keep them aligned if people read the raw files, and let a tool do it. Aligned tables are much easier to read in a terminal, in a pull request diff and in an editor without preview. The cost is diff noise: when one long value is added, every row of that column gets new padding, so a one-cell change shows as a change to every line of the table. Some teams accept the noise in exchange for readability. Others choose compact tables with a single space around each cell, which markdownlint's MD060 rule calls the `compact` style, and enforce that instead. Either choice works if a formatter applies it consistently. What does not work is a mix: hand-aligned tables that drift out of alignment the first time someone edits them without a formatter. If you only need a one-off fix, paste the table into the formatter, copy it back, and move on. If tables change often, run Prettier in CI with `--check` so misaligned tables are caught before merge. ## How do I format markdown in VS Code? URL: https://docs-md.com/markdown-formatter/format-markdown-in-vs-code Updated: 2026-10-20 VS Code does not ship a formatter for markdown, so Format Document does nothing until you install one. Add the Prettier extension (or markdownlint), make it the default formatter for markdown files, and run Format Document with Shift+Alt+F on Windows, Shift+Option+F on macOS or Ctrl+Shift+I on Linux. Format on save is one setting more. VS Code has two built-in format actions, **Format Document** and **Format Selection**, but each language needs a formatter extension behind them ([VS Code docs, Formatting](https://code.visualstudio.com/docs/editing/codebasics#_formatting)). For markdown, VS Code's own extension gives you preview, outline, link completions and optional link validation, not formatting. If you run Format Document on a `.md` file with nothing installed, VS Code tells you there is no formatter for markdown files and offers to search the Marketplace. ## Which extension should I use to format markdown in VS Code? Use Prettier if you want the whole file reprinted in one consistent style, and markdownlint if you want rule-based warnings that can also fix some problems. Prettier is the closest thing to a standard md formatter: it parses the file and prints it back with fixed choices for bullets, emphasis, tables and spacing. markdownlint is a linter first, but it registers itself as a formatter too. The two extensions are: - **Prettier - Code formatter**, identifier `esbenp.prettier-vscode`. It uses the Prettier version installed in your project's `node_modules` if there is one, and otherwise the copy bundled with the extension ([prettier-vscode README](https://github.com/prettier/prettier-vscode#readme)). - **markdownlint**, identifier `DavidAnson.vscode-markdownlint`. It underlines rule violations as you type and, per its README, "registers itself as a source code formatter for Markdown files", so Format Document applies its automatic fixes ([vscode-markdownlint README](https://github.com/DavidAnson/vscode-markdownlint#readme)). Many people install both: Prettier for layout, markdownlint for things a printer cannot decide for you, such as a skipped heading level or an image without alt text. The difference is explained in more detail in [What is the difference between a markdown formatter and a linter?](/markdown-formatter/markdown-formatter-vs-linter). ## How do I set Prettier as the default formatter for markdown? Install the extension, then add a language-specific entry to your `settings.json`. Open the Command Palette (Ctrl+Shift+P, or Cmd+Shift+P on macOS), run **Preferences: Open User Settings (JSON)**, and add: ```json { "[markdown]": { "editor.defaultFormatter": "esbenp.prettier-vscode" } } ``` The Prettier extension's README notes that VS Code does not support combined language syntax for this setting, so markdown needs its own block even if you already set Prettier for JavaScript. To set it for one project only, put the same block in `.vscode/settings.json` in the repository instead of your user settings, and commit it so everyone on the project gets the same formatter. If you have both Prettier and markdownlint installed and have not chosen a default, VS Code asks which one to use the first time you format. You can also run **Format Document With...** from the Command Palette to pick a formatter for a single run without changing the default. ## How do I format markdown on save in VS Code? Turn on `editor.formatOnSave`, either globally or only for markdown. The markdown-only version keeps the behaviour from surprising you in other languages: ```json { "[markdown]": { "editor.defaultFormatter": "esbenp.prettier-vscode", "editor.formatOnSave": true } } ``` With this in place, every save reprints the file. If you also want markdownlint to apply its fixes on save, its README shows the setting `editor.codeActionsOnSave` with `"source.fixAll.markdownlint": "explicit"`, which runs the fixes when you save explicitly rather than on auto-save. The extension also adds a **markdownlint: Fix all supported markdownlint violations in the document** command (`markdownlint.fixAll`) if you prefer to run fixes by hand. Format on save is convenient but has one cost in shared repositories: the first save of an old file can produce a large diff that has nothing to do with your change. Format the whole repository once in a separate commit, then turn on format on save, so later diffs only show real edits. ## What will Prettier change in my markdown file? Prettier rewrites style, not content. On the files we tested with Prettier 3 it changed `*` and `+` bullets to `-`, `__bold__` to `**bold**`, `*italic*` to `_italic_`, padded table cells so the pipes line up, and reformatted code inside fenced blocks whose language it knows, such as JavaScript or JSON. It left long lines of prose alone. That last point surprises people. Prettier's `proseWrap` option defaults to `preserve`, which keeps your existing line breaks as they are, because some renderers treat a line break inside a paragraph as a visible break ([Prettier options, Prose Wrap](https://prettier.io/docs/options#prose-wrap)). If you want hard-wrapped paragraphs at 80 characters, set `"proseWrap": "always"` in a `.prettierrc` file. The full set of options and the command line are covered in [How do I format markdown files with Prettier?](/markdown-formatter/format-markdown-with-prettier). To keep Prettier away from part of a file, put `` on the line before a block, or wrap a range in `` and ``. Prettier's docs say the range form needs a blank line before each comment to be recognised. ## Can I format markdown without installing anything? Yes. Paste the text into the [Markdown Formatter](/markdown-formatter), pick a list marker, emphasis character and code fence style, and copy or download the result. It parses the document with remark and prints it back, so the rendered output stays the same while the source becomes consistent. It runs in the browser, which makes it a quick md formatter for a single file on a machine where you cannot install extensions. It is not a substitute for an editor setup on a project you work on every day. A browser tool does not know your repository's config, and you have to paste the result back by hand. For a team, the durable answer is Prettier in `.vscode/settings.json` plus the same Prettier version in `package.json`, so the editor and your CI agree. ## Why does Format Document not change my markdown? Usually because no formatter is set for markdown, or a different one is winning. Check these in order: 1. **No default formatter.** Run **Format Document With...** and see what is listed. If only "None" or nothing useful appears, install an extension as described above. 2. **Wrong default.** The status bar shows the language mode; make sure the file is recognised as Markdown, not plain text. A `.markdown` or `.mdx` file may be mapped differently from `.md`. 3. **Ignored file.** Prettier skips files listed in `.prettierignore`. The Prettier output channel (View, Output, then choose Prettier) shows when a file was ignored. 4. **Nothing to change.** If the file already matches the formatter's style, the format runs and produces no edits. Try it on a file with mixed `*` and `-` bullets to confirm it works. When you also want to check the result for structural problems, such as duplicate headings or bare URLs, run the file through the [Markdown Lint](/markdown-lint) tool or keep the markdownlint extension enabled alongside Prettier. ## How do I format markdown files with Prettier? URL: https://docs-md.com/markdown-formatter/format-markdown-with-prettier Updated: 2026-10-20 Prettier formats markdown out of the box, with no plugin. Run `npx prettier --write "**/*.md"` from the project root to rewrite every markdown file in place, or `npx prettier --check "**/*.md"` to only report which files would change. Set `proseWrap` in a `.prettierrc` file if you want long paragraphs wrapped at a fixed width. Prettier picks its parser from the file extension, so `.md` and `.markdown` files go through its markdown printer automatically ([Prettier docs, Configuration](https://prettier.io/docs/configuration)). Unlike a linter, it has few options: you get its style, and the point is that nobody on the team argues about it again. ## How do I run Prettier on markdown from the command line? Install Prettier as a dev dependency so everyone uses the same version, then run it against your files. The Prettier docs recommend installing an exact version, because a minor release can change output. ```bash npm install --save-dev --save-exact prettier # format every markdown file in place npx prettier --write "**/*.md" # report files that are not formatted, change nothing npx prettier --check "**/*.md" # format a single file and print the result instead of saving npx prettier README.md ``` Keep the quotes around the glob. Without them your shell expands `**/*.md` before Prettier sees it, and in shells where `**` is not recursive you silently format only the top-level files. With quotes, Prettier expands the pattern itself. Prettier's CLI docs warn that `--write` overwrites files, so commit or stash your work first ([Prettier CLI](https://prettier.io/docs/cli)). `--check` exits with a non-zero status when any file needs formatting and prints a line such as "Code style issues found in the above file. Run Prettier with --write to fix." That makes it the command to put in CI. If you want just the file names, for piping to another command, use `--list-different` instead. To skip folders such as `node_modules`, generated docs or vendored content, list them in a `.prettierignore` file at the project root. It uses the same pattern syntax as `.gitignore`. ## What does Prettier change in a markdown file? It reprints the file from a parsed syntax tree, so the content stays the same and the source style becomes uniform. Running Prettier 3 on a deliberately messy test file, we saw these changes: - `*` and `+` bullets became `-`. Two separate lists placed next to each other get `-` and `*` alternately, so they do not merge into one list. - `__bold__` became `**bold**` and `*italic*` became `_italic_`. - Table cells were padded so the pipes line up, including the delimiter row. Alignment colons such as `:-:` were kept. - Code inside fenced blocks with a language Prettier knows, such as `js` or `json`, was formatted with Prettier's rules for that language. The `embeddedLanguageFormatting` option set to `"off"` disables this. - Ordered lists numbered `1. 1. 1.` stayed that way; lists numbered `1. 2. 3.` stayed incrementing. What it left alone matters as much. A setext heading (a title underlined with `=====`) stayed setext, and a long paragraph kept its original line breaks. That second point is controlled by `proseWrap`. ## What does the proseWrap option do? `proseWrap` decides whether Prettier rewraps paragraphs. It has three values, and the default is `preserve` ([Prettier options, Prose Wrap](https://prettier.io/docs/options#prose-wrap)): | Value | Effect | |---|---| | `preserve` | Keeps your line breaks exactly as written. This is the default. | | `always` | Wraps prose at `printWidth`, which defaults to 80 characters. | | `never` | Joins each paragraph onto a single line and leaves wrapping to the editor or viewer. | The docs explain why the default is hands-off: some services, such as GitHub comments, render a line break inside a paragraph as a visible break, so rewrapping could change how the text looks there. In README files and documentation sites, a single newline inside a paragraph is normally ignored and `always` is safe. There is a practical reason to choose `never` too. One line per paragraph means an edit to one sentence shows up as a one-line change in a diff, but the whole paragraph is that line, so reviewers see more. Some teams prefer `always` with a narrow width, others one sentence per line written by hand with `preserve`. Pick one and set it in config so it is not left to each editor. ## How do I configure Prettier only for markdown files? Use `overrides` in a `.prettierrc` file. This keeps your code settings untouched and applies markdown settings only to markdown: ```json { "overrides": [ { "files": ["*.md"], "options": { "proseWrap": "always", "printWidth": 80 } } ] } ``` `printWidth` only affects prose when `proseWrap` is `always`; with the default `preserve` it has no visible effect on paragraphs. Tables are always printed aligned unless `proseWrap` is `never` and the aligned table would be wider than `printWidth`, in which case Prettier falls back to a compact table with single spaces around each cell. ## How do I stop Prettier from formatting part of a file? Put `` on the line before the block you want left alone, such as a hand-aligned table or a list whose odd numbering is intentional. For a longer range, usually something another tool generates, wrap it: ```markdown | Name | Role | |-|-| | Ada | Maintainer | ``` Prettier's docs say there must be a blank line before both the start and the end comment for them to be recognised, and that the range form only works at the top level of the document ([Prettier, Ignoring Code](https://prettier.io/docs/ignore)). ## Is there a way to format markdown like this without Node? Yes, for a quick one-off. The [Markdown Formatter](/markdown-formatter) on this site is a browser md formatter built on remark, the parser and printer used throughout the unified ecosystem. Paste the file, choose `-`, `*` or `+` for bullets, `*` or `_` for emphasis and backticks or tildes for code fences, and copy the result. It also aligns table pipes and converts setext headings to `#` headings, which Prettier does not. Its output will not match Prettier byte for byte. The two printers make different default choices, and the browser tool does not format code inside fences or wrap prose. If your repository runs `prettier --check` in CI, run Prettier itself before committing so the check passes. For editor integration, see [How do I format markdown in VS Code?](/markdown-formatter/format-markdown-in-vs-code). ## Should I use Prettier with markdownlint? Yes, they solve different problems, and they work together if you avoid rules that fight. Prettier decides layout. markdownlint reports things a printer cannot fix, such as a heading level that jumps from `##` to `####`, duplicate headings, bare URLs or images without alt text. You can check those in the browser with [Markdown Lint](/markdown-lint) before setting up `markdownlint-cli2`. The one conflict to watch is line length. markdownlint's MD013 rule flags long lines, while Prettier with the default `proseWrap: preserve` will not shorten them. Either set `proseWrap: always` so Prettier wraps for you, or disable MD013 in your markdownlint config. ## What is the difference between a markdown formatter and a linter? URL: https://docs-md.com/markdown-formatter/markdown-formatter-vs-linter Updated: 2026-10-20 A formatter rewrites your markdown into one consistent style without asking: bullets, emphasis, table padding, blank lines. A linter reads the file, checks it against rules and reports problems, some of which a formatter could never fix, such as skipped heading levels or missing alt text. Use a formatter for layout and a linter for structure. The two are often confused because their outputs overlap. Both care that a file uses one bullet marker, and both can fix trailing spaces. The difference is in how they work and what they are allowed to decide. A formatter parses the file into a syntax tree and prints a new file from that tree, so it controls every byte of the output. A linter looks at the file you wrote and points at lines; it changes text only when a rule has a safe, mechanical fix. ## What does a markdown formatter do? It reprints the whole document in a fixed house style, so the rendered output stays the same and the source becomes predictable. Our [Markdown Formatter](/markdown-formatter) is built this way on remark: it parses the markdown, then prints it back with remark-stringify using the style you pick in three drop-downs, for list marker (`-`, `*` or `+`), emphasis (`*` or `_`) and code fence (backticks or tildes). In a single pass it will: - make every bullet use the chosen marker and indent nested lists consistently; - use one character for both emphasis and strong emphasis; - turn setext headings (underlined with `===` or `---`) into `#` headings; - pad table cells so the pipes line up; - collapse runs of blank lines so blocks are separated by exactly one. Prettier works the same way with fewer choices and a few extra behaviours, such as formatting code inside fenced blocks. Neither of them will tell you that your document has two H1 headings, because two H1 headings are valid markdown and print back perfectly. A formatter has no opinion about content, only about how it is written. ## What does a markdown linter do? It checks the document against a list of named rules and reports each violation with a line number. The best-known markdown linter is markdownlint, whose rules have IDs such as MD001 (heading levels should only increase by one), MD025 (a single top-level heading), MD034 (no bare URLs) and MD045 (images need alt text) ([markdownlint rules](https://github.com/DavidAnson/markdownlint#rules--aliases)). Our [Markdown Lint](/markdown-lint) tool implements 19 of these rules in the browser under the same IDs. Some rules overlap with formatting: MD004 checks list marker style, MD049 and MD050 check emphasis and strong style, MD012 flags multiple blank lines. A formatter fixes all of these as a side effect. But many rules are about meaning or accessibility, and no printer can fix them, because the fix needs a human decision: | Problem | Formatter | Linter | |---|---|---| | Mixed `*` and `-` bullets | Fixes it | Reports it (MD004), can often fix it | | Table pipes out of line | Fixes it | Reports inconsistent column style (MD060) | | Heading jumps from `##` to `####` | Leaves it | Reports it (MD001) | | Two `#` headings in one file | Leaves it | Reports it (MD025) | | Image without alt text | Leaves it | Reports it (MD045) | | Bare URL in a sentence | Leaves it | Reports it (MD034) | | Fenced code block without a language | Leaves it | Reports it (MD040) | A linter can suggest that an image needs alt text. It cannot write the alt text for you. ## Do I need both a formatter and a linter? On a project with more than a handful of markdown files, yes. The formatter removes every style argument in one command, and the linter catches the structural problems that are left. Running only a linter means people spend review time fixing bullet characters by hand. Running only an md formatter means a beautifully consistent file can still have broken heading hierarchy. The usual setup is Prettier, or another formatter, run on save in the editor and checked in CI, plus markdownlint run in CI with formatting-related rules either aligned to the formatter's style or turned off. See [How do I format markdown files with Prettier?](/markdown-formatter/format-markdown-with-prettier) for the formatter half and [How do I format markdown in VS Code?](/markdown-formatter/format-markdown-in-vs-code) for the editor setup. For a single document, such as a README you are about to publish or a block of text an AI assistant generated, you can do both steps in the browser: format it, then paste the result into the linter and fix what remains. ## Can a formatter and a linter conflict? Yes, when they enforce different choices for the same thing. Prettier writes italic text with underscores, so a markdownlint config that requires asterisks for emphasis (MD049 set to `asterisk`) will flag every file Prettier touches. The same applies to bullet style and line length. The fix is to decide which tool owns each style choice. Let the formatter own anything it can rewrite, and configure the linter to agree or disable those rules. markdownlint's default for MD004, MD049 and MD050 is `consistent`, meaning one style per file, which any formatter's output satisfies. Line length is the usual exception: MD013 flags lines over 80 characters by default, while Prettier keeps your existing line breaks unless you set `proseWrap: always`. Either turn on wrapping in Prettier or turn off MD013. ## Can a linter fix problems automatically? Partly. markdownlint marks some rules as fixable, and its command-line tool `markdownlint-cli2` applies those fixes with `--fix`; the VS Code extension applies them with Format Document or its fix-all command. Fixable rules are the mechanical ones, such as trailing spaces, missing blank lines around headings or a missing space after `#`. That is still different from formatting. A fix touches the lines that broke a rule and leaves everything else as you wrote it. A formatter rewrites the whole file, including lines that broke no rule. If you want a file that looks the same no matter who wrote it, you need the formatter. If you want to keep your own style and only remove mistakes, a linter with fixes may be enough. ## Which should I run first? Run the formatter first, then the linter. Formatting removes every finding that is purely about style, so the linter's report shrinks to the problems that need a person: heading order, alt text, bare URLs, empty links. Running them the other way round means fixing style warnings by hand that the formatter would have fixed anyway. In CI the order matters less, because both run as checks, not rewrites. Put the formatter check first so a contributor who forgot to format sees that message before a list of lint warnings that formatting would partly resolve. The [headings guide](/guides/markdown-headings) is a useful reference for the most common linter finding that formatting cannot fix. --- # Markdown cheat sheet URL: https://docs-md.com/markdown-cheat-sheet Category: Reference Updated: 2026-09-01 Every element of markdown and GFM with side-by-side syntax and rendered output — headings to footnotes to mermaid diagrams.}