Merge branch 'master' of github.com:space-wizards/docs

.github/workflows/mdBook.yml → .github/workflows/deploy.yml

@@ -1,4 +1,4 @@
-name: Build mdBook Site & Deploy if Necessary
+name: Build & Deploy mdBook Site
 
 on:
   # Run on all pushes -- we check for only running on deploy later

.github/workflows/test.yml

@@ -0,0 +1,28 @@
+name: Test mdBook Build & Upload Artifact
+
+on:
+  # Run on only PR, no gh pages stuff
+  pull_request:
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Install Rust
+        run: |
+          curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf -y | sh
+          rustup update
+      - name: Install mdbook & plugins
+        uses: taiki-e/[email protected]
+        with:
+          tool: [email protected],[email protected],[email protected],[email protected],[email protected]
+      - name: Build with mdBook
+        run: mdbook build
+      - name: Upload artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: Built Site
+          path: ./book/html
+          retention-days: 3

.vscode/launch.json

@@ -0,0 +1,16 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Launch localhost",
+            "type": "firefox",
+            "request": "launch",
+            "reAttach": true,
+            "url": "http://localhost:3000/index.html",
+            "webRoot": "${workspaceFolder}/book"
+        },
+    ]
+}

README.md

@@ -1,6 +1,6 @@
 # Space Wizards Development Wiki
 
-This is a port of the old SS14 Wiki.js documentation to `mdbook`, for the following benefits:
+This is a work-in-progress port of the old SS14 Wiki.js documentation to `mdbook`, for the following benefits:
 - First-class git support, open source and actually editable by everyone
 - No webshit bloat, much faster in general
 - More familiar & comfortable for developers since `mdbook` use is very widespread
@@ -17,35 +17,9 @@ The following `mdbook` features & plugins are available and in use:
 - `mdbook-template`
 - `mdbook-admonish`
 
