Regularly scheduled site maintenance

astro.config.mjs

@@ -12,6 +12,8 @@ export default defineConfig({
   integrations: [
     starlight({
       title: "Docs style guide",
+      description:
+        "The style guide for all Interledger documentation sites. Because we love consistency.",
       customCss: [
         "./node_modules/@interledger/docs-design-system/src/styles/green-theme.css",
         "./node_modules/@interledger/docs-design-system/src/styles/ilf-docs.css",

package.json

@@ -9,12 +9,12 @@
     "astro": "astro"
   },
   "dependencies": {
-    "@astrojs/react": "^3.0.2",
-    "@astrojs/starlight": "^0.10.1",
-    "@interledger/docs-design-system": "0.0.12",
-    "@types/react": "^18.2.22",
-    "@types/react-dom": "^18.2.7",
-    "astro": "^3.1.2",
+    "@astrojs/react": "^3.0.3",
+    "@astrojs/starlight": "^0.10.4",
+    "@interledger/docs-design-system": "0.0.13",
+    "@types/react": "^18.2.25",
+    "@types/react-dom": "^18.2.10",
+    "astro": "^3.2.3",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "remark-mermaidjs": "^6.0.0",

src/content/docs/index.mdx

@@ -3,14 +3,16 @@ title: Interledger documentation style guide
 description: Style guide for Interledger's documentation sites
 ---
 
-Interledger uses Starlight (powered by Astro) for all its documentation sites. In order to keep our visual styling consistent across our numerous documentation sites, we have packaged our styles and shared components in an [npm package](https://www.npmjs.com/package/@interledger/docs-design-system).
+Interledger uses [Starlight](https://starlight.astro.build/getting-started/) (powered by [Astro](https://docs.astro.build/en/getting-started/)) for all its documentation sites. In order to keep our visual styling consistent across our numerous documentation sites, we have packaged our styles and shared components in an [npm package](https://www.npmjs.com/package/@interledger/docs-design-system).
 
 ```bash
 npm i @interledger/docs-design-system
 ```
 
 Feel free to install with the package manager of your choice.
 
+Because we are using Starlight, content has to be authored in Markdown or MDX. Components can be written in JSX, and imported into MDX files. Documentation pages cannot be `.astro` files. You are free to create Astro pages in the /pages folder though.
+
 ## Visual themes
 
 We have 2 visual themes, green for specification documentation and orange for product documentation. These themes are built on top of Starlight's defaults and overrides some of the out-of-the-box styling. They are just CSS files, so use them with the path to `node_modules`. Unfortunately, we did not have enough braincells to figure out how to make it prettier than that. To use them in the `astro.config.mjs`:
@@ -36,6 +38,8 @@ import '/node_modules/@interledger/docs-design-system/src/styles/green-theme
 
 ## Components
 
+Starlight provides some built-in components that are commonly used for documentation sites. Please refer to the [Starlight documentation](https://starlight.astro.build/guides/components#built-in-components) for detailed information on how to use them.
+
 We also have a number of documentation-specific helper components that can be imported and used where necessary. You can refer to the individual pages in the sidebar to see them in action.
 
 For the shared components, if you are using both CodeBlock and Disclosure on the same page, you can import them both like so: