docs: Minor improvements and restructuring (#38)

I wanted to add some content, but got distracted...

### Changes:

- Fix trailing slash error on dev
- Remove default paginaton
- Add missing image handler for dev (sharp)
- Add css file for global custom css (currently empty)
- Add custom Hero component for homepage
- Update homepage content and metadata
- Change documentation startpage
- Content restructuring
- Add introduction to Lightweigt M2M

docs/astro.config.mjs

@@ -4,28 +4,39 @@ import starlight from '@astrojs/starlight';
 // https://astro.build/config
 export default defineConfig({
 	base: '/teamagochi',
+	trailingSlash: 'always',
 	site: 'https://smartuni.github.io',
 	integrations: [
+		// https://starlight.astro.build/reference/configuration/
 		starlight({
 			title: 'Teamagochi',
 			sidebar: [
-				{
-					label: 'Basics',
-					autogenerate: { directory: 'basics' },
-				},
+				{ label: 'Get started', link: '/get-started' },
 				{
 					label: 'Frontend',
 					autogenerate: { directory: 'frontend' },
 				},
 				{
 					label: 'Web Backend',
-					autogenerate: { directory: 'web_backend' },
+					autogenerate: { directory: 'web-backend' },
 				},
 				{
 					label: 'Node',
 					autogenerate: { directory: 'node' },
-				}
+				},
+				{
+					label: 'Cross-Cutting',
+					autogenerate: { directory: 'cross-cutting' },
+				},
+				{
+					label: 'Guides',
+					autogenerate: { directory: 'guides' },
+				},
 			],
+			pagination: false,
+			editLink: { baseUrl: 'https://github.com/smartuni/teamagochi/tree/main/docs/' },
+			components: { Hero: './src/components/Hero.astro' },
+			customCss: [ './src/assets/css/global.css' ],
 		}),
 	],
 });

docs/package.json

@@ -12,7 +12,7 @@
   "dependencies": {
     "@astrojs/starlight": "^0.21.4",
     "astro": "^4.3.5",
-    "sharp": "^0.32.5",
+    "sharp": "^0.33.3",
     "@astrojs/check": "^0.5.10",
     "typescript": "^5.4.4"
   }

docs/src/assets/css/global.css

@@ -0,0 +1,19 @@
+/**
+ * Add global custom css here...
+ */
+.sl-markdown-content .figure > p > img {
+  margin: 0 auto;
+}
+
+.sl-markdown-content .figure .figure-caption {
+  size: 0.8em;
+  text-align: center;
+  margin-top: 0;
+  margin-bottom: 1em;
+}
+
+@media (min-width: 50rem) {
+  .sl-markdown-content .figure > p > img {
+    max-width: 70%;
+  }
+}

docs/src/components/Hero.astro

