Preshare tweaks

Author: cakeGit

.vitepress/config.mjs

@@ -63,63 +63,53 @@ try {
   console.error('generateHiddenProxies error:', e);
 }
 
-// Build the sidebar auto-dynamically by top-level folders in `docs`
+// Build the sidebar auto-dynamically by walking the `docs` tree recursively
 function buildSidebar() {
-  const entries = readdirSync(docsDir, { withFileTypes: true });
-  const sidebar = [];
-
-  // Include top-level pages (root .md files other than index.md)
-  const rootFiles = entries
-    .filter(e => e.isFile() && e.name.endsWith('.md'))
-    .map(e => join(docsDir, e.name));
-
-  const rootItems = rootFiles
-    .map(full => {
-      // Exclude .hidden.md and generated proxies
-      if (full.endsWith('.hidden.md')) return null;
+  // recursive helper: return array of sidebar items for a directory
+  function walk(dir, relPath = '') {
+    const entries = readdirSync(dir, { withFileTypes: true });
+    const items = [];
+
+    // first process files
+    for (const e of entries) {
+      if (!e.isFile() || !e.name.endsWith('.md')) continue;
+      const full = join(dir, e.name);
+      // skip hidden and proxies
+      if (full.endsWith('.hidden.md')) continue;
       try {
         const content = readFileSync(full, 'utf8');
-        if (content.includes(PROXY_MARKER)) return null;
-      } catch (e) {}
+        if (content.includes(PROXY_MARKER)) continue;
+      } catch (err) {}
       const name = basenameWithoutExt(full);
-      // Skip index.md (home) unless it's desired
-      if (name === 'index') return null;
-      return { text: name, link: `/${name}` };
-    })
-    .filter(Boolean);
-
-  if (rootItems.length) {
-    sidebar.push({ text: 'root', items: rootItems });
-  }
+      // skip root index (home) at top level
+      if (relPath === '' && name === 'index') continue;
+
+      // compute link
+      let link;
+      if (name === 'index') {
+        // directory index becomes the path to folder
+        link = `/${relPath}/`.replace(/\\/g, '/');
+      } else {
+        link = `/${relPath}/${name}`.replace(/\\/g, '/');
+      }
+      items.push({ text: name, link });
+    }
 
-  // For each top-level folder, collect its markdown files (non-hidden, non-proxy)
-  for (const e of entries) {
-    if (!e.isDirectory()) continue;
-    const folderPath = join(docsDir, e.name);
-    const files = readdirSync(folderPath, { withFileTypes: true })
-      .filter(f => f.isFile() && f.name.endsWith('.md'))
-      .map(f => join(folderPath, f.name))
-      .filter(full => {
-        if (full.endsWith('.hidden.md')) return false;
-        try {
-          const content = readFileSync(full, 'utf8');
-          if (content.includes(PROXY_MARKER)) return false;
-        } catch (err) {}
-        return true;
-      });
-
-    if (!files.length) continue;
-    const items = files.map(full => {
-      const name = basenameWithoutExt(full);
-      // link should be /folder/name (strip any index specialness)
-      const linkName = name === 'index' ? `/${e.name}/` : `/${e.name}/${name}`;
-      return { text: name, link: linkName };
-    });
+    // then process subdirectories
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      const subdir = e.name;
+      const childItems = walk(join(dir, subdir), relPath ? `${relPath}/${subdir}` : subdir);
+      if (childItems.length) {
+        items.push({ text: subdir, items: childItems });
+      }
+    }
 
-    sidebar.push({ text: e.name, items });
+    return items;
   }
 
-  // Prepend a home link
+  const sidebar = walk(docsDir);
+  // ensure home link is first
   sidebar.unshift({ text: 'home', link: '/' });
   return sidebar;
 }

docs/Advancements/Advancements.md

@@ -25,8 +25,8 @@ public class MyAdvancements {
         .icon(MyItems.MY_ITEM)
         .title("My Mod")
         .description("Get started with My Mod.")
-        .after(() -> AllAdvancements.ROOT) // display inside the Create tab omit to create a new advancement tab
-        .awardedForFree()                  // immediately award when the player first joins
+        .after(() -> AllAdvancements.ROOT) // display inside the Create tab as a descendant of create's root, omit this to create a new tab
+        .awardedForFree()                  // immediately award when the player first joins, important for advancement tabs
         .special(AzimuthAdvancement.TaskType.SILENT)
     );
 
