[docs] add reference section

apps/site/src/components/ReferenceTableRow.tsx

@@ -0,0 +1,39 @@
+import styled from '@emotion/styled';
+import { NospaceIR } from '@repo/parser';
+import { useMemo } from 'react';
+
+const CodeBlock = styled.code`
+  white-space: pre-wrap;
+`;
+
+export type ReferenceTableRowProps = {
+  command: string;
+  link: string;
+};
+
+export default function ReferenceTableRow({
+  command,
+  link,
+}: ReferenceTableRowProps) {
+  const [ns, ws] = useMemo(() => {
+    const ir = NospaceIR.fromNossembly(command);
+    return [ir.toNospace(), ir.toWhitespace()];
+  }, [command]);
+
+  return (
+    <tr>
+      <td>
+        <a href={link}>{command}</a>
+      </td>
+      <td>
+        <code>{ns}</code>
+      </td>
+      <td>
+        <CodeBlock>{ws}</CodeBlock>
+      </td>
+      <td>
+        <code>{command}</code>
+      </td>
+    </tr>
+  );
+}

apps/site/src/components/SyntaxTable.tsx

@@ -0,0 +1,83 @@
+import styled from '@emotion/styled';
+import { NospaceIR } from '@repo/parser';
+import { useMemo } from 'react';
+
+const CodeBlock = styled.code`
+  white-space: pre-wrap;
+`;
+
+export type SyntaxTableProps = {
+  command: string;
+  inter?: string;
+};
+
+export default function SyntaxTable({ command, inter }: SyntaxTableProps) {
+  const [ns, ws] = useMemo(() => {
+    const ir = inter ? undefined : NospaceIR.fromNossembly(command);
+    const nospace = inter
+      ? inter
+          .replace(/s/g, '\u200B')
+          .replace(/t/g, '\u200C')
+          .replace(/n/g, '\u200D')
+          .replace(/x/g, '\u2060')
+      : ir!.toNospace();
+    const whitespace = inter
+      ? inter.replace(/s/g, ' ').replace(/t/g, '\t').replace(/n/g, '\n')
+      : ir!.toWhitespace();
+    return [nospace, inter?.includes('x') ? undefined : whitespace];
+  }, [command]);
+
+  return (
+    <table>
+      <tr>
+        <th></th>
+        <th>Command</th>
+        <th>Unobsfucated</th>
+      </tr>
+      <tr>
+        <td>Nospace</td>
+        <td>
+          <code>{ns}</code>
+        </td>
+        <td>
+          {ns.split('').map((x, i) => (
+            <>
+              {i !== 0 && ', '}
+              <code key={i}>
+                {x
+                  .replace(/\u200B/g, 'ZWSP')
+                  .replace(/\u200C/g, 'ZWNJ')
+                  .replace(/\u200D/g, 'ZWJ')
+                  .replace(/\u2060/g, 'WJ')}
+              </code>
+            </>
+          ))}
+        </td>
+      </tr>
+      <tr>
+        <td>Whitespace</td>
+        <td>{ws ? <CodeBlock>{ws + '\n'}</CodeBlock> : '-'}</td>
+        <td>
+          {ws
+            ? ns.split('').map((x, i) => (
+                <>
+                  {i !== 0 && ', '}
+                  {x
+                    .replace(/\u200B/g, 'Space')
+                    .replace(/\u200C/g, 'Tab')
+                    .replace(/\u200D/g, 'Newline')}
+                </>
+              ))
+            : '-'}
+        </td>
+      </tr>
+      <tr>
+        <td>Nossembly</td>
+        <td>
+          <code>{command}</code>
+        </td>
+        <td>-</td>
+      </tr>
+    </table>
+  );
+}

apps/site/src/components/navbar.astro

@@ -54,6 +54,10 @@ import Icon from './icon.astro';
     margin: -20px;
     padding: 20px;
   }
+
+  .nav-link:hover {
+    color: #eee;
+  }
 </style>
 
 <nav>

apps/site/src/content/docs/Getting Started/Intro for Whitespace Programmers.mdx

@@ -1,6 +1,7 @@
 ---
-title: Nospace for WS Programmers
+title: Nospace for Whitespace Programmers
 sidebar:
