Release Lit v3 pre-release docs with blog post (#1116)

* Copy over all unversioned content into a versioned directory

The only file changed in the move is the root `docs.json` file. Instead
a `v2.json` file was added.

* Add initial build-unversioned-docs script.

This copies over and adds the correct permalinks to the selected
version content. Currently moving `v2` -> `unversioned`.

* Fix wireit so npm run dev doesnt spin infinitely.

* Add rel=canonical link from latestVersion to unversioned page.

* Make all authored cross links versioned.

Unversioned links will be generated automatically by the generated
unversioned pages.

* Add fixUnversionedCrossLinks so unversioned cross-linking work.

This works by piping all the content through a function that will
fix cross links on unversioned pages.

* Add integration tests checking added features.

* unblock failing link by adding it to the known good list.

* Fix api shortcode such that it uses a versioned URL

The versioned URL is stripped for unversioned URLs by our tooling.

Add a test to confirm this behavior.

* Apply code review feedback. Thank you!

* Code review feedback from Justin

 - Replaced sync fs with async fs.
 - Made lightweight YAML parser more robust using regex.

* Add undiscoverable v3 generated documentation.

Currently the Lit 3 commit being used is
d04a3e30eb3ae3520fb0ac163fb5ddbbf6030620 because
lit/lit#3894 fixes building Lit 3.

API docs are visible at /docs/api/v3/

* Explicitly bump node heap size.

This will hopefully avoid the Github Actions failures.

* Add types/codemirror to fix TS 5 error.

Thank you Augustine! Re-ran generator with no content changes.

* Remove unneeded dependency

Co-authored-by: Augustine Kim <[email protected]>

* Code review feedback with Wireit env.

* Fix formatting & filter out v3/api/index.html page

* Copy over v2 docs to v3 unchanged.

* Add banner and config

* Fix all cross links in v3 docs to be v3 specific.

 - Find replace all /v2/ with /v3/
 - Replace api shortcode with api-v3 shortcode - linking to v3 api docs

* Add Lit 3.0 upgrade guide - first attempt.

* Add v3 to the Lit.dev dropdown.

* Upstream ssr client-usage docs to v3 page.

This makes the page a duplicate of the v2 page. Git for some reason did
not include these changes when merging from main.

* Remove pre-release v3 docs from search index

* Add version links so that v2 <-> v3 changing doesnt change page.

A user on v2 docs for a certain page should remain on that page when
switching to v3 and vice-versa. This change makes it so switching
between v2 and v3 will keep you on the same page, but provide the
different versions of the page.

Tested manually on every single page.

* Update tools section for v3 (#1118)

* Update tools section for v3

* Better wording for versions tested

* Add pre-releases banner content to v3 banner.

* Update packages/lit-dev-content/site/docs/v3/releases/upgrade.md

Co-authored-by: Augustine Kim <[email protected]>

* Update packages/lit-dev-content/site/docs/v3/releases/upgrade.md

Co-authored-by: Augustine Kim <[email protected]>

* Lit 3.0 pre-releases blog post (#1115)

* Lit 3.0 pre-releases blog post

* Apply suggestions from code review

* Add link to upgrade guide

---------

Co-authored-by: Augustine Kim <[email protected]>

* Remove a small paragraph that didn't really make sense from upgrade.

* Add missing word "can".

* Fix blog dropdown referring 3.0 -> v3

---------

Co-authored-by: Augustine Kim <[email protected]>
Co-authored-by: Justin Fagnani <[email protected]>

Author: 3 people

packages/lit-dev-content/.eleventy.js

@@ -445,6 +445,14 @@ ${content}
     });
   };
 
