Enforce the rule that no document has multiple top-level headings.

12 files changed, 161 insertions, 212 deletions

diff --git a/spec/SUMMARY.md b/spec/SUMMARY.md
index 9d6207d..fae7259 100644
--- a/spec/SUMMARY.md
+++ b/spec/SUMMARY.md
@@ -43,6 +43,7 @@
       - [Serving bandwidth list files](./dir-spec/serving-bandwidth-list-files.md)
     - [Downloading information from other directory authorities](./dir-spec/downloading-from-other-auths.md)
     - [Computing a consensus from a set of votes](./dir-spec/computing-consensus.md)
+    - [Exchanging detached signatures](./dir-spec/exchanging-detached-signatures.md)
     - [Publishing the signed consensus](./dir-spec/publishing-consensus.md)
   - [Directory cache operation](./dir-spec/directory-cache-operation.md)
   - [Client operation](./dir-spec/client-operation.md)
diff --git a/spec/address-spec.md b/spec/address-spec.md
index c3c779c..f3b0e3c 100644
--- a/spec/address-spec.md
+++ b/spec/address-spec.md
@@ -1,18 +1,8 @@
-```text
-                          Special Hostnames in Tor
-                               Nick Mathewson
-
-Table of Contents
-
-    1. Overview
-    2. .exit
-    3. .onion
-    4. .noconnect
-```
+# Special Hostnames in Tor
 
 <a id="address-spec.txt-1"></a>
 
-# Overview
+## Overview
 
 Most of the time, Tor treats user-specified hostnames as opaque:  When
 the user connects to \<www.torproject.org>, Tor picks an exit node and uses
@@ -28,7 +18,7 @@ option or the MAPADDRESS control command.
 
 <a id="address-spec.txt-2"></a>
 
-# .exit
+## .exit
 
 ```text
   SYNTAX:  [hostname].[name-or-digest].exit
@@ -64,7 +54,7 @@ to potential application-level attacks.
 
 <a id="address-spec.txt-3"></a>
 
-# .onion
+## .onion
 
 ```text
   SYNTAX:  [digest].onion
@@ -97,7 +87,7 @@ is supported in Tor 0.2.4.10-alpha and later.
 
 <a id="address-spec.txt-4"></a>
 
-# .noconnect
+## .noconnect
 
 SYNTAX:  \[string\].noconnect
 
diff --git a/spec/bridgedb-spec.md b/spec/bridgedb-spec.md
index 4ced4bd..b12fcfb 100644
--- a/spec/bridgedb-spec.md
+++ b/spec/bridgedb-spec.md
@@ -13,7 +13,7 @@ behavior.
 
 <a id="bridgedb-spec.txt-1"></a>
 
-# Importing bridge network statuses and bridge descriptors { #importing }
+## Importing bridge network statuses and bridge descriptors { #importing }
 
 BridgeDB learns about bridges by parsing bridge network statuses,
 bridge descriptors, and extra info documents as specified in Tor's
@@ -29,7 +29,7 @@ from a Tor instance that did the validation for us.
 
 <a id="bridgedb-spec.txt-1.1"></a>
 
-## Parsing bridge network statuses { #parsing-network-status }
+### Parsing bridge network statuses { #parsing-network-status }
 
 Bridge network status documents contain the information of which bridges
 are known to the bridge authority and which flags the bridge authority
@@ -57,7 +57,7 @@ with these flags.
 
 <a id="bridgedb-spec.txt-1.2"></a>
 
-## Parsing bridge descriptors { #parsing-bridge-descriptors }
+### Parsing bridge descriptors { #parsing-bridge-descriptors }
 
 BridgeDB learns about a bridge's most recent IP address and OR port
 from parsing bridge descriptors.
@@ -99,7 +99,7 @@ to the set of bridges to be given out to bridge users.
 
 <a id="bridgedb-spec.txt-1.3"></a>
 
-## Parsing extra-info documents { #parsing-extra-info }
+### Parsing extra-info documents { #parsing-extra-info }
 
 BridgeDB learns if a bridge supports a pluggable transport by parsing
 extra-info documents.
@@ -126,7 +126,7 @@ Bridges that do not have an associated extra-info entry are not invalid.
 
 <a id="bridgedb-spec.txt-2"></a>
 
