7 files changed, 51 insertions, 44 deletions
diff --git a/docs/reference/src/SUMMARY.md b/docs/reference/src/SUMMARY.md
index b88cb6b8..4816be30 100644
--- a/docs/reference/src/SUMMARY.md
+++ b/docs/reference/src/SUMMARY.md
@@ -1,7 +1,5 @@
 # Summary
 
-- [Chapter 1](./chapter_1.md)
-
 - [Overview](./overview/index.md)
 
   - [RAW mode](./overview/raw.md)
@@ -51,11 +49,11 @@
     - [nng_msg_set_pipe](msg/nng_msg_set_pipe.md)
     - [nng_msg_trim](msg/nng_msg_trim.md)
 
-  - [Sockets](api/socket/index.md)
+  - [Sockets](sock/index.md)
 
-    - [nng_bus_open](api/socket/nng_bus_open.md)
-    - [nng_close](api/socket/nng_close.md)
-    - [nng_pub_open](api/socket/nng_pub_open.md)
+    - [nng_bus_open](sock/nng_bus_open.md)
+    - [nng_close](sock/nng_close.md)
+    - [nng_pub_open](sock/nng_pub_open.md)
 
   - [Contexts](ctx/index.md)
 
diff --git a/docs/reference/src/api/socket/index.md b/docs/reference/src/api/socket/index.md
deleted file mode 100644
index f9a85b23..00000000
--- a/docs/reference/src/api/socket/index.md
+++ /dev/null
@@ -1,7 +0,0 @@
-# Sockets
-
-## See Also
-
-[nng_bus_open](nng_bus_open.md)
-[nng_close](nng_close.md)
-[nng_pub_open](nng_pub_open.md)
diff --git a/docs/reference/src/refs.md b/docs/reference/src/refs.md
index 47071a0a..4c954596 100644
--- a/docs/reference/src/refs.md
+++ b/docs/reference/src/refs.md
@@ -12,6 +12,7 @@
 [sockaddr_in6]: ../overview/sockaddr_in6.md
 [raw]: ../overview/raw.md
 [url]: ../overview/url.md
+[transport]: ../tran/index.md
 
 <!-- Protocols -->
 
@@ -26,20 +27,20 @@
 [sub]: ../proto/sub.md
 [surveyor]: ../proto/surveyor.md
 
-<!-- API -->
-
-[nng_bus_open]: ../api/nng_bus_open.md
-[nng_ctx_open]: ../api/nng_ctx_open.md
-[nng_pair_open]: ../api/nng_pair_open.md
-[nng_pub_open]: ../api/nng_pub_open.md
-[nng_pull_open]: ../api/nng_pull_open.md
-[nng_push_open]: ../api/nng_push_open.md
-[nng_rep_open]: ../api/nng_rep_open.md
-[nng_req_open]: ../api/nng_req_open.md
-[nng_respondent_open]: ../api/nng_respondent_open.md
-[nng_socket_set]: ../api/nng_socket_set.md
-[nng_surveyor_open]: ../api/nng_surveyor_open.md
-[nng_sub_open]: ../api/nng_sub_open.md
+<!-- Sockets -->
+
+[nng_bus_open]: ../sock/nng_bus_open.md
+[nng_pair_open]: ../sock/nng_pair_open.md
+[nng_pub_open]: ../sock/nng_pub_open.md
+[nng_pull_open]: ../sock/nng_pull_open.md
+[nng_push_open]: ../sock/nng_push_open.md
+[nng_rep_open]: ../sock/nng_rep_open.md
+[nng_req_open]: ../sock/nng_req_open.md
+[nng_respondent_open]: ../sock/nng_respondent_open.md
+[nng_socket_set]: ../sock/nng_socket_set.md
+[nng_surveyor_open]: ../sock/nng_surveyor_open.md
+[nng_sub_open]: ../sock/nng_sub_open.md
+[nng_close]: ../sock/nng_close.md
 
 <!-- Messages -->
 
diff --git a/docs/reference/src/sock/index.md b/docs/reference/src/sock/index.md
new file mode 100644
index 00000000..d90a4fb9
--- /dev/null
+++ b/docs/reference/src/sock/index.md
@@ -0,0 +1,9 @@
+# Sockets
+
+## See Also
+
+[nng_bus_open][nng_bus_open]
+[nng_close][nng_close]
+[nng_pub_open][nng_pub_open]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/api/socket/nng_bus_open.md b/docs/reference/src/sock/nng_bus_open.md
index 3eb235e3..8705ad6f 100644
--- a/docs/reference/src/api/socket/nng_bus_open.md
+++ b/docs/reference/src/sock/nng_bus_open.md
@@ -17,12 +17,12 @@ int nng_bus0_open_raw(nng_socket *s);
 
 ## DESCRIPTION
 
