microsoft/vscode-docs: the repository behind the VS Code documentation site

What vscode-docs actually owns, and what it does not

The repository is the content behind the Visual Studio Code documentation portal. Topics submitted here get published to code.visualstudio.com/docs. That boundary is the first thing to understand, because a large share of issues filed against documentation are really product defects. The README draws the line explicitly: if the problem is with VS Code itself, it belongs in the microsoft/vscode repository, and documentation bugs go to a new issue in this one after checking for duplicates.

The audience is narrow and specific. It is people who want to change what the documentation says: a writer correcting a stale page, an engineer documenting a new setting, a contributor adding release notes for a version. The README also points readers who arrived by mistake toward the product website. Nothing here runs the editor, and nothing here builds a VS Code extension. If you came looking for the editor source, the README names where it lives and this is not it.

How the content pipeline is wired: Markdown, docsify, and generated sidebars

The repository is Markdown first. Top-level directories such as docs/, api/, blogs/, learn/, release-notes/ and remote/ hold the pages, with images/ and templates/ alongside them. The structure is not decorative: the build scripts in build/ are keyed to paths, which is why lint-staged maps release-notes/v1_*.md to a table-of-contents check and image extensions to a Git LFS check.

Local preview is docsify, not a static site generator. The serve script runs the sidebar generator and then docsify serve on the repository root, which is why the preview listens on port 3000. The generate-sidebar script exists because _navbar.md and the sidebar are derived rather than hand-maintained, so a page that is not reachable from the generated structure will not appear in navigation even though the Markdown file is present. A handful of Node test scripts cover specific transformations: replace-youtube-embeds, data-variables, tabs, and release-note-toc. Those tests tell you which page constructs the maintainers consider fragile enough to guard.

Installing the repo and previewing a page locally

There is no package to install from a registry. You clone the repository, and the README is explicit that Git LFS must be enabled first if you touch binary files such as images and .gif files. Run git lfs install once per machine to set up the global hooks.

git lfs install
git clone https://github.com/microsoft/vscode-docs.git

If you only need to edit prose, the README offers a smaller clone. Setting GIT_LFS_SKIP_SMUDGE to 1 leaves the 1.6GB of images behind, and you can pull just the directories you need later.

GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/microsoft/vscode-docs.git
git lfs pull -I "docs/nodejs"

On Windows the environment variable is set through PowerShell instead, using $env:GIT_LFS_SKIP_SMUDGE="1" before the clone. The pattern passed to git lfs pull -I accepts the standard Git LFS include and exclude syntax, so docs,api downloads images across both trees.

For preview, run the two scripts from package.json at the repository root. npm install pulls docsify-cli, eslint, gulp, husky and lint-staged as dev dependencies.

npm install
npm run serve

The serve script generates the sidebar and starts docsify. The README states you then open http://localhost:3000, and that edits to Markdown files refresh the page automatically. That live reload is the practical reason to clone rather than use the Edit button on GitHub, which the README recommends only for small changes.

The Git LFS decision is the repository's real cost

Storing images in Git LFS is a reasonable choice for a documentation site with screenshots and animated GIFs, and the README quantifies the consequence: roughly 1.6GB of images. That number is the whole argument for the skip-smudge workflow. Without it, a contributor who wants to fix a sentence in a Node.js page downloads every screenshot in the repository.

The trade-off is friction in two places. First, hooks: git lfs install has to be run before binary files behave correctly, and lint-staged enforces this by running check-lfs against staged image files, so a contributor who skipped the setup step finds out at commit time rather than at clone time. Second, partial checkouts create a state where the repository looks complete but images are pointer files. That is fine for prose edits and confusing for anyone previewing a page whose screenshots have not been pulled. The README's selective pull examples (docs/nodejs, release-notes/images/1_4*/*) are the escape hatch, and they are worth reading before assuming a broken image is a rendering bug.

The repository history before LFS was adopted lives in a separate archive repository, microsoft/vscode-docs-archive, which the README links. Anyone doing archaeology on old pages needs that second clone; it is not in this one.