-# Assigning bridges to distributors { #assigning-to-distributors }
+## Assigning bridges to distributors { #assigning-to-distributors }
 
 A "distributor" is a mechanism by which bridges are given (or not
 given) to clients.  The current distributors are "email", "https",
@@ -148,7 +148,7 @@ distributors change or distributors are disabled entirely.
 
 <a id="bridgedb-spec.txt-3"></a>
 
-# Giving out bridges upon requests { #distributing }
+## Giving out bridges upon requests { #distributing }
 
 Upon receiving a client request, a BridgeDB distributor provides a
 subset of the bridges assigned to it.
@@ -165,7 +165,7 @@ should not be blocked.
 
 <a id="bridgedb-spec.txt-4"></a>
 
-# Selecting bridges to be given out based on IP addresses { #ip-based }
+## Selecting bridges to be given out based on IP addresses { #ip-based }
 
 ```text
    BridgeDB may be configured to support one or more distributors which
@@ -274,7 +274,7 @@ total."  To do this, BridgeDB combines to the results:
 
 <a id="bridgedb-spec.txt-5"></a>
 
-# Selecting bridges to be given out based on email addresses
+## Selecting bridges to be given out based on email addresses
 
 ```text
    BridgeDB can be configured to support one or more distributors that are
@@ -357,7 +357,7 @@ proceeds as follows:
 
 <a id="bridgedb-spec.txt-6"></a>
 
-# Selecting unallocated bridges to be stored in file buckets { #unallocated-buckets }
+## Selecting unallocated bridges to be stored in file buckets { #unallocated-buckets }
 
 > Kaner should have a look at this section. -NM
 
@@ -387,7 +387,7 @@ proceeds as follows:
 
 <a id="bridgedb-spec.txt-7"></a>
 
-# Displaying Bridge Information { #formatting }
+## Displaying Bridge Information { #formatting }
 
 After bridges are selected using one of the methods described in
 Sections 4 - 6, they are output in one of two formats. Bridges are
@@ -413,7 +413,7 @@ Previously, each line was prepended with the "bridge" keyword, such as
 
 <a id="bridgedb-spec.txt-8"></a>
 
-# Writing bridge assignments for statistics
+## Writing bridge assignments for statistics
 
 BridgeDB can be configured to write bridge assignments to disk for
 statistical analysis.
diff --git a/spec/cert-spec.md b/spec/cert-spec.md
index f78af10..141e1f8 100644
--- a/spec/cert-spec.md
+++ b/spec/cert-spec.md
@@ -31,11 +31,11 @@ in Ed25519 certificates unless explicitly specified otherwise.
 
 <a id="cert-spec.txt-2"></a>
 
-# Document formats
+## Document formats
 
 <a id="cert-spec.txt-2.1"></a>
 
-## Ed25519 Certificates
+### Ed25519 Certificates
 
 When generating a signing key, we also generate a certificate for it.
 Unlike the certificates for authorities' signing keys, these
@@ -92,11 +92,11 @@ sizeof(ed25519_cert) - 64 bytes).
 
 <a id="cert-spec.txt-2.2"></a>
 
-## Basic extensions
+### Basic extensions
 
 <a id="cert-spec.txt-2.2.1"></a>
 
-### Signed-with-ed25519-key extension \[type 04\] { #signed-with-ed25519 }
+#### Signed-with-ed25519-key extension \[type 04\] { #signed-with-ed25519 }
 
 In several places, it's desirable to bundle the key signing a
 certificate along with the certificate.  We do so with this
@@ -113,7 +113,7 @@ sign the certificate.
 
 <a id="cert-spec.txt-2.3"></a>
 
-## RSA->Ed25519 cross-certificate { #rsa-cross-cert }
+### RSA->Ed25519 cross-certificate { #rsa-cross-cert }
 
 Certificate type \[07\] (Cross-certification of Ed25519 identity
 with RSA key) contains the following data:
