feat: start rewriting with Starlight

.editorconfig

@@ -8,6 +8,3 @@ indent_size = 2
 max_line_length = 100
 insert_final_newline = true
 trim_trailing_whitespace = true
-
-[{*.md,*.mdx}]
-indent_size = 4

.github/workflows/build-preview.yaml

@@ -25,16 +25,13 @@ jobs:
       - name: "install dependencies"
         run: "pnpm install"
       - name: "build"
-        run: "pnpm run build"
-        env:
-          CI_ENV: preview
-          GITHUB_PR_HEAD_OWNER: ${{ github.event.pull_request.head.repo.owner.login }}
+        run: "pnpm build"
       - name: "copy cloudflare configuration files to build directory"
         run: |
-          cp _headers build/
-          cp _redirects build/
+          cp _headers dist/
+          cp _redirects dist/
       - name: "upload build artifact"
         uses: "actions/upload-artifact@v4"
         with:
           name: "preview-build"
-          path: "build"
+          path: "dist"

.github/workflows/deploy-preview.yaml

@@ -23,7 +23,7 @@ jobs:
         id: "preview-build-artifact"
         with:
           name: "preview-build"
-          path: "build"
+          path: "dist"
           github-token: ${{ secrets.GITHUB_TOKEN }}
           run-id: ${{ github.event.workflow_run.id }}
       - name: "Deploy to Cloudflare Pages"

.github/workflows/deploy.yaml

@@ -27,13 +27,11 @@ jobs:
       - name: "install dependencies"
         run: "pnpm install"
       - name: "build"
-        run: "pnpm run build"
-        env:
-          CI_ENV: production
+        run: "pnpm build"
       - name: "copy cloudflare configuration files to build directory"
         run: |
-          cp _headers build/
-          cp _redirects build/
+          cp _headers dist/
+          cp _redirects dist/
       - name: "publish (push)"
         id: "cloudflare-publish"
         uses: "AdrianGonz97/refined-cf-pages-action@v1"
@@ -42,5 +40,5 @@ jobs:
           accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
           projectName: "papermc-docs"
           deploymentName: "Production"
-          directory: "build"
-          gitHubToken: ${{ secrets.GITHUB_TOKEN }}
+          directory: "dist"
+          githubToken: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/format.yaml

@@ -23,4 +23,4 @@ jobs:
       - name: Install dependencies
         run: pnpm install
       - name: Check format
-        run: pnpm run format:check
+        run: pnpm format:check

.gitignore

@@ -1,10 +1,23 @@
-/.idea
-/node_modules
-/build
-/.vscode
-/.docusaurus
-.cache-loader
-.DS_Store
+# build output
+dist/
+# generated types
+.astro/
+
+# dependencies
+node_modules/
+
+# logs
 npm-debug.log*
-.pnp.*
-/.meta
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
+.DS_Store
+
+.idea/

.prettierignore

@@ -1,6 +1,8 @@
 pnpm-lock.yaml
-docs/versioned
 *.md
 *.mdx
 !README.md
-!CONTRIBUTING.md
+!CONTRIBUTING.md
+
+# TODO: remove
+old

.prettierrc.json

@@ -2,5 +2,15 @@
   "arrowParens": "always",
   "singleQuote": false,
   "semi": true,
-  "trailingComma": "es5"
+  "trailingComma": "es5",
+  "plugins": ["prettier-plugin-astro", "prettier-plugin-organize-imports"],
+  "organizeImportsSkipDestructiveCodeActions": true,
+  "overrides": [
+    {
+      "files": "*.astro",
+      "options": {
+        "parser": "astro"
+      }
+    }
+  ]
 }

.typos.toml

@@ -1,8 +1,3 @@
-[files]
-extend-exclude = [
-    "docs/versioned" # old documentation shouldn't be checked
-]
-
 [default]
 locale = "en-us"
 

.vscode/extensions.json

@@ -0,0 +1,4 @@
+{
+  "recommendations": ["astro-build.astro-vscode"],
+  "unwantedRecommendations": []
+}

.vscode/launch.json

@@ -0,0 +1,11 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "command": "./node_modules/.bin/astro dev",
+      "name": "Development server",
+      "request": "launch",
+      "type": "node-terminal"
+    }
+  ]
+}

CONTRIBUTING.md

@@ -106,50 +106,50 @@ of a few ways:
 
 1. `SoftwareVersion` component
 
-    This component is used to embed the current version of the software into the documentation. An example of this would be:
+   This component is used to embed the current version of the software into the documentation. An example of this would be:
 
-    ```jsx
-    <SoftwareVersion versionType={"maj-min-pat"}/> // e.g. 1.19.2
-    <SoftwareVersion versionType={"maj-min"}/> // e.g. 1.19
-    <SoftwareVersion versionType={"maj"}/> // e.g. 1
+   ```jsx
+   <SoftwareVersion versionType={"maj-min-pat"}/> // e.g. 1.19.2
+   <SoftwareVersion versionType={"maj-min"}/> // e.g. 1.19
+   <SoftwareVersion versionType={"maj"}/> // e.g. 1
 
-    // You can set the project name to be used for the versioning (defaults to paper):
-    <SoftwareVersion versionType={"maj-min-pat"} project={"velocity"}/> // e.g. 3.3.0-SNAPSHOT
-    ```
+   // You can set the project name to be used for the versioning (defaults to paper):
+   <SoftwareVersion versionType={"maj-min-pat"} project={"velocity"}/> // e.g. 3.3.0-SNAPSHOT
+   ```
 
 2. `Javadoc` component
 
-    This component is used to embed a link to the current version of the corresponding Javadoc. An example of this would be:
+   This component is used to embed a link to the current version of the corresponding Javadoc. An example of this would be:
 