-The `nng_bus0_open()` function creates a [_BUS_](../../protocols/bus.md) version 0
-[socket](index.md) and returns it at the location pointed to by _s_.
+The `nng_bus0_open()` function creates a [_BUS_][bus] version 0
+[socket][socket] and returns it at the location pointed to by _s_.
 
-The `nng_bus0_open_raw()` function creates a [_BUS_](../../protocols/bus.md) version 0
-[socket](index.md) in
-[raw](../overview/raw.md) mode, and returns it at the location pointed to by _s_.
+The `nng_bus0_open_raw()` function creates a [_BUS_][bus] version 0
+[socket][socket] in
+[raw mode][raw], and returns it at the location pointed to by _s_.
 
 ## RETURN VALUES
 
@@ -35,5 +35,7 @@ These functions return 0 on success, and non-zero otherwise.
 
 ## SEE ALSO
 
-[BUS protocol](../../protocols/bus.md),
-[RAW mode](../../overview/raw.md)
+[BUS protocol][bus],
+[RAW mode][raw]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/api/socket/nng_close.md b/docs/reference/src/sock/nng_close.md
index fded0357..649316bd 100644
--- a/docs/reference/src/api/socket/nng_close.md
+++ b/docs/reference/src/sock/nng_close.md
@@ -14,9 +14,9 @@ int nng_close(nng_socket s);
 
 ## DESCRIPTION
 
-The `nng_close()` function closes the supplied socket, _s_.
+The `nng_close()` function closes the [socket][socket] _s_.
 Messages that have been submitted for sending may be flushed or delivered,
-depending upon the transport.
+depending upon the [transport][transport].
 
 Further attempts to use the socket after this call returns will result
 in `NNG_ECLOSED`.
@@ -29,7 +29,7 @@ call is executed may also return with an `NNG_ECLOSED` result.
 > There is no automatic linger or flush to ensure that the socket send buffers
 > have completely transmitted.
 > It is recommended to wait a brief period after calling
-> [`nng_send()`](nng_send.md) or similar functions, before calling this
+> [`nng_send()`][nng_send] or similar functions, before calling this
 > function.
 
 ## RETURN VALUES
@@ -39,3 +39,5 @@ This function returns 0 on success, and non-zero otherwise.
 ## ERRORS
 
 - `NNG_ECLOSED`: The socket _s_ is already closed or was never opened.
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/api/socket/nng_pub_open.md b/docs/reference/src/sock/nng_pub_open.md
index 18321896..0100cfcb 100644
--- a/docs/reference/src/api/socket/nng_pub_open.md
+++ b/docs/reference/src/sock/nng_pub_open.md
@@ -2,7 +2,7 @@
 
 ## NAME
 
-nng*pub_open --- create \_PUB* socket
+nng_pub_open --- create _PUB_ socket
 
 ## SYNOPSIS
 
@@ -15,14 +15,14 @@ int nng_pub0_open(nng_socket *s);
 int nng_pub0_open_raw(nng_socket *s);
 ```
 
-== DESCRIPTION
+## DESCRIPTION
 
-The `nng_pub0_open()` function creates a [_PUB_](../../protocols/pub.md) version 0
-[socket](index.md) and returns it at the location pointed to by _s_.
+The `nng_pub0_open()` function creates a [_PUB_][pub] version 0
+[socket][socket] and returns it at the location pointed to by _s_.
 
-The `nng_pub0_open_raw()` function creates a [_PUB_](../../protocols/pub.md) version 0
-[socket](index.md) in
-[raw](../../overview/raw.md) mode and returns it at the location pointed to by _s_.
+The `nng_pub0_open_raw()` function creates a [_PUB_][pub] version 0
+[socket][socket] in
+[raw mode][raw] and returns it at the location pointed to by _s_.
 
 ## RETURN VALUES
 
@@ -37,3 +37,5 @@ These functions return 0 on success, and non-zero otherwise.
 
 [PUB Protocol](../../protocols/pub.md),
 [SUB Protocol](../../protocols/sub.md)
+
+{{#include ../refs.md}}