diff --git a/spec/dir-list-spec.md b/spec/dir-list-spec.md
index a3e6aae..ecb47cb 100644
--- a/spec/dir-list-spec.md
+++ b/spec/dir-list-spec.md
@@ -1,35 +1,13 @@
+# Tor Directory List Format
+
 ```text
-                        Tor Directory List Format
-                         Tim Wilson-Brown (teor)
 
-Table of Contents
-
-    1. Scope and Preliminaries
-        1.1. Format Overview
-        1.2. Acknowledgements
-        1.3. Format Versions
-        1.4. Future Plans
-    2. Format Details
-        2.1. Nonterminals
-        2.2. List Header
-            2.2.1. List Header Format
-        2.3. List Generation
-            2.3.1. List Generation Format
-        2.4. Directory Entry
-            2.4.1. Directory Entry Format
-    3. Usage Considerations
-        3.1. Caching
-        3.2. Retrieving Directory Information
-        3.3. Fallback Reliability
-    A.1. Sample Data
-        A.1.1. Sample Fallback List Header
-        A.1.2. Sample Fallback List Generation
-        A.1.3. Sample Fallback Entries
+                         Tim Wilson-Brown (teor)
 ```
 
 <a id="dir-list-spec.txt-1"></a>
 
-# Scope and Preliminaries
+## Scope and Preliminaries
 
 This document describes the format of Tor's directory lists, which are
 compiled and hard-coded into the tor binary. There is currently one
@@ -60,7 +38,7 @@ Stem and Relay Search have parsers for this legacy format.
 
 <a id="dir-list-spec.txt-1.1"></a>
 
-## Format Overview
+### Format Overview
 
 A directory list is a C code fragment containing an array of C string
 constants. Each double-quoted C string constant is a valid torrc
@@ -87,7 +65,7 @@ except where noted below.
 
 <a id="dir-list-spec.txt-1.2"></a>
 
-## Acknowledgements
+### Acknowledgements
 
 The original fallback directory script and format was created by
 weasel. The current script uses code written by gsathya & karsten.
@@ -101,7 +79,7 @@ This specification was revised after feedback from:
 
 <a id="dir-list-spec.txt-1.3"></a>
 
-## Format Versions
+### Format Versions
 
 The directory list format uses semantic versioning: <https://semver.org>
 
@@ -125,7 +103,7 @@ The directory list format uses semantic versioning: <https://semver.org>
 
 <a id="dir-list-spec.txt-1.4"></a>
 
-## Future Plans
+### Future Plans
 
 Tor also has an auth_dirs.inc file, but it is not yet in this format.
 Tor uses slightly different formats for authorities and fallback
@@ -141,7 +119,7 @@ fallback update script. See #24839 for details.
 
 <a id="dir-list-spec.txt-2"></a>
 
-# Format Details
+## Format Details
 
 Directory lists contain the following sections:
 
@@ -155,7 +133,7 @@ Directory lists contain the following sections:
 
 <a id="dir-list-spec.txt-2.1"></a>
 
-## Nonterminals
+### Nonterminals
 
 The following nonterminals are defined in the Onionoo details document
 specification:
@@ -214,14 +192,14 @@ specification in dir-spec.txt:
 
 <a id="dir-list-spec.txt-2.2"></a>
 
-## List Header
+### List Header
 
 The list header consists of a number of key-value pairs, embedded in
 C-style comments.
 
 <a id="dir-list-spec.txt-2.2.1"></a>
 
-### List Header Format
+#### List Header Format
 
 "/*" SP+ "type=" Keyword SP+ "*/" SP\* NL
 
@@ -296,7 +274,7 @@ C-style comments.
 
 <a id="dir-list-spec.txt-2.3"></a>
 
-## List Generation
+### List Generation
 
 The list generation information consists of human-readable prose
 describing the content and origin of this directory list. It is contained
@@ -311,7 +289,7 @@ Parsers MUST NOT rely on a version increment when the format changes.
 
 <a id="dir-list-spec.txt-2.3.1"></a>
 
-### List Generation Format
+#### List Generation Format
 
 In general, parsers MUST NOT rely on the format of this section.
 
@@ -328,7 +306,7 @@ section, other than the terminating section separator.
 
 <a id="dir-list-spec.txt-2.4"></a>
 
-## Directory Entry
+### Directory Entry
 
 A directory entry consists of a C string constant, and one or more
 C-style comments. The C string constant is a valid argument to the
@@ -342,7 +320,7 @@ to their weights.)
 
 <a id="dir-list-spec.txt-2.4.1"></a>
 