-    ```jsx
-    <Javadoc name={"org.bukkit.event.Event"}>here</Javadoc>
-    // The project can also be set here, and defaults to Paper
-    ```
+   ```jsx
+   <Javadoc name={"org.bukkit.event.Event"}>here</Javadoc>
+   // The project can also be set here, and defaults to Paper
+   ```
 
 3. `VersionFormattedCode` component
 
-    This component is used to embed a code block with the current version of the software. An example of this would be:
-
-    ````jsx
-    <VersionFormattedCode language={"yaml"}>
-    ```⠀
-    name: Paper-Test-Plugin
-    version: '1.0'
-    main: io.papermc.testplugin.TestPlugin
-    description: Paper Test Plugin
-    api-version: '%%_MAJ_MIN_PAT_MC_%%'
-    bootstrapper: io.papermc.testplugin.TestPluginBootstrap
-    loader: io.papermc.testplugin.TestPluginLoader
-    ```⠀
-    </VersionFormattedCode>
-
-    // The possible placeholders are:
-    %%_MAJ_MIN_MC_%%  - Major-Minor Paper Version (E.g. 1.20)
-    %%_MAJ_MIN_PAT_MC_%% - Major-Minor-Patch Paper Version (E.g. 1.20.4)
-    %%_MAJ_MIN_VEL_%% - Major Velocity Version (E.g. 3.1.0)
-    %%_MAJ_MIN_PAT_VEL_%% - Major-Minor-Patch Velocity Version (E.g. 3.1.1-SNAPSHOT)
-    %%_MAJ_MIN_PAT_USERDEV_%% - Latest Paperweight-Userdev Version (E.g. 1.7.3)
-    ````
+   This component is used to embed a code block with the current version of the software. An example of this would be:
+
+   ````jsx
+   <VersionFormattedCode language={"yaml"}>
+   ```⠀
+   name: Paper-Test-Plugin
+   version: '1.0'
+   main: io.papermc.testplugin.TestPlugin
+   description: Paper Test Plugin
+   api-version: '%%_MAJ_MIN_PAT_MC_%%'
+   bootstrapper: io.papermc.testplugin.TestPluginBootstrap
+   loader: io.papermc.testplugin.TestPluginLoader
+   ```⠀
+   </VersionFormattedCode>
+
+   // The possible placeholders are:
+   %%_MAJ_MIN_MC_%%  - Major-Minor Paper Version (E.g. 1.20)
+   %%_MAJ_MIN_PAT_MC_%% - Major-Minor-Patch Paper Version (E.g. 1.20.4)
+   %%_MAJ_MIN_VEL_%% - Major Velocity Version (E.g. 3.1.0)
+   %%_MAJ_MIN_PAT_VEL_%% - Major-Minor-Patch Velocity Version (E.g. 3.1.1-SNAPSHOT)
+   %%_MAJ_MIN_PAT_USERDEV_%% - Latest Paperweight-Userdev Version (E.g. 1.7.3)
+   ````
 
 When the major version of the software changes, the docs will still need to have a "snapshot" created to keep documentation
 for older versions. This is done by using Docusaurus's `version` command:

README.md

@@ -9,8 +9,8 @@ How to get docs running on your local machine for development.
 
 ### Prerequisites
 
--   [node](https://nodejs.org)
--   [pnpm](https://pnpm.io/installation)
+- [node](https://nodejs.org)
+- [pnpm](https://pnpm.io/installation)
 
 ### Local Development
 

astro.config.ts

@@ -0,0 +1,72 @@
+import starlight from "@astrojs/starlight";
+import { defineConfig } from "astro/config";
+// import starlightLinksValidator from "starlight-links-validator";
+import starlightSidebarTopics from "starlight-sidebar-topics";
+
+const prod = process.env.NODE_ENV === "production";
+
+// https://astro.build/config
+export default defineConfig({
+  site: prod ? "https://docs.papermc.io" : undefined,
+  integrations: [
+    starlight({
+      title: "PaperMC Docs",
+      favicon: "favicon.ico",
+      logo: {
+        light: "./src/assets/logo-marker-light.svg",
+        dark: "./src/assets/logo-marker-dark.svg",
+        replacesTitle: true,
+      },
+      social: [
+        { icon: "github", label: "GitHub", href: "https://github.com/PaperMC" },
+        { icon: "discord", label: "Discord", href: "https://discord.gg/PaperMC" },
+      ],
+      lastUpdated: true,
+      editLink: {
+        baseUrl: "https://github.com/PaperMC/docs/edit/main/",
+      },
+      customCss: [
+        "@fontsource/poppins/400.css",
+        // "@fontsource/poppins/600.css", // see src/styles/custom.css
+        "@fontsource/jetbrains-mono/400.css",
+        "@fontsource/jetbrains-mono/600.css",
+        "./src/styles/custom.css",
+      ],
+      components: {
+        Head: "./src/components/overrides/Head.astro",
+        Sidebar: "./src/components/overrides/Sidebar.astro",
+      },
+      plugins: [
+        // starlightLinksValidator(),
+        starlightSidebarTopics(
+          [
+            {
+              id: "paper",
+              label: "Paper",
+              link: "/paper/",
+              items: [
+                {
+                  label: "Administration",
+                  items: [
+                    {
+                      label: "Getting started",
+                      autogenerate: { directory: "paper/admin/getting-started" },
+                    },
+                    { label: "How-to guides", autogenerate: { directory: "paper/admin/how-to" } },
+                    { label: "Miscellaneous", autogenerate: { directory: "paper/admin/misc" } },
+                  ],
+                },
+              ],
+            },
+          ],
+          {
+            // pages excluded from sidebars
+            topics: {
+              paper: ["/paper/admin"],
+            },
+          }
+        ),
+      ],
+    }),
+  ],
+});