Contributing & editing

This hub is built so that anyone on the team can contribute. Pages are Markdown (.mdx) files; most edits are plain writing. Adding new learning material takes a few extra steps because pages are wired into the roadmap, progress and quizzes, and those steps are listed below.

The mental model

The site is built with Astro + Starlight.
All content lives under src/content/docs/.
There are two tracks (top-level folders): technical-foundations/ and service-desk/.
Inside a track, each topic is either:
- a single .mdx file (a stub: just the overview screen, marked “Coming soon”), or
- a folder with an index.mdx (the topic overview screen) plus one .mdx per reading section. technical-foundations/identity-and-accounts/ is the worked example to copy from.
There is no navigation sidebar and no “On this page” list. Navigation is hub-and-spoke: home → roadmap → topic overview → section. What appears on the roadmap is derived from these folders automatically (topic overviews become trail nodes; sections become the completable pages behind them).

Edit an existing page

Open the matching .mdx file under src/content/docs/….
Edit the text (it’s Markdown). Leave the frontmatter block at the top (between the --- lines) and any import lines in place.
Save. If the dev server is running, the page reloads instantly.
If the page has a German mirror under src/content/docs/de/…, make the same edit there.

Add a reading section to a topic

Copy an existing Identity & accounts section as your starting point.

Create the section file in the topic folder, e.g. src/content/docs/technical-foundations/identity-and-accounts/my-section.mdx, with frontmatter like:
```
---
title: My section
description: One line describing the section.
sidebar:
  order: 7   # position within the topic; lower = earlier
---
```
Write the content, then end the page by mounting the knowledge check:
```
<SectionQuiz client:only="preact"
  pageId="technical-foundations/identity-and-accounts/my-section"
  topic="technical-foundations" />
```
(Passing the quiz is what completes the section, so every section needs one.)
Add the quiz questions in src/data/quizzes/ (keyed by that same pageId), and the German copy in src/data/quizzes/de/. New topics export an array that gets imported once in src/data/quizzes/index.ts.
List the section in the topic’s index.mdx sections prop (title, slug, minutes) so the overview shows it. As soon as a section has a slug, the topic stops being a “Coming soon” stub: its Begin button goes live and its reward appears.
Mirror the page under src/content/docs/de/… (see the German rules below).

Progress counting needs no extra wiring: any non-splash page inside a track folder is picked up automatically and counts toward the roadmap, ranks and Valor.

Add a whole new topic

Create a folder under the track, e.g. src/content/docs/service-desk/my-topic/.
Give it an index.mdx overview with template: splash that mounts the TopicOverview component (copy one from an existing topic and adjust the props: track, number, title, lead, objectives, sections, topicId, minutes, level).
Add its reading sections as described above. The topic appears on the roadmap automatically, ordered by its sidebar.order.

German pages

German content mirrors the English path exactly, one folder deeper: src/content/docs/de/technical-foundations/…. Because of that extra depth, component imports need one extra ../ compared to the English file.
Progress identifiers stay English on German pages: topicId, slug, pageId and quiz ids are shared across languages, so completion carries over. Only the visible text and links are German.
Inside a double-quoted JSX attribute (e.g. lead="…"), nested quotes must be the German glyphs „…", never straight ASCII quotes, or the file fails to build.

Run it locally

From the project folder (service-desk-hub):

npm install      # first time only
npm run dev      # start a local preview at http://localhost:4321

Edit files and the browser refreshes automatically. Press q then Enter to stop.

Build for hosting

npm run build    # outputs a static site to ./dist
npm run preview  # preview the built site locally

The dist/ folder is a plain static bundle. It can be hosted on an internal server, an intranet, or a static host (GitHub Pages, Netlify, …) whenever a hosting decision is made.

Style tips

Keep content generic and tool-agnostic: describe capabilities and concepts, not one vendor’s product. Project-specific details (real tool names, routing rules, SLAs) belong in a separate project space, not here.

For callouts, import and use the <Aside> component. The :::note directive syntax renders incorrectly on this site, so avoid it:

import { Aside } from '@astrojs/starlight/components';

<Aside type="tip" title="The one-line takeaway">
A helpful pointer.
</Aside>

Plain language over jargon; short sections; a clear page title and description; no em dashes in copy.