-### Directory Entry Format
+#### Directory Entry Format
 
 ```text
      If a directory entry does not conform to this format, the entry SHOULD
@@ -459,14 +437,14 @@ to their weights.)
 
 <a id="dir-list-spec.txt-3"></a>
 
-# Usage Considerations
+## Usage Considerations
 
 This section contains recommended library behaviours. It does not affect
 the format of directory lists.
 
 <a id="dir-list-spec.txt-3.1"></a>
 
-## Caching
+### Caching
 
 The fallback list typically changes once every 6-12 months. The data in
 the list represents the state of the fallback directory entries when the
@@ -492,7 +470,7 @@ clone.
 
 <a id="dir-list-spec.txt-3.2"></a>
 
-## Retrieving Directory Information
+### Retrieving Directory Information
 
 Some libraries retrieve directory documents directly from the Tor
 Directory Authorities. The directory authorities are designed to support
@@ -520,7 +498,7 @@ intervals, see dir-spec for details.
 
 <a id="dir-list-spec.txt-3.3"></a>
 
-## Fallback Reliability
+### Fallback Reliability
 
 The fallback list is typically regenerated when the fallback failure
 rate exceeds 25%. Libraries SHOULD NOT rely on any particular fallback
@@ -532,7 +510,7 @@ before trying an authority.
 
 <a id="dir-list-spec.txt-A.1"></a>
 
-## Sample Data
+### Sample Data
 
 A sample version 2.0.0 fallback list is available here:
 
@@ -544,7 +522,7 @@ A sample transitional version 2.0.0 fallback list is available here:
 
 <a id="dir-list-spec.txt-A.1.1"></a>
 
-### Sample Fallback List Header
+#### Sample Fallback List Header
 
 /*type=fallback */
 /* version=2.0.0 */
@@ -552,7 +530,7 @@ A sample transitional version 2.0.0 fallback list is available here:
 
 <a id="dir-list-spec.txt-A.1.2"></a>
 
-### Sample Fallback List Generation
+#### Sample Fallback List Generation
 
 /*Whitelist & blacklist excluded 1326 of 1513 candidates. */
 /* Checked IPv4 DirPorts served a consensus within 15.0s. */
@@ -573,7 +551,7 @@ URL: https:onionoo.torproject.orguptime?first_seen_days=30-&flag=V2Dir&type=rela
 
 <a id="dir-list-spec.txt-A.1.3"></a>
 
-### Sample Fallback Entries
+#### Sample Fallback Entries
 
 "176.10.104.240:80 orport=443 id=0111BA9B604669E636FFD5B503F382A4B7AD6E80"
 /*nickname=foo */
diff --git a/spec/dir-spec/computing-consensus.md b/spec/dir-spec/computing-consensus.md
index e17f4c6..1236e7e 100644
--- a/spec/dir-spec/computing-consensus.md
+++ b/spec/dir-spec/computing-consensus.md
@@ -559,7 +559,7 @@ Wgm=Wgg, Wem=Wee, Weg=Wed
 
 <a id="dir-spec.txt-3.9"></a>
 
-## Computing consensus flavors
+### Computing consensus flavors
 
 Consensus flavors are variants of the consensus that clients can choose
 to download and use instead of the unflavored consensus.  The purpose
@@ -601,7 +601,7 @@ is a string consisting of alphanumeric characters and dashes:
 
 <a id="dir-spec.txt-3.9.1"></a>
 
-### ns consensus
+#### ns consensus
 
 The ns consensus flavor is equivalent to the unflavored consensus.
 When the flavor is omitted from the "network-status-version" line,
@@ -611,7 +611,7 @@ accept consensuses where the flavor is omitted.
 
 <a id="dir-spec.txt-3.9.2"></a>
 
-### Microdescriptor consensus
+#### Microdescriptor consensus
 
 The microdescriptor consensus is a consensus flavor that contains
 microdescriptor hashes instead of descriptor hashes and that omits
@@ -683,80 +683,3 @@ algorithm for its signatures.
 
 <a id="dir-spec.txt-3.10"></a>
 
-## Exchanging detached signatures
-
-Once an authority has computed and signed a consensus network status, it
-should send its detached signature to each other authority in an HTTP POST
-request to the URL:
-
-`http://<hostname>/tor/post/consensus-signature`
-
-\[XXX Note why we support push-and-then-pull.\]
-
-All of the detached signatures it knows for consensus status should be
-available at:
-
-`http://<hostname>/tor/status-vote/next/consensus-signatures.z`
-
-Assuming full connectivity, every authority should compute and sign the
-same consensus including any flavors in each period.  Therefore, it
-isn't necessary to download the consensus or any flavors of it computed
-by each authority; instead, the authorities only push/fetch each
-others' signatures.  A "detached signature" document contains items as
-follows:
-
-"consensus-digest" SP Digest NL
-
-\[At start, at most once.\]
-
-The digest of the consensus being signed.
-
-"valid-after" SP YYYY-MM-DD SP HH:MM:SS NL
-"fresh-until" SP YYYY-MM-DD SP HH:MM:SS NL
-"valid-until" SP YYYY-MM-DD SP HH:MM:SS NL
-
-\[As in the consensus\]
-
-"additional-digest" SP flavor SP algname SP digest NL
-
-\[Any number.\]
-
-For each supported consensus flavor, every directory authority
-adds one or more "additional-digest" lines.  "flavor" is the name
-of the consensus flavor, "algname" is the name of the hash
-algorithm that is used to generate the digest, and "digest" is the
-hex-encoded digest.
-
-The hash algorithm for the microdescriptor consensus flavor is
-defined as SHA256 with algname "sha256".
-
-```text
-    "additional-signature" SP flavor SP algname SP identity SP
-         signing-key-digest NL signature.
-
-        [Any number.]
-```
-
-For each supported consensus flavor and defined digest algorithm,
-every directory authority adds an "additional-signature" line.
-"flavor" is the name of the consensus flavor.  "algname" is the
-name of the algorithm that was used to hash the identity and
-signing keys, and to compute the signature.  "identity" is the
-hex-encoded digest of the authority identity key of the signing
-authority, and "signing-key-digest" is the hex-encoded digest of
-the current authority signing key of the signing authority.
-
-The "sha256" signature format is defined as the RSA signature of
-the OAEP+-padded SHA256 digest of the item to be signed.  When
-checking signatures, the signature MUST be treated as valid if the
-signature material begins with SHA256(document), so that other
-data can get added later.
-\[To be honest, I didn't fully understand the previous paragraph
-and only copied it from the proposals.  Review carefully. -KL\]
-
-"directory-signature"
-
-\[As in the consensus; the signature object is the same as in the
-consensus document.\]
-
-<a id="dir-spec.txt-3.11"></a>
diff --git a/spec/dir-spec/exchanging-detached-signatures.md b/spec/dir-spec/exchanging-detached-signatures.md
new file mode 100644
index 0000000..c076e1c
--- /dev/null
+++ b/spec/dir-spec/exchanging-detached-signatures.md
@@ -0,0 +1,77 @@
+## Exchanging detached signatures
+
+Once an authority has computed and signed a consensus network status, it
+should send its detached signature to each other authority in an HTTP POST
+request to the URL:
+
+`http://<hostname>/tor/post/consensus-signature`
+
+\[XXX Note why we support push-and-then-pull.\]
+
+All of the detached signatures it knows for consensus status should be
+available at:
+
+`http://<hostname>/tor/status-vote/next/consensus-signatures.z`
+
+Assuming full connectivity, every authority should compute and sign the
+same consensus including any flavors in each period.  Therefore, it
+isn't necessary to download the consensus or any flavors of it computed
+by each authority; instead, the authorities only push/fetch each
+others' signatures.  A "detached signature" document contains items as
+follows:
+
+"consensus-digest" SP Digest NL
+
+\[At start, at most once.\]
+
+The digest of the consensus being signed.
+
+"valid-after" SP YYYY-MM-DD SP HH:MM:SS NL
+"fresh-until" SP YYYY-MM-DD SP HH:MM:SS NL
+"valid-until" SP YYYY-MM-DD SP HH:MM:SS NL
+
+\[As in the consensus\]
+
+"additional-digest" SP flavor SP algname SP digest NL
+
+\[Any number.\]
+
+For each supported consensus flavor, every directory authority
+adds one or more "additional-digest" lines.  "flavor" is the name
+of the consensus flavor, "algname" is the name of the hash
+algorithm that is used to generate the digest, and "digest" is the
+hex-encoded digest.
+
+The hash algorithm for the microdescriptor consensus flavor is
+defined as SHA256 with algname "sha256".
+
+```text
+    "additional-signature" SP flavor SP algname SP identity SP
+         signing-key-digest NL signature.
+
+        [Any number.]
+```
+
+For each supported consensus flavor and defined digest algorithm,
+every directory authority adds an "additional-signature" line.
+"flavor" is the name of the consensus flavor.  "algname" is the
+name of the algorithm that was used to hash the identity and
+signing keys, and to compute the signature.  "identity" is the
+hex-encoded digest of the authority identity key of the signing
+authority, and "signing-key-digest" is the hex-encoded digest of
+the current authority signing key of the signing authority.
+
+The "sha256" signature format is defined as the RSA signature of
+the OAEP+-padded SHA256 digest of the item to be signed.  When
+checking signatures, the signature MUST be treated as valid if the
+signature material begins with SHA256(document), so that other
+data can get added later.
+\[To be honest, I didn't fully understand the previous paragraph
+and only copied it from the proposals.  Review carefully. -KL\]
+
+"directory-signature"
+
+\[As in the consensus; the signature object is the same as in the
+consensus document.\]
+
+<a id="dir-spec.txt-3.11"></a>
diff --git a/spec/gettor-spec.md b/spec/gettor-spec.md
index 446f116..337413d 100644
--- a/spec/gettor-spec.md
+++ b/spec/gettor-spec.md
@@ -4,13 +4,13 @@ Jacob Appelbaum
 
 <a id="gettor-spec.txt-0"></a>
 