Publishing is manual, and the README says so plainly

This is the constraint most likely to surprise a first-time contributor. Merging a pull request does not publish it. The README states that publishing is initiated manually after changes have been reviewed on an internal staging server, and that while the intent is for updates to be live within 24 hours, there is no specific time guarantee.

Read that as a design decision rather than an oversight. A documentation site for a shipping editor benefits from a human gate between merge and the public site, especially for release notes that must not appear before a version ships. The cost is that a merged fix is not a shipped fix, and anyone coordinating a launch around a documentation change has to plan for the staging step. The README does not document rollback, so if a published page is wrong, the recovery path is not described anywhere in the repository's contributor documentation.

The workflow guidance splits by size. Small changes go through the Edit button on each page, editing the Markdown directly on GitHub. Significant changes, or anything you want to preview, go through a clone and the Markdown preview in VS Code. That split is sensible, but it means the Edit button path skips the local preview entirely, and the README does not offer a way to preview a change made that way before it is merged.

Where this repository is the wrong tool

If your goal is to change how VS Code behaves, this repository cannot help you. The README routes product issues to microsoft/vscode, and the documentation repository contains content, not editor code. Filing a behaviour bug here wastes a maintainer's time and delays your own fix.

It is also the wrong place if you want a fast, self-service publishing loop. There is no documented way to push a page live yourself; the pipeline runs through an internal staging server and manual publication. Teams that want to publish VS Code-adjacent documentation on their own schedule should host it themselves rather than upstream it here.

Finally, the repository is not a general Markdown site template. The build scripts and lint-staged rules are tied to this content: release-notes/v1_*.md gets a table-of-contents check, image extensions get an LFS check, and the sidebar is generated from this repository's structure. Reusing the tooling for an unrelated docs site means untangling those assumptions first.

How it compares to writing your own docs site

The obvious alternative is a self-hosted documentation site built on a static site generator, where you control the content, the theme, the deployment and the publication timing. The difference in approach is stark: here the Markdown is upstreamed into a Microsoft repository, navigation is generated by build/generate-sidebar.js, preview is docsify on port 3000, and publication is gated by an internal review step. You get the audience of code.visualstudio.com and you give up control of when your words appear.

A second alternative, for people who only want to read the documentation, is not to clone at all. The published site is the product; the repository is the source. Cloning makes sense when you intend to change something, preview something, or check whether a page matches the current editor behaviour before citing it.

There is no package on npm called vscode-docs that installs the documentation. The package.json in this repository exists to run the build and preview scripts, and its name field is vscode-docs with version 0.10.3. Treating it as a distributable library would be a misreading of what the file is for.

Licence and maintenance signals

The repository's licence metadata is reported as NOASSERTION, and the repository carries a LICENSE.md at the top level. Because the licence identifier is not resolved in the metadata, read LICENSE.md directly before reusing content; this article cannot tell you what terms apply, and nothing here is legal advice. Note that the README's own framing is that topics submitted here are published to the VS Code portal, which is a contribution model rather than a redistribution model.

On maintenance, the repository is not archived, and the last push was on 2026-09-21. That is a recent push, so the content is being touched. The upgrade cost for a contributor is low in dependency terms: the dev dependencies are docsify-cli, eslint, eslint-plugin-security, gulp, husky, lint-staged and shelljs, and package-lock.json pins them. The recurring cost is procedural rather than technical, and it comes from the manual publication step and the LFS handling described above.

Editorial conclusion

Adopt this repository if you are fixing a page on code.visualstudio.com, adding a release note, or writing a VS Code tutorial that has to match shipped behaviour. Do not adopt it if you want the editor source (that lives in microsoft/vscode) or if you expect a fast merge-to-live loop, because publishing is manual after an internal staging review and the README gives no fixed time guarantee. Before you spend time on a large edit, open an issue first, and check the pull request against the build scripts that apply to it: check-release-note-toc for release-notes/v1_*.md and check-lfs for image changes.

Frequently asked questions

Official sources

1. Issues
2. microsoft/vscode-docs on GitHub
3. Project website
4. README