+  label: Nospace for WS Programmers
   order: 1
 ---
 import Example from '../../../components/Example.tsx';
@@ -23,7 +24,7 @@ Nospace extends the syntax of Whitespace, adding aliasing of Whitespace characte
 
 In addition, a fourth character—the word joiner (WJ; `U+2060`; `⁠`)—is added to the syntax which is used to namespace Nospace-specific type commands.
 
-## Type System
+## Using Types
 
 ### Types by Inference
 
@@ -128,15 +129,15 @@ When type checking, Nospace uses these values to determine whether an operation
 
 ## Heap Typing
 
-Nospace does not currently type any values on the heap. This limitation is due to Whitespace's ability to allow arbitrary writes to the heap (for example based on a user's input at runtime). In practice this means that when reading off of the heap, developers should take care to cast the value back to a known type to ensure consistency.
+Nospace does not currently type any values on the heap. This limitation is due to Whitespace's ability to write to arbitrary heap addresses (for example based on a user's input at runtime). In practice this means that when reading off of the heap, developers should take care to cast the value back to a known type to ensure consistency.
 
 ## Stack Underflows
 
 In addition to types, Nospace is also able to detect certain situations in which stack underflows will occur. For example, performing `Pop` on an empty stack will result in a compile-time error:
 
 <Example client:load="react" languages={["Nospace", "Nossembly"]} example={`Pop`} error="TypeError: Cannot perform pop as this would result in a stack underflow." />
 
