Version Packages

README.md

@@ -28,7 +28,7 @@
 <p align="center">
   <a href="https://rocket.modern-web.dev">Website</a>
   ·
-  <a href="https://rocket.modern-web.dev/doc/">Documentation</a>
+  <a href="https://rocket.modern-web.dev/docs/">Documentation</a>
   ·
   <a href="https://rocket.modern-web.dev/chat">Discord Community</a>
 </p>

package.json

@@ -35,8 +35,9 @@
     "setup:ts-configs": "node scripts/generate-ts-configs.mjs",
     "start:experimental": "NODE_DEBUG=engine:rendering node --no-warnings --experimental-loader ./packages/engine/src/litCssLoader.js packages/cli/src/cli.js start --open",
     "start": "NODE_DEBUG=engine:rendering node --trace-warnings packages/cli/src/cli.js start --open",
+    "preview": "node packages/cli/src/cli.js preview --open",
     "test": "yarn test:node && yarn test:web",
-    "test:integration": "playwright test packages/*/test-node/*.spec.js",
+    "test:integration": "playwright test packages/*/test-node/*.spec.js --retries=3",
     "test:node": "yarn test:unit && yarn test:integration",
     "test:unit": "node --trace-warnings ./node_modules/.bin/mocha --require ./scripts/testMochaGlobalHooks.js \"packages/*/test-node/**/*.test.{ts,js,mjs,cjs}\" -- --timeout 8000 --reporter dot --exit",
     "test:web": "web-test-runner",

packages/cli/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @rocket/cli
 
+## 0.20.2
+
+### Patch Changes
+
+- 39206a1: `rocket start` now outputs to `_site-dev` instead of `_site`.
+- 39206a1: `rocket start` clears only its output folder (defaults to `_site-dev`)
+- cbfb0f9: Add `rocket preview` command to enable fast checking of the production build
+
+## 0.20.1
+
+### Patch Changes
+
+- 8dedc56: Add start message for `rocket start`
+
+  ```
+  🚀 Rocket Engine v0.2.5
+
+    🚧 Local:    http://localhost:8000/
+    🌐 Network:  http://xxx.xxx.xxx.xxx:8000/
+  ```
+
+- Updated dependencies [8dedc56]
+- Updated dependencies [390335d]
+  - @rocket/engine@0.2.6
+
 ## 0.20.0
 
 ### Minor Changes

packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rocket/cli",
-  "version": "0.20.0",
+  "version": "0.20.2",
   "publishConfig": {
     "access": "public"
   },
@@ -53,16 +53,18 @@
   ],
   "dependencies": {
     "@rocket/building-rollup": "^0.4.0",
-    "@rocket/engine": "^0.2.0",
+    "@rocket/engine": "^0.2.6",
     "@web/rollup-plugin-copy": "^0.3.0",
     "colorette": "^2.0.16",
     "commander": "^9.0.0",
     "fs-extra": "^9.0.1",
     "gray-matter": "^4.0.3",
+    "ip": "^1.1.5",
     "plugins-manager": "^0.3.0",
     "puppeteer": "^13.0.0"
   },
   "devDependencies": {
+    "@types/ip": "^1.1.0",
     "koa-proxy": "^1.0.0-alpha.3"
   },
   "types": "./dist-types/src/index.d.ts",

packages/cli/src/RocketBuild.js