@@ -128,7 +128,6 @@ If you want the advancement to be awarded by a game event (rather than manually)
 
 If none of these are called, a built-in `SimpleCreateTrigger` is created automatically. You can then award the advancement manually (see below).
 
-
 ## Awarding advancements manually
 
 If the advancement uses the built-in trigger (no `.whenX` call), award it directly:
@@ -147,7 +146,6 @@ if (!MyAdvancements.FIRST_CRAFT.isAlreadyAwardedTo(player)) {
 
 `awardTo` will throw `UnsupportedOperationException` if the advancement uses an external trigger.
 
-
 ## `AzimuthAdvancementBehaviour`
 
 If you want a block entity to track a player and award advancements when they interact with it, add `AzimuthAdvancementBehaviour` to its behaviour list:
@@ -167,7 +165,7 @@ Using the static `create` method (rather than constructing directly) means that
 
 ### Tracking the player
 
-Call `setPlacedBy` from your block's `setPlacedBy` override to register the player who placed it:
+Call `setPlacedBy` from your block's `setPlacedBy` override, that way your block will register the player who placed it:
 
 ```java
 @Override

docs/Getting Started.md

@@ -31,7 +31,7 @@ Azimuth doesn't require any explicit initialisation on your part just depend on
 
 An expanded version of Create's `BlockEntityBehaviour` that can do significantly more, in effort to replicate features that would typically take new block entity types. All of which is composable on a single `SmartBlockEntity`. You can also *inject* behaviours onto block entities you don't own, without touching their source, making simple soft-compatability easy.
 
-[Super Block Entity Behaviours](./Super Behaviours/Super Behaviours.md)
+[Super Block Entity Behaviours](./Super%20Behaviours/Super%20Behaviours.md)
 
 ### Advancements
 

docs/Outlines/Outlines.md

@@ -16,7 +16,6 @@ outline
 
 Call `tickGrowingTicksElapsed()` each tick to advance the animation. Once elapsed reaches `growingTicks`, the outline stays at full size.
 
-
 ## `ExpandingLineOutlineInstruction`
 
 A ready-to-use Ponder `TickingInstruction` that wraps `ExpandingLineOutline`. Just add it to your scene and it handles everything.

docs/Super Behaviours/Extension Reference.md

@@ -6,6 +6,6 @@ For more about `SuperBlockEntityBehaviour`s, see [Super Block Entity Behaviours]
 
 | Extension | Description |
 | --- | --- |
-| [`KineticBehaviourExtension`](./Kinetic Extension.md) | Adds propagation positions and rotation transfer overrides for kinetic networks. |
-| [`RenderedBehaviourExtension`](./Rendered Extension.md) | Adds behaviour-level BER rendering, optional Flywheel visuals, and optional render bounds expansion. |
-| [`ItemRequirementBehaviourExtension`](./Item Requirement Extension.md) | Adds per-behaviour item requirements to schematic requirement flows. |
+| [`KineticBehaviourExtension`](./Extensions/Kinetic%20Extension.md) | Adds propagation positions and rotation transfer overrides for kinetic networks. |
+| [`RenderedBehaviourExtension`](./Extensions/Rendered%20Extension.md) | Adds behaviour-level BER rendering, optional Flywheel visuals, and optional render bounds expansion. |
+| [`ItemRequirementBehaviourExtension`](./Extensions/Item%20Requirement%20Extension.md) | Adds per-behaviour item requirements to schematic requirement flows. |

…Behaviours/Item Requirement Extension.md …Extensions/Item Requirement Extension.mddocs/Super Behaviours/Item Requirement Extension.md renamed to docs/Super Behaviours/Extensions/Item Requirement Extension.md docs/Super Behaviours/Item Requirement Extension.md renamed to docs/Super Behaviours/Extensions/Item Requirement Extension.md

@@ -2,7 +2,7 @@
 
 `ItemRequirementBehaviourExtension` lets a behaviour contribute item requirements to Create's schematic placement flow. Implement this if your behaviour places or represents items that should be listed when a player is deploying a schematic containing this block.
 
-For an overview of all extensions, see [Super Block Entity Behaviours](./Super Behaviours.md#extensions).
+For an overview of all extensions, see [Super Block Entity Behaviours](../Super%20Behaviours.md#extensions).
 
 ## Implementing
 

…cs/Super Behaviours/Kinetic Extension.md …haviours/Extensions/Kinetic Extension.mddocs/Super Behaviours/Kinetic Extension.md renamed to docs/Super Behaviours/Extensions/Kinetic Extension.md docs/Super Behaviours/Kinetic Extension.md renamed to docs/Super Behaviours/Extensions/Kinetic Extension.md

@@ -2,7 +2,7 @@
 
 `KineticBehaviourExtension` lets a behaviour participate in kinetic propagation adding extra neighbour positions and overriding the speed that gets propagated. It assumes the block entity this behaviour is attached to is a `KineticBlockEntity`.
 
-For an overview of all extensions, see [Super Block Entity Behaviours](./Super Behaviours.md#extensions).
+For an overview of all extensions, see [Super Block Entity Behaviours](../Super%20Behaviours.md#extensions).
 
 ## Implementing
 

…s/Super Behaviours/Rendered Extension.md …aviours/Extensions/Rendered Extension.mddocs/Super Behaviours/Rendered Extension.md renamed to docs/Super Behaviours/Extensions/Rendered Extension.md docs/Super Behaviours/Rendered Extension.md renamed to docs/Super Behaviours/Extensions/Rendered Extension.md

@@ -2,7 +2,7 @@
 
 `RenderedBehaviourExtension` lets a behaviour contribute rendering output alongside the block entity it's attached to. There are two rendering paths available: a standard Block Entity Renderer (BER) that works unconditionally, and an optional Flywheel visual for hardware-accelerated rendering. You can use either path or both together.
 
-For an overview of all extensions, see [Super Block Entity Behaviours](./Super Behaviours.md#extensions).
+For an overview of all extensions, see [Super Block Entity Behaviours](../Super%20Behaviours.md#extensions).
 
 ## Implementing
 

docs/Super Behaviours/Super Behaviours.md

@@ -151,6 +151,6 @@ Behaviours can implement extension interfaces to opt into additional systems kin
 
 | Extension | Description |
 | --- | --- |
-| [`KineticBehaviourExtension`](./Kinetic Extension.md) | Adds propagation positions and rotation transfer overrides for kinetic networks. |
-| [`RenderedBehaviourExtension`](./Rendered Extension.md) | Adds behaviour-level BER rendering, optional Flywheel visuals, and optional render bounds expansion. |
-| [`ItemRequirementBehaviourExtension`](./Item Requirement Extension.md) | Adds per-behaviour item requirements to schematic requirement flows. |
+| [`KineticBehaviourExtension`](./Extensions/Kinetic%20Extension.md) | Adds propagation positions and rotation transfer overrides for kinetic networks. |
+| [`RenderedBehaviourExtension`](./Extensions/Rendered%20Extension.md) | Adds behaviour-level BER rendering, optional Flywheel visuals, and optional render bounds expansion. |
+| [`ItemRequirementBehaviourExtension`](./Extensions/Item%20Requirement%20Extension.md) | Adds per-behaviour item requirements to schematic requirement flows. |

style_guide.md

@@ -18,9 +18,10 @@ docs/
   Super Behaviours/
     Super Behaviours.md
     Extension Reference.md
-    Kinetic Extension.md
-    Rendered Extension.md
-    Item Requirement Extension.md
+    Extensions/
+      Kinetic Extension.md
+      Rendered Extension.md
+      Item Requirement Extension.md
   Advancements/
     Advancements.md
   Outlines/
@@ -63,7 +64,7 @@ PROVIDER.create("my_advancement", b -> b
     .icon(MyItems.MY_ITEM)
     .title("My Title")
     .description("My description.")
-    .after(() -> AllAdvancements.ROOT) // display inside the Create tab omit to create a new tab
+    .after(() -> AllAdvancements.ROOT) // display inside the Create tab, omit this to create a new tab
     .awardedForFree()
 );
 ```
@@ -89,20 +90,18 @@ For things that are easy to mess up or have non-obvious caveats, use a blockquot
 
 Keep them short. One sentence or two.
 
-
 ## Internal links
 
 Link targets use relative paths and include the `.md` extension:
 
 ```markdown
-[Super Block Entity Behaviours](./Super Behaviours/Super Behaviours.md)
-[Kinetic Extension](./Kinetic Extension.md)
-[back to overview](./Super Behaviours.md#extensions)
+[Super Block Entity Behaviours](./Super%20Behaviours/Super%20Behaviours.md)
+[Kinetic Extension](./docs/Super%20Behaviours/Extensions/Kinetic%20Extension.md)
+[back to overview](./Super%20Behaviours.md#extensions)
 ```
 
 For anchor fragments, use lowercase with hyphens (VitePress converts `## Extensions` `#extensions`).
 
-
 ## What to avoid
 
 - **Horizontal rules (`---`)** don't use them. Section headings already provide visual separation; `---` just adds noise.