Workspace Wiki is a VS Code extension that scans your workspace for documentation files (Markdown, MDX, and plain text by default) and presents them in a sidebar tree view for fast preview and editing. It emphasizes readability, predictable ordering (README/index handling, alphabetical directories), and fast access via preview or edit. All operations are local-first and privacy-friendly.
- Workspace Wiki Tree View: Discover all documentation files in a single sidebar tree.
- Smart and Human Readable Title Display: Automatically converts file names (e.g.,
user-guide.md) to readable titles (User Guide) - YAML Front Matter Support: Markdown and MDX files with YAML front matter
titlefields display that title instead of the filename - Flexible File Types: Supports
.md,.mdx,.txtand other files with configurable extension filtering - Include Files by Name: Pull in individual documentation files such as
doc.goby name or pattern, without showing every file that shares their extension - Intelligent Ordering: README files appear first, index files represent their folders, alphabetical sorting for others
- Acronym Case Preservation: Technical terms like HTML, CSS, API maintain proper casing in titles.
- Intelligent File Exclusion: Respects
.gitignorepatterns, including nested files and negation rules, plus configurable exclude globs to hide unwanted files. - Preview & Edit: By default, single-click opens the best surface for the file type (
workspaceWiki.defaultOpenMode: "preview"), and double-click opens the source in the full editor. - Wiki Site: Open your docs as a documentation site in an editor tab, with a navigation tree, breadcrumbs, an "On this page" outline, and full-text search. Markdown (with Mermaid diagrams), HTML, source files, and images are rendered; the header shows your workspace name and logo. Works in VS Code for the Web too.
- Refresh: Update the tree on demand with the Refresh action; it also re-scans automatically when
workspaceWikisettings change. - Configurable: Supported file types, excludes, open modes, and title formatting are configurable via settings.
- Multi-root Support: Works with multi-root workspaces, scoping each folder's
.gitignorerules and search depth to that folder. - Privacy: No telemetry, no cloud sync, local-only by default.
- VS Code 1.105.0+
This extension contributes the following settings under the workspaceWiki namespace:
Array of file extensions to include in the workspace wiki (default: md, markdown, mdx, txt).
Special Case: If md, markdown, or mdx is included, files named README (with no extension, case-insensitive) are also included and treated as Markdown.
{
"workspaceWiki.supportedExtensions": ["md", "markdown", "mdx", "txt", "html", "pdf"]
}File names or glob patterns to include in addition to supportedExtensions (default: none). Use this when a single file is documentation but its extension is not: adding go to supportedExtensions would show every Go source file, while doc.go here shows only that file.
A pattern containing no / matches at any depth; a pattern with a / is matched as written.
{
"workspaceWiki.includeGlobs": ["doc.go", "*.guide.ts", "docs/notes/*.adoc", "CHANGELOG"]
}Included files are filtered exactly like extension matches: excludeGlobs, .gitignore, the hidden-file rule, and maxSearchDepth all still apply. Their titles come from the file name, since front matter is read only from Markdown and MDX files.
Glob patterns to exclude from scanning (default: **/node_modules/**, **/.git/**). Your list replaces the default rather than adding to it, so include the default patterns in your list if you still want them applied. Files listed in your .gitignore files are also left out unless workspaceWiki.showIgnoredFiles is true.
{
"workspaceWiki.excludeGlobs": [
"**/node_modules/**",
"**/.git/**",
"**/dist/**",
"**/build/**",
"**/coverage/**",
"**/.next/**"
]
}Maximum folder depth to scan (default: 10). If you have a large repository, you may want to adjust this value to best suit your performance needs and workspace/codebase structure.
{
"workspaceWiki.maxSearchDepth": 15
}Show files listed in .gitignore and excludeGlobs (default: false).
workspaceWiki.showHiddenFiles
Show hidden files and folders (those starting with a dot, e.g. .github, .env) in the Workspace Wiki tree (default: false).
Default mode for opening files: "preview" or "editor" (default: "preview").
Commands to use for opening different file types. This supports adding other extensions' commands for specialized previews.
Any extension you add here that is not already in supportedExtensions is added to it, and the updated list is written to your workspace settings.
{
"workspaceWiki.openWith": {
"md": "workspace-wiki.openMarkdown",
"markdown": "workspace-wiki.openMarkdown",
"mdx": "workspace-wiki.openMarkdown",
"txt": "vscode.open",
"pdf": "vscode.open",
"html": "otherExtension.preview"
}
}workspace-wiki.openMarkdown is the default for Markdown, and picks the best surface the running VS Code offers:
- Markdown Editor: VS Code's built-in rendered, in-place-editable Markdown surface, added in VS Code 1.131. It claims
.mdfiles, and from VS Code 1.146.markdownand other Markdown extensions too. - Markdown Preview (
markdown.showPreview), used for files the Markdown Editor does not claim, such as.mdxand an extensionlessREADME, and on any VS Code that predates the Markdown Editor. - A plain open (
vscode.open), which follows whatever yourworkbench.editorAssociationssays, when neither of the above is available.
To always use the read-only preview instead, set the extensions you care about back to markdown.showPreview:
{
"workspaceWiki.openWith": {
"md": "markdown.showPreview"
}
}How to sort files and folders within directories. Options are:
files-first: Show files before foldersfolders-first: Show folders before filesalphabetical: Sort files and folders alphabetically
{
"workspaceWiki.directorySort": "folders-first"
}Array of acronyms to preserve proper casing in file titles.
{
"workspaceWiki.acronymCasing": [
"HTML",
"CSS",
"JS",
"TS",
"API",
"URL",
"JSON",
"XML",
"HTTP",
"HTTPS",
"REST",
"SQL",
"CSV",
"FHIR"
]
}Automatically reveal the active file in the Workspace Wiki tree when the editor changes (default: true).
Delay in milliseconds before revealing the active file in the tree (default: 500).
{
"workspaceWiki.autoRevealDelay": 1000
}Look of the Wiki Site (default: vscode, which follows your colour theme). paper is light with a blue accent, slate is dark, and lagoon is light under a teal header. High-contrast colour themes always use vscode.
Stylesheets, as paths relative to the first workspace folder, loaded after the theme (default: none). Override the --wiki-* variables on .wiki to restyle the site:
{
"workspaceWiki.site.customCss": ["docs/wiki.css"]
}.wiki {
--wiki-accent: #8a3ffc;
--wiki-content-width: 52rem;
}Image shown beside the workspace name in the site header and on its tab, relative to the first workspace folder (default: empty). When empty, the site uses a favicon, logo, icon, or apple-touch-icon file it finds in the workspace, such as public/favicon.ico or favicon-32x32.png.
VS Code can only draw .svg, .png, .jpg, .gif, or .webp images on a tab, so an .ico appears in the header only, and the tab uses one of those images if the workspace has one. Without one, or when the workspace is not on a local or remote file system, as in VS Code for the Web, the tab shows the Workspace Wiki icon.
Click the book icon in the Workspace Wiki view's title bar, or run Workspace Wiki: Open Wiki Site, to read your docs as a site. Right-click a file in the sidebar and choose Open in Wiki Site to open it there.
- Navigate: click a page to read it; middle-click or Ctrl/Cmd+click to open it in a new tab; double-click it in the navigation to edit its file.
- Search: press
/or Ctrl/Cmd+K, type to jump to a page by title, or press Enter to search the text of every page. - Open the file: use Open preview or Edit source under the page title, or right-click a page for Open in New Tab, Open to the Side, Open Original File, Edit Source, and Copy Relative Path.
- External links: a click opens the link the way VS Code opens external links, normally in your default browser; a middle click on a web link opens it in a new tab of VS Code's integrated browser, or the Simple Browser where VS Code has no integrated browser, and otherwise in your default browser.
PDFs, Office documents, and other binary files are not rendered; their page offers to open the file in its own editor.
Enjoy using Workspace Wiki!