TypeScript-wiki: the git mirror behind the TypeScript wiki

A repository that mirrors the wiki in both directions

The TypeScript wiki has its own editing interface on GitHub, which is convenient for small changes and unhelpful for anything larger. TypeScript-wiki exists so the same content can be edited as files in a git repository, with pull requests, review and history.

The repository states that it is a mirror of the wiki and that changes on either side are immediately mirrored to the other. That means the workflow is genuinely two-way: a pull request merged here shows up on the wiki, and an edit made on the wiki appears in this repository as well.

The content is broad. The root of the repository holds pages such as Architectural-Overview.md, Compiler-Internals.md, Compiler-Options.md, Common-Errors.md, Triage.md.md, Nightly-drops.md, Performance.md, Performance-Tracing.md, JSX.md, Using-the-Compiler-API.md and TypeScript's-Release-Process.md, alongside the wiki root Home.md. There is no build output and no runtime. The subject matter ranges from compiler internals and API breaking changes to tooling notes, so the audience is contributors and maintainers who need to write or correct long-form technical documentation about TypeScript, rather than developers looking up a compiler flag.

Two GitHub Actions and a sync script keep the copies equal

The mirroring is implemented by three pieces. The README points to a GitHub Action in this repository at .github/workflows/sync.yml, another one in the TypeScript repository itself at .github/workflows/sync-wiki.yml, and says the main work is done by a sync script under .github/workflows/sync.

Two actions are needed because the wiki and the repository live in different places: the wiki is a separate Git repository attached to the GitHub wiki interface, while the content here sits in the normal repository. Each side has a job that pushes to the other, and the sync script is the code both of them call.

The package metadata shows what the wiki repository itself relies on: markdown-magic for the build step, the TypeScript compiler package pinned to latest, glob, and escape-regex-string. The build script runs markdown-magic across the markdown files, and the lint script runs a node script called convertRelativeLinksToHardcoded.js over the same files.

That lint script is the one that matters most to a contributor, and the README ties it to the custom link syntax described below.

Previewing a page locally with gollum

The README explains that you can run the wiki locally if you have Ruby installed. The setup is a gem install followed by the server:

# Install the deps
gem install gollum

# Start the server
gollum

Once the server is up, the wiki can be opened at http://localhost:4567. Since the pages are plain markdown files in a git repository, gollum renders them with the same engine the wiki uses, so what you see locally is close to what a reader will see after the change is merged and mirrored.

This is the tutorial path for a contributor: clone this repository, install gollum, start it, edit a markdown file, and read the result locally before opening a pull request against the main branch. The alternative is to edit the page on the wiki itself, which the mirroring takes care of pushing back into this repository, but with no local preview and no branch.

Amending a commit and pinning gollum to a branch

The README is candid about the tooling. It says gollum is a bit of a nightmare for testing, and describes the technique the author uses: create a branch for the piece of work, then iterate by amending the commit and re-running gollum against that branch.

# before
git branch -b thing_i_am_working_on

# to iterate, amend the commit and re-run gollum against that bit of git
git add .; git commit --amend --no-edit --no-verify; gollum --ref thing_i_am_working_on

The mechanics are worth understanding. gollum is pointed at a specific git ref with the --ref flag, so the server shows the tree as of that branch rather than the current checkout, and the amend keeps a single work in progress commit instead of a stack of small ones. The --no-verify flag skips hooks during those throwaway commits.

The limitation is real and stated: this workflow is not pleasant, and each preview means a commit and a server restart. For a documentation change that touches one paragraph, editing the wiki page directly and letting the sync action push it into the repository is faster.

Flat filenames and a link syntax that reaches into the compiler source

Two constraints shape what a page can look like.

The first is the file system. Wikis do not support nesting, so filenames have to get a bit wild, and the README shows the shape of the change with a diff between a nested name and a flat one:

- compiler/testing/fourslash.md
+ compiler-testing-fourslash.md

Any page that wants a directory-like organisation has to encode it in the name, and renaming a page means renaming the file.

