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.