Markdown in VS Code: What Actually Happens When You Open a File
VS Code treats Markdown as a first-class language. When you open a .md file, the editor loads syntax highlighting, an outline panel, and a preview pane by default. That is the basic setup. It works. Most people stop there. The question is what happens when you start pushing against the edges of what the extension can do. I spent three years building documentation platforms for engineering teams, and the thing nobody tells you about VS Code Markdown is that the preview renders your content inside an iframe with a stripped-down browser environment. That means certain CSS features, external scripts, and even some fonts behave differently than they do in your actual browser. I spent two days once trying to figure out why a simple table border wasn't rendering in the preview when it worked perfectly in Chrome. Turned out the preview's iframe was stripping the border-collapse property. Switching to the side-by-side preview or opening the preview in a browser fixed it. You just have to know that the preview is not your website.
Vs Markdown Languages
The terminology around "Vs Markdown Languages" usually comes up when people are trying to understand how VS Code handles different Markdown variants. Standard Markdown is straightforward, but the ecosystem includes GitHub Flavored Markdown (GFM), CommonMark, and various flavors with YAML front matter. VS Code defaults to GFM when you open a Markdown file, which means tables and strikethrough work out of the box. If you switch to CommonMark mode, those features disappear and your tables render as plain text with pipe characters. This catches people off guard every time. One thing most guides skip is that VS Code lets you configure the Markdown flavor per-project. You add a settings.json entry in your .vscode folder and point it to the flavor you actually need. I found this when a team had mixed requirements: the docs team needed GFM for GitHub rendering, but the internal wiki generator only accepted CommonMark. Before I set that per-project override, we were constantly shipping broken content because the editor was auto-converting table syntax one way and the build script expecting the other.
Setting Up the Environment
Open VS Code. Create a new file with a .md extension. That is it. The built-in Markdown language support activates automatically. No extensions required for basic use. If you want more, there are plugins, but I usually avoid them unless the project demands it. For the preview, press Ctrl+Shift+V to open the side preview, or Ctrl+K V to open it in a split view next to your editor. The split view lets you edit on one side and see changes on the other in real time. I recommend this over the full preview because it reduces context switching. You are not constantly toggling between the preview window and your editor. The outline panel appears automatically on the left sidebar when you have a Markdown file open. It pulls headings from your document and lets you jump between sections. This is useful once your files grow past 500 lines. Before that threshold, it adds noise to the interface. Disable it if you prefer a cleaner workspace.
Get the Full Details
Common Pitfalls I See People Hit
The first issue is embedded HTML. Markdown allows raw HTML, and VS Code's preview renders it, but the language server does not understand HTML inside Markdown. Autocomplete breaks, syntax highlighting gets confused, and IntelliSense stops working for the surrounding Markdown. If you are mixing significant amounts of HTML into your Markdown files, either isolate those sections in separate HTML templates or accept that you are giving up editor features in those areas. The second issue is image paths. Relative paths work fine when your project structure is flat. Once you start organizing content into subdirectories, image references break because the preview resolves paths relative to the current file, not the project root. I solved this for a documentation project by setting the markdown-preview-enhanced extension's base path to the project root, but that required installing an extension. If you want to stay extension-free, keep images in a single folder and reference them with a consistent base path like . A third problem is front matter parsing. YAML front matter at the top of a Markdown file is ignored by the standard preview. It shows as plain text in the rendered output. If your build pipeline expects front matter for metadata extraction, you need to make sure the pipeline strips it before rendering. VS Code itself does not handle this. I wrote a small preprocessor script once that removed the front matter block before passing files to the renderer. It took about twenty minutes to write and saved us from spending hours debugging why our generated HTML had a config block at the top of every page.
Extensions Worth Considering
Markdown All in One is the most commonly recommended extension, and for good reason. It adds keyboard shortcuts for bold, italic, and headings, plus automatic list continuation and table alignment. The table alignment feature alone is worth the installation. Without it, typing a markdown table means manually padding spaces so the columns line up. With it, you press Ctrl+Alt+A and the columns auto-align to the widest content in each column. Another useful extension is Markdownlint. It checks your files against a style guide and reports issues inline. The default rules are reasonable, but they can be opinionated about things like line length and heading styles. I spent a week adjusting the lint configuration for a team project because their style guide differed from the defaults. The fix was adding a .markdownlint.json file to the project root with custom rule overrides. For advanced use cases, Marked-README highlights README.md files in repository explorers. If you work with multiple Git projects, this lets you scan the quality of READMEs at a glance. It is a minor feature, but it saved me from opening a dozen repos to check documentation quality once.
When VS Code Markdown Falls Short
VS Code's Markdown support is strong for authoring but weak for publishing. The preview is a viewing tool, not a build system. If you need to generate static HTML, PDFs, or publish to a platform, you need additional tooling. Hugo, Jekyll, or MkDocs will handle the generation. VS Code is the editor, nothing more. Another limitation is collaboration. VS Code Live Share exists, but sharing a Markdown editing session with someone who does not use VS Code is friction. If your team uses different editors, stick to the common subset of Markdown features. Avoid complex table syntax or HTML embedding if you expect content to move between different rendering engines. I learned this when a design team sent back a beautifully formatted Markdown document that used GitHub-specific callout syntax. Our renderer did not support it, and the output was a mess of unclosed span tags. We switched to plain blockquotes with explicit labels instead. There is also no native version control for Markdown within VS Code beyond the standard Git integration. If you need to track changes to document content, not just file-level commits, you are on your own. I have seen people use diff tools manually for this, which is tedious for anything larger than a few paragraphs.
Practical Workflow
Here is how I structure a typical documentation project. I keep all Markdown files in a docs folder with a clear hierarchy. Headings follow a consistent pattern: one h1 per file, sequential h2s for sections, and h3s for subsections. I run markdownlint on save using the extension's auto-fix feature. Images go in a separate assets directory with a naming convention that includes the section name. Front matter is used sparingly, only for pages that require metadata like author or date. The build step runs separately. VS Code is not involved. I use a CI pipeline to render the Markdown to HTML and deploy to a static host. This separation means the editor is only concerned with content creation, and the build system handles everything else. It keeps the workflow clean and avoids the common mistake of trying to make VS Code do work it was not designed for.
