Merge pull request #344 from WhyFenceCode/main

Create two sections of docs

.gitignore

@@ -21,5 +21,4 @@ pnpm-debug.log*
 .DS_Store
 
 # VS code
-.vscode/
-pnpm-lock.yaml
+.vscode/

README.md

@@ -30,7 +30,7 @@ pnpm dev
 
 Images can be added to `src/assets/` and embedded in Markdown with a relative link.
 
-Content belongs in either `/guides`, `/reference`, `/how_to` within docs, and in its relative subcategory.
+Content belongs in either `/current/guides`, `/current/reference`, `/current/how-to` within docs, and in its relative subcategory.
 Unfinished/Unfinished docs are marked with the `Unfinished` tag in the warning style.
 
 ### How to write:
@@ -54,7 +54,7 @@ A guide should leave the reader feeling comfortable with the topic, and it shoul
 A how to is a singular short article that walks a user through a small problem in their way (EX transforming shadows to screen space or tonemapping). A how to is made to walk a user through a short section of code and does not need to lead from one outcome to another. It is made to increase/create the understanding on a small section of code, and is rarely open ended. The how to should be written similar to [how to guides on Diataxis](https://diataxis.fr/how-to-guides/).
 
 ### Reference:
-A reference is a docs page. It give objective information on a subject, without moving towards individual use cases. These are often short pages, which are written to provide information about syntax surrounding a line or two of code. These need to be written in a succinct way so that the user can quickly find information. Best practices are located at [references in Diataxis](https://diataxis.fr/reference/)
+A reference is a docs page. It give objective information on a subject, without moving towards individual use cases. These are often short pages, which are written to provide information about syntax surrounding a line or two of code. These need to be written in a succinct way so that the user can quickly find information. Best practices are located at [references in Diataxis](https://diataxis.fr/current/reference/)
 
 For uniform references please look at `alphaTestRef` for formatting. The aside found there can be used for any version specific stuff.
 

astro.config.mjs

@@ -1,6 +1,7 @@
 import { defineConfig } from 'astro/config';
 import starlight from '@astrojs/starlight';
-import starlightImageZoom from 'starlight-image-zoom'
+import starlightImageZoom from 'starlight-image-zoom';
+import starlightUtils from "@lorenzo_lewis/starlight-utils";
 
 export default defineConfig({
 	site: 'https://shaders.properties',
@@ -26,19 +27,18 @@ export default defineConfig({
 			},
 			sidebar: [
 				{
-					label: 'Guides',
-					autogenerate: { directory: 'guides', collapsed: true},
-				},
-				{
-					label: 'Reference',
-					autogenerate: { directory: 'reference', collapsed: true},
-				},
-				{
-					label: 'How To',
-					autogenerate: { directory: 'how_to', collapsed: true},
+					label: '',
+					autogenerate: { directory: 'current', collapsed: true },
 				},
 			],
-			plugins: [starlightImageZoom()]
+			plugins: [
+				starlightImageZoom(),
+				starlightUtils({
+					multiSidebar: {
+						switcherStyle: "horizontalList",
+					},
+				}),
+			]
 		}),
 	],
 });

package.json

@@ -12,11 +12,13 @@
   "dependencies": {
     "@astrojs/check": "^0.5.10",
     "@astrojs/starlight": "^0.28.2",
+    "@lorenzo_lewis/starlight-utils": "^0.2.0",
     "astro": "^4.16.1",
     "astro-og-canvas": "^0.5.0",
     "canvaskit-wasm": "^0.39.1",
     "sharp": "^0.32.5",
     "starlight-image-zoom": "^0.8.0",
-    "typescript": "^5.4.5"
+    "typescript": "^5.4.5",
+    "tslib": "^2.6.2"
   }
-}
+}

src/components/SideBar.astro

@@ -0,0 +1,17 @@
+---
+import type { Props } from '@astrojs/starlight/props';
+import Default from '@astrojs/starlight/components/Sidebar.astro';
+
+// Get the first part of the file path, i.e. "site/setup" would return "site"
+const firstPathSegment = Astro.props.slug.split('/')[0];
+// Filter out groups that don’t include links to the current sub directory
+Astro.props.sidebar = Astro.props.sidebar.filter(
+    (group) =>
+        group.type === 'group' &&
+        group.entries.some(
+            (entry) => entry.type === 'link' && entry.href.startsWith('/' + firstPathSegment)
+        )
+);
+---
+
+<Default {...Astro.props}><slot /></Default>

src/content/docs/guides/Your First Shader/0_intro.mdx → src/content/docs/current/Guides/Your First Shader/0_intro.mdx

