Version Packages

feat: introduce @rocket/engine and use it

.eleventyignore

@@ -1,4 +0,0 @@
-node_modules/**
-/docs/_assets
-/docs/_includes
-/docs/_data

.eslintignore

@@ -10,3 +10,16 @@ _site
 _site-dev
 __output
 __output-dev
+
+docs/_merged*
+*-mdjs-generated.js
+
+# sanity example has a separate backend that is unrelated to Rocket
+# therefore it does not need to follow it code rules
+/examples/04-sanity-minimal-starter/backend/
+
+/packages/engine/test-node/fixtures/06-error-handling/01-page-error/docs/index.rocket.js
+/packages/engine/test-node/fixtures/03b-format-markdown/c01-md-in-js-to-md-html/md-in-js.js
+/packages/engine/test-node/fixtures/03b-format-markdown/04-keep-converted-files/index-converted-md.js
+/packages/engine/test-node/fixtures/03c-format-html/02-client-js/docs/index-converted-html.js
+/packages/engine/test-node/fixtures/03b-format-markdown/04-keep-converted-files/index-converted-md-source.js

.github/workflows/verify.yml

@@ -8,7 +8,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: [14.x]
+        node-version: [16.x]
     steps:
       - uses: actions/checkout@v2
 
@@ -32,7 +32,11 @@ jobs:
       - name: Install dependencies
         run: yarn --frozen-lockfile
 
-      - uses: microsoft/playwright-github-action@v1
+      - name: Install Playwright dependencies
+        run: npx playwright install-deps
+
+      - name: Install Playwright
+        run: npx playwright install
 
       - name: Build Packages
         run: yarn build:packages

.gitignore

@@ -1,6 +1,7 @@
 ## editors
 /.idea
 /.vscode
+/.history
 
 ## system files
 .DS_Store
@@ -27,10 +28,14 @@ dist-types
 stats.html
 *.tsbuildinfo
 
-## Rocket ignore files (need to be the full relative path to the folders)
+# Rocket Search
-docs/_merged_data/
+rocket-search-index.json
-docs/_merged_assets/
+
-docs/_merged_includes/
+## Rocket ignore files
+*-mdjs-generated.js
+*-converted-md-source.js
+*-converted-md.js
+*-converted-html.js
 _site
 _site-dev
 
@@ -40,3 +45,7 @@ _merged_assets
 _merged_includes
 __output
 __output-dev
+docs_backup
+
+## Local playground
+examples/testing

.nvmrc

@@ -1 +1 @@
-v14
+v16

.vscode/extensions.json

@@ -0,0 +1,7 @@
+{
+	// See http://go.microsoft.com/fwlink/?LinkId=827846
+	// for the documentation about the extensions.json format
+	"recommendations": [
+		"dbaeumer.vscode-eslint"
+	]
+}

.vscode/launch.json

@@ -0,0 +1,34 @@
+// A launch configuration that compiles the extension and then opens it inside a new window
+// Use IntelliSense to learn about possible attributes.
+// Hover to view descriptions of existing attributes.
+// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+{
+	"version": "0.2.0",
+	"configurations": [
+		{
+			"name": "Run Web Dev Server Extension",
+			"type": "extensionHost",
+			"request": "launch",
+			"args": [
+				"--extensionDevelopmentPath=${workspaceFolder}/packages/vscode-rocket"
+			],
+			"outFiles": [
+				"${workspaceFolder}/packages/vscode-rocket/out/**/*.js"
+			],
+			"preLaunchTask": "Compile vscode-rocket"
+		},
+		{
+			"name": "Extension Tests",
+			"type": "extensionHost",
+			"request": "launch",
+			"args": [
+				"--extensionDevelopmentPath=${workspaceFolder}",
+				"--extensionTestsPath=${workspaceFolder}/out/test/suite/index"
+			],
+			"outFiles": [
+				"${workspaceFolder}/out/test/**/*.js"
+			],
+			"preLaunchTask": "${defaultBuildTask}"
+		}
+	]
+}

.vscode/settings.json

@@ -0,0 +1,12 @@
+{
+  "gitdoc.enabled": false,
+  "typescript.tsdk": "node_modules/typescript/lib",
+  "files.exclude": {
+    "**/*-mdjs-generated.js": false,
+  },
+  "search.exclude": {
+    "**/*-mdjs-generated.js": true,
+    "**/dist-types": true,
+  },
+  "editor.experimental.stickyScroll.enabled": true
+}

.vscode/tasks.json

@@ -0,0 +1,29 @@
+// See https://go.microsoft.com/fwlink/?LinkId=733558
+// for the documentation about the tasks.json format
+{
+	"version": "2.0.0",
+	"tasks": [
+    {
+      "type": "npm",
+      "script": "watch",
+      "problemMatcher": "$tsc-watch",
+      "isBackground": true,
+      "presentation": {
+        "reveal": "never"
+      },
+      "group": {
+        "kind": "build",
+        "isDefault": true
+      }
+    },
+    {
+      "label": "Compile vscode-rocket",
+      "type": "npm",
+      "script": "compile",
+      "path": "packages/vscode-rocket/",
+      "group": "build",
+      "problemMatcher": [],
+      "detail": "tsc -p ./"
+    }
+  ]
+}

CONTRIBUTING.md