-# Preface
+## Preface
 
 This document describes GetTor and how to properly implementation GetTor.
 
 <a id="gettor-spec.txt-1"></a>
 
-# Overview
+## Overview
 
 GetTor was created to resolve direct and indirect censorship of Tor's
 software.  In many countries and networks Tor's main website is blocked and
@@ -24,7 +24,7 @@ methods such as SMTP between a non-trusted third party or with IRC and XDCC.
 
 <a id="gettor-spec.txt-2"></a>
 
-# Implementation
+## Implementation
 
 Any compliant GetTor implementation will implement at least a single transport
 to meet the needs of a certain class of users. It should be i18n and l10n
@@ -38,13 +38,13 @@ per transport basis.
 
 <a id="gettor-spec.txt-2.1"></a>
 
-## Reference implementation
+### Reference implementation
 
 We have implemented\[0\] a compliant GetTor that supports SMTP as a transport.
 
 <a id="gettor-spec.txt-3"></a>
 
-# SMTP transport
+## SMTP transport
 
 The SMTP transport for GetTor should allow users to send any RFC822 compliant
 message in any known human language; GetTor should respond in whatever
@@ -55,7 +55,7 @@ descriptions.
 
 <a id="gettor-spec.txt-3.1"></a>
 
-## SMTP transport security considerations
+### SMTP transport security considerations
 
 Any GetTor instance that offers SMTP as a transport should optionally
 implement the checking of DKIM signatures to ensure that email is not forged.