@@ -88,6 +88,8 @@ export class RocketBuild {
 
   async build() {
     await this.cli.events.dispatchEventDone('build-start');
+    await this.cli.clearOutputDir();
+    await this.cli.clearOutputDevDir();
 
     this.engine = new Engine();
     this.engine.setOptions({

packages/cli/src/RocketCli.js

@@ -4,6 +4,7 @@ import { RocketStart } from './RocketStart.js';
 import { RocketBuild } from './RocketBuild.js';
 import { RocketInit } from './RocketInit.js';
 import { RocketUpgrade } from './RocketUpgrade.js';
+import { RocketPreview } from './RocketPreview.js';
 // import { ignore } from './images/ignore.js';
 
 import path from 'path';
@@ -34,7 +35,7 @@ export class RocketCli {
     open: false,
     cwd: process.cwd(),
     inputDir: 'FALLBACK',
-    outputDir: '_site',
+    outputDir: 'FALLBACK',
     outputDevDir: '_site-dev',
 
     serviceWorkerSourcePath: '',
@@ -93,6 +94,9 @@ export class RocketCli {
     if (this.options.inputDir === 'FALLBACK') {
       this.options.inputDir = path.join(this.options.cwd, 'site', 'pages');
     }
+    if (this.options.outputDir === 'FALLBACK') {
+      this.options.outputDir = path.join(this.options.cwd, '_site');
+    }
     if (this.options.inputDir instanceof URL) {
       this.options.inputDir = this.options.inputDir.pathname;
     }
@@ -122,7 +126,6 @@ export class RocketCli {
   }
 
   async prepare() {
-    await this.clearOutputDirs();
     if (!this.options.presets) {
       return;
     }
@@ -180,6 +183,7 @@ export class RocketCli {
       { plugin: RocketInit, options: {} },
       // { plugin: RocketLint },
       { plugin: RocketUpgrade, options: {} },
+      { plugin: RocketPreview, options: {} },
     ];
 
     if (Array.isArray(this.options.setupCliPlugins)) {
@@ -230,10 +234,13 @@ export class RocketCli {
     }
   }
 
-  async clearOutputDirs() {
+  async clearOutputDir() {
     if (this.options.outputDir && existsSync(this.options.outputDir)) {
       await rm(this.options.outputDir, { recursive: true, force: true });
     }
+  }
+
+  async clearOutputDevDir() {
     if (this.options.outputDevDir && existsSync(this.options.outputDevDir)) {
       await rm(this.options.outputDevDir, { recursive: true, force: true });
     }

packages/cli/src/RocketPreview.js

@@ -0,0 +1,79 @@
+import { logPreviewMessage } from './preview/logPreviewMessage.js';
+import { startDevServer } from '@web/dev-server';
+import path from 'path';
+import { existsSync } from 'fs';
+import { gray, bold } from 'colorette';
+
+export class RocketPreview {
+  /**
+   * @param {import('commander').Command} program
+   * @param {import('./RocketCli.js').RocketCli} cli
+   */
+  async setupCommand(program, cli) {
+    this.cli = cli;
+    this.active = true;
+
+    program
+      .command('preview')
+      .option('-i, --input-dir <path>', 'path to the folder with the build html files')
+      .option('-o, --open', 'automatically open the browser')
+      .action(async cliOptions => {
+        cli.setOptions(cliOptions);
+        cli.activePlugin = this;
+
+        await this.preview();
+      });
+  }
+
+  async preview() {
+    if (!this.cli) {
+      return;
+    }
+
+    // for typescript as `this.cli.options.outputDir` supports other inputs as well
+    // but the cli will normalize it to a string before calling plugins
+    if (
+      typeof this.cli.options.inputDir !== 'string' ||
+      typeof this.cli.options.outputDir !== 'string'
+    ) {
+      return;
+    }
+
+    const rootIndexHtml = path.join(this.cli.options.outputDir, 'index.html');
+    if (!existsSync(rootIndexHtml)) {
+      console.log(`${bold(`👀 Previewing Production Build`)}`);
+      console.log('');
+      console.log(`  🛑 No index.html found in the build directory ${gray(`${rootIndexHtml}`)}`);
+      console.log('  🤔 Did you forget to run `rocket build` before?');
+      console.log('');
+      return;
+    }
+
+    /** @type {import('@web/dev-server').DevServerConfig} */
+    const config = {
+      open: this.cli.options.open,
+      rootDir: this.cli.options.outputDir,
+      clearTerminalOnReload: false,
+    };
+
+    try {
+      this.devServer = await startDevServer({
+        config,
+        logStartMessage: false,
+        readCliArgs: false,
+        readFileConfig: false,
+        // argv: this.__argv,
+      });
+      logPreviewMessage({ devServerOptions: this.devServer.config }, console);
+    } catch (e) {
+      console.log('🛑 Starting preview server failed');
+      console.error(e);
+    }
+  }
+
+  async stop() {
+    if (this.devServer) {
+      await this.devServer.stop();
+    }
+  }
+}

packages/cli/src/RocketStart.js

@@ -1,6 +1,7 @@
 import { fromRollup } from '@web/dev-server-rollup';
 
 import { Engine } from '@rocket/engine/server';
+import { logStartMessage } from './start/logStartMessage.js';
 
 export class RocketStart {
   /** @type {Engine | undefined} */
@@ -30,11 +31,12 @@ export class RocketStart {
     if (!this.cli) {
       return;
     }
+    await this.cli.clearOutputDevDir();
 
     // TODO: enable URL support in the Engine and remove this "workaround"
     if (
       typeof this.cli.options.inputDir !== 'string' ||
-      typeof this.cli.options.outputDir !== 'string'
+      typeof this.cli.options.outputDevDir !== 'string'
     ) {
       return;
     }
@@ -49,7 +51,7 @@ export class RocketStart {
     this.engine = new Engine();
     this.engine.setOptions({
       docsDir: this.cli.options.inputDir,
-      outputDir: this.cli.options.outputDir,
+      outputDir: this.cli.options.outputDevDir,
       setupPlugins: this.cli.options.setupEnginePlugins,
       open: this.cli.options.open,
       longFileHeaderWidth: this.cli.options.longFileHeaderWidth,
@@ -60,7 +62,14 @@ export class RocketStart {
       setupDevServerPlugins: [...this.cli.options.setupDevServerPlugins, ...withWrap],
     });
     try {
-      console.log('🚀 Engines online');
+      this.engine.events.on('devServerStarted', () => {
+        if (this.engine?.devServer) {
+          logStartMessage(
+            { devServerOptions: this.engine.devServer?.config, engine: this.engine },
+            console,
+          );
+        }
+      });
       await this.engine.start();
     } catch (e) {
       console.log('Engine start errored');
@@ -71,7 +80,6 @@ export class RocketStart {
   async stop({ hard = true } = {}) {
     if (this.engine) {
       await this.engine.stop({ hard });
-      console.log('🚀 Engines offline');
     }
   }
 }

packages/cli/src/helpers/infoMessages.js

@@ -0,0 +1,34 @@
+import ip from 'ip';
+import { white, cyan } from 'colorette';
+
+/** @typedef {import('@web/dev-server').DevServerConfig} DevServerConfig */
+
+/**
+ *
+ * @param {DevServerConfig} devServerOptions
+ * @param {string} host
+ * @param {string} path
+ * @returns {string}
+ */
+export function createAddress(devServerOptions, host, path) {
+  return `http${devServerOptions.http2 ? 's' : ''}://${host}:${devServerOptions.port}${path}`;
+}
+
+/**
+ *
+ * @param {DevServerConfig} devServerOptions
+ * @param {console} logger
+ * @param {string} openPath
+ */
+export function logNetworkAddress(devServerOptions, logger, openPath) {
+  try {
+    const address = ip.address();
+    if (typeof address === 'string') {
+      logger.log(
+        `${white('  🌐 Network:')}  ${cyan(createAddress(devServerOptions, address, openPath))}`,
+      );
+    }
+  } catch (_a) {
+    //
+  }
+}

packages/cli/src/preview/logPreviewMessage.js

@@ -0,0 +1,33 @@
+import { white, bold, cyan, gray } from 'colorette';
+import { createAddress, logNetworkAddress } from '../helpers/infoMessages.js';
+
+/** @typedef {import('@web/dev-server').DevServerConfig} DevServerConfig */
+
+/**
+ * @param {{ devServerOptions: DevServerConfig}} options
+ * @param {console} logger
+ */
+export function logPreviewMessage({ devServerOptions }, logger) {
+  const prettyHost = devServerOptions.hostname ?? 'localhost';
+  let openPath = typeof devServerOptions.open === 'string' ? devServerOptions.open : '/';
+  if (!openPath.startsWith('/')) {
+    openPath = `/${openPath}`;
+  }
+
+  logger.log(`${bold(`👀 Previewing Production Build`)}`);
+  logger.log('');
+  logger.log(
+    `${white('  🚧 Local:')}    ${cyan(createAddress(devServerOptions, prettyHost, openPath))}`,
+  );
+  logNetworkAddress(devServerOptions, logger, openPath);
+  const sourceDir = devServerOptions.rootDir;
+  if (sourceDir) {
+    logger.log(`${white('  📝 Source:')}   ${cyan(sourceDir)}`);
+  }
+  logger.log('');
+  logger.log(
+    gray(
+      'If what you see works as expected then you can upload "source" to your production web server.',
+    ),
+  );
+}

packages/cli/src/start/logStartMessage.js

@@ -0,0 +1,24 @@
+import { white, bold, cyan, gray } from 'colorette';
+import { createAddress, logNetworkAddress } from '../helpers/infoMessages.js';
+
+/** @typedef {import('@web/dev-server').DevServerConfig} DevServerConfig */
+
+/**
+ * @param {{ devServerOptions: DevServerConfig, engine: import('@rocket/engine/server').Engine}} options
+ * @param {console} logger
+ */
+export function logStartMessage({ devServerOptions, engine }, logger) {
+  const prettyHost = devServerOptions.hostname ?? 'localhost';
+  let openPath = typeof devServerOptions.open === 'string' ? devServerOptions.open : '/';
+  if (!openPath.startsWith('/')) {
+    openPath = `/${openPath}`;
+  }
+
+  logger.log(`${bold(`🚀 Rocket Engine`)} ${gray(`v${engine.getVersion()}`)}`);
+  logger.log('');
+  logger.log(
+    `${white('  🚧 Local:')}    ${cyan(createAddress(devServerOptions, prettyHost, openPath))}`,
+  );
+  logNetworkAddress(devServerOptions, logger, openPath);
+  logger.log('');
+}

packages/cli/test-helpers/index.js

@@ -5,7 +5,7 @@ import { setupTestCli } from './test-helpers.js';
 
 export function prepareTestCli(importMetaUrl) {
   const dir = path.dirname(fileURLToPath(importMetaUrl));
-  return (cwd, cliOptions = ['build'], options = {}) => setupTestCli(cwd, cliOptions, options, dir);
+  return fullOptions => setupTestCli({ dir, ...fullOptions });
 }
 
 const { expect } = chai;

packages/cli/test-helpers/test-helpers.js

@@ -60,7 +60,13 @@ function cleanupLitMarkersFn(text) {
   return newText;
 }
 
-export async function setupTestCli(cwd, cliOptions = ['build'], options = {}, dir) {
+export async function setupTestCli({
+  cwd,
+  cliOptions = ['build'],
+  options = {},
+  testOptions = {},
+  dir,
+}) {
   const resolvedCwd = path.join(dir, cwd.split('/').join(path.sep));
   const useOptions = { buildOptimize: false, buildAutoStop: false, ...options, cwd: resolvedCwd };
   if (useOptions.inputDir) {
@@ -69,6 +75,18 @@ export async function setupTestCli(cwd, cliOptions = ['build'], options = {}, di
   useOptions.outputDir = path.join(resolvedCwd, '__output');
   useOptions.outputDevDir = path.join(resolvedCwd, '__output-dev');
 
+  const capturedLogs = [];
+  const origLog = console.log;
+  const origError = console.error;
+  if (testOptions.captureLogs) {
+    console.log = msg => {
+      capturedLogs.push(msg);
+    };
+    console.error = msg => {
+      capturedLogs.push(msg);
+    };
+  }
+
   const cli = new RocketCli({
     argv: [process.argv[0], new URL('../src/cli.js', import.meta.url).pathname, ...cliOptions],
   });
@@ -184,6 +202,10 @@ export async function setupTestCli(cwd, cliOptions = ['build'], options = {}, di
 
   async function cleanup() {
     await cli.stop({ hard: false });
+    if (testOptions.captureLogs) {
+      console.log = origLog;
+      console.error = origError;
+    }
   }
 
   async function build() {
@@ -243,5 +265,6 @@ export async function setupTestCli(cwd, cliOptions = ['build'], options = {}, di
     renameSource,
     backupOrRestoreSource,
     restoreSource,
+    capturedLogs,
   };
 }

packages/cli/test-node/01-config.test.js

@@ -8,11 +8,11 @@ const { expect } = chai;
 
 describe('Config', () => {
   it('01: no config file', async () => {
-    const { build, readOutput, readDevOutput } = await setupTestCli(
+    const { build, readOutput, readDevOutput } = await setupTestCli({
-      'fixtures/01-config/01-no-config/',
+      cwd: 'fixtures/01-config/01-no-config/',
-      undefined,
+      options: { buildOptimize: true },
-      { buildOptimize: true },
+      testOptions: { captureLogs: true },
-    );
+    });
     await build();
 
     expect(readOutput('index.html')).to.equal(
@@ -31,14 +31,21 @@ describe('Config', () => {
   });
 
   it('02: change input dir', async () => {
-    const { build, readDevOutput } = await setupTestCli('fixtures/01-config/02-change-input-dir/');
+    const { build, readDevOutput } = await setupTestCli({
+      cwd: 'fixtures/01-config/02-change-input-dir/',
+      testOptions: { captureLogs: true },
+    });
     await build();
 
     expect(readDevOutput('index.html')).to.equal(['Hello World!'].join('\n'));
   });
 
   it('03: can add a middleware (api proxy) to the dev server', async () => {
-    const { cleanup, cli } = await setupTestCli('fixtures/01-config/03-add-middleware/', ['start']);
+    const { cleanup, cli } = await setupTestCli({
+      cwd: 'fixtures/01-config/03-add-middleware/',
+      cliOptions: ['start'],
+      testOptions: { captureLogs: true },
+    });
     const apiServer = http.createServer((request, response) => {
       if (request.url === '/api/message') {
         response.writeHead(200);
@@ -61,20 +68,22 @@ describe('Config', () => {
   });
 
   it('04: can add a rollup plugin via setupDevServerAndBuildPlugins to build', async () => {
-    const { build, readOutput } = await setupTestCli(
+    const { build, readOutput } = await setupTestCli({
-      'fixtures/01-config/04-add-rollup-plugin/',
+      cwd: 'fixtures/01-config/04-add-rollup-plugin/',
-      undefined,
+      options: { buildOptimize: true },
-      { buildOptimize: true },
+      testOptions: { captureLogs: true },
-    );
+    });
     await build();
     const inlineModule = await readOutput('e97af63d.js', { format: false });
     expect(inlineModule).to.equal('var a={test:"data"};console.log(a);\n');
   });
 
   it('04a: can add a rollup plugin via setupDevServerAndBuildPlugins to start', async () => {
-    const { cli, cleanup } = await setupTestCli('fixtures/01-config/04-add-rollup-plugin/', [
+    const { cli, cleanup } = await setupTestCli({
-      'start',
+      cwd: 'fixtures/01-config/04-add-rollup-plugin/',
-    ]);
+      cliOptions: ['start'],
+      testOptions: { captureLogs: true },
+    });
     await cli.start();
     const { port } = cli?.activePlugin?.engine.devServer.config;
 
@@ -88,9 +97,10 @@ describe('Config', () => {
   });
 
   it('05: long file header comments', async () => {
-    const { build, readSource } = await setupTestCli(
+    const { build, readSource } = await setupTestCli({
-      'fixtures/01-config/05-long-file-header-comment/',
+      cwd: 'fixtures/01-config/05-long-file-header-comment/',
-    );
+      testOptions: { captureLogs: true },
+    });
     await build();
 
     expect(readSource('index.rocket.js', { format: false })).to.equal(

packages/cli/test-node/02-build.test.js

@@ -5,13 +5,13 @@ const { expect } = chai;
 
 describe('Build', () => {
   it('01: copy public files', async () => {
-    const { build, readOutput, outputExists, readDevOutput } = await setupTestCli(
+    const { build, readOutput, outputExists, readDevOutput } = await setupTestCli({
-      'fixtures/02-build/01-copy-public-files/',
+      cwd: 'fixtures/02-build/01-copy-public-files/',
-      undefined,
+      options: {
-      {
         buildOptimize: true,
       },
-    );
+      testOptions: { captureLogs: true },
+    });
     await build();
 
     expect(readOutput('index.html')).to.equal(

packages/cli/test-node/03-upgrade.test.js

@@ -6,7 +6,11 @@ const { expect } = chai;
 describe('Upgrade System', () => {
   it('2021-09-menu', async () => {
     const { build, sourceExists, readSource, backupOrRestoreSource, restoreSource } =
-      await setupTestCli('fixtures/03-upgrade/2022-03-menu', ['upgrade']);
+      await setupTestCli({
+        cwd: 'fixtures/03-upgrade/2022-03-menu',
+        cliOptions: ['upgrade'],
+        testOptions: { captureLogs: true },
+      });
     await backupOrRestoreSource();
 
     await build();

packages/cli/test-node/04-open-graph.test.js

@@ -5,13 +5,13 @@ const { expect } = chai;
 
 describe('Open Graph', () => {
   it('generates the image and adds the meta tags', async () => {
-    const { build, readOutput, outputExists } = await setupTestCli(
+    const { build, readOutput, outputExists } = await setupTestCli({
-      'fixtures/04-open-graph/01-generate-image-and-inject-meta',
+      cwd: 'fixtures/04-open-graph/01-generate-image-and-inject-meta',
-      undefined,
+      options: {
-      {
         buildOptimize: true,
       },
-    );
+      testOptions: { captureLogs: true },
+    });
     await build();
 
     expect(readOutput('index.html', { replaceImageHashes: true })).to.equal(
@@ -35,13 +35,13 @@ describe('Open Graph', () => {
   });
 
   it('handles multiple pages', async () => {
-    const { build, readOutput } = await setupTestCli(
+    const { build, readOutput } = await setupTestCli({
-      'fixtures/04-open-graph/02-multiple-pages',
+      cwd: 'fixtures/04-open-graph/02-multiple-pages',
-      undefined,
+      options: {
-      {
         buildOptimize: true,
       },
-    );
+      testOptions: { captureLogs: true },
+    });
     await build();
 
     expect(readOutput('index.html', { replaceImageHashes: true })).to.equal(

packages/cli/test-node/05-start.test.js

@@ -0,0 +1,25 @@
+import chai from 'chai';
+import { white, bold } from 'colorette';
+
+import { setupTestCli } from './test-helpers.js';
+
+const { expect } = chai;
+
+describe('Start', () => {
+  it('Start Message', async () => {
+    const { cli, capturedLogs, cleanup } = await setupTestCli({
+      cwd: 'fixtures/05-start/01-start-message',
+      cliOptions: ['start'],
+      testOptions: { captureLogs: true },
+    });
+
+    await cli.start();
+    await cleanup();
+
+    expect(capturedLogs[0].startsWith(`${bold(`🚀 Rocket Engine`)} `)).to.be.true;
+    expect(capturedLogs[1]).to.equal('');
+    expect(capturedLogs[2].startsWith(`${white('  🚧 Local:')}`)).to.be.true;
+    expect(capturedLogs[3].startsWith(`${white('  🌐 Network:')}`)).to.be.true;
+    expect(capturedLogs[4]).to.equal('');
+  });
+});

packages/cli/test-node/06-preview.test.js

@@ -0,0 +1,49 @@
+import chai from 'chai';
+import { white, bold, gray } from 'colorette';
+
+import { setupTestCli } from './test-helpers.js';
+
+const { expect } = chai;
+
+describe('Preview', () => {
+  it('01: Preview Message', async () => {
+    const { cli, capturedLogs, cleanup } = await setupTestCli({
+      cwd: 'fixtures/06-preview/01-preview-message',
+      cliOptions: ['preview'],
+      testOptions: { captureLogs: true },
+    });
+
+    await cli.start();
+    await cleanup();
+
+    expect(capturedLogs[0]).to.equal(`${bold(`👀 Previewing Production Build`)}`);
+    expect(capturedLogs[1]).to.equal('');
+    expect(capturedLogs[2].startsWith(`${white('  🚧 Local:')}`)).to.be.true;
+    expect(capturedLogs[3].startsWith(`${white('  🌐 Network:')}`)).to.be.true;
+    expect(capturedLogs[4].startsWith(`${white('  📝 Source:')}`)).to.be.true;
+    expect(capturedLogs[5]).to.equal('');
+    expect(capturedLogs[6]).to.equal(
+      `${gray(
+        'If what you see works as expected then you can upload "source" to your production web server.',
+      )}`,
+    );
+  });
+
+  it('02: Error Message if there is no build output', async () => {
+    const { cli, capturedLogs, cleanup } = await setupTestCli({
+      cwd: 'fixtures/06-preview/02-error-no-build',
+      cliOptions: ['preview'],
+      testOptions: { captureLogs: true },
+    });
+
+    await cli.start();
+    await cleanup();
+
+    expect(capturedLogs[0]).to.equal(`${bold(`👀 Previewing Production Build`)}`);
+    expect(capturedLogs[1]).to.equal('');
+    expect(capturedLogs[2].startsWith(`  🛑 No index.html found in the build directory`)).to.be
+      .true;
+    expect(capturedLogs[3]).to.equal('  🤔 Did you forget to run `rocket build` before?');
+    expect(capturedLogs[4]).to.equal('');
+  });
+});

packages/cli/test-node/fixtures/05-start/01-start-message/site/pages/index.rocket.js

@@ -0,0 +1,5 @@
+/* START - Rocket auto generated - do not touch */
+export const sourceRelativeFilePath = 'index.rocket.js';
+/* END - Rocket auto generated - do not touch */
+
+export default () => 'Hello World!';

packages/cli/test-node/fixtures/05-start/01-start-message/site/pages/pageTreeData.rocketGenerated.json

@@ -0,0 +1,8 @@
+{
+  "name": "index.rocket.js",
+  "menuLinkText": "index.rocket.js",
+  "url": "/",
+  "outputRelativeFilePath": "index.html",
+  "sourceRelativeFilePath": "index.rocket.js",
+  "level": 0
+}

packages/cli/test-node/fixtures/06-preview/01-preview-message/.gitignore

@@ -0,0 +1 @@
+!__output

packages/cli/test-node/fixtures/06-preview/01-preview-message/__output/index.html

@@ -0,0 +1 @@
+so preview does not stop

packages/engine/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @rocket/engine
 
+## 0.2.6
+
+### Patch Changes
+
+- 8dedc56: Add `engine.getVersion()` method
+- 390335d: Improve title tag handling
+
+## 0.2.5
+
+### Patch Changes
+
+- 93503ed: HTML in headings will be ignored for the menu
+  Some examples:
+
+  - `<h1>Hello <em>Word</em></h1>` => `Hello Word`
+  - `<h1>Hello <strong>World</strong> of <span>JS <em>(JavaScript)</em></span>!</h1>` => `Hello World of JS (JavaScript)!`
+
+- 3032ba9: Menus now support special characters in markdown headings.
+
+  Examples:
+
+  ```md
+  # Fun Errors & Feedback
+
+  # &lt;some-button>
+  ```
+
 ## 0.2.4
 
 ### Patch Changes

packages/engine/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rocket/engine",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "publishConfig": {
     "access": "public"
   },
@@ -36,7 +36,7 @@
     "debug": "DEBUG=engine:rendering yarn test",
     "debug:integration": "PWDEBUG=1 yarn test:integration",
     "test": "mocha --require ../../scripts/testMochaGlobalHooks.js --timeout 8000 test-node/**/*.test.js test-node/*.test.js",
-    "test:integration": "playwright test test-node/*.spec.js",
+    "test:integration": "playwright test test-node/*.spec.js --retries=3",
     "test:watch": "onchange 'src/**/*.js' 'test-node/**/*.js' -- npm test",
     "types:copy": "copyfiles \"./types/**/*.d.ts\" dist-types/"
   },

packages/engine/src/Engine.js

@@ -7,7 +7,7 @@
 import { existsSync } from 'fs';
 // TODO: implement copy without extra dependency => node 16.7.0 copy has recursive
 import fse from 'fs-extra';
-import { mkdir, rm } from 'fs/promises';
+import { mkdir, readFile, rm } from 'fs/promises';
 import path from 'path';
 import { EventEmitter } from 'events';
 import { startDevServer } from '@web/dev-server';
@@ -32,6 +32,8 @@ import { RocketHeader } from './file-header/RocketHeader.js';
 
 const logRendering = debuglog('engine:rendering');
 
+const pkgJson = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+
 export class Engine {
   /** @type {EngineOptions} */
   options = {
@@ -121,8 +123,10 @@ export class Engine {
       if (pageTree.pageTreeChangedOnSave) {
         for (const sourceFilePath of sourceFiles) {
           const result = await this.renderFile({ sourceFilePath, throwOnError: true });
+          await pageTree.add(result.sourceRelativeFilePath);
           await cleanupAutoGeneratedFiles(result);
         }
+        await pageTree.save();
       }
     }
 
@@ -265,6 +269,7 @@ export class Engine {
       readFileConfig: false,
       // argv: this.__argv,
     });
+    this.events.emit('devServerStarted');
 
     this.devServer.webSockets.on(
       'message',
@@ -467,4 +472,8 @@ export class Engine {
     }
     return result;
   }
+
+  getVersion() {
+    return pkgJson.version;
+  }
 }

packages/engine/src/web-menu/getHtmlMetaData.js

@@ -28,10 +28,28 @@ export function getHtmlMetaData(htmlFilePath) {
   const metaData = {
     // headlinesWithId: [],
   };
-
+  /** @type {string | undefined} */
+  let capturedHeadlineText = undefined;
+  let withinHTMLHead = false;
   parser.eventHandler = (ev, _data) => {
+    if (ev === SaxEventType.OpenTag) {
+      const data = /** @type {Tag} */ (/** @type {any} */ (_data));
+      if (isHeadline(data)) {
+        capturedHeadlineText = '';
+      }
+      if (data.name === 'head') {
+        withinHTMLHead = true;
+      }
+    }
+
+    if (capturedHeadlineText !== undefined && ev === SaxEventType.Text) {
+      const data = /** @type {Text} */ (/** @type {any} */ (_data));
+      capturedHeadlineText += data.value;
+    }
+
     if (ev === SaxEventType.CloseTag) {
       const data = /** @type {Tag} */ (/** @type {any} */ (_data));
+      // ********** <meta name="*" content="*">
       if (data.name === 'meta') {
         const metaName = getAttribute(data, 'name');
         if (metaName === 'menu:link.text') {
@@ -60,29 +78,39 @@ export function getHtmlMetaData(htmlFilePath) {
           metaData.menuNoLink = getAttribute(data, 'content') !== 'false';
         }
       }
-      if (!metaData.title && data.name === 'title') {
+      if (withinHTMLHead && data.name === 'title') {
         metaData.title = getText(data);
       }
-      if (!metaData.h1 && data.name === 'h1') {
-        metaData.h1 = getText(data);
-      }
 
+      // ********** <h1> - <h6>
       if (isHeadline(data)) {
         const id = getAttribute(data, 'id');
-        const rawText = getText(data);
         const linkText = getAttribute(data, 'link-text');
-        if (id && rawText) {
+        const processedCapturedHeadlineText = capturedHeadlineText
+          ?.replace(/&#x3C;/g, '&lt;')
+          .replace(/&#x26;/g, '&')
+          .trim();
+        const text = linkText || processedCapturedHeadlineText || '';
+        if (!metaData.h1 && data.name === 'h1') {
+          metaData.h1 = text;
+        }
+        if (id && text) {
           if (!metaData.headlinesWithId) {
             metaData.headlinesWithId = [];
           }
-          const rawTextObj = linkText ? { rawText } : {};
+          const rawTextObj = linkText ? { rawText: processedCapturedHeadlineText } : {};
           metaData.headlinesWithId.push({
-            text: linkText || rawText,
+            text,
             id,
             level: parseInt(data.name[1], 10),
             ...rawTextObj,
           });
         }
+        capturedHeadlineText = undefined;
+      }
+
+      if (data.name === 'head') {
+        withinHTMLHead = false;
       }
     }
   };
@@ -97,6 +125,7 @@ export function getHtmlMetaData(htmlFilePath) {
     });
     readable.on('end', () => {
       parser.end();
+      capturedHeadlineText = undefined;
 
       resolve(metaData);
     });

packages/engine/src/web-menu/sax-parser.js

@@ -9,6 +9,9 @@ const require = createRequire(import.meta.url);
 export const streamOptions = { highWaterMark: 128 * 1024 };
 const saxPath = require.resolve('sax-wasm/lib/sax-wasm.wasm');
 const saxWasmBuffer = await readFile(saxPath);
-export const parser = new SAXParser(SaxEventType.CloseTag, streamOptions);
+export const parser = new SAXParser(
+  SaxEventType.OpenTag | SaxEventType.CloseTag | SaxEventType.Text,
+  streamOptions,
+);
 
 await parser.prepareWasm(saxWasmBuffer);

packages/engine/test-node/05z-menu.test.js

@@ -834,4 +834,118 @@ describe('Engine menus', () => {
 
     await cleanup();
   });
+
+  it('14: get-all-text-but-strip-html', async () => {
+    const { build, readSource } = await setupTestEngine(
+      'fixtures/05-menu/14-get-all-text-but-strip-html/docs',
+    );
+    await build();
+
+    expect(JSON.parse(readSource('pageTreeData.rocketGenerated.json'))).to.deep.equal({
+      h1: 'Hello World of JS (JavaScript)!',
+      name: 'Hello World of JS (JavaScript)!',
+      menuLinkText: 'Hello World of JS (JavaScript)!',
+      url: '/',
+      outputRelativeFilePath: 'index.html',
+      sourceRelativeFilePath: 'index.rocket.js',
+      level: 0,
+    });
+  });
+
+  it('15: markdown special characters', async () => {
+    const { build, readSource } = await setupTestEngine(
+      'fixtures/05-menu/15-md-special-characters/docs',
+    );
+    await build();
+
+    expect(JSON.parse(readSource('pageTreeData.rocketGenerated.json'))).to.deep.equal({
+      children: [
+        {
+          h1: '<some-button>',
+          headlinesWithId: [
+            {
+              id: 'some-button',
+              level: 1,
+              text: '<some-button>',
+            },
+          ],
+          level: 1,
+          menuLinkText: '<some-button>',
+          name: '<some-button>',
+          outputRelativeFilePath: 'component/index.html',
+          sourceRelativeFilePath: 'component.rocket.md',
+          url: '/component/',
+        },
+      ],
+      h1: 'Fun Errors & Feedback',
+      headlinesWithId: [
+        {
+          id: 'fun-errors--feedback',
+          level: 1,
+          text: 'Fun Errors & Feedback',
+        },
+      ],
+      level: 0,
+      menuLinkText: 'Fun Errors & Feedback',
+      name: 'Fun Errors & Feedback',
+      outputRelativeFilePath: 'index.html',
+      sourceRelativeFilePath: 'index.rocket.md',
+      url: '/',
+    });
+  });
+
+  it('16: link-text attribute', async () => {
+    const { build, readSource } = await setupTestEngine(
+      'fixtures/05-menu/16-link-text-attribute/docs',
+    );
+    await build();
+
+    expect(JSON.parse(readSource('pageTreeData.rocketGenerated.json'))).to.deep.equal({
+      h1: 'Home',
+      headlinesWithId: [
+        {
+          id: 'home',
+          level: 1,
+          rawText: 'Welcome to Rocket',
+          text: 'Home',
+        },
+        {
+          id: 'first',
+          level: 2,
+          text: 'First',
+        },
+        {
+          id: 'second',
+          level: 2,
+          rawText: 'Second is best',
+          text: 'Second',
+        },
+      ],
+      level: 0,
+      menuLinkText: 'Home',
+      name: 'Home',
+      outputRelativeFilePath: 'index.html',
+      sourceRelativeFilePath: 'index.rocket.js',
+      url: '/',
+    });
+  });
+
+  it('17: title-tag', async () => {
+    const { build, readSource, deleteSource } = await setupTestEngine(
+      'fixtures/05-menu/17-title-tag/docs',
+    );
+    await deleteSource('pageTreeData.rocketGenerated.json');
+    await build();
+
+    expect(JSON.parse(readSource('pageTreeData.rocketGenerated.json'))).to.deep.equal({
+      h1: 'Welcome to Rocket',
+      level: 0,
+      menuLinkText: 'Welcome to Rocket',
+      name: 'Welcome to Rocket',
+      outputRelativeFilePath: 'index.html',
+      sourceRelativeFilePath: 'index.rocket.js',
+      title: 'Welcome to Rocket | Rocket',
+      url: '/',
+    });
+  });
 });

packages/engine/test-node/09b-watch-error-handling.test.js

@@ -116,10 +116,21 @@ describe('Engine start error handling', () => {
   });
 
   it('04: update-header-while-rendering', async () => {
-    const { readOutput, writeSource, cleanup, engine, setAsOpenedInBrowser, outputExists } =
+    const {
-      await setupTestEngine(
+      readOutput,
+      writeSource,
+      cleanup,
+      engine,
+      setAsOpenedInBrowser,
+      outputExists,
+      anEngineEvent,
+    } = await setupTestEngine(
       'fixtures/09b-watch-error-handling/04-update-header-while-rendering/docs',
     );
+    expect(outputExists('index.html')).to.be.false;
+
+    await engine.start();
+    setAsOpenedInBrowser('index.rocket.js');
     await writeSource(
       'index.rocket.js',
       [
@@ -140,13 +151,7 @@ describe('Engine start error handling', () => {
         '`;',
       ].join('\n'),
     );
-
+    await anEngineEvent('rocketUpdated');
-    await engine.start();
-    setAsOpenedInBrowser('index.rocket.js');
-
-    const { port } = engine.devServer.config;
-    expect(outputExists('index.html')).to.be.false;
-    await fetch(`http://localhost:${port}/`);
 
     expect(readOutput('index.html')).to.equal(
       [

packages/engine/test-node/fixtures/04-layouts/01-function/docs/pageTreeData.rocketGenerated.json

@@ -1,15 +1,15 @@
 {
   "title": "Fixed Title",
-  "h1": "\n    Welcome Members:\n  ",
+  "h1": "Welcome Members:",
   "headlinesWithId": [
     {
-      "text": "\n    Welcome Members:\n  ",
+      "text": "Welcome Members:",
       "id": "welcome-members",
       "level": 1
     }
   ],
   "name": "Fixed Title",
-  "menuLinkText": "\n    Welcome Members:\n  ",
+  "menuLinkText": "Welcome Members:",
   "url": "/",
   "outputRelativeFilePath": "index.html",
   "sourceRelativeFilePath": "index.rocket.js",

packages/engine/test-node/fixtures/05-menu/02-generate-page-tree/docs/about.rocket.js

@@ -6,7 +6,13 @@ export { layout };
 
 import { html } from 'lit';
 export default () => html`
-  <meta name="menu:link.text" content="About" />
+  <html>
+    <head>
       <title>About | MyPage</title>
+    </head>
+    <body>
+      <meta name="menu:link.text" content="About" />
       <h1>This is About</h1>
+    </body>
+  </html>
 `;

packages/engine/test-node/fixtures/05-menu/02-generate-page-tree/docs/pageTreeData.rocketGenerated.json

@@ -8,8 +8,8 @@
   "level": 0,
   "children": [
     {
-      "menuLinkText": "About",
       "title": "About | MyPage",
+      "menuLinkText": "About",
       "h1": "This is About",
       "name": "This is About",
       "url": "/about/",

packages/engine/test-node/fixtures/05-menu/14-get-all-text-but-strip-html/docs/index.rocket.js

@@ -0,0 +1,11 @@
+/* START - Rocket auto generated - do not touch */
+export const sourceRelativeFilePath = 'index.rocket.js';
+import { layout, html } from './recursive.data.js';
+export { layout, html };
+/* END - Rocket auto generated - do not touch */
+
+export default () =>
+  html`<h1>
+    Hello <strong>World</strong> of <span>JS <em>(JavaScript)</em></span
+    >!
+  </h1>`;

packages/engine/test-node/fixtures/05-menu/14-get-all-text-but-strip-html/docs/pageTreeData.rocketGenerated.json

@@ -0,0 +1,9 @@
+{
+  "h1": "Hello World of JS (JavaScript)!",
+  "name": "Hello World of JS (JavaScript)!",
+  "menuLinkText": "Hello World of JS (JavaScript)!",
+  "url": "/",
+  "outputRelativeFilePath": "index.html",
+  "sourceRelativeFilePath": "index.rocket.js",
+  "level": 0
+}

packages/engine/test-node/fixtures/05-menu/14-get-all-text-but-strip-html/docs/recursive.data.js

@@ -0,0 +1,18 @@
+import { PageTree, SiteMenu } from '@rocket/engine';
+import { html } from 'lit';
+
+const pageTree = new PageTree({
+  inputDir: new URL('./', import.meta.url),
+  outputDir: new URL('../__output', import.meta.url),
+});
+
+await pageTree.restore();
+
+export const layout = data => {
+  return html`
+    ${pageTree.renderMenu(new SiteMenu(), data.sourceRelativeFilePath)}
+    <main>${data.content()}</main>
+  `;
+};
+
+export { html };

packages/engine/test-node/fixtures/05-menu/15-md-special-characters/docs/component.rocket.md

@@ -0,0 +1,9 @@
+```js server
+/* START - Rocket auto generated - do not touch */
+export const sourceRelativeFilePath = 'component.rocket.md';
+import { layout, html } from './recursive.data.js';
+export { layout, html };
+/* END - Rocket auto generated - do not touch */
+```
+
+# <some-button>

packages/engine/test-node/fixtures/05-menu/15-md-special-characters/docs/index.rocket.md

@@ -0,0 +1,9 @@
+```js server
+/* START - Rocket auto generated - do not touch */
+export const sourceRelativeFilePath = 'index.rocket.md';
+import { layout, html } from './recursive.data.js';
+export { layout, html };
+/* END - Rocket auto generated - do not touch */
+```
+
+# Fun Errors & Feedback

packages/engine/test-node/fixtures/05-menu/15-md-special-characters/docs/pageTreeData.rocketGenerated.json

@@ -0,0 +1,34 @@
+{
+  "h1": "Fun Errors & Feedback",
+  "headlinesWithId": [
+    {
+      "text": "Fun Errors & Feedback",
+      "id": "fun-errors--feedback",
+      "level": 1
+    }
+  ],
+  "name": "Fun Errors & Feedback",
+  "menuLinkText": "Fun Errors & Feedback",
+  "url": "/",
+  "outputRelativeFilePath": "index.html",
+  "sourceRelativeFilePath": "index.rocket.md",
+  "level": 0,
+  "children": [
+    {
+      "h1": "<some-button>",
+      "headlinesWithId": [
+        {
+          "text": "<some-button>",
+          "id": "some-button",
+          "level": 1
+        }
+      ],
+      "name": "<some-button>",
+      "menuLinkText": "<some-button>",
+      "url": "/component/",
+      "outputRelativeFilePath": "component/index.html",
+      "sourceRelativeFilePath": "component.rocket.md",
+      "level": 1
+    }
+  ]
+}

packages/engine/test-node/fixtures/05-menu/15-md-special-characters/docs/recursive.data.js

@@ -0,0 +1,18 @@
+import { PageTree, SiteMenu } from '@rocket/engine';
+import { html } from 'lit';
+
+const pageTree = new PageTree({
+  inputDir: new URL('./', import.meta.url),
+  outputDir: new URL('../__output', import.meta.url),
+});
+
+await pageTree.restore();
+
+export const layout = data => {
+  return html`
+    ${pageTree.renderMenu(new SiteMenu(), data.sourceRelativeFilePath)}
+    <main>${data.content()}</main>
+  `;
+};
+
+export { html };

packages/engine/test-node/fixtures/05-menu/16-link-text-attribute/docs/index.rocket.js

@@ -0,0 +1,11 @@
+/* START - Rocket auto generated - do not touch */
+export const sourceRelativeFilePath = 'index.rocket.js';
+import { layout, html } from './recursive.data.js';
+export { layout, html };
+/* END - Rocket auto generated - do not touch */
+
+export default () => html`
+  <h1 id="home" link-text="Home">Welcome to Rocket</h1>
+  <h2 id="first">First</h2>
+  <h2 link-text="Second" id="second">Second is best</h2>
+`;

packages/engine/test-node/fixtures/05-menu/16-link-text-attribute/docs/pageTreeData.rocketGenerated.json

@@ -0,0 +1,28 @@
+{
+  "h1": "Home",
+  "headlinesWithId": [
+    {
+      "text": "Home",
+      "id": "home",
+      "level": 1,
+      "rawText": "Welcome to Rocket"
+    },
+    {
+      "text": "First",
+      "id": "first",
+      "level": 2
+    },
+    {
+      "text": "Second",
+      "id": "second",
+      "level": 2,
+      "rawText": "Second is best"
+    }
+  ],
+  "name": "Home",
+  "menuLinkText": "Home",
+  "url": "/",
+  "outputRelativeFilePath": "index.html",
+  "sourceRelativeFilePath": "index.rocket.js",
+  "level": 0
+}

packages/engine/test-node/fixtures/05-menu/16-link-text-attribute/docs/recursive.data.js

@@ -0,0 +1,18 @@
+import { PageTree, SiteMenu } from '@rocket/engine';
+import { html } from 'lit';
+
+const pageTree = new PageTree({
+  inputDir: new URL('./', import.meta.url),
+  outputDir: new URL('../__output', import.meta.url),
+});
+
+await pageTree.restore();
+
+export const layout = data => {
+  return html`
+    ${pageTree.renderMenu(new SiteMenu(), data.sourceRelativeFilePath)}
+    <main>${data.content()}</main>
+  `;
+};
+
+export { html };

packages/engine/test-node/fixtures/05-menu/17-title-tag/docs/index.rocket.js

@@ -0,0 +1,7 @@
+/* START - Rocket auto generated - do not touch */
+export const sourceRelativeFilePath = 'index.rocket.js';
+import { layout, html } from './recursive.data.js';
+export { layout, html };
+/* END - Rocket auto generated - do not touch */
+
+export default () => html` <h1>Welcome to Rocket</h1> `;

packages/engine/test-node/fixtures/05-menu/17-title-tag/docs/pageTreeData.rocketGenerated.json

@@ -0,0 +1,10 @@
+{
+  "title": "Welcome to Rocket | Rocket",
+  "h1": "Welcome to Rocket",
+  "name": "Welcome to Rocket",
+  "menuLinkText": "Welcome to Rocket",
+  "url": "/",
+  "outputRelativeFilePath": "index.html",
+  "sourceRelativeFilePath": "index.rocket.js",
+  "level": 0
+}

packages/engine/test-node/fixtures/05-menu/17-title-tag/docs/recursive.data.js

@@ -0,0 +1,28 @@
+import { PageTree } from '@rocket/engine';
+import { html } from 'lit';
+
+const pageTree = new PageTree({
+  inputDir: new URL('./', import.meta.url),
+  outputDir: new URL('../__output', import.meta.url),
+});
+
+await pageTree.restore();
+
+const titleWrapperFn = title => (title ? `${title} | Rocket` : '');
+
+export const layout = data => {
+  const title = titleWrapperFn(pageTree.getPage(data.sourceRelativeFilePath)?.model?.name);
+  return html`
+    <html>
+      <head>
+        <title-server-only>${title}</title-server-only>
+      </head>
+    </html>
+    <body>
+      <main>${data.content()}</main>
+    </body>
+    </html>
+  `;
+};
+
+export { html };

packages/launch/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @rocket/launch
 
+## 0.21.1
+
+### Patch Changes
+
+- 390335d: Improve title tag handling
+- Updated dependencies [8dedc56]
+- Updated dependencies [390335d]
+- Updated dependencies [8dedc56]
+  - @rocket/engine@0.2.6
+  - @rocket/cli@0.20.1
+
 ## 0.21.0
 
 ### Minor Changes

packages/launch/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rocket/launch",
-  "version": "0.21.0",
+  "version": "0.21.1",
   "publishConfig": {
     "access": "public"
   },
@@ -46,9 +46,9 @@
     "preset"
   ],
   "dependencies": {
-    "@rocket/cli": "^0.20.0",
+    "@rocket/cli": "^0.20.1",
     "@rocket/components": "^0.2.0",
-    "@rocket/engine": "^0.2.0",
+    "@rocket/engine": "^0.2.6",
     "@webcomponents/template-shadowroot": "^0.1.0",
     "lit": "^2.3.0",
     "workbox-window": "^6.1.5"

packages/launch/src/LayoutMain.js

@@ -65,7 +65,7 @@ export class LayoutMain extends Layout {
       },
     ],
     footerMenu: [],
-    titleWrapperFn: title => `${title} | ${this.options.siteName}`,
+    titleWrapperFn: title => (title ? `${title} | ${this.options.siteName}` : ''),
   };
 
   /**

packages/search/test-node/rocket.test.js

@@ -7,13 +7,13 @@ const { expect } = chai;
 
 describe('Search', () => {
   it('01: writes the search index', async () => {
-    const { build, readOutput, readPublic } = await setupTestCli(
+    const { build, readOutput, readPublic } = await setupTestCli({
-      'fixtures/01-single-page/',
+      cwd: 'fixtures/01-single-page/',
-      undefined,
+      options: {
-      {
         buildOptimize: true,
       },
-    );
+      testOptions: { captureLogs: true },
+    });
     await build();
 
     const indexString =

presets/spark/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @rocket/spark
 
+## 0.2.1
+
+### Patch Changes
+
+- 390335d: Improve title tag handling
+- Updated dependencies [8dedc56]
+- Updated dependencies [390335d]
+  - @rocket/engine@0.2.6
+
 ## 0.2.0
 
 ### Minor Changes

presets/spark/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rocket/spark",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "publishConfig": {
     "access": "public"
   },
@@ -41,7 +41,7 @@
   ],
   "dependencies": {
     "@rocket/components": "^0.2.0",
-    "@rocket/engine": "^0.2.0",
+    "@rocket/engine": "^0.2.6",
     "lit": "^2.3.0"
   },
   "devDependencies": {},

presets/spark/src/LayoutHome.js

@@ -31,7 +31,7 @@ export class LayoutHome extends Layout {
           return nothing;
         }
         const page = this.options.pageTree.getPage(data.sourceRelativeFilePath);
-        if (page.model.headlinesWithId) {
+        if (page?.model?.headlinesWithId) {
           return html`
             ${page.model.headlinesWithId.map(
               headline => html`

site/pages/10--docs/10--setup/10--getting-started.rocket.md

@@ -54,7 +54,7 @@ Like any unfamiliar technology, Rocket comes with a slight learning curve. Howev
 
 ### Example Projects
 
-If you prefer to learn Rocket by example, check out our [examples](https://github.com/modernweb-dev/rocket/tree/next/examples) on GitHub.
+If you prefer to learn Rocket by example, check out our [examples](https://github.com/modernweb-dev/rocket/tree/main/examples) on GitHub.
 
 You locally install any of these examples by running `npx @rocket/create@latest` and selecting it within the wizard.
 

site/pages/10--docs/10--setup/20--adding-pages.rocket.md

@@ -48,11 +48,11 @@ This with start rocket in development mode and you will see your site running in
 
 ## What is a page?
 
-A page is a file that ends either with `*.rocket.js`, `*.rocket.md` or `*.rocket.html` and is located in the input directory (`docs` by default). Pages will make up the majority or your website.
+A page is a file that ends either with `*.rocket.js`, `*.rocket.md` or `*.rocket.html` and is located in the input directory (`site/pages` by default). Pages will make up the majority or your website.
 
 The simplest way to get started is to create a file
 
-👉 `docs/index.rocket.md`
+👉 `site/pages/index.rocket.md`
 
 ```md
 # Hello World
@@ -78,15 +78,23 @@ This section will be used to auto inject settings and data via a data cascade.
 
 To test it you can create a file
 
-👉 `docs/recursive.data.js`
+👉 `site/pages/recursive.data.js`
 
 ```js
 import { html } from 'lit';
 
-export const layout = data => html`<div>${data.content()}</div>`;
+export const layout = data => html`
+  <!DOCTYPE html>
+  <html>
+    <body>
+      <header>My Website</header>
+      <div>${data.content()}</div>
+    </body>
+  </html>
+`;
 ```
 
-Now if you go back to your `docs/index.rocket.md` you will see that `layout` got automatically injected.
+Now if you go back to your `site/pages/index.rocket.md` you will see that `layout` got automatically injected.
 
 ````md
 ```js server

site/pages/10--docs/20--basics/10--project-structure.rocket.md

@@ -31,7 +31,7 @@ export const description = 'Learn how to structure a project with Rocket.';
 # Project Structure
 
 Rocket works with one input folder for all your pages that defaults to `site/pages`.
-Within `pages` there is a `__public` folder that will be copied as is to the output folder.
+Within `pages` there is a `public` folder that will be copied as is to the output folder.
 
 All other files like `layouts`, `css`, `data`, ... can be placed anywhere in your project.
 

site/pages/10--docs/20--basics/70--navigation.rocket.md

@@ -11,6 +11,8 @@ export async function registerCustomElements() {
   // prettier-ignore
   customElements.define('rocket-header', await import('@rocket/components/header.js').then(m => m.RocketHeader));
   // prettier-ignore
+  customElements.define('inline-notification', await import('@rocket/components/inline-notification.js').then(m => m.InlineNotification));
+  // prettier-ignore
   customElements.define('rocket-main-docs', await import('@rocket/components/main-docs.js').then(m => m.RocketMainDocs));
   // prettier-ignore
   customElements.define('rocket-content-area', await import('@rocket/components/content-area.js').then(m => m.RocketContentArea));
@@ -85,22 +87,22 @@ In most cases you probably will not need to do anything as it will take the text
 So if you have a page like this:
 
 ```md
-# Hello World
+# Learning Rocket
 ```
 
-then it will be called "Hello World" in the menu.
+then it will be called "Learning Rocket" in the menu.
 
 You can overwrite that by using the property `menuLinkText`;
 
 ````md
 ```js server
-export const menuLinkText = 'Hello';
+export const menuLinkText = 'Docs';
 ```
 
-# Hello World
+# Learning Rocket
 ````
 
-Now the menu will be called "Hello".
+Now the menu will be called "Docs".
 
 Within a menu the text of the links is defined by the following priority:
 
@@ -111,6 +113,32 @@ Within a menu the text of the links is defined by the following priority:
 
 You can influence that data that gets provided to the menu by setting exports.
 
+### link-text="..."
+
+If you want to rename the menu text you can use the attribute `link-text`.
+It works on your h1 for the page title as well as on your h2-h6 for a table of contents menu.
+
+Examples:
+
+```html
+<h1 link-text="Docs">Learning Rocket</h1>
+
+<h2 link-text="Contact">Write us a message</h2>
+```
+
+<inline-notification>
+  You can use HTML within markdown too!
+</inline-notification>
+
+## Headings with HTML
+
+HTML in headings will be ignored for the menu
+
+Some examples:
+
+- `<h1>Hello <em>Word</em></h1>` => `Hello Word`
+- `<h1>Hello <strong>World</strong> of <span>JS <em>(JavaScript)</em></span>!</h1>` => `Hello World of JS (JavaScript)!`
+
 ## Menu No Link
 
 Often you have sections or groups of pages which you want to provide a heading for.

site/pages/30--tools/10--plugins-manager/10--overview.rocket.md

@@ -22,6 +22,8 @@ export async function registerCustomElements() {
 }
 export const needsLoader = true;
 /* END - Rocket auto generated - do not touch */
+export const title = 'Plugins Manager';
+export const subTitle = 'Enable fully customizable options for your plugin system';
 ```
 
 # Overview

site/pages/30--tools/20--markdown-javascript/10--overview.rocket.md

@@ -22,6 +22,9 @@ export async function registerCustomElements() {
 }
 export const needsLoader = true;
 /* END - Rocket auto generated - do not touch */
+
+export const title = 'Markdown JavaScript';
+export const subTitle = 'Executable JavaScript in markdown by annotating code blocks';
 ```
 
 # Overview

site/pages/30--tools/30--rollup-config/10--overview.rocket.md

@@ -22,6 +22,10 @@ export async function registerCustomElements() {
 }
 export const needsLoader = true;
 /* END - Rocket auto generated - do not touch */
+
+export const title = 'Rocket Rollup Config';
+export const subTitle =
+  'A ready to use and customizable rollup config for web sites, MPAs and SPAs';
 ```
 
 # Overview

site/pages/30--tools/40--check-html-links/10--overview.rocket.md

@@ -24,11 +24,14 @@ export async function registerCustomElements() {
 }
 export const needsLoader = true;
 /* END - Rocket auto generated - do not touch */
+
+export const title = 'Check HTML links';
+export const subTitle = 'A fast checker for broken links/references in HTML files';
 ```
 
 # Overview
 
-A fast checker for broken links/references in HTML.
+A fast checker for broken links/references in HTML files.
 
 <inline-notification type="tip">
 

site/pages/pageTreeData.rocketGenerated.json

@@ -1,8 +1,8 @@
 {
   "title": "Welcome to Rocket",
-  "h1": "\n        \n      ",
+  "h1": "",
-  "name": "\n        \n      ",
+  "name": "Welcome to Rocket",
-  "menuLinkText": "\n        \n      ",
+  "menuLinkText": "Welcome to Rocket",
   "url": "/",
   "outputRelativeFilePath": "index.html",
   "sourceRelativeFilePath": "index.rocket.js",
@@ -386,6 +386,31 @@
                   "text": "Recommended Project Structure",
                   "id": "recommended-project-structure",
                   "level": 2
+                },
+                {
+                  "text": "site/pages/",
+                  "id": "sitepages",
+                  "level": 3
+                },
+                {
+                  "text": "site/src/",
+                  "id": "sitesrc",
+                  "level": 3
+                },
+                {
+                  "text": "site/src/components",
+                  "id": "sitesrccomponents",
+                  "level": 3
+                },
+                {
+                  "text": "site/src/layouts",
+                  "id": "sitesrclayouts",
+                  "level": 3
+                },
+                {
+                  "text": "site/public/",
+                  "id": "sitepublic",
+                  "level": 3
                 }
               ],
               "name": "Project Structure",
@@ -758,6 +783,16 @@
                   "id": "menu-link-text",
                   "level": 3
                 },
+                {
+                  "text": "link-text=\"...\"",
+                  "id": "link-text",
+                  "level": 3
+                },
+                {
+                  "text": "Headings with HTML",
+                  "id": "headings-with-html",
+                  "level": 2
+                },
                 {
                   "text": "Menu No Link",
                   "id": "menu-no-link",
@@ -937,7 +972,7 @@
                   "level": 2
                 },
                 {
-                  "text": "The  Function",
+                  "text": "The :resolve Function",
                   "id": "the-resolve-function",
                   "level": 2
                 },
@@ -1432,7 +1467,7 @@
                   "level": 2
                 },
                 {
-                  "text": "1. Simple  Tags and External Files",
+                  "text": "1. Simple <link> Tags and External Files",
                   "id": "1-simple-link-tags-and-external-files",
                   "level": 3
                 },
@@ -1447,7 +1482,7 @@
                   "level": 3
                 },
                 {
-                  "text": "Recommendations & Best Practices",
+                  "text": "Recommendations & Best Practices",
                   "id": "recommendations--best-practices",
                   "level": 2
                 },
@@ -2239,7 +2274,7 @@
           "needsLoader": true,
           "children": [
             {
-              "title": "Overview | Rocket",
+              "title": "Plugins Manager",
               "h1": "Overview",
               "headlinesWithId": [
                 {
@@ -2313,7 +2348,7 @@
                   "level": 2
                 }
               ],
-              "name": "Overview",
+              "name": "Plugins Manager",
               "menuLinkText": "Overview",
               "url": "/tools/plugins-manager/overview/",
               "outputRelativeFilePath": "tools/plugins-manager/overview/index.html",
@@ -2345,7 +2380,8 @@
                 "launch-blog-details": "@rocket/launch/blog-details.js::LaunchBlogDetails",
                 "my-counter": "#src/components/MyCounter.js::MyCounter"
               },
-              "needsLoader": true
+              "needsLoader": true,
+              "subTitle": "Enable fully customizable options for your plugin system"
             }
           ]
         },
@@ -2388,7 +2424,7 @@
           "needsLoader": true,
           "children": [
             {
-              "title": "Overview | Rocket",
+              "title": "Markdown JavaScript",
               "h1": "Overview",
               "headlinesWithId": [
                 {
@@ -2451,13 +2487,23 @@
                   "id": "basic",
                   "level": 3
                 },
+                {
+                  "text": "mdjsDocPage",
+                  "id": "mdjsdocpage",
+                  "level": 4
+                },
+                {
+                  "text": "mdjsProcess",
+                  "id": "mdjsprocess",
+                  "level": 4
+                },
                 {
                   "text": "Advanced",
                   "id": "advanced",
                   "level": 3
                 }
               ],
-              "name": "Overview",
+              "name": "Markdown JavaScript",
               "menuLinkText": "Overview",
               "url": "/tools/markdown-javascript/overview/",
               "outputRelativeFilePath": "tools/markdown-javascript/overview/index.html",
@@ -2489,7 +2535,8 @@
                 "launch-blog-details": "@rocket/launch/blog-details.js::LaunchBlogDetails",
                 "my-counter": "#src/components/MyCounter.js::MyCounter"
               },
-              "needsLoader": true
+              "needsLoader": true,
+              "subTitle": "Executable JavaScript in markdown by annotating code blocks"
             },
             {
               "title": "Preview | Rocket",
@@ -2655,7 +2702,7 @@
           "needsLoader": true,
           "children": [
             {
-              "title": "Overview | Rocket",
+              "title": "Rocket Rollup Config",
               "h1": "Overview",
               "headlinesWithId": [
                 {
@@ -2689,7 +2736,7 @@
                   "level": 3
                 }
               ],
-              "name": "Overview",
+              "name": "Rocket Rollup Config",
               "menuLinkText": "Overview",
               "url": "/tools/rollup-config/overview/",
               "outputRelativeFilePath": "tools/rollup-config/overview/index.html",
@@ -2721,7 +2768,8 @@
                 "launch-blog-details": "@rocket/launch/blog-details.js::LaunchBlogDetails",
                 "my-counter": "#src/components/MyCounter.js::MyCounter"
               },
-              "needsLoader": true
+              "needsLoader": true,
+              "subTitle": "A ready to use and customizable rollup config for web sites, MPAs and SPAs"
             }
           ]
         },
@@ -2764,7 +2812,7 @@
           "needsLoader": true,
           "children": [
             {
-              "title": "Overview | Rocket",
+              "title": "Check HTML links",
               "h1": "Overview",
               "headlinesWithId": [
                 {
@@ -2803,7 +2851,7 @@
                   "level": 2
                 }
               ],
-              "name": "Overview",
+              "name": "Check HTML links",
               "menuLinkText": "Overview",
               "url": "/tools/check-html-links/overview/",
               "outputRelativeFilePath": "tools/check-html-links/overview/index.html",
@@ -2835,7 +2883,8 @@
                 "launch-blog-details": "@rocket/launch/blog-details.js::LaunchBlogDetails",
                 "my-counter": "#src/components/MyCounter.js::MyCounter"
               },
-              "needsLoader": true
+              "needsLoader": true,
+              "subTitle": "A fast checker for broken links/references in HTML files"
             }
           ]
         }

yarn.lock

@@ -1656,6 +1656,13 @@
   resolved "https://registry.yarnpkg.com/@types/http-errors/-/http-errors-1.8.2.tgz#7315b4c4c54f82d13fa61c228ec5c2ea5cc9e0e1"
   integrity sha512-EqX+YQxINb+MeXaIqYDASb6U6FCHbWjkj4a1CKDBks3d/QiB2+PqBLyO72vLDgAO1wUI4O+9gweRcQK11bTL/w==
 
+"@types/ip@^1.1.0":
+  version "1.1.0"
+  resolved "https://registry.yarnpkg.com/@types/ip/-/ip-1.1.0.tgz#aec4f5bfd49e4a4c53b590d88c36eb078827a7c0"
+  integrity sha512-dwNe8gOoF70VdL6WJBwVHtQmAX4RMd62M+mAB9HQFjG1/qiCLM/meRy95Pd14FYBbEDwCq7jgJs89cHpLBu4HQ==
+  dependencies:
+    "@types/node" "*"
+
 "@types/is-ci@^3.0.0":
   version "3.0.0"
   resolved "https://registry.yarnpkg.com/@types/is-ci/-/is-ci-3.0.0.tgz#7e8910af6857601315592436f030aaa3ed9783c3"
@@ -2085,9 +2092,9 @@
     glob "^7.1.6"
 
 "@web/rollup-plugin-html@^1.8.0":
-  version "1.10.3"
+  version "1.11.0"
-  resolved "https://registry.yarnpkg.com/@web/rollup-plugin-html/-/rollup-plugin-html-1.10.3.tgz#78fa06a9a7f2ec6973a12bd1000b900c1fd4e4eb"
+  resolved "https://registry.yarnpkg.com/@web/rollup-plugin-html/-/rollup-plugin-html-1.11.0.tgz#46c2bcb3a3b9db55d53b897ffc7e7ef2f618a052"
-  integrity sha512-2RMIeKxpGtrcXiqPTgMVq5neGa5xa69MfNK860BHVMEO2N/MrHFuQNr1eNLsspcq2DL/xnymwC3w5hgjtlgxag==
+  integrity sha512-EqUcV5plGYTV/utdbX8g5t8Yq/z6VfFuQuPD39ckOQuRj7Rj6HD15FHwLHpFAWOR0+GrDnNzR74RvI4ipGm0qQ==
   dependencies:
     "@web/parse5-utils" "^1.3.0"
     glob "^7.1.6"