{"id":2668,"date":"2020-08-04T10:02:31","date_gmt":"2020-08-04T18:02:31","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/typescript\/?p=2668"},"modified":"2020-08-04T12:48:15","modified_gmt":"2020-08-04T20:48:15","slug":"announcing-the-new-typescript-website","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/typescript\/announcing-the-new-typescript-website\/","title":{"rendered":"Announcing the new TypeScript Website"},"content":{"rendered":"<p>Hey folks, I&#39;m happy to announce that the next iteration version of the TypeScript Website has launched on <a href=\"https:\/\/www.typescriptlang.org\/\">typescriptlang.org<\/a>.<\/p>\n<p>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 <a href=\"https:\/\/www.microsoft.com\/design\/fluent\/\" rel=\"nofollow\">modern<\/a> Microsoft styles.<\/p>\n<p><img decoding=\"async\" src=\"https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2020\/08\/ts-web.png\" alt=\"New TypeScript website homepage\" width=\"1280\" height=\"640\" class=\"aligncenter size-full wp-image-2673\" srcset=\"https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2020\/08\/ts-web.png 1280w, https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2020\/08\/ts-web-300x150.png 300w, https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2020\/08\/ts-web-1024x512.png 1024w, https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2020\/08\/ts-web-768x384.png 768w\" sizes=\"(max-width: 1280px) 100vw, 1280px\" \/><\/p>\n<p>To get a sense of what people wanted, <a href=\"https:\/\/github.com\/microsoft\/TypeScript\/issues\/31983\" data-hovercard-type=\"issue\" data-hovercard-url=\"\/microsoft\/TypeScript\/issues\/31983\/hovercard\">we reached out to the community<\/a> about where they would like to see improvements and road-mapped based on that feedback.<\/p>\n<p>Community feedback generally coalesced into a few major areas:<\/p>\n<ul>\n<li>Navigation can be difficult<\/li>\n<li>The playground feels limited<\/li>\n<li>Missing or not up-to-date docs<\/li>\n<li>It&#39;s hard to read up about <code>tsconfig.json<\/code><\/li>\n<\/ul>\n<p>On top of that we wanted:<\/p>\n<ul>\n<li>A revised intro to TypeScript on the homepage<\/li>\n<li>Compiler-backed code samples<\/li>\n<li>Improved accessibility<\/li>\n<li>To support learning TypeScript in your own (human) language<\/li>\n<\/ul>\n<p>Let&#39;s go through these points and learn about how the new TypeScript website addresses them.<\/p>\n<h2>Welcome to the new TypeScript Website<\/h2>\n<p>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.<\/p>\n<p>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&#39;t have to be an all or nothing choice.<\/p>\n<p>Hopefully, the new homepage makes it easier to understand TypeScript&#39;s place in the JavaScript ecosystem.<\/p>\n<p>Also, a personal highlight from the re-design, the new TypeScript logo which more closely reflects what people use in the wild:<\/p>\n<p><a href=\"https:\/\/www.typescriptlang.org\/branding\"><img decoding=\"async\" src=\"https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2020\/08\/ts-logo-intr.png\" alt=\"TypeScript Logo Image\" width=\"800\" height=\"480\" class=\"size-full wp-image-2671\" srcset=\"https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2020\/08\/ts-logo-intr.png 800w, https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2020\/08\/ts-logo-intr-300x180.png 300w, https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2020\/08\/ts-logo-intr-768x461.png 768w\" sizes=\"(max-width: 800px) 100vw, 800px\" \/><\/a><\/p>\n<h2>New Navigation<\/h2>\n<p>We addressed a lot of site navigation issues by:<\/p>\n<ul>\n<li>Completely <a href=\"https:\/\/github.com\/microsoft\/TypeScript-Website\/issues\/130#issuecomment-560546774\" data-hovercard-type=\"issue\" data-hovercard-url=\"\/microsoft\/TypeScript-Website\/issues\/130\/hovercard\">splitting mobile vs desktop<\/a> site navigation so they are more focused on their domains<\/li>\n<li>Adding search for our documentation<\/li>\n<li>Interweaving code samples for the playground with existing documentation, making it easy to interact with ideas instead of just passively reading<\/li>\n<\/ul>\n<p>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&#39;re looking for quickly.<\/p>\n<h2>Playground v3<\/h2>\n<p>Over the past year, the playground has jumped in leaps and bounds &#45; you can find out all of the features and changes to TypeScript&#39;s interactive code explorer in it&#39;s own post coming soon.<\/p>\n<p><a href=\"https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2020\/08\/12323.jpg\"><img decoding=\"async\" src=\"https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2020\/08\/12323.jpg\" alt=\"Playground Screenshot\" width=\"1220\" height=\"659\" class=\"aligncenter size-full wp-image-2677\" srcset=\"https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2020\/08\/12323.jpg 1220w, https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2020\/08\/12323-300x162.jpg 300w, https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2020\/08\/12323-1024x553.jpg 1024w, https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2020\/08\/12323-768x415.jpg 768w\" sizes=\"(max-width: 1220px) 100vw, 1220px\" \/><\/a><\/p>\n<p>However, the summary:<\/p>\n<ul>\n<li>Sharable URLs are compressed to make sure they&#39;re not too long<\/li>\n<li>There is a comprehensive set of examples teaching TypeScript in the Playground<\/li>\n<li>Options from the <code>tsconfig.json<\/code> have explanations<\/li>\n<li>The you can resize the sidebar<\/li>\n<li>You can write in JS or TS, and see the .js or .d.ts outputs<\/li>\n<li>Errors show in the sidebar<\/li>\n<li>Types get downloaded from npm<\/li>\n<li>The Playground can be extended by <a href=\"https:\/\/www.typescriptlang.org\/dev\/playground-plugins\/\" rel=\"nofollow\">user plugins<\/a><\/li>\n<\/ul>\n<p>Here&#39;s an <a href=\"https:\/\/www.typescriptlang.org\/play?install-plugin=playground-clippy\">example<\/a> plugin which adds Clippy to the Playground:<\/p>\n<p><a href=\"https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2020\/08\/clippy2.jpg\"><img decoding=\"async\" src=\"https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2020\/08\/clippy2.jpg\" alt=\"TypeScript Playground Plugin Example\" width=\"1220\" height=\"659\" class=\"aligncenter size-full wp-image-2681\" srcset=\"https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2020\/08\/clippy2.jpg 1220w, https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2020\/08\/clippy2-300x162.jpg 300w, https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2020\/08\/clippy2-1024x553.jpg 1024w, https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2020\/08\/clippy2-768x415.jpg 768w\" sizes=\"(max-width: 1220px) 100vw, 1220px\" \/><\/a><\/p>\n<h2>Documentation<\/h2>\n<h4>Handbook v1.5<\/h4>\n<p>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:<\/p>\n<ul>\n<li><strong>Intros to TypeScript<\/strong> &#45; which help you get an understanding of the language based on different backgrounds<\/li>\n<li><strong>Handbook<\/strong> &#45; the &#39;read from a-z&#39; of TypeScript to get a better understanding of the language<\/li>\n<li><strong>Handbook Reference<\/strong> &#45; singular deep dives into a particular topic<\/li>\n<\/ul>\n<p>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.<\/p>\n<p><a href=\"https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2020\/08\/handbok.jpg\"><img decoding=\"async\" src=\"https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2020\/08\/handbok.jpg\" alt=\"Handbook example page\" width=\"1220\" height=\"659\" class=\"aligncenter size-full wp-image-2683\" srcset=\"https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2020\/08\/handbok.jpg 1220w, https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2020\/08\/handbok-300x162.jpg 300w, https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2020\/08\/handbok-1024x553.jpg 1024w, https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2020\/08\/handbok-768x415.jpg 768w\" sizes=\"(max-width: 1220px) 100vw, 1220px\" \/><\/a><\/p>\n<h4>Compiler-Checked Samples<\/h4>\n<p>We&#39;re moving more and more of our code samples to use a new <a href=\"https:\/\/github.com\/microsoft\/TypeScript-Website\/tree\/v2\/packages\/ts-twoslasher#typescript-twoslasher\">TypeScript markup format called twoslash<\/a>. 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.<\/p>\n<p><a href=\"https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2020\/08\/ts-twoslash-gif.gif\"><img decoding=\"async\" src=\"https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2020\/08\/ts-twoslash-gif.gif\" alt=\"Compiler backed code samples example\" width=\"936\" height=\"520\" class=\"aligncenter size-full wp-image-2685\" \/><\/a><\/p>\n<p>With this technique we can be certain that our code samples stay accurate and up-to-date as we work on the TypeScript compiler.<\/p>\n<h2>TSConfig Updates<\/h2>\n<p>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.<\/p>\n<p><a href=\"https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2020\/08\/tsconfig-ref-2.jpg\"><img decoding=\"async\" src=\"https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2020\/08\/tsconfig-ref-2.jpg\" alt=\"TSConfig Reference\" width=\"1220\" height=\"659\" class=\"aligncenter size-full wp-image-2694\" srcset=\"https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2020\/08\/tsconfig-ref-2.jpg 1220w, https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2020\/08\/tsconfig-ref-2-300x162.jpg 300w, https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2020\/08\/tsconfig-ref-2-1024x553.jpg 1024w, https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2020\/08\/tsconfig-ref-2-768x415.jpg 768w\" sizes=\"(max-width: 1220px) 100vw, 1220px\" \/><\/a><\/p>\n<h2>Accessibility<\/h2>\n<p>The new website has been built with accessibility in mind from day one. To give a sense of the support matrix, here&#39;s what we account for with each page:<\/p>\n<ul>\n<li>JavaScript being disabled<\/li>\n<li>Keyboard-only navigation<\/li>\n<li>Text-to-Speech users<\/li>\n<li>Cookies\/Local Storage being denied<\/li>\n<li>A focused mobile navigation design<\/li>\n<li>Light and Dark OS mode support, with a user-preference switcher<\/li>\n<\/ul>\n<h2>Localization<\/h2>\n<p>Anyone can learn to code, but adding the extra barrier of being proficient in English to master a programming language is a worry. We&#39;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.<\/p>\n<p><a href=\"https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2020\/08\/play-zh.png\"><img decoding=\"async\" src=\"https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2020\/08\/play-zh.png\" alt=\"Image play zh\" width=\"1220\" height=\"659\" class=\"aligncenter size-full wp-image-2687\" srcset=\"https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2020\/08\/play-zh.png 1220w, https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2020\/08\/play-zh-300x162.png 300w, https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2020\/08\/play-zh-1024x553.png 1024w, https:\/\/devblogs.microsoft.com\/typescript\/wp-content\/uploads\/sites\/11\/2020\/08\/play-zh-768x415.png 768w\" sizes=\"(max-width: 1220px) 100vw, 1220px\" \/><\/a><\/p>\n<p>We&#39;ve gotten far on the translations for Chinese, Japanese, Portuguese and Spanish &#45; you can see how far along they are via <a href=\"https:\/\/github.com\/microsoft\/TypeScript-website\/issues?q=is%3Aopen+is%3Aissue+label%3A%22Localization+Summary%22\">these GitHub issues<\/a>. If you&#39;re interested in helping out, come and say hi in the <a href=\"https:\/\/discord.gg\/typescript\" rel=\"nofollow\">TypeScript Community Discord<\/a>.<\/p>\n<h2>Try it today<\/h2>\n<p>The new site was started exactly <a href=\"https:\/\/github.com\/microsoft\/TypeScript-Website\/commit\/7d8d0bd6c3771f7a3f9f5951731b9b5f5d745db4\">a year ago<\/a>, getting here took over 1600 commits and received contributions from over <a href=\"https:\/\/github.com\/microsoft\/TypeScript-Website\/graphs\/contributors\">100 people<\/a>. You can read more about the motivations for how the site was designed and architected in the <a href=\"https:\/\/github.com\/microsoft\/TypeScript-Website\/issues\/130\" data-hovercard-type=\"issue\" data-hovercard-url=\"\/microsoft\/TypeScript-Website\/issues\/130\/hovercard\">&#39;Web Infra Updates&#39;<\/a> GitHub issue.<\/p>\n<p>With that said, we&#39;re always <a href=\"https:\/\/github.com\/microsoft\/TypeScript-Website\/issues\/new\/choose\">open to feedback<\/a> and there&#39;s a lot of space for improvement now that everyone can provide some fresh perspective.<\/p>\n<p>Give the new site a shot:<\/p>\n<ul>\n<li><a href=\"https:\/\/www.typescriptlang.org\/\" rel=\"nofollow\">Homepage<\/a><\/li>\n<li><a href=\"https:\/\/www.typescriptlang.org\/tsconfig\" rel=\"nofollow\">TSConfig Reference<\/a><\/li>\n<li><a href=\"https:\/\/www.typescriptlang.org\/play\" rel=\"nofollow\">Playground<\/a><\/li>\n<li><a href=\"https:\/\/www.typescriptlang.org\/docs\" rel=\"nofollow\">Docs Overview<\/a><\/li>\n<\/ul>\n<p>If you&#39;re interested in seeing the great localization work:<\/p>\n<ul>\n<li><a href=\"https:\/\/www.typescriptlang.org\/zh\" rel=\"nofollow\">Chinese Homepage<\/a><\/li>\n<li><a href=\"https:\/\/www.typescriptlang.org\/ja\/tsconfig\" rel=\"nofollow\">Japanese TSConfig Reference<\/a><\/li>\n<li><a href=\"https:\/\/www.typescriptlang.org\/es\/play\" rel=\"nofollow\">Spanish Playground<\/a><\/li>\n<li><a href=\"https:\/\/www.typescriptlang.org\/pt\/play\" rel=\"nofollow\">Portuguese TSConfig Reference<\/a><\/li>\n","protected":false},"excerpt":{"rendered":"<p>The new TypeScript website is live, with big changes to the handbook, playground and a new section covering the tsconfig.json.<\/p>\n","protected":false},"author":6925,"featured_media":1797,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[],"class_list":["post-2668","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-typescript"],"acf":[],"blog_post_summary":"<p>The new TypeScript website is live, with big changes to the handbook, playground and a new section covering the tsconfig.json.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/typescript\/wp-json\/wp\/v2\/posts\/2668","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/typescript\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/typescript\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/typescript\/wp-json\/wp\/v2\/users\/6925"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/typescript\/wp-json\/wp\/v2\/comments?post=2668"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/typescript\/wp-json\/wp\/v2\/posts\/2668\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/typescript\/wp-json\/wp\/v2\/media\/1797"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/typescript\/wp-json\/wp\/v2\/media?parent=2668"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/typescript\/wp-json\/wp\/v2\/categories?post=2668"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/typescript\/wp-json\/wp\/v2\/tags?post=2668"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}