@@ -64,7 +64,7 @@ response with a blinded message.
 
 <a id="gettor-spec.txt-3.2"></a>
 
-## SMTP transport privacy considerations
+### SMTP transport privacy considerations
 
 Any GetTor instance that offers SMTP as a transport must at least store the
 requester's address for the time that it takes to process a response. This
@@ -78,14 +78,14 @@ information about any of the requester beyond language selection.
 
 <a id="gettor-spec.txt-4"></a>
 
-# Other transports
+## Other transports
 
 At this time no other transports have been specified. IRC XDCC is a likely
 useful system as is XMPP/Jabber with the newest OTR file sharing transport.
 
 <a id="gettor-spec.txt-5"></a>
 
-# Implementation suggestions
+## Implementation suggestions
 
 It is suggested that any compliant GetTor instance should be written in a so
 called "safe" language such as Python.
diff --git a/spec/glossary.md b/spec/glossary.md
index 908686c..5a3649a 100644
--- a/spec/glossary.md
+++ b/spec/glossary.md
@@ -13,7 +13,7 @@ citing them authoritatively. ;)
 
 <a id="glossary.txt-0"></a>
 
-# Preliminaries
+## Preliminaries
 
 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
 NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and
diff --git a/spec/param-spec.md b/spec/param-spec.md
index 025110c..2f79120 100644
--- a/spec/param-spec.md
+++ b/spec/param-spec.md
@@ -1,11 +1,11 @@
-Tor network parameters
+# Tor network parameters
 
 This file lists the recognized parameters that can appear on the "params"
 line of a directory consensus.
 
 <a id="param-spec.txt-1"></a>
 