@@ -4,37 +4,37 @@
 
 > Please note that this project is released with a [Contributor Code of Conduct](./CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.
 
-First, create a fork of the [modernweb-dev/rocket](https://github.com/modernweb-dev/rocket) repo by hitting the `fork` button on the GitHub page.
+First, create a fork of the [modernweb-dev/rocket](https://github.com/modernweb-dev/rocket) repository by hitting the `fork` button on the GitHub page.
 
-Next, clone our repository onto your computer with this command (replacing YOUR_USERNAME with your actual GitHub username)
+Next, clone our repository onto your computer.
 
-```sh
+```shell
 git clone git@github.com:modernweb-dev/rocket.git
 ```
 
-Once cloning is complete, change directory to the repo.
+Once cloning is complete, change directory to the repository.
 
-```sh
+```shell
 cd rocket
 ```
 
-Now add your fork as a remote
+Now add your fork as a remote (replacing YOUR_USERNAME with your GitHub username).
 
-```sh
+```shell
-git remote add fork git@github.com:<YOUR_NAME>/rocket.git
+git remote add fork git@github.com:<YOUR_USERNAME>/rocket.git
 ```
 
-Create a new local branch
+Create a new local branch.
 
-```sh
+```shell
 git checkout -b my-awesome-fix
 ```
 
 ## Preparing Your Local Environment for Development
 
-Now that you have cloned the repository, ensure you have [yarn](https://classic.yarnpkg.com/lang/en/) installed run the following commands to set up the development environment.
+Now that you have cloned the repository, ensure you have [yarn](https://classic.yarnpkg.com/lang/en/) installed, then run the following commands to set up the development environment.
 
-```sh
+```shell
 yarn install
 ```
 
@@ -42,25 +42,25 @@ This will download and install all packages needed.
 
 ## Making Your Changes
 
-Make your changes to the project. Commits are linted using precommit hooks, meaning that any code that raises linting error cannot be committed. In order to help avoid that, we recommend using an IDE or editor with an eslint plugin in order to streamline the development process. Plugins are available for all the popular editors. For more information see [ESLint Integrations](https://eslint.org/docs/user-guide/integrations)
+Make your changes to the project. Commits are linted using precommit hooks, meaning that any code that raises a linting error cannot be committed. In order to help avoid that, we recommend using an IDE or editor with an ESLint plugin in order to streamline the development process. Plugins are available for all the popular editors. For more information see [ESLint Integrations](https://eslint.org/docs/user-guide/integrations)
 
-### Compiling the typescript code
+### Compiling the TypeScript Code
 
-If you're making cross-package changes, you need to compile the typescript code. We recommend executing `tsc:watch` from the root of the package and keeping that running while you make your changes.
+If you're making cross-package changes, you need to compile the TypeScript code. We recommend executing `tsc:watch` from the root of the package and keeping that running while you make your changes.
 
-### Running tests
+### Running Tests
 
 To run the tests of a package, it's recommended to `cd` into the package directory and then using `yarn test` to run them. This way you're only running tests of that specific package.
 
-### Integration testing
+### Integration Testing
 
 To see how your changes integrate with everything together you can use the `test-runner` package. There are different commands in this package which you can execute to trigger different scenarios in the test runner.
 
-## Adding new packages
+## Adding New Packages
 
 For all projects the tsconfig/jsconfig configuration files are auto generated. You need to add an entry to the [./workspace-packages.ts](./workspace-packages.ts) to let it generate a config for you. After adding an entry, run `yarn update-package-configs` to generate the files for you.
 
-## Create a Changeset
+## Creating a Changeset
 
 If you made changes for which you want to trigger a release, you need to create a changeset.
 This documents your intent to release, and allows you to specify a message that will be put into the changelog(s) of the package(s).
@@ -69,7 +69,7 @@ This documents your intent to release, and allows you to specify a message that
 
 Run
 
-```sh
+```shell
 yarn changeset
 ```
 
@@ -92,7 +92,7 @@ Exceptions:
 Commit messages must follow the [conventional commit format](https://www.conventionalcommits.org/en/v1.0.0/)
 Modern-web uses package name as scope. So for example if you fix a _terrible bug_ in the package `@web/test-runner`, the commit message should look like this:
 
-```sh
+```shell
 fix(test-runner): fix terrible bug
 ```
 
@@ -100,7 +100,7 @@ fix(test-runner): fix terrible bug
 
 Now it's time to push your branch that contains your committed changes to your fork.
 
-```sh
+```shell
 git push -u fork my-awesome-fix
 ```
 

README.md

@@ -1,11 +1,10 @@
-> This project is in it's BETA phase
+> This project is in its BETA phase
 
 <p align="center">
-  <img
+  <picture width="60%">
-    width="60%"
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/modernweb-dev/rocket/main/site/src/assets/rocket-logo-dark-with-text.svg">
-    src="./assets/logo.png"
+    <img alt="Rocket Logo" src="https://raw.githubusercontent.com/modernweb-dev/rocket/main/site/src/assets/rocket-logo-light-with-text.svg">
-    alt="Rocket"
+  </picture>
-  />
 </p>
 
 <p align="center">
@@ -19,42 +18,57 @@
       src="https://img.shields.io/badge/twitter-@modern_web_dev-1DA1F3?style=flat-square"
       alt="Follow @modern_web_dev on Twitter"
   /></a>
+  <a href="https://open.vscode.dev/modernweb-dev/rocket"
+    ><img
+      src="https://img.shields.io/static/v1?logo=visualstudiocode&label=&message=Open%20in%20Visual%20Studio%20Code&labelColor=2c2c32&color=007acc&logoColor=007acc"
+      alt="Open in VS Code"
+  /></a>
 </p>
 
 <p align="center">
   <a href="https://rocket.modern-web.dev">Website</a>
   ·
-  <a href="https://rocket.modern-web.dev/guides/">Guides</a>
-  ·
   <a href="https://rocket.modern-web.dev/docs/">Documentation</a>
+  ·
+  <a href="https://rocket.modern-web.dev/chat">Discord Community</a>
 </p>
 
 <h1></h1>
 
 **The modern web setup for static sites with a sprinkle of JavaScript!**
 
-- **Meta Framework:** Build on top of giants like <a href="https://www.11ty.dev/">eleventy</a>, <a href="https://rollupjs.org/">Rollup</a>, and <a href="https://www.modern-web.dev/">Modern Web</a>.
+- **Meta Framework:** Build on top of giants like <a href="https://lit.dev/">Lit</a>, <a href="https://rollupjs.org/">Rollup</a> and <a href="https://www.modern-web.dev/">Modern Web</a>.
 - **Powerful Default Template:** Provide content and you are ready to go.
 - **Small:** No overblown tools or frontend frameworks, add JavaScript and/or Web Components only on pages where needed..
 
 <p align="center">
-  <a href="https://rocket.modern-web.dev/guides/"><strong>Explore the Rocket Guides&nbsp;&nbsp;▶</strong></a>
+  <a href="https://rocket.modern-web.dev/docs/setup/getting-started/"><strong>Getting Started With Rocket&nbsp;&nbsp;▶</strong></a>
 </p>
 
-## The goal for Rocket
+## The Goal for Rocket
 
-> Our goal is to provide developers with a meta framework for static websites with a spricle of JavaScript.
+> Our goal is to provide developers with a meta framework for static websites with a sprinkle of JavaScript.
 
 Get a site up and running in no time and focus on the content.
-You can still tweak every details of every underlying tool that get's used.
+You can still tweak every detail of every underlying tool that gets used.
 
 Rocket is part of the [Modern Web Family](https://twitter.com/modern_web_dev).
 
+<p align="center">
+  <a href="https://rocket.modern-web.dev/chat"><strong>Join our Discord Community&nbsp;&nbsp;▶</strong></a>
+</p>
+
+## Quick Start
+
+```
+npx @rocket/create@latest
+```
+
 ## 🤝 Contributing
 
 We are always looking for contributors of all skill levels! If you're looking to ease your way into the project, try out a [good first issue](https://github.com/modernweb-dev/rocket/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
 
-If you are interested in helping contribute to Modern Web, please take a look at our [Contributing Guide](https://github.com/modernweb-dev/rocket/blob/main/CONTRIBUTING.md). Also, feel free to drop into [slack](https://rocket.modern-web.dev/discover/slack/) and say hi. 👋
+If you are interested in helping contribute to Modern Web, please take a look at our [Contributing Guide](https://github.com/modernweb-dev/rocket/blob/main/CONTRIBUTING.md). Also, feel free to drop into [discord](https://rocket.modern-web.dev/chat) and say hi. 👋
 
 ### Financial Contributors
 

TODO.md

@@ -0,0 +1,43 @@
+## TODO
+
+- 404 page background images are not being loaded
+- sitemap.xml not deployed on netlify
+
+## Features
+
+- recursive rendering of lit / html / and markdown
+  - "import" markdown with frontmatter
+- mdjs update to unified v10 AND go esm only (only cjs pkg we have now)
+
+## Nice to have
+
+- Add "menuExclude" => to actually exclude the menu item
+
+## Bugs
+
+- write to `_site-dev` instead of `_site` while using `rocket start`
+- nested `recursive.data.js` do not overwrite the parent data
+- support <!-- asdf --> in markdown
+
+## Error Handling
+
+- make error nice for parent page not found in index => auto generate page? 🤔
+
+## Examples
+
+- docs site, blog (simple), blog (complex), minimal
+- add stackblitz/codesandbox examples => does not work because of `@parcel/watcher` https://github.com/parcel-bundler/watcher/issues/99
+
+- Example: export variable and use it in rendering
+- Example: fetch data from an api and display it
+- Example: usage of image
+
+## later
+
+- support `@change` in markdown
+- support "hey ${foo.map(f => `${f} + 1`)}"
+- ENGINE: Rename "options.docsDir" to "options.inputDir"
+
+## consider
+
+- Replace magic "resolve:pkg/foo.css" with a directive `${resolve()}`?

config/rocket.config.js

@@ -0,0 +1,47 @@
+import { rocketLaunch } from '@rocket/launch';
+import { rocketSpark } from '@rocket/spark';
+import { presetRocketSearch } from '@rocket/search';
+
+/**
+ * Extracts the current applicable absoluteBaseUrl from Netlify system variables
+ *
+ * @param {string} fallback
+ */
+export function absoluteBaseUrlNetlify(fallback) {
+  let absoluteBaseUrl = fallback;
+
+  switch (process.env.CONTEXT) {
+    case 'production':
+      absoluteBaseUrl = process.env.URL ?? '';
+      break;
+    case 'deploy-preview':
+      absoluteBaseUrl = process.env.DEPLOY_URL ?? '';
+      break;
+    case 'branch-deploy':
+      absoluteBaseUrl = process.env.DEPLOY_PRIME_URL ?? '';
+      break;
+    /* no default */
+  }
+  return absoluteBaseUrl;
+}
+
+export default /** @type {import('@rocket/cli/types/main').RocketCliOptions} */ ({
+  absoluteBaseUrl: absoluteBaseUrlNetlify('http://localhost:8080'),
+  longFileHeaderWidth: 100,
+  longFileHeaderComment: '// prettier-ignore',
+  // adjustDevServerOptions: (options) => ({
+  //   ...options,
+  //   nodeResolve: {
+  //     ...options.nodeResolve,
+  //     exportConditions: ['development'],
+  //   },
+  // }),
+
+  // buildOpenGraphImages: false,
+
+  presets: [rocketLaunch(), rocketSpark(), presetRocketSearch()],
+  // serviceWorkerName: 'sw.js',
+  // pathPrefix: '/_site/',
+
+  // clearOutputDir: false,
+});

docs/404.md

@@ -1,4 +0,0 @@
----
-layout: 404.njk
-permalink: 404.html
----

docs/_assets/head.html

@@ -1,9 +0,0 @@
-<link
-  href="https://fonts.googleapis.com/css2?family=Open+Sans:wght@400;700&display=swap"
-  rel="stylesheet"
-/>
-<link
-  href="https://fonts.googleapis.com/css2?family=Montserrat:wght@400;700&display=swap"
-  rel="stylesheet"
-/>
-<meta name="twitter:creator" content="@modern_web_dev" />

docs/_assets/style.css

@@ -1,21 +0,0 @@
-body[layout='home'] .markdown-body .call-to-action:nth-of-type(2) {
-  --primary-color: #222;
-  --primary-color-lighter: #333;
-  --primary-color-darker: #000;
-}
-
-@media screen and (min-width: 1024px) {
-  body[layout='home'][home-layout='background'] .page-background {
-    top: -210px;
-    right: -463px;
-    transform: rotate(45deg);
-  }
-}
-
-rocket-navigation {
-  font-family: 'Montserrat', sans-serif;
-}
-
-header {
-  font-family: 'Montserrat', sans-serif;
-}

docs/_assets/webmanifest.json

@@ -1,29 +0,0 @@
-{
-  "name": "Rocket",
-  "short_name": "rocket",
-  "theme_color": "#e63946",
-  "background_color": "#1d3557",
-  "display": "standalone",
-  "orientation": "portrait",
-  "Scope": "/",
-  "start_url": "/",
-  "icons": [
-    {
-      "src": "../_merged_assets/_static/icons/android-chrome-192x192.png",
-      "sizes": "128x128",
-      "type": "image/png"
-    },
-    {
-      "src": "../_merged_assets/_static/icons/android-chrome-512x512.png",
-      "sizes": "512x512",
-      "type": "image/png"
-    },
-    {
-      "src": "../_merged_assets/_static/icons/maskable-icon.jpg",
-      "sizes": "1024x1024",
-      "type": "image/jpg",
-      "purpose": "any maskable"
-    }
-  ],
-  "splash_pages": null
-}

docs/_data/footer.json

@@ -1,45 +0,0 @@
-[
-  {
-    "name": "Discover",
-    "children": [
-      {
-        "text": "Blog",
-        "href": "/blog/"
-      },
-      {
-        "text": "Help and Feedback",
-        "href": "https://github.com/modernweb-dev/rocket/issues"
-      }
-    ]
-  },
-  {
-    "name": "Follow",
-    "children": [
-      {
-        "text": "Github",
-        "href": "https://github.com/modernweb-dev/rocket"
-      },
-      {
-        "text": "Twitter",
-        "href": "https://twitter.com/modern_web_dev"
-      },
-      {
-        "text": "Slack",
-        "href": "/about/slack/"
-      }
-    ]
-  },
-  {
-    "name": "Support",
-    "children": [
-      {
-        "text": "Sponsor",
-        "href": "/about/sponsor/"
-      },
-      {
-        "text": "Contribute",
-        "href": "https://github.com/modernweb-dev/rocket/blob/main/CONTRIBUTING.md"
-      }
-    ]
-  }
-]

docs/_data/rocketLaunch.json

@@ -1,4 +0,0 @@
-{
-  "homeLayout": "background",
-  "newsletter": false
-}

docs/_data/site.cjs

@@ -1,23 +0,0 @@
-module.exports = async function () {
-  return {
-    dir: 'ltr',
-    lang: 'en',
-    name: 'Rocket',
-    description: 'Rocket is the way to build fast static websites with a sprinkle of javascript',
-    socialLinks: [
-      {
-        name: 'GitHub',
-        url: 'https://github.com/modernweb-dev/rocket',
-      },
-    ],
-    gitSiteUrl: 'https://github.com/modernweb-dev/rocket',
-    gitBranch: 'main',
-    helpUrl: 'https://github.com/modernweb-dev/rocket/issues',
-    logoAlt: 'Rocket Logo',
-    iconColorMaskIcon: '#3f93ce',
-    iconColorMsapplicationTileColor: '#1d3557',
-    iconColorThemeColor: '#1d3557',
-    socialMediaImage: '/_assets/social-media-image.jpg',
-    // analytics: 'UA-131782693-2', // modern web key
-  };
-};

docs/about/slack.md

@@ -1,5 +0,0 @@
-# Slack
-
-You can also find us on the Polymer slack in the [#open-wc](https://slack.com/share/IUQNUPWUF/awabyN8iYH4dXX6aGpu16ES9/enQtOTc2Nzc2ODEyOTY3LWM5ZGExNGFiMmM4NDY2YWI2MzYwOGY5ZTNlZjk4OGU4NTFhMGJjNmVhNGI4MzVlNTMwNGRiNGIxNjc4MGJhNDg) channel.
-
-You can join the Polymer slack by visiting https://www.polymer-project.org/slack-invite.

docs/about/sponsor.md

@@ -1,9 +0,0 @@
----
-title: Sponsor
-eleventyNavigation:
-  key: Sponsor
----
-
-We currently can only accept sponsoring in the form of services or contributions.
-
-If you are interested in monetary sponsoring please [let as know as](mailto:hello@modern-web.dev).

docs/blog/index.md

@@ -1,14 +0,0 @@
----
-title: Rocket Blog
-layout: blog
-eleventyNavigation:
-  key: Blog
-  order: 30
-pagination:
-  data: collections.blog
-  size: 10
-  reverse: true
-  alias: posts
----
-
-Discover articles from the core team and contributors about Rocket, tips and tricks included!

docs/blog/introducing-rocket/index.md

@@ -1,16 +0,0 @@
----
-title: Introducing rocket - effective static content with some javascript
-published: true
-description: Write Interactive Demos Using Markdown and JavaScript
-tags: [markdown, javascript, webcomponents, demos]
-cover_image: /blog/introducing-rocket/images/blog-header.jpg
-socialMediaImage: /blog/introducing-rocket/images/social-media-image.jpg
----
-
-Welcome to the next level of content creation.
-
-## Here comes the navigation
-
-Stuff
-
-## Another anchor

docs/browserconfig.xml

@@ -1,9 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<browserconfig>
-    <msapplication>
-        <tile>
-            <square150x150logo src="/mstile-150x150.png"/>
-            <TileColor>#1d3557</TileColor>
-        </tile>
-    </msapplication>
-</browserconfig>

docs/docs/configuration/index.md

@@ -1 +0,0 @@
-# Configuration ||10

docs/docs/configuration/overview.md

@@ -1,85 +0,0 @@
-# Configuration >> Overview ||10
-
-The configuration file is `rocket.config.js` or `rocket.config.mjs`.
-
-The config files consists of the following parts:
-
-```js
-import { rocketLaunch } from '@rocket/launch';
-
-export default {
-  presets: [rocketLaunch()],
-  emptyOutputDir: true,
-  pathPrefix: 'subfolder-only-for-build',
-};
-```
-
-Rocket is primarily build around plugins for each of it's systems.
-
-New plugins can be added and all default plugins can be adjusted or even removed by using the following functions.
-
-```js
-export default {
-  // add remark/unified plugin to the markdown processing (e.g. enable special code blocks)
-  setupUnifiedPlugins: [],
-
-  // add a rollup plugins to the web dev server (will be wrapped with @web/dev-server-rollup) AND the rollup build (e.g. enable json importing)
-  setupDevAndBuildPlugins: [],
-
-  // add a plugin to the web dev server (will not be wrapped) (e.g. esbuild for typescript)
-  setupDevPlugins: [],
-
-  // add a plugin to the rollup build (e.g. optimization steps)
-  setupBuildPlugins: [],
-
-  // add a plugin to eleventy (e.g. a filter packs)
-  setupEleventyPlugins: [],
-
-  // add a plugin to the cli (e.g. a new command like "rocket my-command")
-  setupCliPlugins: [],
-};
-```
-
-## Adding Rollup Plugins
-
-For some projects you might want to enable non-standard behaviors like importing JSON files as JavaScript.
-
-```js
-import data from './data.json';
-```
-
-You can accomplish this with rollup and dev server plugins. Make sure to add both the dev-server plugin as well as the rollup plugin, so that the behaviors is the same during development as it is in the production build.
-
-For these cases you can use `setupDevAndBuildPlugins`, which will automatically add the plugin for you to both rollup and dev-server:
-
-```js
-import json from '@rollup/plugin-json';
-import { addPlugin } from 'plugins-manager';
-
-/** @type {Partial<import("@rocket/cli").RocketCliOptions>} */
-const config = {
-  setupDevAndBuildPlugins: [
-    addPlugin({ name: 'json', plugin: json, location: 'top', options: { my: 'settings' } }),
-  ],
-};
-
-export default config;
-```
-
-This will add the rollup plugin `json` with the id `json` at the top of the plugin list of rollup and the dev server. It needs to be at the top so further plugins down the line can work with json imports.
-For the Dev Server the plugins are automatically wrapped by `@web/dev-server-rollup`. Note that [not all rollup plugins](https://modern-web.dev/docs/dev-server/plugins/rollup/#compatibility-with-rollup-plugins) will work with the dev-server.
-
-## Modifying Options of Plugins
-
-All plugins which are either default or are added via a preset can still be adjusted by using `adjustPluginOptions`.
-
-```js
-import { adjustPluginOptions } from 'plugins-manager';
-
-/** @type {Partial<import("@rocket/cli").RocketCliOptions>} */
-const config = {
-  setupDevAndBuildPlugins: [adjustPluginOptions('json', { my: 'overwrite settings' })],
-};
-
-export default config;
-```

docs/docs/eleventy-plugins/index.md

@@ -1 +0,0 @@
-# Eleventy Plugins ||40

docs/docs/eleventy-plugins/mdjs-unified.md

@@ -1,94 +0,0 @@
-# Eleventy Plugins >> Markdown JavaScript (Mdjs)
-
-Use mdjs in your 11ty site.
-
-## Setup
-
-```
-npm install @rocket/eleventy-plugin-mdjs
-```
-
-Create an 11ty config file `.eleventy.js`
-
-```js
-const pluginMdjs = require('@rocket/eleventy-plugin-mdjs');
-
-module.exports = function (eleventyConfig) {
-  eleventyConfig.addPlugin(pluginMdjs);
-};
-```
-
-## Configure a unified or remark plugin with mdjs
-
-By providing a `setupUnifiedPlugins` function as an option to `eleventy-plugin-mdjs` you can set options for all unified/remark plugins.
-
-We do use [plugins-manager](../plugins-manager/overview.md).
-
-This example adds a CSS class to the `htmlHeading` plugin so heading links can be selected in CSS.
-
-```js
-const pluginMdjs = require('@rocket/eleventy-plugin-mdjs');
-const { adjustPluginOptions } = require('plugins-manager');
-
-module.exports = function (eleventyConfig) {
-  eleventyConfig.addPlugin(pluginMdjs, {
-    setupUnifiedPlugins: [
-      adjustPluginOptions('htmlHeading', {
-        properties: {
-          className: ['anchor'],
-        },
-      }),
-    ],
-  });
-};
-```
-
-## Add a unified or remark plugin
-
-The order of plugins is important in unified as each plugin processes the content and passes on its result.
-Some plugins do work with the markdown AST and some with the rehype (e.g. html) AST. In order to get access to the correct AST the plugin needs to be in a specific location in the processing order.
-
-Examples on how to insert a plugin right after creating the markdown AST.
-
-```js
-const pluginMdjs = require('@rocket/eleventy-plugin-mdjs');
-const { addPlugin } = require('plugins-manager');
-const { myRemarkPlugin } = require('./my-remark-plugin.js');
-
-module.exports = function (eleventyConfig) {
-  eleventyConfig.addPlugin(pluginMdjs, {
-    setupUnifiedPlugins: [
-      addPlugin({ name: 'my-remark-plugin', plugin: myRemarkPlugin, location: 'markdown' }),
-    ],
-  });
-};
-```
-
-Examples on how to insert a plugin right after creating the rehype AST.
-
-```js
-const pluginMdjs = require('@rocket/eleventy-plugin-mdjs');
-const { addPlugin } = require('plugins-manager');
-const { myRehypePlugin } = require('./my-rehype-plugin.js');
-
-module.exports = function (eleventyConfig) {
-  eleventyConfig.addPlugin(pluginMdjs, {
-    setupUnifiedPlugins: [
-      addPlugin({ name: 'my-rehype-plugin', plugin: myRehypePlugin, location: 'remark2rehype' }),
-    ],
-  });
-};
-```
-
-You can also add both
-
-```js
-module.exports = function (eleventyConfig) {
-  eleventyConfig.addPlugin(pluginMdjs, {
-    setupUnifiedPlugins: [
-      addPlugin({ name: 'my-remark-plugin', plugin: myRemarkPlugin, location: 'markdown' }),
-      addPlugin({ name: 'my-rehype-plugin', plugin: myRehypePlugin, location: 'remark2rehype' }),
-    ],
-  });
-};
-```

docs/docs/index.md

@@ -1,12 +0,0 @@
----
-title: Documentation
-eleventyNavigation:
-  key: Docs
-  order: 20
----
-
-Here you will find all the details for each of the packages/systems we offer.
-
-You should check out:
-
-- [@rocket/launch](./presets/launch.md) which is our default preset

docs/docs/markdown-javascript/index.md

@@ -1 +0,0 @@
-# Markdown JavaScript ||30

docs/docs/markdown-javascript/overview.md

@@ -1,237 +0,0 @@
-# Markdown JavaScript >> Overview || 10
-
-Markdown JavaScript (Mdjs) is a format that allows you to use JavaScript with Markdown, to create interactive demos. It does so by "annotating" JavaScript that should be executed in Markdown.
-
-To annotate we use a code block with `js script`.
-
-````md
-```js script
-// execute me
-```
-````
-
-## Web Components
-
-One very good use case for that can be web components.
-HTML already works in markdown so all you need is to load a web components definition file.
-
-You could even do so within the same markdown file.
-
-````md
-## This is my-card
-
-Here's an example of the component:
-
-```html preview-story
-<my-card>
-  <h2>Hello world!</h2>
-  <button>Click me!</button>
-</my-card>
-```
-````
-
-You can even execute some JavaScript:
-
-````md
-## This is my-el
-
-<my-el></my-el>
-
-```js script
-import { LitElement, html } from 'https://unpkg.com/lit-element?module';
-
-class MyEl extends LitElement {
-  render() {
-    this.innerHTML = '<p style="color: red">I am alive</p>';
-  }
-}
-
-customElements.define('my-el', MyEl);
-```
-````
-
-## Demo Support (Story)
-
-mdjs comes with some additional helpers you can choose to import via
-
-````md
-```js script
-import '@mdjs/mdjs-story/mdjs-story.js';
-import '@mdjs/mdjs-preview/mdjs-preview.js';
-```
-````
-
-once loaded you can use them like so.
-
-````md
-```js script
-import '@mdjs/mdjs-story/mdjs-story.js';
-import '@mdjs/mdjs-preview/mdjs-preview.js';
-```
-````
-
-once loaded you can use them like so.
-
-### story
-
-The code snippet will actually get executed at that place and you will have a live demo
-
-````md
-```js story
-export const JsStory = () => html` <demo-wc-card>JS Story</demo-wc-card> `;
-```
-````
-
-````md
-```html story
-<demo-wc-card>HTML Story</demo-wc-card>
-```
-````
-
-#### full code support
-
-````md
-```js story
-export const JsStory = () => {
-  const calculateSomething = 12;
-  return html`
-    <demo-wc-card .header=${`Something: ${calculateSomething}`}>JS Story</demo-wc-card>
-  `;
-};
-```
-````
-
-### preview story
-
-Will become a live demo wrapped in a container with a show code button.
-
-````md
-```js preview-story
-export const JsPreviewStory = () => html` <demo-wc-card>JS Preview Story</demo-wc-card> `;
-```
-````
-
-````md
-```html preview-story
-<demo-wc-card>HTML Preview Story</demo-wc-card>
-```
-````
-
-Here is a live example from [demo-wc-card](https://www.npmjs.com/package/demo-wc-card).
-
-```js script
-import '@mdjs/mdjs-story/mdjs-story.js';
-import '@mdjs/mdjs-preview/mdjs-preview.js';
-import { html } from 'lit-html';
-```
-
-```js preview-story
-import 'demo-wc-card/demo-wc-card.js';
-export const header = () => {
-  return html` <demo-wc-card .header=${'my new header'}></demo-wc-card> `;
-};
-```
-
-## Supported Systems
-
-### es-dev-server
-
-Preview your mdjs readme with live demos and auto reload.
-
-- Add to your `package.json`:
-
-  ```json
-  "scripts": {
-    "start": "es-dev-server",
-  }
-  ```
-
-- Create a `es-dev-server.config.js` in the root of your repo.
-
-  ```js
-  const { mdjsTransformer } = require('@mdjs/core');
-
-  module.exports = {
-    nodeResolve: true,
-    open: 'README.md',
-    watch: true,
-    responseTransformers: [mdjsTransformer],
-  };
-  ```
-
-### Storybook
-
-Please check out [@open-wc/demoing-storybook](https://open-wc.org/demoing/) for a fully integrated setup.
-
-It includes [storybook-addon-markdown-docs](https://open-wc.org/demoing/storybook-addon-markdown-docs.html) which uses mdjs under the hood.
-
-### Chrome Extension (currently only for Github)
-
-See live demos directly inside github page, markdown files, issues, pull requests...
-
-Please check out [mdjs-viewer](https://github.com/open-wc/mdjs-viewer).
-
-## Build mdjs
-
-### Basic
-
-mdjs offers two more "basic" integrations
-
-#### `mdjsDocPage`
-
-Creates a full blown html page by passing in the markdown.
-
-```js
-const { mdjsDocPage } = require('@mdjs/core');
-
-const page = await mdjsDocPage(markdownString);
-/*
-<html>
-  ... // load styles/components for mdjs, start stories
-  <body>
-    <h1>Some Markdown</h1>
-  </body>
-</html>
-*/
-```
-
-#### `mdjsProcess`
-
-Pass in multiple markdown documents and you get back all the jsCode and rendered html.
-
-```js
-const { mdjsProcess } = require('@mdjs/core');
-
-const data = await mdjsProcess(markdownString);
-console.log(data);
-/*
-{
-  jsCode: "
-    import '@mdjs/mdjs-story/mdjs-story.js';
-    ...
-  ",
-  html: '<h1>Markdown One</h1>',
-}
-*/
-```
-
-### Advanced
-
-mdjs is build to be integrated within the [unifiedjs](https://unifiedjs.com/) system.
-
-```js
-const unified = require('unified');
-const markdown = require('remark-parse');
-const htmlStringify = require('remark-html');
-const mdjsParse = require('@mdjs/core');
-
-const parser = unified().use(markdown).use(mdjsParse).use(htmlStringify);
-const result = await parser.process(body);
-const { jsCode } = result.data;
-console.log(result.contents);
-// <h1>This is my-el></h1>
-// <my-el></my-el>
-console.log(jsCode);
-// customElements.define('my-el', class extends HTMLElement {
-// ...
-```

docs/docs/markdown-javascript/preview.md

@@ -1,19 +0,0 @@
-# Markdown JavaScript >> Preview ||20
-
-You can showcase live running code by annotating a code block with `js preview-story`.
-
-````md
-```js preview-story
-import { html } from 'lit-html';
-
-export const foo = () => html` <p>my html</p> `;
-```
-````
-
-will result in
-
-```js preview-story
-import { html } from 'lit-html';
-
-export const foo = () => html` <p>my html</p> `;
-```

docs/docs/markdown-javascript/story.md

@@ -1,19 +0,0 @@
-# Markdown JavaScript >> Story ||30
-
-You can showcase live running code by annotating a code block with `js story`.
-
-````md
-```js story
-import { html } from 'lit-html';
-
-export const foo = () => html` <p>my html</p> `;
-```
-````
-
-will result in
-
-```js story
-import { html } from 'lit-html';
-
-export const foo = () => html` <p>my html</p> `;
-```

docs/docs/presets/blog.md

@@ -1,21 +0,0 @@
-# Presets >> Blog ||30
-
-Enable writing blog posts within your rocket site
-
-## Installation
-
-```bash
-npm i @rocket/blog
-```
-
-## Usage
-
-👉 `rocket.config.mjs`
-
-```js
-import { rocketBlog } from '@rocket/blog';
-
-export default {
-  presets: [rocketBlog()],
-};
-```

docs/docs/presets/index.md

@@ -1,5 +0,0 @@
----
-excludeFromSearch: true
----
-
-# Presets ||20

docs/docs/presets/launch.md

@@ -1,119 +0,0 @@
-# Presets >> Launch ||10
-
-Rocket comes with a preset you will love. Simple, Responsive and behaving like native it sure is going to be a hit among your users.
-
-## Installation
-
-```bash
-npm i @rocket/launch
-```
-
-👉 `rocket.config.mjs`
-
-```js
-import { rocketLaunch } from '@rocket/launch';
-
-export default {
-  presets: [rocketLaunch()],
-};
-```
-
-## Data
-
-Most data comes from `site.cjs`.
-
-There is also a specific `rocketLaunch.json`.
-
-The footer data comes from `footer.json`
-
-## Inline Notification
-
-Notification are web components that bring in some styles.
-
-To use them in Markdown you need to write the html tag and have it separated by an empty line.
-
-```js script
-import '@rocket/launch/inline-notification/inline-notification.js';
-```
-
-First you need to import the script
-
-````
-```js script
-import '@rocket/launch/inline-notification/inline-notification.js';
-```
-````
-
-### Tip
-
-<inline-notification type="tip">
-
-I am a tip
-
-</inline-notification>
-
-**Usage**
-
-```md
-<inline-notification type="tip">
-
-I am a tip
-
-</inline-notification>
-```
-
-### Modify the title
-
-To override the title you can provide a property success.
-
-<inline-notification type="tip" title="success">
-
-I am a success message
-
-</inline-notification>
-
-**Usage**
-
-```md
-<inline-notification type="tip" title="success">
-
-I am a success message
-
-</inline-notification>
-```
-
-### Warning
-
-<inline-notification type="warning">
-
-I am a warning
-
-</inline-notification>
-
-**Usage**
-
-```md
-<inline-notification type="warning">
-
-I am a warning
-
-</inline-notification>
-```
-
-### Danger
-
-<inline-notification type="danger">
-
-I am a dangerous message
-
-</inline-notification>
-
-**Usage**
-
-```md
-<inline-notification type="danger">
-
-I am a dangerous message
-
-</inline-notification>
-```

docs/docs/presets/search.md

@@ -1,19 +0,0 @@
-# Presets >> Search ||20
-
-Add a search for all your static content.
-
-## Installation
-
-```bash
-npm i @rocket/search
-```
-
-👉 `rocket.config.mjs`
-
-```js
-import { rocketSearch } from '@rocket/search';
-
-export default {
-  presets: [rocketSearch()],
-};
-```

docs/docs/tools/index.md

@@ -1 +0,0 @@
-# Tools ||50

docs/docs/tools/plugins-manager.md

@@ -1,269 +0,0 @@
-# Tools >> Plugins Manager ||10
-
-The Plugins Manager replaces the specific registration/execution (with options) in a given plugin system by an intend to use a plugin (with these options).
-This allows your users to adjust the options before actually applying the plugins.
-
-## Problem
-
-Many plugin systems require you to either execute a plugin function like in `rollup`.
-
-```js
-import json from '@rollup/plugin-json';
-export default {
-  plugins: [json({ preferConst: true })],
-};
-```
-
-or add it in a special way like in `eleventy`
-
-```js
-const pluginSyntaxHighlight = require('@11ty/eleventy-plugin-syntaxhighlight');
-module.exports = function (eleventyConfig) {
-  eleventyConfig.addPlugin(pluginSyntaxHighlight, { templateFormats: ['md'] });
-};
-```
-
-or `unified/remark`.
-
-```js
-var unified = require('unified');
-var markdown = require('remark-parse');
-var toc = require('remark-toc');
-
-var processor = unified().use(markdown).use(toc, { maxDepth: 2 });
-// ...
-```
-
-## Problem statement
-
-> Executing or adding a plugin in a special way is a one time process. You can not transparently later change the options of the given plugin.
-
-This means if you wish to define default plugins and allow your user to override all of the settings it's "impossible".
-
-## Solution
-
-The plugins manager let's you orchestrate a set of "meta plugins" which are defined by
-
-- name
-- plugin
-- options
-
-```js
-import beep from '@rollup/plugin-beep';
-import url from '@rollup/plugin-url';
-
-let metaPlugins = [
-  { name: 'beep', plugin: beep },
-  { name: 'url', plugin: url, options: { limit: 10000 } },
-];
-```
-
-This array can be modified by adding/removing or adjusting options.
-
-```js
-// raw add
-metaPlugins.push({
-  // another plugin
-});
-
-// raw adjust
-metaPlugins[1].options.limit = 20000;
-```
-
-And then you can convert it into the specific format that can be assigned to your system in question.
-
-```js
-// execute plugins for rollup
-const plugins = metaPlugins.map(pluginObj => {
-  if (pluginObj.options) {
-    return pluginObj.plugin(pluginObj.options);
-  } else {
-    return pluginObj.plugin();
-  }
-});
-
-// rollup.config.js
-export default {
-  plugins,
-};
-```
-
-### Adding Helpers
-
-Doing array manipulations is kinda error-prone so we offer encourage to use an array of setup function. Where as each setup function can either add a new plugin (with a unique name) or adjust an already existing plugin.
-
-```js
-import { addPlugin, adjustPluginOptions } from 'plugins-manager';
-
-const systemSetupFunctions = [
-  addPlugin({ name: 'first', plugin: first }),
-  addPlugin({ name: 'second', plugin: second }),
-];
-const userSetupFunctions = [adjustPluginOptions('first', { my: 'options' })];
-```
-
-Arrays of functions can by merged like so
-
-```js
-const finalSetupFunctions = [...systemSetupFunctions, ...userSetupFunctions];
-```
-
-and then converted to the final output.
-
-```js
-import { metaPluginsToRollupPlugins } from 'plugins-manager';
-
-const plugins = metaPluginsToRollupPlugins(finalSetupFunctions, metaPlugins);
-```
-
-## Adding a Plugin
-
-This makes sure that
-
-- the name is unique
-- you can add at at `top`, `bottom` and `after/before` a given other plugin
-
-By default it adds at the bottom.
-
-```js
-import json from '@rollup/plugin-json';
-import { addPlugin } from 'plugins-manager';
-
-const userSetupFunctions = [
-  addPlugin({ name: 'json', plugin: json, options: { preferConst: true } }),
-];
-```
-
-Example usage:
-
-```js
-addPlugin({ name: 'json', plugin: json }); // Add at the bottom (default)
-addPlugin({ name: 'json', plugin: json, location: 'top' }); // Add at the top/beginning of the array
-addPlugin({ name: 'json', plugin: json, location: 'beep' }); // Add after (default) plugin 'beep'
-addPlugin({ name: 'json', plugin: json, location: 'beep', how: 'before' }); // Add before plugin 'beep'
-```
-
-## Adjusting Plugin Options
-
-Adjusting options means to either
-
-- flatly merge objects (e.g. only the first level will be preserved)
-- calling a function to do the merge yourself
-- setting the raw value (if not an object or function)
-
-```js
-import { adjustPluginOptions } from 'plugins-manager';
-
-const userSetupFunctions = [
-  adjustPluginOptions('json', { preferConst: false, anotherOption: 'format' }),
-];
-```
-
-Example usage:
-
-```js
-// given
-addPlugin({
-  name: 'json',
-  plugin: json,
-  options: {
-    other: {
-      nested: 'other.nested',
-      nested2: 'other.nested2',
-    },
-    main: true,
-  },
-});
-
-// merge objects flately
-adjustPluginOptions('json', { other: { nested: '--overwritten--' } });
-// resulting options = { other: { nested: '--overwritten--' }, main: true }
-// NOTE: nested2 is removed
-
-// merge via function
-adjustPluginOptions('json', config => ({ other: { ...config.other, nested: '--overwritten--' } }));
-// resulting options = { other: { nested: '--overwritten--', nested2: 'other.nested2' }, main: true }
-
-// merge via function to override full options
-adjustPluginOptions('json', config => ({ only: 'this' }));
-// resulting options = { only: 'this' }
-
-// setting a raw value
-adjustPluginOptions('json', false);
-// resulting options = false
-```
-
-## Converting metaPlugins to an actual plugin
-
-To execute all setup function you can use this little helper
-
-```js
-const finalMetaPlugins = executeSetupFunctions(finalSetupFunctions, metaPlugins);
-```
-
-And then you can convert it into your format.
-For Rollup you would execute the plugin with the options if there are any.
-
-```js
-const plugins = finalMetaPlugins.map(pluginObj => {
-  if (pluginObj.options) {
-    return pluginObj.plugin(pluginObj.options);
-  } else {
-    return pluginObj.plugin();
-  }
-});
-```
-
-**Examples**
-
-Rollup has a more specific helper that handles
-
-- `config.setupPlugins`
-
-Note: if you provide `config.plugins` then it will return that directly ignoring `setupPlugins`
-
-```js
-import { metaConfigToRollupConfig } from 'plugins-manager';
-
-const finalConfig = metaConfigToRollupConfig(currentConfig, defaultMetaPlugins);
-```
-
-Web Dev Server has a more specific helper that handles
-
-- `config.setupPlugins`
-- `config.setupRollupPlugins`
-
-Note: if you provide `config.plugins` then it will return that directly ignoring `setupPlugins` and `setupRollupPlugins`
-
-```js
-import { metaConfigToWebDevServerConfig } from 'plugins-manager';
-import { fromRollup } from '@web/dev-server-rollup';
-
-const finalConfig = metaConfigToWebDevServerConfig(currentConfig, defaultMetaPlugins, {
-  rollupWrapperFunction: fromRollup,
-});
-```
-
-Eleventy
-
-```js
-module.exports = eleventyConfig => {
-  for (const pluginObj of metaPlugins) {
-    if (pluginObj.options) {
-      eleventyConfig.addPlugin(pluginObj.plugin, pluginObj.options);
-    } else {
-      eleventyConfig.addPlugin(pluginObj.plugin);
-    }
-  }
-};
-```
-
-Unified/Remark
-
-```js
-const parser = unified();
-
-for (const pluginObj of metaPlugins) {
-  parser.use(pluginObj.plugin, pluginObj.options);
-}
-```

docs/guides/configuration/getting-started.md

@@ -1,38 +0,0 @@
-# Configuration >> Getting Started ||10
-
-The main config file is `rocket.config.js` or `rocket.config.mjs`.
-
-It typically looks something like this
-
-```js
-import { rocketLaunch } from '@rocket/launch';
-import { rocketBlog } from '@rocket/blog';
-import { rocketSearch } from '@rocket/search';
-import { absoluteBaseUrlNetlify } from '@rocket/core/helpers';
-
-export default /** @type {Partial<import('@rocket/cli').RocketCliOptions>} */ ({
-  presets: [rocketLaunch(), rocketBlog(), rocketSearch()],
-  absoluteBaseUrl: absoluteBaseUrlNetlify('http://localhost:8080'),
-});
-```
-
-The Plugins Manager helps you register and execute your plugins across the various Rocket components - rollup, dev-server, eleventy, and markdown. It replaces the specific registration/execution call in a given plugin system by an intent to use that plugin.
-
-## Adding Remark/Unified Plugins
-
-If you want to a plugin to the markdown processing you can use `setupUnifiedPlugins`.
-
-```js
-import emoji from 'remark-emoji';
-import { addPlugin } from 'plugins-manager';
-
-/** @type {Partial<import('@rocket/cli').RocketCliOptions>} */
-const config = {
-  setupUnifiedPlugins: [addPlugin({ location: 'markdown', name: 'emoji', plugin: emoji })],
-};
-
-export default config;
-```
-
-For plugins that should handle the markdown <abbr title="Abstract Syntax Tree">AST</abbr> you should use `addPlugin({ location: 'markdown', name: 'my-plugin', plugin: MyPlugin})`. <br>
-While for the rehype ast you should use `addPlugin({ location: 'remark2rehype', name: 'my-plugin', plugin: MyPlugin})`.

docs/guides/configuration/index.md

@@ -1 +0,0 @@
-# Configuration ||30

docs/guides/first-pages/adding-pages.md

@@ -1,85 +0,0 @@
-# First Pages >> Adding Pages ||12
-
-<inline-notification type="warning">
-
-You can do this whole part of the tutorial in a couple minutes. It's almost _**too**_ fast.
-
-It can help to examine each new page and menu carefully, to come to terms with the implicit navigation created by your addition of new content, at least the first couple of times.
-
-</inline-notification>
-
-## Add a section
-
-In most cases you will have multiple sections in your website and each of those sections will come with it's own sidebar navigation.
-
-To create a section you need to create a folder with an `index.md`.
-
-```bash
-mkdir docs/guides
-```
-
-👉 `docs/guides/index.md`
-
-```md
-# Guides
-
-You can read all about...
-```
-
-Observe that this creates a section named "Guides" at the top menu bar, and a page with the same title.
-
-<inline-notification type="tip">
-
-Don't worry if this isn't how you would have styled or placed your menu bar or sidebar navigation, we'll get to customization of the default preset later in the tutorials.
-
-</inline-notification>
-
-> How many sections should I add?
-
-It might be more practical to stay below 5 sections.
-
-## Adding a category
-
-Often each section will have multiple categories.
-
-To create a category you need to create a folder with an `index.md`.
-
-```bash
-mkdir docs/guides/first-pages/
-```
-
-👉 `docs/guides/first-pages/index.md`
-
-```md
-# First Pages
-```
-
-## Adding a page to a category
-
-👉 `docs/guides/first-pages/getting-started.md`
-
-```md
-# First Pages >> Getting Started
-
-This is how you get started.
-```
-
-## Headings as anchor and menu items
-
-_**Within**_ any page, you can still add links to your navigation!
-
-Note that md text prefixed with one or two # signs also becomes and anchor in the page and a link in the sidebar navigation when the page is open.
-
-```md
-## Headings as anchor and menu items
-
-_**Within**_ any page, you can still add links to your navigation!
-```
-
-```js script
-import '@rocket/launch/inline-notification/inline-notification.js';
-```
-
-## Example as a reference
-
-If implicit navigation, derived from content, is a bit too much to grasp in one sitting, feel free to examine the **docs** folder in [the rocket codebase behind the pages you are reading](https://github.com/modernweb-dev/rocket) for more examples.

docs/guides/first-pages/getting-started.md

@@ -1,117 +0,0 @@
-# First Pages >> Getting Started ||10
-
-Rocket is has the following prerequisits:
-
-- [Node 14+](https://nodejs.org/en/)
-
-Make sure they are installed before proceeding.
-
-## Setup
-
-The fastest way to get started is by using an existing preset like the launch preset.
-
-1. Start with an empty new folder
-
-   ```
-   mkdir my-project
-   cd my-project
-   npm init -y
-   ```
-
-2. Install dependencies
-
-   ```
-   npm install --save-dev @rocket/cli @rocket/launch
-   ```
-
-3. Add to your .gitignore
-
-   ```
-   ## Rocket ignore files (need to be the full relative path to the folders)
-   docs/_merged_data/
-   docs/_merged_assets/
-   docs/_merged_includes/
-   ```
-
-<inline-notification type="danger">
-
-You may be tempted to skip the step above, because you're not ready to commit to git yet!
-
-Rocket uses the .gitignore file to manage it's requirements. If you skip this step, rocket will fail to deploy!
-
-</inline-notification>
-
-4. Create a `rocket.config.mjs` (or `.js` if you have type: "module" in you package.json)
-
-   ```js
-   import { rocketLaunch } from '@rocket/launch';
-
-   export default {
-     presets: [rocketLaunch()],
-   };
-   ```
-
-5. (optionally) Create a file `.eleventyignore` (this file will be needed once you start customizing presets)
-
-   ```
-   node_modules/**
-   /docs/_assets
-   /docs/_includes
-   /docs/_data
-   ```
-
-<inline-notification type="warning" title="note">
-
-All further pathes are relative to your project root (my-project in this case)
-
-</inline-notification>
-
-## Add your first page
-
-👉 `docs/index.md`
-
-```md
-# Welcome to your Rocket site
-
-Text here, like any markdown file.
-```
-
-This tutorial assumes you are familiar with Markdown, for page authoring.
-
-Please note that the heading - text prefixed with `#` or `##` - is not optional for each page in this tutorial. Everything below that first line is optional Markdown text.
-
-## Start up:
-
-👉 `package.json`
-
-Add `"start": "rocket start"` to your package.json
-
-```json
-"scripts": {
-  "start": "rocket start"
-}
-```
-
-Now you can launch your site locally with
-
-```bash
-npm run start
-```
-
-## Taking Inventory Before Adding Pages:
-
-We're about to add both content and navigation at the same time.
-
-It can be helpful to take an inventory, before we start, to separate basic setup from the creation of content and navigation.
-
-- We built the project with basic npm commands
-- Added a couple required files manually
-- Adjusted package.json
-- **doc/index.md** to seed the content
-- Launches with `npm start`
-
-That's all it takes to get a new super-fast and powerful site, complete with a service worker, default styling, navigation, and ready to deploy as a plain old static files.
-
-```js script
-import '@rocket/launch/inline-notification/inline-notification.js';
-```

docs/guides/first-pages/index.md

@@ -1 +0,0 @@
-# First Pages ||10

docs/guides/first-pages/link-to-other-pages.md

@@ -1,7 +0,0 @@
-# First Pages >> Linking ||20
-
-Standard markdown applies and you can link via
-
-```md
-[visible label](./path/to/other-file.md)
-```

docs/guides/first-pages/manage-sidebar.md

@@ -1,49 +0,0 @@
-# First Pages >> Managing sidebar ||30
-
-The sidebar will show all the content of the current section.
-
-## Nesting Pages
-
-You nest by adding `>>` between parent and child.
-
-## Sorting Pages
-
-You can sort by adding `||xx` at the end.
-
-e.g.
-
-```
-# Second || 20
-# First || 10
-```
-
-Will be ordered as `First`, `Second`,
-
-## How it works
-
-Internally `# Foo >> Bar >> Baz ||20` get's converted to.
-
-```
----
-title: Bar: Baz
-eleventyNavigation:
-  key: Foo >> Bar >> Baz
-  parent: Foo >> Bar
-  order: 20
----
-```
-
-You can also look at this live playground:
-
-```js story
-import { html } from 'lit-html';
-
-export const headlineConverter = () => html`
-  <p>
-    <strong style="color: red;">TODO: </strong>I will become a web component that has an input and
-    out that live udpates
-  </p>
-`;
-```
-
-How it then works is very similar to https://www.11ty.dev/docs/plugins/navigation/

docs/guides/first-pages/urls.md

@@ -1,5 +0,0 @@
-# First Pages >> Urls ||100
-
-Urls will be represented by the folder structure...
-
-You can use a frontmatter with permalink to override

docs/guides/first-pages/use-javascript.md

@@ -1,25 +0,0 @@
-# First Pages >> Use JavaScript ||40
-
-You can use `js script` to execute javascript (type = module)
-
-````
-```js script
-console.log('foo');
-```
-````
-
-This can be useful for importing web components and using them in markdown
-
-````
-```js script
-import 'magic-reveal/magic-reveal.js';
-
-<magic-reveal>
-
-This text will get magically revealed. I can **still** use markdown as long as between the opening/closing tag there is an empty line.
-
-</magic-reveal>
-```
-````
-
-or you can use `js story`, `js preview-story`, ...

docs/guides/go-live/index.md

@@ -1 +0,0 @@
-# Go Live ||40

docs/guides/go-live/overview.md

@@ -1,51 +0,0 @@
-# Go Live >> Overview ||10
-
-A few things are usually needed before going live "for real".
-
-## Add a not found page
-
-When a user enters a url that does not exists then a "famous" 404 page not found error occures.
-Many servers are configured to handle this automatically and to serve a 404.html page instead.
-
-The [Rocket Lauch Preset](../../docs/presets/launch.md) ships a default 404 template you can use.
-
-To enable it you need to creating a 404.md and use the 404 layout.
-
-👉 `docs/404.md`
-
-```
----
-layout: 404.njk
-permalink: 404.html
----
-```
-
-## Add a sitemap
-
-A sitemap can be used to inform search engines or services about the pages your site has.
-
-You can create one by adding this file
-
-👉 `docs/sitemap.njk`
-
-{% raw %}
-
-```
----
-layout: pure-content.njk
-permalink: /sitemap.xml
-eleventyExcludeFromCollections: true
----
-<?xml version="1.0" encoding="utf-8"?>
-<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
-  {% for page in collections.all %}
-    <url>
-      <loc>{{ rocketConfig.absoluteBaseUrl }}{{ page.url | url }}</loc>
-      <lastmod>{{ page.date.toISOString() }}</lastmod>
-      <changefreq>{{ page.data.changeFreq if page.data.changeFreq else "monthly" }}</changefreq>
-    </url>
-  {% endfor %}
-</urlset>
-```
-
-{% endraw %}

docs/guides/go-live/social-media.md

@@ -1,44 +0,0 @@
-# Go Live >> Social Media ||20
-
-Having a nice preview image for social media can be very helpful.
-For that reason Rocket creates those automatically with the title, parent title, section and your logo.
-
-It will look like this but with your logo
-
-<img src="{{ socialMediaImage }}" width="1200" height="630" alt="Social Media Image of this page" style="border: 1px solid #000" />
-
-There are multiple ways you can modify it.
-
-## Setting it via frontMatter
-
-You can create your own image and link it with something like this
-
-```
----
-socialMediaImage: path/to/my/image.png
----
-```
-
-## Providing your own text
-
-Sometimes extracting the title + title of parent is not enough but you still want to use the "default image".
-
-You can create an `11tydata.cjs` file next to your page. If your page is `docs/guides/overview.md` then you create a `docs/guides/overview.11tydata.cjs`.
-
-In there you can use the default `createPageSocialImage` but provide your own values.
-
-```js
-const { createPageSocialImage } = require('@rocket/cli');
-
-module.exports = async function () {
-  const socialMediaImage = await createPageSocialImage({
-    title: 'Learning Rocket',
-    subTitle: 'Have a website',
-    subTitle2: 'in 5 Minutes',
-    footer: 'Rocket Guides',
-  });
-  return {
-    socialMediaImage,
-  };
-};
-```

docs/guides/index.11tydata.cjs

@@ -1,13 +0,0 @@
-const { createPageSocialImage } = require('@rocket/cli');
-
-module.exports = async function () {
-  const socialMediaImage = await createPageSocialImage({
-    title: 'Learning Rocket',
-    subTitle: 'Have a website',
-    subTitle2: 'in 5 Minutes',
-    footer: 'Rocket Guides',
-  });
-  return {
-    socialMediaImage,
-  };
-};

docs/guides/index.md

@@ -1,8 +0,0 @@
----
-title: Learning Rocket
-eleventyNavigation:
-  key: Guides
-  order: 10
----
-
-Rocket is a fundamentally straight forward way to generate static pages while still allowing to sprinkle in some JavaScript where needed.

docs/guides/presets/create-your-own.md

@@ -1,7 +0,0 @@
-# Presets >> Create your own || 90
-
-All loaded presets will be combined but you can override each file.
-
-Take a look at `docs/_merged_includes` and override what you want to override by placing the same filename into `_includes`.
-
-Also works for `_assets`, `_data` ...

docs/guides/presets/getting-started.md

@@ -1,7 +0,0 @@
-# Presets >> Getting Started ||10
-
-Presets are ...
-
-You can use a preset via the config...
-
-You can load multiple presets.

docs/guides/presets/index.md

@@ -1 +0,0 @@
-# Presets || 20

docs/guides/presets/overriding.md

@@ -1,7 +0,0 @@
-# Presets >> Overriding ||20
-
-All loaded presets will be combined but you can override each file.
-
-Take a look at `docs/_merged_includes` and override what you want to override by placing the same filename into `_includes`.
-
-Also works for `_assets`, `_data` ...

docs/guides/presets/using-templates.md

@@ -1,3 +0,0 @@
-# Presets >> Using templates ||30
-
-Most presetse have specific entry files you can override...

docs/index.11tydata.cjs

@@ -1,13 +0,0 @@
-const { createPageSocialImage } = require('@rocket/cli');
-
-module.exports = async function () {
-  const socialMediaImage = await createPageSocialImage({
-    title: 'Rocket',
-    subTitle: 'Static sites with',
-    subTitle2: 'a sprinkle of JavaScript.',
-    footer: 'A Modern Web Product',
-  });
-  return {
-    socialMediaImage,
-  };
-};

docs/sitemap.njk

@@ -1,15 +0,0 @@
----
-layout: pure-content.njk
-permalink: /sitemap.xml
-eleventyExcludeFromCollections: true
----
-<?xml version="1.0" encoding="utf-8"?>
-<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
-  {% for page in collections.all %}
-    <url>
-      <loc>{{ rocketConfig.absoluteBaseUrl }}{{ page.url | url }}</loc>
-      <lastmod>{{ page.date.toISOString() }}</lastmod>
-      <changefreq>{{ page.data.changeFreq if page.data.changeFreq else "monthly" }}</changefreq>
-    </url>
-  {% endfor %}
-</urlset>

examples/01-hydration-starter/.gitignore

@@ -0,0 +1,22 @@
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
+.DS_Store
+
+# Rocket ignore files
+*-mdjs-generated.js
+*-converted-html.js
+*-converted-md.js
+*-converted-md-source.js
+_site
+_site-dev

examples/01-hydration-starter/.vscode/settings.json

@@ -0,0 +1,8 @@
+{
+  "files.exclude": {
+    "**/*-mdjs-generated.js": true,
+  },
+  "search.exclude": {
+    "**/*-mdjs-generated.js": true,
+  }
+}

examples/01-hydration-starter/README.md

@@ -0,0 +1,44 @@
+# Rocket Starter Kit: Minimal
+
+```
+npx @rocket/create@latest --template 01-hydration-starter
+```
+
+> 🧑‍🚀 **Seasoned astronaut?** Delete this file. Have fun!
+
+## 🚀 Project Structure
+
+Inside of your Rocket project, you'll see the following folders and files:
+
+```
+.
+├── config
+│   └── rocket.config.js
+├── site
+│   ├── pages
+│   │   └── index.rocket.html
+│   └── public
+│       └── favicon.ico
+└── package.json
+```
+
+Rocket looks for `.rocket.md` or `.rocket.js` or `.rocket.html` files in the `site/pages` directory. Each page is exposed as a route based on its file name.
+
+There's nothing special about `site/src/components/`, but that's where we like to put our web components.
+
+Any static assets, that is not referenced via HTML but you still want to be on the web server we can place in the `site/public/` directory.
+
+## 🧞 Commands
+
+All commands are run from the root of the project, from a terminal:
+
+| Command           | Action                                       |
+| :---------------- | :------------------------------------------- |
+| `npm install`     | Installs dependencies                        |
+| `npm run start`   | Starts local dev server at `localhost:8000`  |
+| `npm run build`   | Build your production site to `./_site/`     |
+| `npm run preview` | Preview your build locally, before deploying |
+
+## 👀 Want to learn more?
+
+Feel free to check [our documentation](https://rocket.modern-web.dev) or jump into our [Discord server](https://rocket.modern-web.dev/chat).

examples/01-hydration-starter/config/rocket.config.js

@@ -0,0 +1,3 @@
+export default /** @type {import('@rocket/cli').RocketCliOptions} */ ({
+  absoluteBaseUrl: 'http://localhost:8080',
+});

examples/01-hydration-starter/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "rocket-hydration-starter",
+  "version": "0.0.1",
+  "private": true,
+  "description": "Example on how to hydrate web components",
+  "type": "module",
+  "scripts": {
+    "build": "rocket build",
+    "dev": "npm start",
+    "preview": "rocket preview",
+    "start": "NODE_DEBUG=engine:rendering rocket start --open"
+  },
+  "devDependencies": {
+    "@rocket/cli": "^0.20.0",
+    "@rocket/engine": "^0.2.0",
+    "@webcomponents/template-shadowroot": "^0.1.0",
+    "lit": "^2.3.0"
+  },
+  "@rocket/template-name": "Hydration Starter",
+  "imports": {
+    "#components/*": "./site/src/components/*"
+  }
+}

examples/01-hydration-starter/site/pages/index.rocket.js

@@ -0,0 +1,34 @@
+/* START - Rocket auto generated - do not touch */
+export const sourceRelativeFilePath = 'index.rocket.js';
+import { html, components, layout } from './recursive.data.js';
+export { html, components, layout };
+export async function registerCustomElements() {
+  // server-only components
+  customElements.define(
+    'hello-wave',
+    await import('#components/HelloWave.js').then(m => m.HelloWave),
+  );
+  // hydrate-able components
+  customElements.define(
+    'hello-typer',
+    await import('#components/HelloTyper.js').then(m => m.HelloTyper),
+  );
+  customElements.define(
+    'my-counter',
+    await import('#components/MyCounter.js').then(m => m.MyCounter),
+  );
+}
+export const needsLoader = true;
+/* END - Rocket auto generated - do not touch */
+
+export default () => html`
+  <h1>Hello World</h1>
+  <hello-wave></hello-wave>
+  <hello-typer loading="hydrate:onVisible"></hello-typer>
+  <details open>
+    <!-- put an open attribute on the details element to check hydration as you scroll down -->
+    <summary>👇</summary>
+    <p style="height: 120vh;">Emptiness of space</p>
+  </details>
+  <my-counter loading="hydrate:onVisible"></my-counter>
+`;

examples/01-hydration-starter/site/pages/pageTreeData.rocketGenerated.json

@@ -0,0 +1,15 @@
+{
+  "h1": "Hello World",
+  "name": "Hello World",
+  "menuLinkText": "Hello World",
+  "url": "/",
+  "outputRelativeFilePath": "index.html",
+  "sourceRelativeFilePath": "index.rocket.js",
+  "level": 0,
+  "components": {
+    "hello-wave": "#components/HelloWave.js::HelloWave",
+    "hello-typer": "#components/HelloTyper.js::HelloTyper",
+    "my-counter": "#components/MyCounter.js::MyCounter"
+  },
+  "needsLoader": true
+}

examples/01-hydration-starter/site/pages/recursive.data.js

@@ -0,0 +1,24 @@
+import { html } from 'lit';
+
+export { html };
+
+export const components = {
+  'hello-wave': '#components/HelloWave.js::HelloWave',
+  'hello-typer': '#components/HelloTyper.js::HelloTyper',
+  'my-counter': '#components/MyCounter.js::MyCounter',
+  //             👆 we are using a private import defined in the package json that maps
+  //             "#components/*": "./site/src/components/*"
+  //             (see https://nodejs.org/api/packages.html#packages_imports)
+};
+
+export const layout = data => html`
+  <!DOCTYPE html>
+  <html lang="en">
+    <head>
+      <meta charset="utf-8" />
+    </head>
+    <body>
+      ${data.content()}
+    </body>
+  </html>
+`;

examples/01-hydration-starter/site/public/icon.svg

@@ -0,0 +1,12 @@
+<svg width="105" height="101" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <path d="m19.91 91.438 12.445-4.705-8.09-7.465-4.355 12.17Z" fill="#FCB736"/>
+  <path d="M53.778 41.196c-1.6-5.176 1.444-10.652 6.844-12.192 5.378-1.54 11.067 1.39 12.667 6.588a9.426 9.426 0 0 1 .277 4.512 9.595 9.595 0 0 1-1.86 4.151 10.076 10.076 0 0 1-3.6 2.902 10.485 10.485 0 0 1-4.573 1.033c-4.4 0-8.444-2.738-9.755-6.994ZM68.666 16.62c-9.066 2.952-19.088 8.085-27.022 16.042-6.4 6.416-11.311 12.47-15 17.71a28.068 28.068 0 0 0-3.889.32A23.592 23.592 0 0 0 18.6 51.72C9.533 54.928-.49 63.42.133 65.11c.6 1.69 6.467-1.433 11.467-1.818 2.91-.236 5.178.042 6.91.492-.577 1.154-1.066 2.138-1.421 2.93-.378.791-.645 1.369-.823 1.732l18.09 16.705c.733-.385 2.377-1.112 4.733-2.353.266.813.51 1.776.644 2.866.156 1.091.222 2.332.156 3.743-.2 4.813-3.2 10.588-1.423 11.101 1.778.514 10.178-9.475 13.134-18.33.91-2.695 1.133-5.433 1.066-7.786 5.29-3.785 11.356-8.726 17.756-15.164 7.933-7.957 12.844-17.796 15.533-26.65 2.356-7.765 2.978-14.738 2.4-19.037a22.605 22.605 0 0 0-2.155-.085c-4.511-.022-10.756.962-17.534 3.165Z" fill="url(#a)"/>
+  <path d="m12.4 89.535 15.911-6.545-9.777-9.026-6.134 15.57Z" fill="#D08A06"/>
+  <path d="m10.488 82.733 12.467-4.684-8.089-7.465-4.378 12.149ZM90.644 16.406c.044 2.823-.267 6.096-.912 9.54 7.712 10.544 10.889 24.083 7.578 37.623-5.778 23.591-29.178 38.756-53.622 35.612-.133.15-.267.278-.4.428 27.045 4.834 53.556-11.614 59.911-37.666 4.111-16.897-1.155-33.752-12.555-45.537ZM2.82 42.158C8.955 17.048 35.088 1.477 61.177 7.401c5 1.134 9.644 2.973 13.822 5.39 3.6-.791 7.067-1.262 10.067-1.347-5.822-4.492-12.756-7.828-20.511-9.582C36.665-4.47 8.733 12.172 2.177 39.014a47.973 47.973 0 0 0-.511 20.619c.111-.107.222-.193.333-.3-.8-5.56-.6-11.378.822-17.175Z" fill="#FCB736"/>
+  <defs>
+    <linearGradient id="a" x1="26.5" y1="57" x2="89" y2="13" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#D21B1D"/>
+      <stop offset="1" stop-color="#C9181A"/>
+    </linearGradient>
+  </defs>
+</svg>

examples/01-hydration-starter/site/public/site.webmanifest

@@ -0,0 +1,19 @@
+{
+  "name": "Rocket",
+  "short_name": "Rocket",
+  "icons": [
+    {
+      "src": "/android-chrome-192x192.png",
+      "sizes": "192x192",
+      "type": "image/png"
+    },
+    {
+      "src": "/android-chrome-512x512.png",
+      "sizes": "512x512",
+      "type": "image/png"
+    }
+  ],
+  "theme_color": "#ffffff",
+  "background_color": "#ffffff",
+  "display": "standalone"
+}

examples/01-hydration-starter/site/src/components/HelloTyper.js

@@ -0,0 +1,54 @@
+import { LitElement, html, css } from 'lit';
+
+let i = 0;
+const fullText = [...'to this wonderful world of progressive hydration 🤯'];
+
+export class HelloTyper extends LitElement {
+  static properties = {
+    msg: { type: String },
+    counter: { type: Number },
+  };
+
+  constructor() {
+    super();
+    this.msg = ' ';
+    this.counter = 0;
+  }
+
+  updated(changedProperties) {
+    super.updated(changedProperties);
+    if (i < fullText.length) {
+      setTimeout(() => {
+        this.msg += fullText[i];
+        i += 1;
+      }, Math.floor(Math.random() * 50) + 40);
+    }
+  }
+
+  render() {
+    return html`
+      <p>🤔 Hello <span>${this.msg}</span>${'🤯'.repeat(this.counter)}</p>
+      <button @click=${this._inc}>+</button>
+    `;
+  }
+
+  _inc() {
+    if (i >= fullText.length) {
+      this.counter += 1;
+    }
+  }
+
+  static styles = [
+    css`
+      button {
+        font-size: 200%;
+        width: 64px;
+        height: 64px;
+        border: none;
+        border-radius: 10px;
+        background-color: seagreen;
+        color: white;
+      }
+    `,
+  ];
+}

examples/01-hydration-starter/site/src/components/HelloWave.js

@@ -0,0 +1,13 @@
+import { LitElement, html, css } from 'lit';
+
+export class HelloWave extends LitElement {
+  render() {
+    return html`<h2>Hello 👋</h2>`;
+  }
+
+  static styles = css`
+    h2 {
+      color: #e03131;
+    }
+  `;
+}

examples/01-hydration-starter/site/src/components/MyCounter.js

@@ -0,0 +1,41 @@
+import { LitElement, css, html } from 'lit';
+
+export class MyCounter extends LitElement {
+  constructor() {
+    super();
+    this.counter = 0;
+  }
+
+  render() {
+    return html`
+      <button @click=${() => (this.counter -= 1)}>-</button>
+      <span>${this.counter}</span>
+      <button @click=${() => (this.counter += 1)}>+</button>
+    `;
+  }
+
+  static styles = css`
+    * {
+      font-size: 200%;
+    }
+
+    span {
+      width: 4rem;
+      display: inline-block;
+      text-align: center;
+    }
+
+    button {
+      width: 64px;
+      height: 64px;
+      border: none;
+      border-radius: 10px;
+      background-color: seagreen;
+      color: white;
+    }
+  `;
+
+  static properties = {
+    counter: { type: Number },
+  };
+}

examples/01-hydration-starter/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "compilerOptions": {
+    "moduleResolution": "node",
+    "allowJs": true,
+    "checkJs": false,
+  }
+}

examples/02-blog-starter/.gitignore

@@ -0,0 +1,22 @@
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
+.DS_Store
+
+# Rocket ignore files
+*-mdjs-generated.js
+*-converted-html.js
+*-converted-md.js
+*-converted-md-source.js
+_site
+_site-dev

examples/02-blog-starter/README.md

@@ -0,0 +1,44 @@
+# Rocket Starter Kit: Blog
+
+```
+npx @rocket/create@latest --template 02-blog-starter
+```
+
+> 🧑‍🚀 **Seasoned astronaut?** Delete this file. Have fun!
+
+## 🚀 Project Structure
+
+Inside of your Rocket project, you'll see the following folders and files:
+
+```
+.
+├── config
+│   └── rocket.config.js
+├── site
+│   ├── pages
+│   │   └── index.rocket.html
+│   └── public
+│       └── favicon.ico
+└── package.json
+```
+
+Rocket looks for `.rocket.md` or `.rocket.js` or `.rocket.html` files in the `site/pages` directory. Each page is exposed as a route based on its file name.
+
+There's nothing special about `site/src/components/`, but that's where we like to put our web components.
+
+Any static assets, that is not referenced via HTML but you still want to be on the web server we can place in the `site/public/` directory.
+
+## 🧞 Commands
+
+All commands are run from the root of the project, from a terminal:
+
+| Command           | Action                                       |
+| :---------------- | :------------------------------------------- |
+| `npm install`     | Installs dependencies                        |
+| `npm run start`   | Starts local dev server at `localhost:8000`  |
+| `npm run build`   | Build your production site to `./_site/`     |
+| `npm run preview` | Preview your build locally, before deploying |
+
+## 👀 Want to learn more?
+
+Feel free to check [our documentation](https://rocket.modern-web.dev) or jump into our [Discord server](https://rocket.modern-web.dev/chat).

examples/02-blog-starter/config/rocket.config.js

@@ -0,0 +1,5 @@
+export default /** @type {import('@rocket/cli').RocketCliOptions} */ ({
+  absoluteBaseUrl: 'http://localhost:8080',
+  longFileHeaderWidth: 100,
+  longFileHeaderComment: '// prettier-ignore',
+});

examples/02-blog-starter/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "rocket-blog-starter",
+  "version": "0.0.1",
+  "private": true,
+  "description": "Get started with a new blog",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js",
+    "./styles/*": "./site/src/styles/*",
+    "./components/*": "./site/src/components/*.js"
+  },
+  "scripts": {
+    "build": "rocket build",
+    "dev": "npm start",
+    "preview": "rocket preview",
+    "start": "NODE_DEBUG=engine:rendering rocket start --open"
+  },
+  "devDependencies": {
+    "@rocket/cli": "^0.20.0",
+    "@rocket/engine": "^0.2.0",
+    "lit": "^2.3.0"
+  },
+  "@rocket/template-name": "Blog Starter"
+}

examples/02-blog-starter/site/pages/about.rocket.md

@@ -0,0 +1,18 @@
+```js server
+/* START - Rocket auto generated - do not touch */
+export const sourceRelativeFilePath = 'about.rocket.md';
+import { html, layout, components } from './recursive.data.js';
+export { html, layout, components };
+export async function registerCustomElements() {
+  // server-only components
+  // prettier-ignore
+  customElements.define('blog-header', await import('rocket-blog-starter/components/BlogHeader').then(m => m.BlogHeader));
+  // prettier-ignore
+  customElements.define('site-footer', await import('rocket-blog-starter/components/SiteFooter').then(m => m.SiteFooter));
+}
+/* END - Rocket auto generated - do not touch */
+```
+
+# About
+
+I love writing about things.

examples/02-blog-starter/site/pages/blog/hello-world.rocket.md

@@ -0,0 +1,42 @@
+```js server
+/* START - Rocket auto generated - do not touch */
+export const sourceRelativeFilePath = 'blog/hello-world.rocket.md';
+import { html, components } from '../recursive.data.js';
+import { layout } from './local.data.js';
+export { html, layout, components };
+export async function registerCustomElements() {
+  // server-only components
+  // prettier-ignore
+  customElements.define('blog-header', await import('rocket-blog-starter/components/BlogHeader').then(m => m.BlogHeader));
+  // prettier-ignore
+  customElements.define('blog-author', await import('rocket-blog-starter/components/BlogAuthor').then(m => m.BlogAuthor));
+  // prettier-ignore
+  customElements.define('blog-post', await import('rocket-blog-starter/components/BlogPost').then(m => m.BlogPost));
+  // prettier-ignore
+  customElements.define('site-footer', await import('rocket-blog-starter/components/SiteFooter').then(m => m.SiteFooter));
+}
+/* END - Rocket auto generated - do not touch */
+
+export const title = 'Hello world!';
+export const publishDate = '12 Sep 2021';
+export const author = 'Thomas Allmer (@daKmoR)';
+export const authorHref = 'https://twitter.com/daKmoR';
+export const value = 128;
+export const description = 'Just a Hello World Post!';
+```
+
+hey
+
+This is so cool!
+
+Do variables work ${value \* 2}?
+
+<br>
+
+---
+
+<br>
+
+There are multiple Co-Authors:
+
+- <blog-author name="Another Author" href="https://twitter.com/daKmoR"></blog-author>

examples/02-blog-starter/site/pages/blog/index.rocket.js

@@ -0,0 +1,9 @@
+/* START - Rocket auto generated - do not touch */
+export const sourceRelativeFilePath = 'blog/index.rocket.js';
+import { html, components } from '../recursive.data.js';
+export { html, components };
+/* END - Rocket auto generated - do not touch */
+
+export const layout = false;
+
+export default () => 'posts';

examples/02-blog-starter/site/pages/blog/local.data.js

@@ -0,0 +1,5 @@
+// everything you export here will be automatically injected into all pages
+
+import { LayoutBlogPost } from '../../src/layouts/LayoutBlogPost.js';
+
+export const layout = new LayoutBlogPost();

examples/02-blog-starter/site/pages/blog/with-image.rocket.md

@@ -0,0 +1,36 @@
+```js server
+/* START - Rocket auto generated - do not touch */
+export const sourceRelativeFilePath = 'blog/with-image.rocket.md';
+import { html, components } from '../recursive.data.js';
+import { layout } from './local.data.js';
+export { html, layout, components };
+export async function registerCustomElements() {
+  // server-only components
+  // prettier-ignore
+  customElements.define('blog-header', await import('rocket-blog-starter/components/BlogHeader').then(m => m.BlogHeader));
+  // prettier-ignore
+  customElements.define('blog-author', await import('rocket-blog-starter/components/BlogAuthor').then(m => m.BlogAuthor));
+  // prettier-ignore
+  customElements.define('blog-post', await import('rocket-blog-starter/components/BlogPost').then(m => m.BlogPost));
+  // prettier-ignore
+  customElements.define('site-footer', await import('rocket-blog-starter/components/SiteFooter').then(m => m.SiteFooter));
+}
+/* END - Rocket auto generated - do not touch */
+
+export const title = 'With Image!';
+export const publishDate = '13 Sep 2021';
+export const author = 'Thomas Allmer (@daKmoR)';
+export const authorHref = 'https://twitter.com/daKmoR';
+export const value = 128;
+export const description = 'Now with an image!';
+export const heroImage = './assets/liftoff-flames.jpg';
+export const alt = 'Liftoff Flames';
+```
+
+hey
+
+<blog-author name="Another Author" href="https://twitter.com/daKmoR"></blog-author>
+
+This is so cool!
+
+Do variables work ${value \* 2}?

examples/02-blog-starter/site/pages/index.rocket.js

@@ -0,0 +1,105 @@
+/* START - Rocket auto generated - do not touch */
+export const sourceRelativeFilePath = 'index.rocket.js';
+import { html, components } from './recursive.data.js';
+export { html, components };
+export async function registerCustomElements() {
+  // server-only components
+  // prettier-ignore
+  customElements.define('blog-header', await import('rocket-blog-starter/components/BlogHeader').then(m => m.BlogHeader));
+  // prettier-ignore
+  customElements.define('blog-post-preview', await import('rocket-blog-starter/components/BlogPostPreview').then(m => m.BlogPostPreview));
+  // prettier-ignore
+  customElements.define('site-footer', await import('rocket-blog-starter/components/SiteFooter').then(m => m.SiteFooter));
+}
+/* END - Rocket auto generated - do not touch */
+
+export const layout = false;
+
+import { PageTree } from '@rocket/engine';
+import { nothing } from 'lit';
+import { baseHead } from '../src/parts/baseHead.js';
+
+export const title = 'Example Blog';
+export const description = 'The perfect starter for your perfect blog.';
+export const permalink = 'https://example.com/';
+
+export const pageTree = new PageTree();
+await pageTree.restore(new URL('./pageTreeData.rocketGenerated.json', import.meta.url));
+
+class BlogMenu {
+  /**
+   * @returns {TemplateResult | nothing}
+   */
+  render() {
+    if (!this.currentNode || !this.currentNode.children) {
+      return nothing;
+    }
+    return html`
+      <div>
+        ${this.currentNode.children.map(
+          /** @param {NodeOfPage} child */ child => html`
+            <blog-post-preview .post=${child.model}></blog-post-preview>
+          `,
+        )}
+      </div>
+    `;
+  }
+}
+
+export default () => html`
+  <html lang="en">
+    <head>
+      ${baseHead({ title, description, permalink })}
+      <style>
+        header {
+          width: 100%;
+          height: 100%;
+          background-color: var(--theme-bg-offset);
+          display: flex;
+          align-items: center;
+          justify-content: center;
+        }
+
+        .content {
+          margin-top: 4rem;
+          margin-bottom: 8rem;
+        }
+
+        .content :global(main > * + *) {
+          margin-top: 1rem;
+        }
+
+        .intro {
+          padding-bottom: 4rem;
+          margin-bottom: 2rem;
+          border-bottom: 4px solid var(--theme-divider);
+        }
+
+        .intro > * {
+          margin: 0;
+        }
+
+        .latest {
+          font-size: 2.5rem;
+          font-weight: 700;
+        }
+      </style>
+    </head>
+
+    <body>
+      <blog-header></blog-header>
+      <div class="wrapper">
+        <main class="content">
+          <section class="intro">
+            <h1 class="latest">${title}</h1>
+            <p>${description}</p>
+          </section>
+          <section aria-label="Blog post list">
+            ${pageTree.renderMenu(new BlogMenu(), 'blog/index.rocket.js')}
+          </section>
+        </main>
+      </div>
+      <site-footer></site-footer>
+    </body>
+  </html>
+`;

examples/02-blog-starter/site/pages/pageTreeData.rocketGenerated.json

@@ -0,0 +1,110 @@
+{
+  "title": "Example Blog",
+  "h1": "\n            \n          ",
+  "name": "Example Blog",
+  "menuLinkText": "\n            \n          ",
+  "url": "/",
+  "outputRelativeFilePath": "index.html",
+  "sourceRelativeFilePath": "index.rocket.js",
+  "level": 0,
+  "components": {
+    "blog-author": "rocket-blog-starter/components/BlogAuthor::BlogAuthor",
+    "blog-header": "rocket-blog-starter/components/BlogHeader::BlogHeader",
+    "blog-post": "rocket-blog-starter/components/BlogPost::BlogPost",
+    "blog-post-preview": "rocket-blog-starter/components/BlogPostPreview::BlogPostPreview",
+    "site-footer": "rocket-blog-starter/components/SiteFooter::SiteFooter"
+  },
+  "description": "The perfect starter for your perfect blog.",
+  "layout": false,
+  "permalink": "https://example.com/",
+  "children": [
+    {
+      "title": "",
+      "h1": "\n            \n          ",
+      "headlinesWithId": [
+        {
+          "text": "About",
+          "id": "about",
+          "level": 1
+        }
+      ],
+      "name": "\n            \n          ",
+      "menuLinkText": "\n            \n          ",
+      "url": "/about/",
+      "outputRelativeFilePath": "about/index.html",
+      "sourceRelativeFilePath": "about.rocket.md",
+      "level": 1,
+      "components": {
+        "blog-author": "rocket-blog-starter/components/BlogAuthor::BlogAuthor",
+        "blog-header": "rocket-blog-starter/components/BlogHeader::BlogHeader",
+        "blog-post": "rocket-blog-starter/components/BlogPost::BlogPost",
+        "blog-post-preview": "rocket-blog-starter/components/BlogPostPreview::BlogPostPreview",
+        "site-footer": "rocket-blog-starter/components/SiteFooter::SiteFooter"
+      }
+    },
+    {
+      "name": "blog/index.rocket.js",
+      "menuLinkText": "blog/index.rocket.js",
+      "url": "/blog/",
+      "outputRelativeFilePath": "blog/index.html",
+      "sourceRelativeFilePath": "blog/index.rocket.js",
+      "level": 1,
+      "components": {
+        "blog-author": "rocket-blog-starter/components/BlogAuthor::BlogAuthor",
+        "blog-header": "rocket-blog-starter/components/BlogHeader::BlogHeader",
+        "blog-post": "rocket-blog-starter/components/BlogPost::BlogPost",
+        "blog-post-preview": "rocket-blog-starter/components/BlogPostPreview::BlogPostPreview",
+        "site-footer": "rocket-blog-starter/components/SiteFooter::SiteFooter"
+      },
+      "layout": false,
+      "children": [
+        {
+          "title": "Hello world!",
+          "h1": "\n            \n          ",
+          "name": "Hello world!",
+          "menuLinkText": "\n            \n          ",
+          "url": "/blog/hello-world/",
+          "outputRelativeFilePath": "blog/hello-world/index.html",
+          "sourceRelativeFilePath": "blog/hello-world.rocket.md",
+          "level": 2,
+          "author": "Thomas Allmer (@daKmoR)",
+          "authorHref": "https://twitter.com/daKmoR",
+          "components": {
+            "blog-author": "rocket-blog-starter/components/BlogAuthor::BlogAuthor",
+            "blog-header": "rocket-blog-starter/components/BlogHeader::BlogHeader",
+            "blog-post": "rocket-blog-starter/components/BlogPost::BlogPost",
+            "blog-post-preview": "rocket-blog-starter/components/BlogPostPreview::BlogPostPreview",
+            "site-footer": "rocket-blog-starter/components/SiteFooter::SiteFooter"
+          },
+          "description": "Just a Hello World Post!",
+          "publishDate": "12 Sep 2021",
+          "value": 128
+        },
+        {
+          "title": "With Image!",
+          "h1": "\n            \n          ",
+          "name": "With Image!",
+          "menuLinkText": "\n            \n          ",
+          "url": "/blog/with-image/",
+          "outputRelativeFilePath": "blog/with-image/index.html",
+          "sourceRelativeFilePath": "blog/with-image.rocket.md",
+          "level": 2,
+          "alt": "Liftoff Flames",
+          "author": "Thomas Allmer (@daKmoR)",
+          "authorHref": "https://twitter.com/daKmoR",
+          "components": {
+            "blog-author": "rocket-blog-starter/components/BlogAuthor::BlogAuthor",
+            "blog-header": "rocket-blog-starter/components/BlogHeader::BlogHeader",
+            "blog-post": "rocket-blog-starter/components/BlogPost::BlogPost",
+            "blog-post-preview": "rocket-blog-starter/components/BlogPostPreview::BlogPostPreview",
+            "site-footer": "rocket-blog-starter/components/SiteFooter::SiteFooter"
+          },
+          "description": "Now with an image!",
+          "heroImage": "./assets/liftoff-flames.jpg",
+          "publishDate": "13 Sep 2021",
+          "value": 128
+        }
+      ]
+    }
+  ]
+}

examples/02-blog-starter/site/pages/recursive.data.js

@@ -0,0 +1,15 @@
+// everything you export here will be automatically injected into all pages
+
+import { LayoutPage } from '../src/layouts/LayoutPage.js';
+
+export { html } from 'lit';
+
+export const layout = new LayoutPage();
+
+export const components = {
+  'blog-author': 'rocket-blog-starter/components/BlogAuthor::BlogAuthor',
+  'blog-header': 'rocket-blog-starter/components/BlogHeader::BlogHeader',
+  'blog-post': 'rocket-blog-starter/components/BlogPost::BlogPost',
+  'blog-post-preview': 'rocket-blog-starter/components/BlogPostPreview::BlogPostPreview',
+  'site-footer': 'rocket-blog-starter/components/SiteFooter::SiteFooter',
+};