From 041fc113ee6d20140b60f42c8f980dff599f561e Mon Sep 17 00:00:00 2001
From: Niklas van Schrick <mc.taucher2003@gmail.com>
Date: Mon, 25 Dec 2023 15:40:00 +0100
Subject: [PATCH] Add basic preview docs

---
 docs/content/index.mdx    | 11 +++++++++++
 docs/content/preview.md   | 21 +++++++++++++++++++++
 docs/content/structure.md | 20 ++++++++++++++++++++
 3 files changed, 52 insertions(+)
 create mode 100644 docs/content/preview.md
 create mode 100644 docs/content/structure.md

diff --git a/docs/content/index.mdx b/docs/content/index.mdx
index 9e64aa0..946f317 100644
--- a/docs/content/index.mdx
+++ b/docs/content/index.mdx
@@ -4,4 +4,15 @@ description: Find out how the documentation page works
 template: splash
 ---
 
+import {CardGrid, Card} from "@astrojs/starlight/components";
+
 Telescopium is the documentation page for Code0.
+
+<CardGrid stagger>
+    <Card title='<a href="structure.md">Directory structure</a>' icon="document">
+        Learn about the directory structure requirements for projects containing documentation.
+    </Card>
+    <Card title='<a href="preview.md">Preview locally</a>' icon="open-book">
+        Learn how to preview documentation locally.
+    </Card>
+</CardGrid>
diff --git a/docs/content/preview.md b/docs/content/preview.md
new file mode 100644
index 0000000..4471ada
--- /dev/null
+++ b/docs/content/preview.md
@@ -0,0 +1,21 @@
+---
+title: Previewing locally
+---
+
+The telescopium project can start a local preview for the documentation a project.
+
+This is done with the `project:preview` script which calls `scripts/docs_preview.js`.
+
+## Start local preview
+
+Requirements:
+
+- Dependencies of Telescopium are installed
+- The other project is cloned in the same parent directory as telescopium
+- The other project follows the [expected structure](structure.md)
+
+Run `npm run project:preview <project-name>` where `<project-name>` is replaced with
+the name of the directory which contains the project you want to preview.
+
+The preview relies on symbolic links. If symbolic links are not supported by your platform,
+you can't use the preview.
diff --git a/docs/content/structure.md b/docs/content/structure.md
new file mode 100644
index 0000000..4bce52f
--- /dev/null
+++ b/docs/content/structure.md
@@ -0,0 +1,20 @@
+---
+title: Directory Structure
+---
+
+The telescopium project sets some expectations on projects that use it as documentation page.
+
+Requirements:
+
+- `docs/starlight.json`
+- `docs/content/`
+
+## `docs/starlight.json`
+
+This file contains the [starlight configuration](https://starlight.astro.build/reference/configuration/).
+
+## `docs/content/`
+
+This directory contains the actual documentation pages. It is configured as a content collection of
+documentation type. It can contain `*.md` and `*.mdx` files. Every page needs a `title` set in the
+front-matter configuration.