-# Network protocol parameters {#network-protocol}
+## Network protocol parameters {#network-protocol}
 
 "circwindow" -- the default package window that circuits should be
 established with. It started out at 1000 cells, but some research
@@ -58,7 +58,7 @@ First appeared: 0.4.5.1-alpha.
 
 <a id="param-spec.txt-2"></a>
 
-# Performance-tuning parameters {#performance-tuning}
+## Performance-tuning parameters {#performance-tuning}
 
 "CircuitPriorityHalflifeMsec" -- the halflife parameter used when
 weighting which circuit will send the next cell. Obeyed by Tor
@@ -108,7 +108,7 @@ First appeared: 0.4.8.2
 
 <a id="param-spec.txt-3"></a>
 
-# Voting-related parameters {#voting}
+## Voting-related parameters {#voting}
 
 "bwweightscale" -- Value that bandwidth-weights are divided by. If not
 present then this defaults to 10000.
@@ -146,7 +146,7 @@ dirauth.
 
 <a id="param-spec.txt-4"></a>
 
-# Circuit-build-timeout parameters {#cbt}
+## Circuit-build-timeout parameters {#cbt}
 
 "cbtdisabled", "cbtnummodes", "cbtrecentcount", "cbtmaxtimeouts",
 "cbtmincircs", "cbtquantile", "cbtclosequantile", "cbttestfreq",
@@ -157,7 +157,7 @@ consensus parameters.
 
 <a id="param-spec.txt-5"></a>
 
-# Directory-related parameters {#directory}
+## Directory-related parameters {#directory}
 
 "max-consensus-age-to-cache-for-diff" -- Determines how much
 consensus history (in hours) relays should try to cache in order to
@@ -169,7 +169,7 @@ try to find a diff for it.  (min 0, max 8192, default 72)
 
 <a id="param-spec.txt-6"></a>
 
-# Pathbias parameters {#pathbias}
+## Pathbias parameters {#pathbias}
 
 "pb_mincircs", "pb_noticepct", "pb_warnpct", "pb_extremepct",
 "pb_dropguards", "pb_scalecircs", "pb_scalefactor",
@@ -178,7 +178,7 @@ try to find a diff for it.  (min 0, max 8192, default 72)
 
 <a id="param-spec.txt-7"></a>
 
-# Relay behavior parameters {#relay-behavior}
+## Relay behavior parameters {#relay-behavior}
 
 "refuseunknownexits" -- if set to one, exit relays look at the previous
 hop of circuits that ask to open an exit stream, and refuse to exit if
@@ -262,7 +262,7 @@ First appeared: 0.4.7.5-alpha.
 
 <a id="param-spec.txt-8"></a>
 
-# V3 onion service parameters {#onion-service}
+## V3 onion service parameters {#onion-service}
 
 "hs_intro_min_introduce2", "hs_intro_max_introduce2" --
 Minimum/maximum amount of INTRODUCE2 cells allowed per circuits
@@ -321,7 +321,7 @@ First appeared: 0.4.2.1-alpha.
 
 <a id="param-spec.txt-9"></a>
 
-# Denial-of-service parameters {#dos}
+## Denial-of-service parameters {#dos}
 
 Denial of Service mitigation parameters. Introduced in 0.3.3.2-alpha:
 
@@ -368,7 +368,7 @@ rendezvous points for single hop clients.
 
 <a id="param-spec.txt-10"></a>
 
-# Padding-related parameters {#padding}
+## Padding-related parameters {#padding}
 
 "circpad_max_circ_queued_cells" -- The circuitpadding module will
 stop sending more padding cells if more than this many cells are in
@@ -402,7 +402,7 @@ First appeared: 0.4.0.3-alpha.
 
 <a id="param-spec.txt-11"></a>
 
-# Guard-related parameters
+## Guard-related parameters
 
 (See guard-spec.txt for more information on the vocabulary used here.)
 
