diff --git a/docs/README.md b/docs/README.md
index 99d635bb33..886363dccc 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -7,8 +7,8 @@
 - [glossary.md](glossary.md) — Glossary of all the terms used in codebase.
 - [multitenancy.md](multitenancy.md) — how multitenancy is organized in the pageserver and Zenith CLI.
 - [sourcetree.md](sourcetree.md) — Overview of the source tree layeout.
-- [pageserver/README](/pageserver/README) — pageserver overview.
-- [postgres_ffi/README](/libs/postgres_ffi/README) — Postgres FFI overview.
+- [pageserver/README.md](/pageserver/README.md) — pageserver overview.
+- [postgres_ffi/README.md](/libs/postgres_ffi/README.md) — Postgres FFI overview.
 - [test_runner/README.md](/test_runner/README.md) — tests infrastructure overview.
-- [safekeeper/README](/safekeeper/README) — WAL service overview.
+- [safekeeper/README.md](/safekeeper/README.md) — WAL service overview.
 - [core_changes.md](core_changes.md) - Description of Zenith changes in Postgres core
diff --git a/docs/sourcetree.md b/docs/sourcetree.md
index 5fd5fe19e5..5ddc6208d2 100644
--- a/docs/sourcetree.md
+++ b/docs/sourcetree.md
@@ -28,7 +28,7 @@ The pageserver has a few different duties:
 - Receive WAL from the WAL service and decode it.
 - Replay WAL that's applicable to the chunks that the Page Server maintains
 
-For more detailed info, see `/pageserver/README`
+For more detailed info, see [/pageserver/README](/pageserver/README.md)
 
 `/proxy`:
 
@@ -57,7 +57,7 @@ PostgreSQL extension that contains functions needed for testing and debugging.
 The zenith WAL service that receives WAL from a primary compute nodes and streams it to the pageserver.
 It acts as a holding area and redistribution center for recently generated WAL.
 
-For more detailed info, see `/safekeeper/README`
+For more detailed info, see [/safekeeper/README](/safekeeper/README.md)
 
 `/workspace_hack`:
 The workspace_hack crate exists only to pin down some dependencies.
diff --git a/libs/postgres_ffi/README b/libs/postgres_ffi/README.md
similarity index 100%
rename from libs/postgres_ffi/README
rename to libs/postgres_ffi/README.md
diff --git a/safekeeper/README b/safekeeper/README.md
similarity index 99%
rename from safekeeper/README
rename to safekeeper/README.md
index 4407837463..3f097d0c24 100644
--- a/safekeeper/README
+++ b/safekeeper/README.md
@@ -7,6 +7,7 @@ replica. A replication slot is used in the primary to prevent the
 primary from discarding WAL that hasn't been streamed to the WAL
 service yet.
 
+```
 +--------------+              +------------------+
 |              |     WAL      |                  |
 | Compute node |  ----------> |   WAL Service    |
@@ -23,7 +24,7 @@ service yet.
                               | Pageservers  |
                               |              |
                               +--------------+
-
+```
 
 
 The WAL service consists of multiple WAL safekeepers that all store a
@@ -31,6 +32,7 @@ copy of the WAL. A WAL record is considered durable when the majority
 of safekeepers have received and stored the WAL to local disk. A
 consensus algorithm based on Paxos is used to manage the quorum.
 
+```
   +-------------------------------------------+
   | WAL Service                               |
   |                                           |
@@ -48,7 +50,7 @@ consensus algorithm based on Paxos is used to manage the quorum.
   |  +------------+                           |
   |                                           |
   +-------------------------------------------+
-
+```
 
 The primary connects to the WAL safekeepers, so it works in a "push"
 fashion.  That's different from how streaming replication usually