Add titles to most pages, fix links

Signed-off-by: Robert Detjens <github@detjens.dev>

Author: detjensrobert

docs/.vitepress/config.mts

@@ -8,8 +8,15 @@ export default defineConfig({
   themeConfig: {
     // https://vitepress.dev/reference/default-theme-config
     nav: [
-      { text: "Home", link: "/" },
-      // { text: "Examples", link: "/markdown-examples" },
+      { text: "Setup", link: "for-sysadmins/quickstart" },
+      {
+        text: "Config Reference",
+        link: "for-sysadmins/config-reference",
+      },
+      {
+        text: "Challenge Reference",
+        link: "for-authors/challenge-reference",
+      },
     ],
 
     // auto generate sidebar from directory structure, via vitepress-sidebar
@@ -19,10 +26,14 @@ export default defineConfig({
       useTitleFromFileHeading: true,
       useTitleFromFrontmatter: true,
       keepMarkdownSyntaxFromTitle: true,
+      useFolderTitleFromIndexFile: true,
       // transform name to sentence case
       hyphenToSpace: true,
       underscoreToSpace: true,
-      capitalizeEachWords: true,
+      // capitalizeEachWords: true,
+
+      sortFolderTo: "bottom",
+      sortMenusByFrontmatterOrder: true,
     }),
 
     socialLinks: [

docs/for-authors/challenge-reference.md

@@ -1,4 +1,8 @@
-# Challenge Config Reference
+---
+title: <code>challenge.yaml</code> Reference
+---
+
+# `challenge.yaml` Config Reference
 
 Challenge configuration is expected to be at `<category>/<name>/challenge.yaml`.
 

docs/for-authors/index.md

@@ -0,0 +1,3 @@
+---
+title: For Challenge Authors
+---

docs/for-authors/quickstart.md

@@ -1,16 +1,25 @@
-# Challenge Config Quickstart
+# Challenge Quickstart
 
 All information about a challenge is configured in a `challenge.yaml` in the
 challenge's directory in the repo, generally `<category>/<name>`.
 
-For a tldr: see a full example for  [a TCP/`nc` challenge](#full-tcp-example) or [a web challenge](#full-http-example).
+There are a few [complete examples](#examples) at the bottom of the page.
 
-### Metadata
+### Name
 
-Self explanatory.
+The challenge name can contain any characters, though whitespace or special
+characters may be removed in some cases.
 
 ```yaml
 name: yet another pyjail
+```
+
+### Author
+
+The author or authors that created this challenge. Multiple authors are not
+handled
+
+```yaml
 author: somebody, John Author
 ```
 
@@ -152,15 +161,15 @@ description: |-
 
   {{ nc }}
 
+flag:
+  file: ./flag
+
 provide:
   - from: main
     include:
       - /chal/notsh
       - /lib/x86_64-linux-gnu/libc.so.6
 
-flag:
-  file: ./flag
-
 pods:
   - name: main
     build: .
@@ -199,3 +208,22 @@ pods:
         expose:
           http: bar # subdomain only
 ```
+
+## Full static file example
+
+```yaml
+name: ghostint
+author: the guessers geo
+description: |
+  where was this picture taken?
+
+  flag format: `example{LAT__LONG}`, rounded to five places
+
+difficulty: 1
+
+flag:
+  string: "example{51.51771__-0.20495}"
+
+provide:
+  - the-view-from-your-balcony.png
+```

docs/repo-structure.md renamed to docs/for-sysadmins/challenge-repo-structure.md

@@ -1 +1,3 @@
+# Challenge Repo Structure
+
 expected layout of challenges repo

docs/for-sysadmins/config-reference.md

@@ -0,0 +1,11 @@
+---
+title: <code>rcds.yaml</code> Reference
+---
+
+# `rcds.yaml`
+
+`rcds.yaml` is the 'global' config for beaverCDS. This defines what challenges
+are available, where to deploy them to, and what credentials to use for building
+and deploying them.
+
+This will always be at `/rcds.yaml` in the challenges repository.

docs/for-sysadmins/config.md

@@ -0,0 +1,3 @@
+---
+title: For Sysadmins
+---