diff --git a/api/machines/index.mdx b/api/machines/index.mdx
index 411cc4dc9c..3c463f16fc 100644
--- a/api/machines/index.mdx
+++ b/api/machines/index.mdx
@@ -1,5 +1,6 @@
---
-title: Overview
+title: "Machines API overview"
+sidebarTitle: "Overview"
icon: book-open
---
diff --git a/blueprints/review-apps-guide.mdx b/blueprints/review-apps-guide.mdx
index b501b0b06c..07cf991934 100644
--- a/blueprints/review-apps-guide.mdx
+++ b/blueprints/review-apps-guide.mdx
@@ -6,7 +6,7 @@ source_url: https://fly.io/docs/blueprints/review-apps-guide/
-# Overview
+## Overview
Review apps are a great way to preview new features, changes, and bug fixes. This guide will teach you how to automatically generate ephemeral "review apps" on Fly.io for each pull request (PR) using GitHub Actions. This approach can be applied to other Git services and source code versioning software that supports branching and hooks.
diff --git a/machines/api/machines-resource.mdx b/machines/api/machines-resource.mdx
index a0915eab1f..8e5ea00b31 100644
--- a/machines/api/machines-resource.mdx
+++ b/machines/api/machines-resource.mdx
@@ -3,8 +3,6 @@ title: Machines
description: "Create, list, update, stop, suspend, start, and delete Machines on Fly.io with the Machines API, plus leases, metadata, wait states, and config properties."
---
-# Machines
-
You can use the Machines resource to create, stop, start, update, and delete Fly Machines. Fly Machines are fast-launching VMs on Fly.io. The Machine resource is the configuration and state for a Machine.
diff --git a/machines/guides-examples/machines-app-using-flyctl.mdx b/machines/guides-examples/machines-app-using-flyctl.mdx
index 993bc171b5..b466af7744 100644
--- a/machines/guides-examples/machines-app-using-flyctl.mdx
+++ b/machines/guides-examples/machines-app-using-flyctl.mdx
@@ -4,7 +4,7 @@ source_url: https://fly.io/docs/machines/guides-examples/machines-app-using-flyc
---
-# This Document is Stale!
+**This document is stale.**
This document illustrates some ways to work with Fly Machines individually using flyctl, and was written before Fly Apps V2 made it possible to manage Machines as a group, using a `fly.toml` config file and `fly deploy`. For most web apps, the [Fly Apps docs](/apps) are a better place to start!
diff --git a/model-context-protocol/deploy-with/machines-api.mdx b/model-context-protocol/deploy-with/machines-api.mdx
index 5886e462ab..edfd5b46e7 100644
--- a/model-context-protocol/deploy-with/machines-api.mdx
+++ b/model-context-protocol/deploy-with/machines-api.mdx
@@ -204,7 +204,7 @@ curl -i -X POST \
Note: at this time the machine is created but not yet started. It will start once it receives its first request and stop when there is a period when there are no requests.
-# Accessing the MCP
+## Accessing the MCP
Normally you would access the MCP using [`fly mcp proxy`](/flyctl/cmd/fly_mcp_proxy) to create a STDIO MCP server for your MCP client, even if you are using the Machines API to deploy an existing MCP server on a Fly Machine.
diff --git a/rails/cookbooks/build.mdx b/rails/cookbooks/build.mdx
index 9cd6518344..19c84a1c17 100644
--- a/rails/cookbooks/build.mdx
+++ b/rails/cookbooks/build.mdx
@@ -3,7 +3,7 @@ title: Optimizing your build
source_url: https://fly.io/docs/rails/cookbooks/build/
---
-# Ordering steps
+## Ordering steps
The initial cookbooks in this series seemed to automatically cache
build steps and perform predictably - make a change to the Dockerfile
@@ -46,7 +46,7 @@ two specific files have changed.
This can result in a dramatic reduction in build times for cases
where the Gemfile did not change.
-# Multi-stage builds
+## Multi-stage builds
Now consider `bundle install` and `yarn install`. Both can be
time consuming. They can be run in either order. If run sequentially,
@@ -88,7 +88,7 @@ Even better, if both changed, they will be run concurrently.
In fact, on the first run they will be run concurrently with
the installation of `postgresql-client`.
-# Caching
+## Caching
We've seen how splitting COPY statements can reduce the number of
steps, but it still remains the case that any change to the Gemfile
@@ -134,7 +134,7 @@ pick up the configuration as well as the gems.
With this in place, adding a single gem to your Gemfile will
result in only the installation of that one gem.
-## recap
+### Recap
Starting from a simple sequence of two statements (potentially three
if `yarn install` is added) we have explored a number of techniques
diff --git a/rails/the-basics/turbo-streams-and-action-cable.mdx b/rails/the-basics/turbo-streams-and-action-cable.mdx
index 72eaca3d1a..d6c660e693 100644
--- a/rails/the-basics/turbo-streams-and-action-cable.mdx
+++ b/rails/the-basics/turbo-streams-and-action-cable.mdx
@@ -133,7 +133,7 @@ Of course, if this were a real application, inserting and removing names would
cause those changes to be broadcast. As they say, this is left as an exercise
for the student.
-# Arrived at Destination
+## Arrived at Destination
You have successfully built, deployed, and connected to your first Rails application on Fly.io.