@@ -63,4 +63,4 @@ These passes run for every vertex of every item rendered onscreen. This allows u
 
 The final type of pass is the shadow pass, which runs before all other passes. This pass renders all terrain from the perspective of the sun/moon to a few buffers we can access later, known as the 'shadow maps'. The main shadow map stores how far away the closest thing it can see is. From this, we can check if something is further from the sun than the closest thing it can see, and if it is, it must be in shadow. We will cover this later on in the tutorial.
 
-For a full list of programs and what they do, see the [Iris Docs](https://shaders.properties/reference/programs/overview/).
+For a full list of programs and what they do, see the [Iris Docs](https://shaders.properties/current/reference/programs/overview/).

src/content/docs/guides/Your First Shader/1_composite.mdx → src/content/docs/current/Guides/Your First Shader/1_composite.mdx

@@ -78,7 +78,7 @@ The `main` function is the code that is run when the shader is invoked, just lik
 gl_Position = ftransform();
 ```
 
-This transforms the position of the vertex from model space to clip space. The `ftransform` function is actually deprecated but Iris patches it to the relevant modern code. For more information, see the howto on [coordinate spaces](/how_to/coordinate_spaces).
+This transforms the position of the vertex from model space to clip space. The `ftransform` function is actually deprecated but Iris patches it to the relevant modern code. For more information, see the howto on [coordinate spaces](/current/how-to/coordinate_spaces).
 
 ```glsl
 texcoord = (gl_TextureMatrix[0] * gl_MultiTexCoord0).xy;
@@ -113,7 +113,7 @@ Let's analyse this as well a bit.
 uniform sampler2D colortex0
 ```
 
-This allows the shader to read from `colortex0`. Iris provides you with a number of `colortex` buffers you can read and write to. Each buffer is a texture with the same resolution as your screen. For more information on the `colortex` buffers, see the [docs](/reference/buffers/colortex/). `colortex0` usually contains the main scene, and we can use the other 15 for whatever we want.
+This allows the shader to read from `colortex0`. Iris provides you with a number of `colortex` buffers you can read and write to. Each buffer is a texture with the same resolution as your screen. For more information on the `colortex` buffers, see the [docs](/current/reference/buffers/colortex/). `colortex0` usually contains the main scene, and we can use the other 15 for whatever we want.
 
 ```glsl
 in vec2 texcoord
@@ -125,7 +125,7 @@ This is where we recieve the `texcoord` passed `out` in the vertex shader. This
 /* RENDERTARGETS: 0 */
 ```
 
-This is a comment that the Iris patcher reads. It tells the shader to write back to `colortex0`. For more info, see [the docs](/reference/constants/rendertargets).
+This is a comment that the Iris patcher reads. It tells the shader to write back to `colortex0`. For more info, see [the docs](/current/reference/constants/rendertargets).
 
 ```glsl
 layout(location = 0) out vec4 color;
@@ -155,7 +155,7 @@ color.rgb = vec3(dot(color.rgb, vec3(1.0/3.0)));
 
 Your screen should now look like this!
 
-![](../../../../assets/beginner_tutorial/monochrome.webp)
+![](../../../../../assets/beginner_tutorial/monochrome.webp)
 
 :::tip[Next steps]
 See if you can make the screen red, or green. Using `texcoord`, can you make one half green and the other half red?

src/content/docs/guides/Your First Shader/2_gbuffers.mdx → src/content/docs/current/Guides/Your First Shader/2_gbuffers.mdx

@@ -27,7 +27,7 @@ For the purposes of this tutorial, we will only be covering the shading of terra
 ```
 
 :::note[Info]
-When a gbuffers program is not present, Iris will fall back to using the most similar program that exists. If no such similar program exists, a built in one will be used instead. See [the docs](/reference/programs/gbuffers/) for more info.
+When a gbuffers program is not present, Iris will fall back to using the most similar program that exists. If no such similar program exists, a built in one will be used instead. See [the docs](/current/reference/programs/gbuffers/) for more info.
 :::
 
 ## The Vertex Shader
@@ -65,7 +65,7 @@ This now gets us the correct light level. You will notice now that if you reload
 ### `glcolor`
 Some blocks, like grass, have a tint based on their biome, provided in the form of `gl_Color`. If you look in the files for the grass block texture, it is actually grey. To demonstrate this, let's set `glcolor` to `vec4(1.0)`. Since the color is multiplied by glcolor in the fragment shader, and multiplying by 1 does nothing, this will remove the tint.
 
-![](../../../../assets/beginner_tutorial/notint.webp)
+![](../../../../../assets/beginner_tutorial/notint.webp)
 
 Let's undo that, since having color is quite nice.
 
@@ -99,7 +99,7 @@ With those values being passed through, let's move onto the fragment shader (`gb
 ### `gtexture`
 This is the texture atlas we mentioned earlier. It contains the textures of all the blocks onscreen, and `texcoord` tells us where in the atlas the current fragment texture is.
 
-![](../../../../assets/beginner_tutorial/textureatlas.webp)
+![](../../../../../assets/beginner_tutorial/textureatlas.webp)
 This is an example of what the texture atlas looks like, however it can vary.
 
 ### `lightmap`
@@ -125,7 +125,7 @@ To do this, we can just add a new line at the end of `main`:
 ```glsl
 color.rgb = normal;
 ```
-![](../../../../assets/beginner_tutorial/normals.webp)
+![](../../../../../assets/beginner_tutorial/normals.webp)
 You can see that faces that face upwards are green. Colors are stored in the `rgba` format and vectors/coordinates in the `xyzw` format. Since both of these are stored in the same `vec4` format, this means that the `r` component represents the `x` component, and so on. Since `g` represents `y`, this means that if the face is green, then the normal must only have a value in the `y` component, and hence is facing upwards.
 
 You'll notice some faces are black, this is where the normals are negative - you cannot have a negative color!
@@ -166,7 +166,7 @@ layout(location = 1) out vec4 someMoreData; // writes to colortex3
 
 
 :::note[Note]
-Iris implements by default something known as 'buffer flipping'. This means that the texture you write to is not actually the same one you read from. This is because different instances of the shader might run at different times and if multiple of them try to access the same pixel, the output could be different depending on which one gets to it first. For more information, see [the docs](/reference/shadersproperties/rendering#flip)
+Iris implements by default something known as 'buffer flipping'. This means that the texture you write to is not actually the same one you read from. This is because different instances of the shader might run at different times and if multiple of them try to access the same pixel, the output could be different depending on which one gets to it first. For more information, see [the docs](/current/reference/shadersproperties/rendering#flip)
 :::
 
 Finally, in main, let's write this data to the textures, so we can access it in `composite`.

src/content/docs/guides/Your First Shader/3_composite_lighting.mdx → src/content/docs/current/Guides/Your First Shader/3_composite_lighting.mdx

@@ -49,7 +49,7 @@ Next, let's verify everything is being decoded correctly.
 ```glsl
 color.rgb = vec3(lightmap, 0.0);
 ```
-![](../../../../assets/beginner_tutorial/lightmap.webp)
+![](../../../../../assets/beginner_tutorial/lightmap.webp)
 
 You can see that where there is skylight, only the green component is set. However, where there is blocklight (by the torch), the color is yellow. Since red and green make yellow in RGB, we know that blocklight is stored in the red component and sunlight is stored in the green component.
 
@@ -90,7 +90,7 @@ color.rgb *= blocklight + skylight + ambient + sunlight;
 ```
 
 Things should look something like this:
-![](../../../../assets/beginner_tutorial/lighting1.webp)
+![](../../../../../assets/beginner_tutorial/lighting1.webp)
 
 ## Sunlight
 Now, what about that sunlight? Well, if something is facing directly towards the sun, then we want it to be fully sunlit. On the other hand, if something is facing away from the sun, we want there to be no sunlight. So, we need a function that returns 1.0 if two vectors are facing in the same direction, and 0.0 if they are facing away from each other. Happily, we can use a dot product for this.
@@ -120,7 +120,7 @@ vec3 sunlight = sunlightColor * clamp(dot(worldLightVector, normal), 0.0, 1.0) *
 
 With that change, your lighting should seem a bit more realistic.
 
-![](../../../../assets/beginner_tutorial/lighting2.webp)
+![](../../../../../assets/beginner_tutorial/lighting2.webp)
 
 ## Fixing the sky
 At this point, it may appear as if your Minecraft world is currently undergoing an apocalypse. This is because we are also applying lighting to the sky, despite the fact we do not have normal or lightmap data for it. So, how do we tell if a pixel is the sky or not? Well, we have access to something called the depth buffer, which tells you how far away a pixel is. If the pixel is at the maximum view distance, the depth buffer will store 1.0.
@@ -139,4 +139,4 @@ The depth is not stored in a linear format. This means that while a pixel that i
 :::
 
 Having done that, your Minecraft world should hopefully have been saved from the apocalypse.
-![](../../../../assets/beginner_tutorial/fixedsky.webp)
+![](../../../../../assets/beginner_tutorial/fixedsky.webp)