@@ -0,0 +1,161 @@
+---
+import { Image } from 'astro:assets';
+import type { Props } from '@astrojs/starlight/props';
+import CallToAction from '@astrojs/starlight/components/CallToAction.astro';
+import Default from '@astrojs/starlight/components/Hero.astro';
+
+/**
+ * Custom Hero section which is only rendered on the homepage
+ */
+
+// Hack, cause constants are not exported, see https://github.com/withastro/starlight/issues/860
+//import { PAGE_TITLE_ID } from '@astrojs/starlight/constants';
+const PAGE_TITLE_ID = '_top';
+
+const isHomepage = Astro.props.slug === '';
+
+const { data } = Astro.props.entry;
+const { title = data.title, tagline, image, actions = [] } = data.hero || {};
+
+const imageAttrs = {
+	loading: 'eager' as const,
+	decoding: 'async' as const,
+	width: 400,
+	height: 400,
+};
+
+import riotLogo from '../assets/img/riot-logo-large.png';
+const riotLogoAttrs = {
+	...imageAttrs,
+	alt: 'Logo of RIOT, the friendly Operating System for the Internet of Things.'
+}
+
+import inetLogo from '../assets/img/inet-haw.png';
+const inetLogoAttrs = {
+	...imageAttrs,
+	alt: 'Logo of INET working group at University of Applied Sciences Hamburg.'
+}
+---
+
+{
+	!isHomepage ? (
+		<Default {...Astro.props} />
+	) : (
+		<div class="hero">
+			<div class="sl-flex stack">
+				<div class="sl-flex copy">
+					<h1 id={PAGE_TITLE_ID} data-page-title set:html={title} />
+					{tagline && <div class="tagline" set:html={tagline} />}
+				</div>
+				{
+					actions.length > 0 && (
+						<div class="sl-flex actions">
+							{actions.map(({ text, ...attrs }) => (
+								<CallToAction {...attrs} set:html={text} />
+							))}
+						</div>
+					)
+				}
+			</div>
+			<div class="sl-flex stack hero-org">
+				{riotLogo && <Image src={riotLogo} {...riotLogoAttrs} />}
+				{inetLogo && <Image src={inetLogo} {...inetLogoAttrs} />}
+				<div class="info">
+					<p><a href="https://inet.haw-hamburg.de/teaching/ss-2024/riot-im-internet-of-things">RIOT im Internet of Things</a></p>
+					<p>Computer Science and Electrical Engineering</p>
+					<p>Bachelor Project, 04/2024 - 07/2024</p>
+				</div>
+			</div>
+		</div>
+	)
+}
+
+<style>
+	.hero {
+		display: grid;
+		align-items: center;
+		gap: 1rem;
+		padding-bottom: 1rem;
+	}
+
+	.hero > img,
+	.hero > .hero-html,
+	.hero > .hero-org > img {
+		object-fit: contain;
+		width: min(30%, 20rem);
+		height: auto;
+		margin-inline: auto;
+	}
+
+	.hero > .hero-org {
+		margin-top: 1em;
+	}
+
+	.stack {
+		flex-direction: column;
+		gap: clamp(1.5rem, calc(1.5rem + 1vw), 2rem);
+		text-align: center;
+	}
+
+	.copy {
+		flex-direction: column;
+		gap: 1rem;
+		align-items: center;
+	}
+
+	.copy > * {
+		max-width: 50ch;
+	}
+
+	.info {
+		text-align: center;
+	}
+
+	h1 {
+		font-size: clamp(var(--sl-text-3xl), calc(0.25rem + 5vw), var(--sl-text-5xl));
+		line-height: var(--sl-line-height-headings);
+		font-weight: 600;
+		color: var(--sl-color-white);
+	}
+
+	#_top > hr {
+		padding: 2em;
+	}
+
+	.tagline {
+		font-size: clamp(var(--sl-text-base), calc(0.0625rem + 2vw), var(--sl-text-xl));
+		color: var(--sl-color-gray-2);
+	}
+
+	.actions {
+		gap: 1rem 2rem;
+		flex-wrap: wrap;
+		justify-content: center;
+	}
+
+	@media (min-width: 50rem) {
+		.hero {
+			grid-template-columns: 8fr 4fr;
+			gap: 3%;
+			padding-block: clamp(2.5rem, calc(1rem + 10vmin), 10rem);
+		}
+
+		.hero > img,
+		.hero > .hero-html,
+		.hero > .hero-org > img {
+			width: min(80%, 25rem);
+		}
+
+		.stack {
+			text-align: start;
+		}
+
+		.copy {
+			align-items: flex-start;
+		}
+
+		.actions {
+			justify-content: flex-start;
+		}
+	}
+</style>

docs/src/content/docs/cross-cutting/lwM2M.md