+  addApiShortcode(
+    'api-v3',
+    '/docs/v3/api',
+    JSON.parse(
+      fsSync.readFileSync('../lit-dev-api/api-data/lit-3/symbols.json', 'utf8')
+    )
+  );
+
   addApiShortcode(
     'api',
     '/docs/v2/api',

packages/lit-dev-content/site/_includes/default.html

@@ -28,8 +28,10 @@
     {% endif %}
     {% inlinejs "global/dsd-polyfill.js" %}
 
-    {% if selectedVersion !== latestVersion %}
+    {% if selectedVersion == "v1" %}
       <link rel="canonical" href="{{ versions[latestVersion].path }}/{{ versionLinks[latestVersion] }}">
+    {% endif %}
+    {% if selectedVersion !== latestVersion %}
       {% inlinejs "components/litdev-banner.js" %}
     {% endif %}
 
@@ -65,12 +67,17 @@
 
     {% include 'header.html' %}
 
-    {% if selectedVersion !== latestVersion %}
+    {% if selectedVersion !== latestVersion and selectedVersion !== "v3"  %}
       <litdev-banner>
         You're viewing docs for an older version of Lit. Click
         <a href="{{ versions[latestVersion].path }}/{{ versionLinks[latestVersion] }}">
         here</a> for the latest version.
       </litdev-banner>
+    {% elif selectedVersion === "v3" %}
+      <litdev-banner>
+        You're viewing docs for a pre-release version of Lit. Read the Lit 3.0 pre-releases
+        announcement <a href="/blog/2023-05-15-lit-3.0-prerelease/">here</a>.
+      </litdev-banner>
     {% endif %}
 
     <main {% if not page.url.includes('/docs/')

packages/lit-dev-content/site/blog/2023-05-15-lit-3.0-prerelease.md

@@ -0,0 +1,66 @@
+---
+tags: blogPosts
+layout: blog-post.html
+title: "Announcing Lit 3.0 Pre-releases"
+summary: "Get an early look at the upcoming Lit 3.0 release."
+date: 2023-05-15
+author:
+  - justin-fagnani
+---
+
+# Announcing Lit 3.0 Pre-releases
+
+The Lit team is excited to announce the first pre-releases of Lit 3.0!
+
+Lit 3.0 is our first major version since [introducing the unified Lit project and Lit 2.0](https://lit.dev/blog/2021-04-21-lit-2.0-meet-lit-all-over-again/) two years ago. We really value stability and backwards compatibility for our community, so we've focused on adding new features with minor versions of the core libraries and new labs packages, and not making any breaking changes.
+
+But the time is right for just a few breaking changes that will improve development velocity and testing stability on the core Lit project.
+
+## Changes
+
+Lit 3.0 adds no new features, because new features are generally not breaking changes and can be added in minor versions, according to semver. The Lit 3.0 release is an opportunity to make a few breaking changes that trim out some technical debt to unlock new features we have scheduled for our 3.x release series.
+
+The Lit 3.0 changes are mostly in browser support, removing deprecated APIs, and how packages are published. If you run Lit 2.x with no deprecation warnings, this should be a seamless upgrade!
+
+Here are the biggest things Lit 3.0 changes:
+- IE11 is no longer supported.
+- Lit's npm modules are now published as ES2021.
+- APIs deprecated during the Lit 1.x release timeframe have been removed.
+- SSR hydration support modules were moved to the `@lit-labs/ssr-client` package.
+
+A preview of the [Lit v2 to v3 upgrade guide](/docs/v3/releases/upgrade/) is available on the site.
+
+Detailed change logs can be found [on GitHub](https://github.com/lit/lit/releases?q=%22-pre.0%22&expanded=true).
+
+## Trying the Pre-releases
+
+We would love your help testing the new versions, to ensure a smooth upgrade process with the final releases. We're especially interested in making sure the new language version works with your toolchains. We expect some users may need to upgrade their tooling to the latest versions.
+
+You can try the pre-releases out by updating your package.json file to include the following:
+
+```json
+  "lit": "^3.0.0-pre.0"
+  "lit-html": "^3.0.0-pre.0"
+  "lit-element": "^4.0.0-pre.0"
+  "@lit/reactive-element": "^2.0.0-pre.0"
+```
+
+You can also use the `pre` npm tag, like `npm i lit@pre`.
+
+All other packages, like labs packages, have pre-release versions too that depend on the pre-release core libraries. If you depend on those you'll have to update them too. If you're more daring you can use npm overrides to select the pre-releases even for dependencies. This should work for most dependencies.
+
+Even if dependencies are using Lit 2.x, the good news is that Lit 2.x and Lit 3.x are interoperable, because:
+1. The inherent interoperability web components: components built with different libraries work together, including those build with different versions of Lit.
+2. We made interop of core features like templates and directives a priority for Lit 2. You can share templates, directives, decorators, etc., across Lit versions.
+
+## Docs
+
+We are preparing new docs for 3.0 on [lit.dev](https://lit.dev). Even though these will be mostly the same as 2.x, we are clarifying the browser and toolchain support, and want to make it easy to select the right docs set for the version you're using to enable future changes specific to to 3.x. At the 3.0 launch, we’ll archive the 2.x docs (but they will remain available in the doc version dropdown, as will 1.x). During the 3.0 pre-release phase, 2.x will remain the default, and you can select v3 from the dropdown next to the Documentation tab.
+
+## Feedback
+
+We hope you enjoy Lit 3.0! If you have questions or feedback, please let us know in [GitHub issues](https://github.com/lit/lit/issues) or on our [Lit and Friends Discord](https://lit.dev/discord/).
+
+**Thanks!,**
+
+**-The Lit Team**

packages/lit-dev-content/site/docs/v2/components/decorators.md

@@ -6,6 +6,7 @@ eleventyNavigation:
   order: 8
 versionLinks:
   v1: components/decorators/
+  v3: components/decorators/
 ---
 
 Decorators are special functions that can modify the behavior of classes, class methods, and class fields. Lit uses decorators to provide declarative APIs for things like registering elements, reactive properties, and queries.

packages/lit-dev-content/site/docs/v2/components/defining.md

@@ -6,6 +6,7 @@ eleventyNavigation:
   order: 1
 versionLinks:
   v1: components/templates/
+  v3: components/defining/
 ---
 
 Define a Lit component by creating a class extending `LitElement` and registering your class with the browser:

packages/lit-dev-content/site/docs/v2/components/events.md

@@ -6,6 +6,7 @@ eleventyNavigation:
   order: 7
 versionLinks:
   v1: components/events/
+  v3: components/events/
 ---
 
 Events are the standard way that elements communicate changes. These changes typically occur due to user interaction. For example, a button dispatches a click event when a user clicks on it; an input dispatches a change event when the user enters a value in it.

packages/lit-dev-content/site/docs/v2/components/lifecycle.md

@@ -6,6 +6,7 @@ eleventyNavigation:
   order: 5
 versionLinks:
   v1: components/lifecycle/
+  v3: components/lifecycle/
 ---
 
 Lit components use the standard custom element lifecycle methods. In addition Lit introduces a reactive update cycle that renders changes to DOM when reactive properties change.

packages/lit-dev-content/site/docs/v2/components/overview.md

@@ -6,6 +6,7 @@ eleventyNavigation:
   order: 0
 versionLinks:
   v1: components/templates/
+  v3: components/overview/
 ---
 
 A Lit component is a reusable piece of UI. You can think of a Lit component as a container that has some state and that displays a UI based on its state. It can also react to user input, fire events—anything you'd expect a UI component to do. And a Lit component is an HTML element, so it has all of the standard element APIs.

packages/lit-dev-content/site/docs/v2/components/properties.md

@@ -6,6 +6,7 @@ eleventyNavigation:
   order: 3
 versionLinks:
   v1: components/properties/
+  v3: components/properties/
 ---
 
 Lit components receive input and store their state as JavaScript class fields or properties. *Reactive properties* are properties that can trigger the reactive update cycle when changed, re-rendering the component, and optionally be read or written to attributes.

packages/lit-dev-content/site/docs/v2/components/rendering.md

@@ -6,6 +6,7 @@ eleventyNavigation:
   order: 2
 versionLinks:
   v1: components/templates/
+  v3: components/rendering/
 ---
 
 Add a template to your component to define what it should render. Templates can include _expressions_, which are placeholders for dynamic content.

packages/lit-dev-content/site/docs/v2/components/shadow-dom.md

@@ -6,6 +6,7 @@ eleventyNavigation:
   order: 6
 versionLinks:
   v1: components/templates/#accessing-nodes-in-the-shadow-dom
+  v3: components/shadow-dom/
 ---
 
 Lit components use [shadow DOM](https://developers.google.com/web/fundamentals/web-components/shadowdom) to encapsulate their DOM. Shadow DOM provides a way to add a separate isolated and encapsulated DOM tree to an element. DOM encapsulation is the key to unlocking interoperability with any other code—including other web components or Lit components—functioning on the page.

packages/lit-dev-content/site/docs/v2/components/styles.md

@@ -6,6 +6,7 @@ eleventyNavigation:
   order: 4
 versionLinks:
   v1: components/styles/
+  v3: components/styles/
 ---
 
 Your component's template is rendered to its shadow root. The styles you add to your component are automatically _scoped_ to the shadow root and only affect elements in the component's shadow root.

packages/lit-dev-content/site/docs/v2/composition/component-composition.md

@@ -4,6 +4,8 @@ eleventyNavigation:
   parent: Composition
   key: Component composition
   order: 2
+versionLinks:
+  v3: composition/component-composition/
 ---
 
 The most common way to handle complexity and factor Lit code into separate units is _component composition_: that is, the process of building a large, complex component out of smaller, simpler components. Imagine you've been tasked with implementing a screen of UI:

packages/lit-dev-content/site/docs/v2/composition/controllers.md

@@ -4,6 +4,8 @@ eleventyNavigation:
   parent: Composition
   key: Controllers
   order: 4
+versionLinks:
+  v3: composition/controllers/
 ---
 
 Lit 2 introduces a new concept for code reuse and composition called _reactive controllers_.

packages/lit-dev-content/site/docs/v2/composition/mixins.md

@@ -4,6 +4,8 @@ eleventyNavigation:
   parent: Composition
   key: Mixins
   order: 3
+versionLinks:
+  v3: composition/mixins/
 ---
 
 Class mixins are a pattern for sharing code between classes using standard JavaScript. As opposed to "has-a" composition patterns like [reactive

packages/lit-dev-content/site/docs/v2/composition/overview.md

@@ -4,6 +4,8 @@ eleventyNavigation:
   parent: Composition
   key: Overview
   order: 1
+versionLinks:
+  v3: composition/overview/
 ---
 
 Composition is a strategy for managing complexity and organizing code into reusable pieces. Lit provides a few options for composition and code reuse:

packages/lit-dev-content/site/docs/v2/data/context.md

@@ -5,6 +5,8 @@ eleventyNavigation:
   parent: Managing Data
   order: 1
   labs: true
+versionLinks:
+  v3: data/context/
 ---
 
 {% labs-disclaimer %}

packages/lit-dev-content/site/docs/v2/frameworks/react.md

@@ -5,6 +5,8 @@ eleventyNavigation:
   parent: Frameworks
   order: 1
   labs: true
+versionLinks:
+  v3: frameworks/react/
 ---
 
 {% labs-disclaimer %}

packages/lit-dev-content/site/docs/v2/getting-started.md

@@ -6,6 +6,7 @@ eleventyNavigation:
   order: 3
 versionLinks:
   v1: getting-started/
+  v3: getting-started/
 ---
 
 There are many ways to get started using Lit, from our Playground and interactive tutorial to installing into an existing project.

packages/lit-dev-content/site/docs/v2/index.md

@@ -6,6 +6,7 @@ eleventyNavigation:
   order: 1
 versionLinks:
   v1:
+  v3:
 ---
 
 ![Lit Logo]({{ site.baseurl }}/images/logo.svg){.logo width="425" height="200"}

packages/lit-dev-content/site/docs/v2/libraries/labs.md

@@ -5,6 +5,8 @@ eleventyNavigation:
   parent: Related libraries
   order: 3
   labs: true
+versionLinks:
+  v3: libraries/labs/
 ---
 
 Lit Labs is an umbrella for Lit packages under development that we are actively seeking feedback on. While we encourage real-world use in order to help the feedback process, please note:

packages/lit-dev-content/site/docs/v2/libraries/standalone-templates.md

@@ -4,6 +4,8 @@ eleventyNavigation:
   key: Standalone lit-html
   parent: Related libraries
   order: 1
+versionLinks:
+  v3: libraries/standalone-templates/
 ---
 
 Lit combines the component model of LitElement with JavaScript template literal-based rendering into an easy-to-use package. However, the templating portion of Lit is factored into a standalone library called `lit-html`, which can be used outside of the Lit component model anywhere you need to efficiently render and update HTML.

packages/lit-dev-content/site/docs/v2/localization/best-practices.md

@@ -4,6 +4,8 @@ eleventyNavigation:
   key: Best practices
   parent: Localization
   order: 5
+versionLinks:
+  v3: localization/best-practices/
 ---
 
 

packages/lit-dev-content/site/docs/v2/localization/cli-and-config.md

@@ -4,6 +4,8 @@ eleventyNavigation:
   key: CLI and config
   parent: Localization
   order: 4
+versionLinks:
+  v3: localization/cli-and-config/
 ---
 
 ## CLI

packages/lit-dev-content/site/docs/v2/localization/overview.md

@@ -4,6 +4,8 @@ eleventyNavigation:
   key: Overview
   parent: Localization
   order: 1
+versionLinks:
+  v3: localization/overview/
 ---
 
 Localization is the process of supporting multiple languages and regions in your

packages/lit-dev-content/site/docs/v2/localization/runtime-mode.md

@@ -4,6 +4,8 @@ eleventyNavigation:
   key: Runtime mode
   parent: Localization
   order: 2
+versionLinks:
+  v3: localization/runtime-mode/
 ---
 
 In Lit Localize runtime mode, one JavaScript or TypeScript module is generated

packages/lit-dev-content/site/docs/v2/localization/transform-mode.md

@@ -4,6 +4,8 @@ eleventyNavigation:
   key: Transform mode
   parent: Localization
   order: 3
+versionLinks:
+  v3: localization/transform-mode/
 ---
 
 In Lit Localize transform mode, a separate folder is generated for each locale.

packages/lit-dev-content/site/docs/v2/releases/upgrade.md

@@ -4,6 +4,8 @@ eleventyNavigation:
   key: Upgrade guide
   parent: Releases
   order: 3
+versionLinks:
+  v3: releases/upgrade/
 ---
 
 ## Overview

packages/lit-dev-content/site/docs/v2/resources/community.md

@@ -6,6 +6,7 @@ eleventyNavigation:
   order: 1
 versionLinks:
   v1: resources/community/
+  v3: resources/community/
 ---
 
 There are many great resources and locations to learn about Lit,

packages/lit-dev-content/site/docs/v2/ssr/authoring.md

@@ -4,6 +4,8 @@ eleventyNavigation:
   key: Authoring components
   parent: Server rendering
   order: 4
+versionLinks:
+  v3: ssr/authoring/
 ---
 
 {% labs-disclaimer %}

packages/lit-dev-content/site/docs/v2/ssr/client-usage.md

@@ -4,6 +4,8 @@ eleventyNavigation:
   key: Client usage
   parent: Server rendering
   order: 3
+versionLinks:
+  v3: ssr/client-usage/
 ---
 
 {% labs-disclaimer %}

packages/lit-dev-content/site/docs/v2/ssr/dom-emulation.md

@@ -4,6 +4,8 @@ eleventyNavigation:
   key: DOM emulation
   parent: Server rendering
   order: 5
+versionLinks:
+  v3: ssr/dom-emulation/
 ---
 
 {% labs-disclaimer %}

packages/lit-dev-content/site/docs/v2/ssr/overview.md

@@ -4,6 +4,8 @@ eleventyNavigation:
   key: Overview
   parent: Server rendering
   order: 1
+versionLinks:
+  v3: ssr/overview/
 ---
 
 {% labs-disclaimer %}

packages/lit-dev-content/site/docs/v2/ssr/server-usage.md

@@ -4,6 +4,8 @@ eleventyNavigation:
   key: Server usage
   parent: Server rendering
   order: 2
+versionLinks:
+  v3: ssr/server-usage/
 ---
 
 {% labs-disclaimer %}

packages/lit-dev-content/site/docs/v2/templates/conditionals.md

@@ -6,6 +6,7 @@ eleventyNavigation:
   order: 3
 versionLinks:
   v1: components/templates/#use-properties-loops-and-conditionals-in-a-template
+  v3: templates/conditionals/
 ---
 
 Since Lit leverages normal Javascript expressions, you can use standard Javascript control flow constructs like [conditional operators](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Conditional_Operator), function calls, and `if` or `switch` statements to render conditional content.

packages/lit-dev-content/site/docs/v2/templates/custom-directives.md

@@ -7,6 +7,7 @@ eleventyNavigation:
   order: 6
 versionLinks:
   v1: lit-html/creating-directives/
+  v3: templates/custom-directives/
 ---
 
 Directives are functions that can extend Lit by customizing how a template expression renders. Directives are useful and powerful because they can be stateful, access the DOM, be notified when templates are disconnected and reconnected, and independently update expressions outside of a render call.