chore: add docs & tests for link-text for headlines

Author: daKmoR

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

@@ -893,4 +893,40 @@ describe('Engine menus', () => {
  url: '/',
  });
  });
+
+ it('15: 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: '/',
+ });
+ });
 });

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 };

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

@@ -85,22 +85,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 +111,23 @@ 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