-There are examples which Nospace will not warn about which may seem surprising at first, for example consider this program which recursively `Pop`s items off the stack:
+There are situations in which underflows will occur but Nospace will not warn about which may seem surprising at first, for example consider this program which recursively `Pop`s items off the stack:
 
 <Example client:load="react" languages={["Nospace", "Nossembly"]} example={`Push 1
 

apps/site/src/content/docs/Reference/Quick reference.mdx

@@ -0,0 +1,43 @@
+---
+title: Quick Reference
+sidebar:
+  order: 20
+---
+import ReferenceTableRow from '../../../components/ReferenceTableRow.tsx';
+
+This page features a quick reference of all Nospace commands in the one place. You can click into each command for more details.
+
+<table>
+  <tr>
+    <th>Command name</th>
+    <th>Nospace syntax</th>
+    <th>Whitespace syntax</th>
+    <th>Nossembly syntax</th>
+  </tr>
+  <ReferenceTableRow command="Add" link="/reference/arithmetic#addition" />
+  <ReferenceTableRow command="Assert" link="/reference/types#assert" />
+  <ReferenceTableRow command="Call" link="/reference/control-flow#call" />
+  <ReferenceTableRow command="Cast" link="/reference/types#cast" />
+  <ReferenceTableRow command="Copy" link="/reference/stack#copy" />
+  <ReferenceTableRow command="Divide" link="/reference/arithmetic#integer-division" />
+  <ReferenceTableRow command="Duplicate" link="/reference/stack#duplicate" />
+  <ReferenceTableRow command="End" link="/reference/control-flow#end" />
+  <ReferenceTableRow command="Jump" link="/reference/control-flow#jump" />
+  <ReferenceTableRow command="JumpNegative" link="/reference/control-flow#jumpnegative" />
+  <ReferenceTableRow command="JumpZero" link="/reference/control-flow#jumpzero" />
+  <ReferenceTableRow command="Label" link="/reference/control-flow#label" />
+  <ReferenceTableRow command="Mod" link="/reference/arithmetic#modulo" />
+  <ReferenceTableRow command="Multiply" link="/reference/arithmetic#multiplication" />
+  <ReferenceTableRow command="Pop" link="/reference/stack#pop" />
+  <ReferenceTableRow command="Push" link="/reference/stack#push" />
+  <ReferenceTableRow command="ReadChar" link="/reference/io#readchar" />
+  <ReferenceTableRow command="ReadInt" link="/reference/io#readint" />
+  <ReferenceTableRow command="Retrieve" link="/reference/heap#retrieve" />
+  <ReferenceTableRow command="Return" link="/reference/control-flow#return" />
+  <ReferenceTableRow command="Slide" link="/reference/stack#slide" />
+  <ReferenceTableRow command="Store" link="/reference/heap#store" />
+  <ReferenceTableRow command="Subtract" link="/reference/arithmetic#subtraction" />
+  <ReferenceTableRow command="Swap" link="/reference/stack#swap" />
+  <ReferenceTableRow command="WriteChar" link="/reference/io#writechar" />
+  <ReferenceTableRow command="WriteInt" link="/reference/io#writeint" />
+</table>

apps/site/src/content/docs/Reference/arithmetic.mdx

@@ -0,0 +1,138 @@
+---
+title: Arithmetic
+---
+import Example from '../../../components/Example.tsx';
+import SyntaxTable from '../../../components/SyntaxTable.tsx';
+
+All artithmetic commands use the `‌​` prefix and operate on two items in the stack. The second from top (first pushed) item is considered to be to the left of the operator, and top item (last pushed) is to the right of the operator.
+
+## Integer Literals
+
+Integers are expressed in Nospace as a binary squence of `​` and `‌`s (representing `0` and `1` respectively)
+prefixed by a `​` or `‌` indicating signedness (`+` and `-` respectievly) and terminated by a `‍`. For example, the number `518929412845` is represented as `​‌‌‌‌​​​‌‌​‌​​‌​‌​​‌‌​‌​​‌‌‌​​‌​‌‌‌​‌‌​‌‍`.
+
+## Addition
+
+The addition command takes two numbers from the top of the stack, adds them together, and pushes the result back to the stack.
+
+### Syntax
+
+<SyntaxTable command="Add" />
+
+### Parameters
+
+The addition command takes no parameters
+
+### Stack parameters
+
+The following parameters should be pushed in the order expressed below:
+
+- `Int` representing the left hand side of the operator
+- `Int` representing the right hand side of the operator
+
+### Example
+
+<Example client:load="react" example={`Push 1
+Push 2
+Add`}/>
+
+## Subtraction
+
+The subtract command takes two numbers from the top of the stack, subtracts the one pushed last, and pushes the result back to the stack.
+
+### Syntax
+
+<SyntaxTable command="Subtract" />
+
+
+### Parameters
+
+The subtract command takes no parameters
+
+### Stack parameters
+
+The following parameters should be pushed in the order expressed below:
+
+- `Int` representing the left hand side of the operator
+- `Int` representing the right hand side of the operator
+
+### Example
+
+<Example client:load="react" example={`Push 2
+Push 1
+Subtract`}/>
+
+## Multiplication
+
+The multiplication command takes two numbers from the top of the stack, multiplies them, and pushes the result back to the stack.
+
+### Syntax
+
+<SyntaxTable command="Multiply" />
+
+### Parameters
+
+The multiplication command takes no parameters
+
+### Stack parameters
+
+The following parameters should be pushed in the order expressed below:
+
+- `Int` representing the left hand side of the operator
+- `Int` representing the right hand side of the operator
+
+### Example
+
+<Example client:load="react" example={`Push 5
+Push 6
+Multiply`}/>
+
+## Integer Division
+
+The integer division command takes two numbers from the top of the stack, divides the item pushed last from the one pushed first, and pushes the result back to the stack.
+
+### Syntax
+
+<SyntaxTable command="Divide" />
+
+### Parameters
+
+The integer division command takes no parameters
+
+### Stack parameters
+
+The following parameters should be pushed in the order expressed below:
+
+- `Int` representing the left hand side of the operator
+- `Int` representing the right hand side of the operator
+
+### Example
+
+<Example client:load="react" example={`Push 15
+Push 3
+Divide`}/>
+
+## Modulo
+
+The modulo command takes two numbers from the top of the stack, multiplies them, and pushes the result back to the stack.
+
+### Syntax
+
+<SyntaxTable command="Mod" />
+
+### Parameters
+
+The modulo command takes no parameters
+
+### Stack parameters
+
+The following parameters should be pushed in the order expressed below:
+
+- `Int` representing the left hand side of the operator
+- `Int` representing the right hand side of the operator
+
+### Example
+
+<Example client:load="react" example={`Push 5
+Push 7
+Mod`}/>