@@ -499,7 +499,7 @@ First appeared: 0.3.0
 
 <a id="param-spec.txt-X"></a>
 
-# Obsolete parameters {#obsolete}
+## Obsolete parameters {#obsolete}
 
 "NumDirectoryGuards", "NumEntryGuards" -- Number of guard nodes
 clients should use by default.  If NumDirectoryGuards is 0, we
diff --git a/spec/socks-extensions.md b/spec/socks-extensions.md
index d4d7010..25b3eab 100644
--- a/spec/socks-extensions.md
+++ b/spec/socks-extensions.md
@@ -1,20 +1,8 @@
-Tor's extensions to the SOCKS protocol
-
-Table of Contents
-
-```text
-    1. Overview
-        1.1. Extent of support
-    2. Name lookup
-    3. Other command extensions.
-    4. HTTP-resistance
-    5. Optimistic data
-    6. Extended error codes
-```
+# Tor's extensions to the SOCKS protocol
 
 <a id="socks-extensions.txt-1"></a>
 
-# Overview
+## Overview
 
 The SOCKS protocol provides a generic interface for TCP proxies.  Client
 software connects to a SOCKS server via TCP, and requests a TCP connection
@@ -34,7 +22,7 @@ hostnames.
 
 <a id="socks-extensions.txt-1.1"></a>
 
-## Extent of support
+### Extent of support
 
 Tor supports the SOCKS4, SOCKS4A, and SOCKS5 standards, except as follows:
 
@@ -72,7 +60,7 @@ manpage.)
 
 <a id="socks-extensions.txt-2"></a>
 
-# Name lookup
+## Name lookup
 
 As an extension to SOCKS4A and SOCKS5, Tor implements a new command value,
 "RESOLVE" \[F0\].  When Tor receives a "RESOLVE" SOCKS command, it initiates
@@ -92,7 +80,7 @@ address" portion of the reply.
 
 <a id="socks-extensions.txt-3"></a>
 
-# Other command extensions
+## Other command extensions
 
 Tor 0.1.2.4-alpha added a new command value: "CONNECT_DIR" \[F2\].
 In this case, Tor will open an encrypted direct TCP connection to the
@@ -105,7 +93,7 @@ new use_begindir flag in edge_connection_t.
 
 <a id="socks-extensions.txt-4"></a>
 
-# HTTP-resistance
+## HTTP-resistance
 
 Tor checks the first byte of each SOCKS request to see whether it looks
 more like an HTTP request (that is, it starts with a "G", "H", or "P").  If
@@ -115,7 +103,7 @@ use Tor as an HTTP proxy instead of a SOCKS proxy.
 
 <a id="socks-extensions.txt-5"></a>
 
-# Optimistic data
+## Optimistic data
 
 Tor allows SOCKS clients to send connection data before Tor has sent a
 SOCKS response.  When using an exit node that supports "optimistic data",
@@ -128,7 +116,7 @@ data.
 
 <a id="socks-extensions.txt-6"></a>
 
-# Extended error codes
+## Extended error codes
 
 We define a set of additional extension error codes that can be returned
 by our SOCKS implementation in response to failed onion service
diff --git a/spec/version-spec.md b/spec/version-spec.md
index a4b6373..ab2abc2 100644
--- a/spec/version-spec.md
+++ b/spec/version-spec.md
@@ -1,16 +1,8 @@
-HOW TOR VERSION NUMBERS WORK
-
-Table of Contents
-
-```text
-    1. The Old Way
-    2. The New Way
-    3. Version status.
-```
+# How Tor Version Numbers Work
 
 <a id="version-spec.txt-1"></a>
 
-# The Old Way
+## The Old Way
 
 Before 0.1.0, versions were of the format:
 
@@ -31,7 +23,7 @@ and any eventual bugfix release would be "0.0.8.1".
 
 <a id="version-spec.txt-2"></a>
 
-# The New Way
+## The New Way
 
 Starting at 0.1.0.1-rc, versions are of the format:
 
@@ -68,7 +60,7 @@ suffix instead of the "-cvs" suffix.
 
 <a id="version-spec.txt-3"></a>
 
-# Version status
+## Version status
 
 ```text
   Sometimes we need to determine whether a Tor version is obsolete,