The second constraint is a custom link syntax for referencing TypeScript code, which is looked up at deploy time:

link to [`runFourSlashTest`][0]

[0]: <src/harness/fourslash.ts - function runFourSlashTest(>

The engine looks for the file src/harness/fourslash.ts in the microsoft/TypeScript repository, finds the line matching the given text and produces a direct link to it in the wiki. The value is that a link cannot rot silently, since it points at real source, and the cost is that it depends on the compiler repository keeping that exact text. The README says these links can be audited with the script npm run lint, which is the same convertRelativeLinksToHardcoded.js script registered in package.json.

Licensing splits documentation from code

The legal notices grant two different licences. Microsoft and contributors license the documentation and other content in the repository under the Creative Commons Attribution 4.0 International Public License, pointed at the LICENSE file, and license any code in the repository under the MIT License, pointed at LICENSE-CODE.

That split is worth knowing if you want to quote a page in a slide deck or copy a script from the repository. Documentation text is attribution-licensed, so reuse needs a credit line, while code can be reused under MIT terms. The notices also state that the licences do not grant rights to use Microsoft names, logos or trademarks, and that other rights are reserved by Microsoft and contributors.

Contributions go through a Contributor License Agreement. The README states that most contributions require agreeing to a CLA declaring the right to grant the rights to use the contribution, with the details at cla.microsoft.com. When a pull request is submitted, a CLA bot checks whether the contributor needs to sign and decorates the pull request accordingly, and the author only has to do it once across all repositories using the same CLA. The project has also adopted the Microsoft Open Source Code of Conduct.

Where the mirror is the wrong tool

The obvious limit is that this repository is documentation infrastructure, not a place for compiler questions. The pages it holds describe the TypeScript compiler, the language service and the release process, but the wiki is not where behaviour is defined, and a page describing a compiler option is a description of something rather than the thing itself.

A second limit is structural. Because the wiki cannot nest, a large reorganisation of the documentation is expensive here: every page involved needs a new flat name, and every inbound reference has to follow. The convertRelativeLinksToHardcoded.js lint script and the markdown-magic build exist to keep references honest, but they cannot decide how the content should be restructured.

A third limit is the tooling itself. Running the wiki locally needs Ruby and gollum, and the README describes the iteration loop as awkward enough to need a specific workaround with git commit --amend and gollum --ref. For a one-paragraph correction, editing on the wiki and letting the sync action mirror it back is the faster path, and the two-way mirror means the pull request path is optional rather than mandatory.

An active mirror without a release cadence

The repository is not archived and the last push was on 2026-10-06, so the content is still being worked on. There are no GitHub releases, which is expected for a documentation mirror and means there is no version history to track beyond the git log of each page.

What changes in practice is the set of files at the root. The listing shows pages for areas that shift over time, including Nightly-drops.md, API-Breaking-Changes.md, Breaking-Changes.md and TypeScript's-Release-Process.md, and pages tied to specific tooling contexts such as Updating-TypeScript-in-Visual-Studio-2017.md. A contributor who edits an old page may find that the tool it describes has been superseded, and that check belongs to them.

The upgrade cost for a reader is therefore close to zero, since the wiki is read in place, and the cost for a contributor is a small one: keep the flat naming convention, keep the source link syntax valid, and run npm run lint before sending the pull request.

Editorial conclusion

TypeScript-wiki fits contributors who want to change a TypeScript wiki page through a reviewed pull request and preview it locally with gollum before submitting, and it is the only route that gives that review trail. It does not fit anyone who just wants a page edited quickly, because the same content can be changed directly on the wiki and mirrored back automatically, and its tooling punishes large reorganisations since filenames must stay flat. Before opening a pull request, run npm run lint to audit the source-code link syntax and confirm your page does not rely on nested directories.

Frequently asked questions

Official sources

1. Issues
2. License: CC-BY-4.0
3. microsoft/TypeScript-wiki on GitHub
4. Project website
5. README