-Eventually this will be hosted on GitHub pages but not right now im lazy
+The site is currently hosted at [https://spacestation14.io/docs/](https://spacestation14.io/docs/). This will likely change in the future, so links here should not be relied on.
 
-## Building
-
-Necessary dependencies are Rust, as well as `mdbook` and the plugins listed above, installed using cargo.
-
-Call `mdbook serve` to build and locally host the documentation from the `book` directory.
-
-## Contributing & porting pages
-
-To port a page, you'll need write access to `docs.spacestation14.io` (old wiki.js), or find some way to view MD source idk.
-
-1. Find a page with the `Porting` template on the top
-2. Find the corresponding page in Wiki.js -- it should just have the same name 
-3. Copy over the Wiki.js markdown
-4. Change any relative links to point to their correct corresponding
-5. Change any self-hosted or imgur images to be hosted in `src/en/assets` instead
-6. Adjust any admonishments as follows:
-    ``````
-    > etc text example
-    {.is-(danger/warning/info/example)}
-    ``````
-    to
-    ``````
-    ```admonish danger/warning/info/example "Title Text Or Leave blank etc"
-    etc text example
-    ```
-    ``````
-7. Add a redirect for the original wiki.js link to the new `src/SUMMARY.md` link in `book.toml`--follow the example
+**For information such as how to edit, build & test these docs, see [Guide to Editing Docs](https://spacestation14.io/docs/en/meta/guide-to-editing-docs.html). on the site itself** (or [in this repo](./src/en/meta/guide-to-editing-docs.md))
 
 ## Screenshots
 
@@ -55,4 +29,4 @@ To port a page, you'll need write access to `docs.spacestation14.io` (old wiki.j
 
 ## License
 
-The Space Wizards Development Wiki is released under the Mozilla Public License v2.0.
+The Space Wizards Development Wiki is released under the Mozilla Public License v2.0.

book.toml

@@ -15,13 +15,14 @@ assets_version = "2.0.2" # do not edit: managed by `mdbook-admonish install`
 before = ["mermaid", "admonish"] # templates can include these so we run this first
 
 [output.html]
-additional-js = ['scripts/mermaid.min.js', 'scripts/mermaid-init.js', 'scripts/sidebar.js']
-additional-css = ['theme/mdbook-admonish.css', 'theme/ss14.css', 'theme/sidebar-style.css']
+additional-js = ['scripts/mermaid.min.js', 'scripts/mermaid-init.js', 'scripts/nav-additions.js']
+additional-css = ['theme/mdbook-admonish.css', 'theme/ss14.css', 'theme/nav-style.css']
 default-theme = "navy"
 preferred-dark-theme = "navy"
 
 git-repository-url = "https://github.com/space-wizards/space-station-14"
 edit-url-template = "https://github.com/space-wizards/docs/blob/master/{path}"
+site-url = "/docs/" # remove when we move to docs.ss14.io -- needed for 404 pages to render properly in subdirectories
 
 mathjax-support = true
 curly-quotes = true
@@ -42,7 +43,43 @@ traverse-parent-directories = false
 warning-policy = "ignore" # false-positives like hell with absolute links & latex, so.. cant do
 
 # Redirects
+# These are used to map between old Wiki.js links and current docs site links,
+# so we can avoid the hell that was dead links with the old hackmd transfer.
+# Wiki.js doesn't have `.html` endings on files, so we hack it by putting /index.html
+# and just letting the browser look there, then get redirected
 [output.html.redirect]
-"/en/getting-started/how-do-i-code" = "en/general-development/setup/howdoicode.md"
-"/en/getting-started/dev-setup" = "en/general-development/setup/setting-up-a-development-environment.md"
-"/en/getting-started/git" = "en/general-development/setup/git-for-the-ss14-developer.md"
+"/en/getting-started/how-do-i-code/index.html" = "en/general-development/setup/howdoicode.html"
+"/en/getting-started/dev-setup/index.html" = "en/general-development/setup/setting-up-a-development-environment.html"
+"/en/getting-started/git/index.html" = "en/general-development/setup/git-for-the-ss14-developer.html"
+"/en/content/yaml/index.html" = "en/general-development/tips/yaml-crash-course.html"
+"/en/getting-started/pr-guideline/index.html" = "en/general-development/codebase-info/pull-request-guidelines.html"
+"/en/getting-started/conventions/index.html" = "/en/general-development/codebase-info/conventions.html"
+"/en/content/chemistry/index.html" = "/en/space-station-14/chemistry.html"
+"/en/content/writing-guidebook-entries/index.html" = "/en/general-development/tips/writing-guidebook-entries.html"
+"/en/content/device-network/index.html" = "/en/space-station-14/device-network.html"
+"/en/content/pow3r/index.html" = "/en/spcae-station-14/pow3r.html"
+# yes this one is correct
+"/en/content/construction/index/index.html" = "/en/space-station-14/construction.html"
+"/en/content/destructible/index.html" = "/en/space-station-14/destructible.html"
+"/en/administration/commands/index.html" = "/en/community/admin/admin-tooling/admin-command-cookbook.html"
+"/en/administration/tooling/index.html" = "/en/community/admin/admin-tooling.html"
+"/en/administration/policy/index.html" = "/en/community/admin/wizards-den-admin-policy.html"
+"/en/administration/banning-policy/index.html" = "/en/community/admin/wizards-den-banning-policy.html"
+"/en/getting-started/hosting/index.html" = "/en/general-development/setup/server-hosting-tutorial.html"
+"/en/hosting/replays/index.html" = "/en/server-hosting/server-replay-recording.html"
+"/en/hosting/changelogs/index.html" = "/en/server-hosting/setting-up-ss14-changelog.html"
+"/en/hosting/SS14-Admin/index.html" = "/en/server-hosting/setting-up-ss14-admin.html"
+"/en/hosting/robust-cdn/index.html" = "/en/server-hosting/setting-up-robust-cdn.html"
+"/en/technical-docs/acronyms-and-nomenclature/index.html" = "/en/general-development/codebase-info/acronyms-and-nomenclature.html"
+"/en/getting-started/engine-changes/index.html" = "/en/general-developmnet/codebase-info/prs-with-engine-changes.html"
+"/en/getting-started/debugging-tools/index.html" = "/en/general-development/tips/debugging-tools.html"
+"/en/getting-started/troubleshooting/index.html" = "/en/general-development/tips/troubleshooting-faq.html"
+"/en/config-reference/index.html" = "/en/general-development/tips/config-file-reference.html"
+"/en/technical-docs/codebase-organization/index.html" = "/en/general-development/codebase-info/codebase-organization.html"
+"/en/content/mapping/index.html" = "/en/space-station-14/mapping.html"
+"/en/content/mapping-sins/index.html" = "/en/space-station-14/mapping/mapping-sins.html"
+"/en/content/mapping-checklist/index.html" = "/en/space-station-14/mapping/mapping-checklist.html"
+"/en/content/dungeons/index.html" = "/en/space-station-14/dungeons.html"
+"/en/content/node-networks/index.html" = "/en/space-station-14/node-networks.html"
+"/en/content/NPCs/index.html" = "/en/space-station-14/npcs.html"
+"/en/content/cartridge-loader/index.html" = "/en/space-station-14/cartridge-loaders.html"

scripts/sidebar.js → scripts/nav-additions.js

@@ -22,20 +22,47 @@ var updateFunction = function() {
         el.classList.remove("active");
     });
 
+    if (id == undefined)
+        return;
+
     Array.prototype.forEach.call(document.getElementsByClassName("pagetoc")[0].children, function(el) {
         if (id.href.localeCompare(el.href) == 0) {
             el.classList.add("active");
         }
     });
 };
 
