Announcing the new TypeScript Website

Orta Therox

Hey folks, I'm happy to announce that the next iteration version of the TypeScript Website has launched on typescriptlang.org.

The new version of the website was built out of a desire to make the documentation for TypeScript feel as expansive as its type-system, with a design that fits modern Microsoft styles.

New TypeScript website homepage

To get a sense of what people wanted, we reached out to the community about where they would like to see improvements and road-mapped based on that feedback.

Community feedback generally coalesced into a few major areas:

  • Navigation can be difficult
  • The playground feels limited
  • Missing or not up-to-date docs
  • It's hard to read up about tsconfig.json

On top of that we wanted:

  • A revised intro to TypeScript on the homepage
  • Compiler-backed code samples
  • Improved accessibility
  • To support learning TypeScript in your own (human) language

Let's go through these points and learn about how the new TypeScript website addresses them.

Welcome to the new TypeScript Website

We decided on the design and copy for the homepage for TypeScript 6 years ago, but things have changed quite a lot since then. TypeScript has grown up and understands what it wants to be: a type layer above JavaScript that provides great tooling support.

This focus means explaining how the team works with JavaScript standard bodies, describing how DefinitelyTyped allows TypeScript to provide types to un-typed libraries, and teaching how adoption of TypeScript doesn't have to be an all or nothing choice.

Hopefully, the new homepage makes it easier to understand TypeScript's place in the JavaScript ecosystem.

Also, a personal highlight from the re-design, the new TypeScript logo which more closely reflects what people use in the wild:

TypeScript Logo Image

New Navigation

We addressed a lot of site navigation issues by:

  • Completely splitting mobile vs desktop site navigation so they are more focused on their domains
  • Adding search for our documentation
  • Interweaving code samples for the playground with existing documentation, making it easy to interact with ideas instead of just passively reading

The sitemap has been revised (without breaking any links) to allow for more sections of documentation, the new sitemap provides a more hierarchical approach to the documentation which should make it easier to find what you're looking for quickly.

Playground v3

Over the past year, the playground has jumped in leaps and bounds - you can find out all of the features and changes to TypeScript's interactive code explorer in it's own post coming soon.

Playground Screenshot

However, the summary:

  • Sharable URLs are compressed to make sure they're not too long
  • There is a comprehensive set of examples teaching TypeScript in the Playground
  • Options from the tsconfig.json have explanations
  • The you can resize the sidebar
  • You can write in JS or TS, and see the .js or .d.ts outputs
  • Errors show in the sidebar
  • Types get downloaded from npm
  • The Playground can be extended by user plugins

Here's an example plugin which adds Clippy to the Playground:

TypeScript Playground Plugin Example

Documentation

Handbook v1.5

The new handbook has a different structure. The previous handbook was a single section of the website, the new site features a lot more documentation pages and splits the handbook into three main sections:

  • Intros to TypeScript - which help you get an understanding of the language based on different backgrounds
  • Handbook - the 'read from a-z' of TypeScript to get a better understanding of the language
  • Handbook Reference - singular deep dives into a particular topic

This split is especially helpful when starting to learn TypeScript, as it provides a focused track to learn. Then later, as you need particular techniques, there are reference docs which explore a topic in more depth.

Handbook example page

Compiler-Checked Samples

We're moving more and more of our code samples to use a new TypeScript markup format called twoslash. Twoslash code samples use the TypeScript compiler to generate accurate error messages, get compiler outputs, and query hover tooltips for quick-info. This information can then be rendered in a a static page for code samples.

Compiler backed code samples example

With this technique we can be certain that our code samples stay accurate and up-to-date as we work on the TypeScript compiler.

TSConfig Updates

One of the biggest areas for improvement was our documentation for the collection of over 100 compiler flags. The new TypeScript website includes a long-form description for every flag and examples are compiler-backed. This means we can be sure that the examples show exactly what happens when a particular config is changed.

TSConfig Reference

Accessibility

The new website has been built with accessibility in mind from day one. To give a sense of the support matrix, here's what we account for with each page:

  • JavaScript being disabled
  • Keyboard-only navigation
  • Text-to-Speech users
  • Cookies/Local Storage being denied
  • A focused mobile navigation design
  • Light and Dark OS mode support, with a user-preference switcher

Localization

Anyone can learn to code, but adding the extra barrier of being proficient in English to master a programming language is a worry. We're a small compiler team, and wanted to provide the infrastructure to enable others to localize our site. Every section of the new site is built with multi-language support in mind.

Image play zh

We've gotten far on the translations for Chinese, Japanese, Portuguese and Spanish - you can see how far along they are via these GitHub issues. If you're interested in helping out, come and say hi in the TypeScript Community Discord.

Try it today

The new site was started exactly a year ago, getting here took over 1600 commits and received contributions from over 100 people. You can read more about the motivations for how the site was designed and architected in the 'Web Infra Updates' GitHub issue.

With that said, we're always open to feedback and there's a lot of space for improvement now that everyone can provide some fresh perspective.

Give the new site a shot:

If you're interested in seeing the great localization work:

6 comments

Discussion is closed. Login to edit/delete existing comments.

  • Nickolay Platonov 0

    Congratulations, a major improvement indeed!

  • Carlos Muñoz Rodriguez 0

    The site looks amazing.
    It makes me want to read the docs again to make sure I’m up to date with the latest language additions.

  • Patrick Hintermayer 0

    The new website looks great. Personally I’d change the “Install localy” button to a more general “Get started”.
    I really like the option to easily try it in your browser and on the docs page the “TS for …” – this seems like a good and clear starting point. I could simply send a non-programmer friend the URL for “TypeScript for the New Programmer” and he could start with it.

    Are there any plans to make such a website for C#? The current situation for C# is very chaotic and not very beginner friendly in my opinion.

  • Brandon Duffany 0

    Looks great!

    FYI, The code samples on the home page don’t show up properly on mobile.

  • Mia Taylor 0

    Curious question, am I able to embed or integrate TypeScript into my WordPress website? I understand WordPress probably offers their own languages that I can’t use, and I cannot find a suitable WordPress plugin to embed TrueScript (I may have missed it however). I got a web hosting plan with https://lightyearhosting.com/ and so far so good. I am looking for a way to integrate the latest version of TrueScript into my site. Is this possible? 🙂

  • frms xgq 0

    Awesome, playground support change editor theme is also wanted! ✅

Feedback usabilla icon