@@ -0,0 +1,108 @@
+---
+title: Lightweight M2M (LwM2M)
+description: Introduction to the LightweightM2M protocol.
+---
+OMA Lightweight M2M (LwM2M) is a protocol for machine to machine (M2M) or Internet of things (IoT) device management and service enablement. It was designed for sensor networks and the demands of a machine-to-machine (M2M) environment and specified at the Open Mobile Alliance (OMA) SpecWorks Device Management Working Group.
+
+**Protocol scope:**
+- **Device management**, including remote provisioning of security credentials, firmware updates, remote device diagnostics and troubleshooting.
+- **Service enablement**, including sensor and meter readings, remote actuation and configuration of host devices.
+
+## Documents & Resources
+
+:::tip[Did you know?]
+The **specifications** are best source of informations! Don't let yourself be overwhelmed. Open the table of contents and jump directly to the sections you need. 
+
+A good introduction is provided by the [LwM2M v1.1 slides][lwm2m_slides_intro],
+:::
+
+**Documents:**
+
+- [Lightweight Machine to Machine Technical Specification: Core (1.2.1 / 2022-12-09)][lwm2m_spec_core]
+- [Lightweight Machine to Machine Technical Specification: Transport Bindings (1.2.1 / 2022-12-09)][lwm2m_spec_transport]
+- [Lightweight Machine to Machine Requirements (1.2 / 2020-11-10)][lwm2m_requirements]
+
+**Useful links:**
+
+- [OMA Technical Dashboard][lwm2m_oma_home]
+  - [Object and Resource Registry][lwm2m_registry]
+  - [Object schema v1.1 (LWM2M-v1_1.xsd)][lwmwm_object_schema_1_1]
+- [Introduction slides (LwM2M v1.1)][lwm2m_slides_intro]
+
+[lwm2m_spec_core]: https://www.openmobilealliance.org/release/LightweightM2M/V1_2_1-20221209-A/OMA-TS-LightweightM2M_Core-V1_2_1-20221209-A.pdf
+[lwm2m_spec_transport]: https://www.openmobilealliance.org/release/LightweightM2M/V1_2_1-20221209-A/OMA-TS-LightweightM2M_Transport-V1_2_1-20221209-A.pdf
+[lwm2m_requirements]: https://www.openmobilealliance.org/release/LightweightM2M/V1_2_1-20221209-A/OMA-RD-LightweightM2M-V1_2-20201110-A.pdf
+[lwm2m_slides_intro]: https://www.openmobilealliance.org/release/LightweightM2M/Lightweight_Machine_to_Machine-v1_1-OMASpecworks.pdf
+[lwm2m_oma_home]: https://technical.openmobilealliance.org/
+[lwm2m_registry]: https://technical.openmobilealliance.org/OMNA/LwM2M/LwM2MRegistry.html
+[lwmwm_object_schema_1_1]: http://www.openmobilealliance.org/tech/profiles/LWM2M-v1_1.xsd
+
+## Architecture overview
+
+The whole system is called **LwM2M Enabler** has two components. The **LwM2M Server** and the **LwM2M Client**. The **LwM2M Device** acts as a Client and the **M2M service, platform or application** acts as the Server.
+
+<div class="figure">
+
+![Shows the overall architecture](./LwM2M-Enabler.jpg)
+
+<p class="figure-caption">Source: Technical Specification: Core v1.2.1</p>
+</div>
+
+### Interfaces
+
+Four **interfaces** are designed between these two components.
+
+- Bootstrap
+- Client Registration
+- Device management and service enablement
+- Information Reporting
+
+:::note
+The **Bootstrap** interface and server are not in the scope of this project!  
+We are going to register Clients with a pre-defined Server.
+:::
+
+Each of these interfaces is related to a set of **operations**.
+
+### Operations
+
+The operations can be classified into **uplink** operations and **downlink** operations. The uplink operatations are initiated by the device and the downlink operations are initiated by the server. They are mapped to protocol mechanisms in the LwM2M Transport specification.
+
+| Interface                                | Direction | Operation                                                                                         |
+|------------------------------------------|-----------|---------------------------------------------------------------------------------------------------|
+| Bootstrap                                | Uplink    | Bootstrap-Request, Bootstrap-Pack-Request                                                         |
+| Bootstrap                                | Downlink  | Bootstrap-Write, Bootstrap-Read, Bootstrap-Discover, Bootstrap-Delete, Bootstrap-Finish           |
+| Client Registration                      | Uplink    | Register, Update, De-register                                                                     |
+| Device Management and Service Enablement | Downlink  | Create, Read, Read-Composite, Write, Delete, Execute, Write-Attributes, Write-Composite, Discover |
+| Information Reporting                    | Downlink  | Observe, Observe-Composite, Cancel Observation, Cancel Observation-Composite                      |
+| Information Reporting                    | Uplink    | Notify, Send                                                                                      |
+
+## Resource Model
+
+The LWM2M Enabler defines a simple **resource model**. Relationships between Resources, Objects, and the Client are illustrated in the following figure.
+
+<div class="figure">
+
+![Shows model of object and resources](./LwM2M-Objects-Resources.png)
+
+<p class="figure-caption">Source: Technical Specification: Core v1.2.1</p>
+</div>
+
+- Each piece of information made available by the LWM2M Client is a **Resource**.
+- Resources are logically organized into **Objects**.
+- The **Client** may have any number of Resources, each of which belongs to an Object.
+- Resources are defined per Object, and each Resource is given a unique identifier within that Object.
+- Resources and Objects have the capability to have **multiple instances** of the Resource or Object, called **Object Instance** and **Resource Instance**.
+- Each Object and Resource is defined to have one or more **operations** that it supports.
+
+
+
+
+<!--
+https://wiki.openmobilealliance.org/display/TOOL/What+is+LwM2M
+
+https://github.com/eclipse-leshan/leshan/tree/master
+
+SCHEMA?: Not that easy:
+http://www.openmobilealliance.org/tech/profiles/LWM2M-v1_1.xsd
+-->

docs/src/content/docs/get-started.md

@@ -0,0 +1,11 @@
+---
+title: Get started
+description: A guide on how to start.
+---
+
+Imagine a modern twist on the beloved Tamagotchi of the 90s - introducing Teamagochi,  
+**the ultimate fusion of nostalgia and cutting-edge technology**.
+Our student term project aims to create a revolutionary IoT device equipped with a digital twin, granting it access to the vast realm of the internet.
+Just like its inspirational predecessor, the Teamagochi will rely on its owners for care and interaction, but with the added dimension of online connectivity,
+offering endless possibilities for learning, entertainment, and community experiences. Join us as we embark on a journey to redefine the boundaries of
+virtual pet ownership in the digital age!

docs/src/content/docs/basics/git.md → docs/src/content/docs/guides/git.md

@@ -1,5 +1,5 @@
 ---
-title: Git Tutorial
+title: Git
 description: Some basic Git commands to get you started.
 ---