-// Populate sidebar on load
 window.addEventListener('load', function() {
+
+    /* Scroll the page index on the left to the current active page */
+    var active = document.querySelector(".chapter li a.active");
+    active.scrollIntoView({ behavior: "instant", block: "center", inline: "nearest" });
+
+    /* Populate subpage footer */
+
+    /* Get next sibling of active list element
+       then check if it has a nested ol
+       if so, this implies our current active element has nested subpages */
+    var nextListEl = active.parentElement.nextElementSibling;
+    var footer = document.getElementById("subpage-footer");
+    footer.style.display = "none";
+    if (nextListEl != null)
+    {
+        console.log(nextListEl);
+        var list = nextListEl.querySelector(".section")
+        if (list != null)
+        {
+            footer.style.display = "block";
+            footer.appendChild(list.cloneNode(true));
+        }
+    }
+
+    /* Populate pagetoc sidebar */
+
     var pagetoc = document.getElementsByClassName("pagetoc")[0];
     var elements = document.getElementsByClassName("header");
-
-    // don't show sidebar with only 1 header (or less)
-    if (elements.length <= 1)
+    // don't show pagetoc sidebar with less than 2 headers
+    if (elements.length < 2)
         return;
 
     Array.prototype.forEach.call(elements, function(el) {
@@ -53,6 +80,8 @@ window.addEventListener('load', function() {
             case "H4":
                 indent = "60px";
                 break;
+            case "H5":
+                indent = "80px";
             default:
                 break;
         }

src/SUMMARY.md

@@ -3,49 +3,50 @@ Space Wizards Development Wiki
 
 [The Robust Book](index.md)
 
-- [Links](en/links.md)
+Meta
+====
+
+----------------------
+
+- [Guide to Editing Docs](en/meta/guide-to-editing-docs.md)
+- [Docs Example Page](en/meta/docs-example-page.md)
+- [Docs are for Discoverability](en/meta/docs-are-for-discoverability.md)
 
 General Development
 ===================
 
 ----------------------
 
-- [Setup]()
+- [Setup](en/general-development/setup.md)
   - [How do I code?](en/general-development/setup/howdoicode.md)
   - [Setting up a Development Environment](en/general-development/setup/setting-up-a-development-environment.md)
   - [Git for the SS14 Developer](en/general-development/setup/git-for-the-ss14-developer.md)
-- [Codebase Info]()
+  - [Server Hosting Tutorial](en/general-development/setup/server-hosting-tutorial.md)
+- [Codebase Info](en/general-development/codebase-info.md)
   - [Conventions](en/general-development/codebase-info/conventions.md)
   - [Pull Request Guidelines](en/general-development/codebase-info/pull-request-guidelines.md)
   - [Codebase Organization](en/general-development/codebase-info/codebase-organization.md)
   - [Acronyms & Nomenclature](en/general-development/codebase-info/acronyms-and-nomenclature.md)
-- [Tips]()
-  - [Debugging](en/general-development/tips/debugging.md)
-  - [Troubleshooting](en/general-development/tips/troubleshooting.md)
+- [Tips](en/general-development/tips.md)
+  - [Troubleshooting FAQ](en/general-development/tips/troubleshooting-faq.md)
+  - [Debugging Tools](en/general-development/tips/debugging-tools.md)
   - [PRs With Engine Changes](en/general-development/tips/prs-with-engine-changes.md)
   - [Writing Guidebook Entries](en/general-development/tips/writing-guidebook-entries.md)
   - [Config File Reference](en/general-development/tips/config-file-reference.md)
   - [YAML Crash Course](en/general-development/tips/yaml-crash-course.md)
 
 
-Tutorials
-================
+SS14 By Example
+===============
 
 ----------------------
 
-- [Server Hosting](en/tutorials/server-hosting.md)
-  - [Port Forwarding](en/tutorials/server-hosting/port-forwarding.md)
-  - [Server Replay Recording](en/tutorials/server-hosting/server-replay-recording.md)
-  - [Setting up Robust.Cdn](en/tutorials/server-hosting/setting-up-robust-cdn.md)
-  - [Setting up SS14.Admin](en/tutorials/server-hosting/setting-up-ss14-admin.md)
-  - [Setting up SS14.Changelog](en/tutorials/server-hosting/setting-up-ss14-changelog.md)
-- [Super Simple 14](en/tutorials/super-simple-14.md)
-  - [Adding a Simple Bikehorn](en/tutorials/super-simple-14/adding-a-simple-bikehorn.md)
-  - [Making a Sprite Dynamic](en/tutorials/super-simple-14/making-a-sprite-dynamic.md)
-    - [Porting Appearance Visualizers](en/tutorials/super-simple-14/making-a-sprite-dynamic/porting-appearance-visualizers.md)
-  - [Basic Networking and You](en/tutorials/super-simple-14/basic-networking-and-you.md)
-  - [Fluent and Localization](en/tutorials/super-simple-14/fluent-and-localization.md)
-  - [UI Survival Guide](en/tutorials/super-simple-14/ui-survival-guide.md) 
+- [Adding a Simple Bikehorn](en/ss14-by-example/adding-a-simple-bikehorn.md)
+- [Making a Sprite Dynamic](en/ss14-by-example/making-a-sprite-dynamic.md)
+  - [Porting Appearance Visualizers](en/ss14-by-example/making-a-sprite-dynamic/porting-appearance-visualizers.md)
+- [Basic Networking and You](en/ss14-by-example/basic-networking-and-you.md)
+- [Fluent and Localization](en/ss14-by-example/fluent-and-localization.md)
+- [UI Survival Guide](en/ss14-by-example/ui-survival-guide.md) 
 
 
 Robust Toolbox
@@ -96,6 +97,10 @@ Space Station 14
   - [Mapping Checklist](en/space-station-14/mapping/mapping-checklist.md)
   - [Mapping Sins](en/space-station-14/mapping/mapping-sins.md)
 - [Chemistry](en/space-station-14/chemistry.md)
+  - [Solution Containers](en/space-station-14/chemistry/solution-containers.md)
+  - [Reagents](en/space-station-14/chemistry/reagents.md)
+  - [Metabolism](en/space-station-14/chemistry/metabolism.md)
+  - [Reactions](en/space-station-14/chemistry/reactions.md)
 - [Construction](en/space-station-14/construction.md)
 - [Destructible](en/space-station-14/destructible.md)
 - [Device Network](en/space-station-14/device-network.md)
@@ -105,6 +110,17 @@ Space Station 14
 - [Dungeons](en/space-station-14/dungeons.md)
 - [NPCs](en/space-station-14/npcs.md)
 
+Server Hosting
+==============
+
+----------------------
+
+- [Port Forwarding](en/server-hosting/port-forwarding.md)
+- [Server Replay Recording](en/server-hosting/server-replay-recording.md)
+- [Setting up Robust.Cdn](en/server-hosting/setting-up-robust-cdn.md)
+- [Setting up SS14.Admin](en/server-hosting/setting-up-ss14-admin.md)
+- [Setting up SS14.Changelog](en/server-hosting/setting-up-ss14-changelog.md)
+
 Other Projects
 ==============
 
@@ -113,30 +129,30 @@ Other Projects
 - [Launcher]()
   - [Content Bundles](en/other-projects/launcher/content-bundles.md)
   - [Delta Updates & Manifests](en/other-projects/launcher/delta-updates-and-manifests.md)
+- [SpaceWizards Lidgren]()
 
 Specifications
 ==============
 
 ----------------------
 
-- [RSI](en/specifications/rsi.md)
+- [Robust Station Image](en/specifications/robust-station-image.md)
+- [Robust Generic Attribution](en/specifications/robust-generic-attribution.md)
 
 Community
 ========================
 
 ----------------------
 
-- [Infrastructure References]()
+- [Infrastructure References](en/community/infrastructure-references.md)
   - [Wizards Den Infrastructure](en/community/infrastructure-reference/wizards-den-infrastructure.md)
   - [Publishing Scripts](en/community/infrastructure-reference/publishing-scripts.md)
   - [Grafana Dashboards](en/community/infrastructure-reference/grafana-dashboards.md)
 - [Space Wizards Hub Rules](en/community/space-wizards-hub-rules.md)
 - [Space Wizards Role Hierarchy](en/community/space-wizards-role-hierarchy.md)
 - [Discord Rich Presence Repository](en/community/discord-rich-presence-repository.md)
-
-Miscellaneous
-=============
-
-----------------------
-
-- [Test Page](en/miscellaneous/test_page.md)
+- [Admin](en/community/admin.md)
+  - [Admin Tooling](en/community/admin/admin-tooling.md)
+    - [Admin Command Cookbook](en/community/admin/admin-tooling/admin-command-cookbook.md)
+  - [Wizards Den Admin Policy](en/community/admin/wizards-den-admin-policy.md)
+  - [Wizards Den Banning Policy](en/community/admin/wizards-den-banning-policy.md)