Restructur and start dedicated pages for user tutorials (#7)

* rename filenames to reflect order

* introduce editorconfig

* Restructur and start dedicated pages for terminology and user tutorials

* update docusaurus and add mermaidjs support

* Add simplified architecture as diagram for now

* finish

.editorconfig

@@ -0,0 +1,18 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+tab_width = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+
+[*.md]
+trim_trailing_whitespace = false
+indent_size = 1
+
+[*.{css,js,json}]
+indent_style = tab

docs/01-overview.md

@@ -0,0 +1,35 @@
+---
+sidebar_position: 1
+---
+
+# Overview
+
+Stardust XR _(formerly known as Stardust)_ is an XR [display server](https://itsfoss.com/display-server) designed for Linux-based systems<!-- (possibly most unix-based too, but untested)-->.<br/>
+Unlike traditional display servers that focus on 2D screens, Stardust XR introduces new conventions to utilize unbounded 3D space in virtual or real environments.
+
+## Priorities
+
+- **3D Environment Focus**: While supporting 2D clients through the Wayland protocol, Stardust XR primarily aims to create and manage 3D environments.
+
+- **Standard Interfaces**: Utilizes Wayland and OpenXR for 2D and XR app integration.
+
+- **Stardust Protocol**: Implements a special protocol for:
+  - Creating virtual objects
+  - Developing 3D UIs around 2D apps (Panel Shells)
+  - Handling data as Items that can represent files, Wayland surfaces, etc.
+
+- **Personal Device Interaction**: Focuses on individual user interactions rather than collaborative 3D spaces.
+
+- **Flexible Object Interaction**: Users can choose objects that best suit their current scenario, with easy setup for default configurations.
+
+## Architecture
+
+![simplified architecture diagram](./simplified-architecture.png)
+
+## Projects & Components
+
+- [**telescope**](https://github.com/StardustXR/telescope): bundle most used components to have a demo environment set up
+- ...
+
+<!-- TODO: add more core components and projects! -->
+

docs/02-getting-started/01-tutorial.md

@@ -0,0 +1,86 @@
+---
+sidebar_position: 1
+---
+
+# Tutorial
+
+## Setup OpenXR
+
+:::note
+if you have no headset or other OpenXR device, you can skip this step and start with [installing nix](#install-nix).
+:::
+
+### SteamVR
+
+#### Archlinux
+
+TODO
+
+#### NixOS
+
+TODO
+
+#### Others
+
+TODO: collect links for setup on different distrons
+
+### [Monado](https://monado.dev/)
+
+#### Archlinux
+
+TODO
+
+#### NixOS
+
+TODO
+
+#### Others
+
+TODO: collect links for setup on different distrons
+
+## Install nix
+
+For easy development and distribution this project uses the [nix package manager](https://nix.dev/).<br/>
+This allows to ensure all dependency requirements are met.
+
+:::info
+Make sure to have [flakes enabled](https://nixos.wiki/wiki/flakes).
+:::
+
+You can install nix on all common linux systems:
+
+#### Archlinux
+
+```shell
+# install git and nix
+sudo pacman -Sy git nix
+# enable flakes
+echo 'experimental-features = nix-command flakes' | sudo tee -a /etc/nix/nix.conf
+# enable nix daemon service
+sudo systemctl enable nix-daemon.service
+# add the current user to nix-users group
+sudo usermod -aG nix-users $(id -un)
+# reboot to apply user and service changes
+sudo systemctl reboot
+```
+
+#### NixOS
+
+TODO
+
+#### Others
+
+TODO: collect links for setup on different distrons
+
+## Run Demo
+
+1. clone https://github.com/StardustXR/telescope
+2. make sure your OpenXR device works (if 2D mode is not used)
+3. run `nix run .`
+
+## Run wayland client
+
+```shell
+# run demo.mp4 video in a loop within Stardust
+WAYLAND_DISPLAY=wayland-0 DISPLAY= mpv Downloads/demo.mp4 --loop
+```

docs/02-getting-started/_category_.json

@@ -1,4 +1,4 @@
 {
 	"label": "Getting Started",
-	"position": 1
+	"position": 2
 }

docs/09-terminology.md

@@ -0,0 +1,5 @@
+# Glossary
+
+- **Item**: a virtual object that represents data
+- **Panel Shells**: 3D UIs around 2D apps
+- ...

docs/getting-started/overview.md

@@ -1,12 +0,0 @@
----
-sidebar_position: 1
----
-
-# Overview
-
-## Description
-Stardust XR (informally known as Stardust) is an XR display server for Linux-based distros (possibly most unix-based too, but untested). Unlike display servers of the past that were run on bounded 2D screens, Stardust has to break convention in order to account for unbounded 3D space in any potential virtual or real environment.
-
-Unlike many display servers, Stardust is not trying to reinvent how applications interface with the system. Stardust uses Wayland and will use OpenXR for 2D/XR app integration. Stardust however has a special protocol for creation of virtual objects such as 3D UIs around 2D apps (called Panel Shells) and handling of data as objects (called Items, can represent files or Wayland surfaces or such). Stardust is not a collaborative 3D space, instead focusing on your own personal device and interactions with it.
-
-Put simply, Stardust is a system UI base where multiple different clients (programs that connect to Stardust directly) can create objects for the user to interact with their apps and device. The user can choose to use the objects that work best for their current scenario, and default setups can easily be created so users start out with all the essentials.

docusaurus.config.js

@@ -13,6 +13,10 @@ module.exports = {
 	favicon: 'img/favicon.ico',
 	organizationName: 'StardustXR', // Usually your GitHub org/user name.
 	projectName: 'website', // Usually your repo name.
+	markdown: {
+		mermaid: true,
+	},
+	themes: ['@docusaurus/theme-mermaid'],
 	themeConfig: {
 		colorMode: {
 			defaultMode: "dark",
@@ -33,7 +37,7 @@ module.exports = {
 				},
 				{
 					type: 'doc',
-					docId: 'getting-started/overview',
+					docId: 'overview',
 					position: 'left',
 					label: 'Docs',
 				},
@@ -76,7 +80,7 @@ module.exports = {
 						},
 						{
 							label: 'Getting Started',
-							to: '/docs/getting-started/overview',
+							to: '/docs/getting-started/tutorial',
 						},
 					],
 				},

package.json

@@ -14,8 +14,9 @@
 		"write-heading-ids": "docusaurus write-heading-ids"
 	},
 	"dependencies": {
-		"@docusaurus/core": "2.0.0-beta.3",
-		"@docusaurus/preset-classic": "2.0.0-beta.3",
+		"@docusaurus/core": "2.4.1",
+		"@docusaurus/preset-classic": "2.4.1",
+		"@docusaurus/theme-mermaid": "2.4.1",
 		"@mdx-js/react": "^1.6.21",
 		"@svgr/webpack": "^5.5.0",
 		"clsx": "^1.1.1",

sidebars.js

@@ -1,12 +1,13 @@
 /**
- * Creating a sidebar enables you to:
- - create an ordered group of docs
- - render a sidebar for each doc of that group
- - provide next/previous navigation
+	Creating a sidebar enables you to:
+		- create an ordered group of docs
+		- render a sidebar for each doc of that group
+		- provide next/previous navigation
 
- The sidebars can be generated from the filesystem, or explicitly defined here.
 
- Create as many sidebars as you want.
+	The sidebars can be generated from the filesystem, or explicitly defined here.
+
+	Create as many sidebars as you want.
  */
 
 module.exports = {

src/pages/index.js

@@ -19,7 +19,7 @@ function HomepageHeader() {
 				<div className={styles.buttons}>
 					<Link
 						className="button button--secondary button--lg"
-						to="/docs/getting-started/overview">
+						to="/docs/getting-started/tutorial">
 						Get Started
 					</Link>
 				</div>