Writing Documentation

This article guides you on how to write documentation for NUS Digital Twin.

NUS Digital Twin provides the following 3 sets of documentations for users and developers:

• User Guide
• Developer Guide
• API Reference

The documentation site is powered by Starlight, and supports all the features offered by Starlight.

Documentation Structure

The files for the documentation is stored in the directory src/content/docs.

The documentation is mostly written in MDX, though Markdown files are also supported. MDX is the preferred format because it allows for the inclusion of components and the ability to import and reuse other Markdown snippets.

Custom Components

NUS Digital Twin’s documentation utilises several custom components. The custom components can be found in the src/components/docs directory. The purpose of each custom component is described below.

Head.astro

A custom Head component is used to preload the fonts used in the documentation site. This approach is used instead of using the head configuration as imported fontsource URLs are not properly processed in the head configuration during production, leading to issues with preloading the fonts.

SiteTitle.astro

A custom SiteTitle.astro component is implemented to override the default site title, to allow a different title to be displayed for each set of documentation.

Add Custom Components

More custom components can be added via the Starlight configuration in astro.config.mjs. See Overriding Components in Starlight’s documentation for the steps.

Route Data

NUS Digital Twin uses the Route Data functionality provided by Astro Starlight to override the default behaviour of the sidebar and pagination. The route data is found in /src/routeData.ts.

Pagination behaviour

Starlight does not support a multi-instance structure out-of-the-box, hence, the default pagination behaviour is overridden to ensure that the documentation sites do not link to one another.

Sidebar behaviour

The default sidebar content is overridden, ensuring that only the relevant sections are displayed for each specific set of documentation, rather than displaying all sections.

This customization groups the sections based on their URL structure, where any section matching the first path segment after the initial slash is grouped together within the same sidebar group.

Markdown Snippets

Reusable markdown snippets are stored in src/content/docs-partials to share content between different documentation pages.

You can import and use these snippets within MDX files.

---
title: Page Title
---

import About from '@content/docs-partials/about.mdx';

<About />

Update User Guide

The content for the user guide is stored in src/content/docs/user-guide. To update the user guide, edit the MDX/Markdown files within the directory.

To update the sidebar for the user guide, see Starlight’s documentation, and update astro.config.mjs accordingly.

Update Developer Guide

The content for the developer guide is stored in src/content/docs/dev-guide. To update the developer guide, edit the MDX/Markdown files within the directory.

To update the sidebar for the developer guide, see Starlight’s documentation, and update astro.config.mjs accordingly.

Update API Reference

The content for the API Reference is stored in src/content/docs/api-reference. To update the API Reference, edit the MDX/Markdown files within the directory.

To update the sidebar for the API Reference, see Starlight’s documentation, and update astro.config.mjs accordingly.