Enforce the rule that every md has a toplevel (\#) section.

41 files changed, 121 insertions, 121 deletions

diff --git a/spec/bandwidth-file-spec/definitions.md b/spec/bandwidth-file-spec/definitions.md
index 0300fb5..c01b407 100644
--- a/spec/bandwidth-file-spec/definitions.md
+++ b/spec/bandwidth-file-spec/definitions.md
@@ -1,6 +1,6 @@
 <a id="bandwidth-file-spec.txt-2.1"></a>
 
-## Definitions
+# Definitions
 
 The following nonterminals are defined in Tor directory protocol
 sections 1.2., 2.1.1., 2.1.3.:
diff --git a/spec/bandwidth-file-spec/header-list-format.md b/spec/bandwidth-file-spec/header-list-format.md
index 075ddd6..6b7f9df 100644
--- a/spec/bandwidth-file-spec/header-list-format.md
+++ b/spec/bandwidth-file-spec/header-list-format.md
@@ -1,6 +1,6 @@
 <a id="bandwidth-file-spec.txt-2.2"></a>
 
-## Header List format
+# Header List format
 
 It consists of a Timestamp line and zero or more HeaderLines.
 
diff --git a/spec/bandwidth-file-spec/implementation-details.md b/spec/bandwidth-file-spec/implementation-details.md
index 1695793..6775e05 100644
--- a/spec/bandwidth-file-spec/implementation-details.md
+++ b/spec/bandwidth-file-spec/implementation-details.md
@@ -1,10 +1,10 @@
 <a id="bandwidth-file-spec.txt-2.4"></a>
 
-## Implementation details
+# Implementation details
 
 <a id="bandwidth-file-spec.txt-2.4.1"></a>
 
-### Writing bandwidth files atomically { #write-atomically }
+## Writing bandwidth files atomically { #write-atomically }
 
 To avoid inconsistent reads, implementations SHOULD write bandwidth files
 atomically. If the file is transferred from another host, it SHOULD be
@@ -19,13 +19,13 @@ Torflow does not write bandwidth files atomically.
 
 <a id="bandwidth-file-spec.txt-2.4.2"></a>
 
-### Additional KeyValue pair definitions { #key-value-pairs }
+## Additional KeyValue pair definitions { #key-value-pairs }
 
 KeyValue pairs in RelayLines that current implementations generate.
 
 <a id="bandwidth-file-spec.txt-2.4.2.1"></a>
 
-#### Simple Bandwidth Scanner { #sbws }
+### Simple Bandwidth Scanner { #sbws }
 
 sbws RelayLines contain these keys:
 
@@ -381,7 +381,7 @@ This KeyValue was added in version 1.7.0 of this specification.
 
 <a id="bandwidth-file-spec.txt-2.4.2.2"></a>
 
-#### Torflow
+### Torflow
 
 Torflow RelayLines include node_id and bw, and other KeyValue pairs \[2\].
 
diff --git a/spec/bandwidth-file-spec/relay-line-format.md b/spec/bandwidth-file-spec/relay-line-format.md
index 275abc6..4a73a01 100644
--- a/spec/bandwidth-file-spec/relay-line-format.md
+++ b/spec/bandwidth-file-spec/relay-line-format.md
@@ -1,6 +1,6 @@
 <a id="bandwidth-file-spec.txt-2.3"></a>
 
-## Relay Line format { #relay-line }
+# Relay Line format { #relay-line }
 
 It consists of zero or more RelayLines containing relay ids and
 bandwidths. The relays and their KeyValues are in arbitrary order.
diff --git a/spec/dir-spec/accepting-relay-documents.md b/spec/dir-spec/accepting-relay-documents.md
index b507b9c..ffcf7c7 100644
--- a/spec/dir-spec/accepting-relay-documents.md
+++ b/spec/dir-spec/accepting-relay-documents.md
@@ -1,6 +1,6 @@
 <a id="dir-spec.txt-3.2"></a>
 
-## Accepting server descriptor and extra-info document uploads
+# Accepting server descriptor and extra-info document uploads
 
 When a router posts a signed descriptor to a directory authority, the
 authority first checks whether it is well-formed and correctly
diff --git a/spec/dir-spec/assigning-flags-vote.md b/spec/dir-spec/assigning-flags-vote.md
index 7b7a59e..7eb3849 100644
--- a/spec/dir-spec/assigning-flags-vote.md
+++ b/spec/dir-spec/assigning-flags-vote.md
@@ -1,6 +1,6 @@
 <a id="dir-spec.txt-3.4.2"></a>
 
-### Assigning flags in a vote
+# Assigning flags in a vote
 
 (This section describes how directory authorities choose which status
 flags to apply to routers. Later directory authorities MAY do things
diff --git a/spec/dir-spec/computing-consensus.md b/spec/dir-spec/computing-consensus.md
index 1236e7e..39d6e5f 100644
--- a/spec/dir-spec/computing-consensus.md
+++ b/spec/dir-spec/computing-consensus.md
@@ -1,5 +1,5 @@
 
-## Computing a consensus from a set of votes { #computing-consensus }
+# Computing a consensus from a set of votes { #computing-consensus }
 
 Given a set of votes, authorities compute the contents of the consensus.
 
@@ -233,7 +233,7 @@ earlier item.
 
 <a id="dir-spec.txt-3.8.0.1"></a>
 
-### Deciding which Ids to include { #choosing-relay-ids }
+## Deciding which Ids to include { #choosing-relay-ids }
 
 This sorting algorithm is used for consensus-method 22 and later.
 
@@ -260,7 +260,7 @@ This sorting algorithm is used for consensus-method 22 and later.
 
 <a id="dir-spec.txt-3.8.0.2"></a>
 
-#### Deciding which descriptors to include { #choosing-relay-descs }
+### Deciding which descriptors to include { #choosing-relay-descs }
 
 Deciding which descriptors to include.
 
@@ -279,7 +279,7 @@ published, and then in favor of the smaller server descriptor digest.
 
 <a id="dir-spec.txt-3.8.1"></a>
 
-### Forward compatibility { #consensus-method-list }
+## Forward compatibility { #consensus-method-list }
 
 Future versions of Tor will need to include new information in the
 consensus documents, but it is important that all authorities (or at least
@@ -354,7 +354,7 @@ NOT advertise support for them:
 
 <a id="dir-spec.txt-3.8.2"></a>
 
-### Encoding port lists
+## Encoding port lists
 
 Whether the summary shows the list of accepted ports or the list of
 rejected ports depends on which list is shorter (has a shorter string
@@ -376,7 +376,7 @@ possible within these 1000 bytes.  \[XXXX be more specific.\]
 
 <a id="dir-spec.txt-3.8.3"></a>
 
-### Computing Bandwidth Weights
+## Computing Bandwidth Weights
 
 Let weight_scale = 10000, or the value of the "bwweightscale" parameter.
 (Before consensus method 31 there was a bug in parsing bwweightscale, so
@@ -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
diff --git a/spec/dir-spec/computing-microdescriptors.md b/spec/dir-spec/computing-microdescriptors.md
index 5270ffa..bca4eb1 100644
--- a/spec/dir-spec/computing-microdescriptors.md
+++ b/spec/dir-spec/computing-microdescriptors.md
@@ -1,6 +1,6 @@
 <a id="dir-spec.txt-3.3"></a>
 
-## Computing microdescriptors
+# Computing microdescriptors
 
 Microdescriptors are a stripped-down version of server descriptors
 generated by the directory authorities which may additionally contain
diff --git a/spec/dir-spec/consensus-formats.md b/spec/dir-spec/consensus-formats.md
index 6fe5637..7a6cd46 100644
--- a/spec/dir-spec/consensus-formats.md
+++ b/spec/dir-spec/consensus-formats.md
@@ -1,6 +1,6 @@
 <a id="dir-spec.txt-3.4.1"></a>
 
-### Vote and consensus status document formats
+# Vote and consensus status document formats
 
 Votes and consensuses are more strictly formatted than other documents
 in this specification, since different authorities must be able to
diff --git a/spec/dir-spec/creating-key-certificates.md b/spec/dir-spec/creating-key-certificates.md
index ebe3e2f..fc3326f 100644
--- a/spec/dir-spec/creating-key-certificates.md
+++ b/spec/dir-spec/creating-key-certificates.md
@@ -1,6 +1,6 @@
 <a id="dir-spec.txt-3.1"></a>
 
-## Creating key certificates
+# Creating key certificates
 
 Key certificates consist of the following items:
 
diff --git a/spec/dir-spec/exchanging-detached-signatures.md b/spec/dir-spec/exchanging-detached-signatures.md
index c076e1c..7a8495e 100644
--- a/spec/dir-spec/exchanging-detached-signatures.md
+++ b/spec/dir-spec/exchanging-detached-signatures.md
@@ -1,4 +1,4 @@
-## Exchanging detached signatures
+# 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
diff --git a/spec/dir-spec/exchanging-votes.md b/spec/dir-spec/exchanging-votes.md
index 066f825..924aa67 100644
--- a/spec/dir-spec/exchanging-votes.md
+++ b/spec/dir-spec/exchanging-votes.md
@@ -1,6 +1,6 @@
 <a id="dir-spec.txt-3.4"></a>
 
-## Exchanging votes
+# Exchanging votes
 
 Authorities divide time into Intervals.  Authority administrators SHOULD
 try to all pick the same interval length, and SHOULD pick intervals that
diff --git a/spec/dir-spec/extra-info-document-format.md b/spec/dir-spec/extra-info-document-format.md
index 24d6a03..e743ff3 100644
--- a/spec/dir-spec/extra-info-document-format.md
+++ b/spec/dir-spec/extra-info-document-format.md
@@ -1,6 +1,6 @@
 <a id="dir-spec.txt-2.1.2"></a>
 
-### Extra-info document format
+# Extra-info document format
 
 Extra-info documents consist of the following items:
 
diff --git a/spec/dir-spec/nonterminals-server-descriptors.md b/spec/dir-spec/nonterminals-server-descriptors.md
index 4991e9e..e2240ae 100644
--- a/spec/dir-spec/nonterminals-server-descriptors.md
+++ b/spec/dir-spec/nonterminals-server-descriptors.md
@@ -1,6 +1,6 @@
 <a id="dir-spec.txt-2.1.3"></a>
 
-### Nonterminals in server descriptors
+# Nonterminals in server descriptors
 
 ```text
    nickname ::= between 1 and 19 alphanumeric characters ([A-Za-z0-9]),
diff --git a/spec/dir-spec/server-descriptor-format.md b/spec/dir-spec/server-descriptor-format.md
index 49820fc..9a0c175 100644
--- a/spec/dir-spec/server-descriptor-format.md
+++ b/spec/dir-spec/server-descriptor-format.md
@@ -1,6 +1,6 @@
 <a id="dir-spec.txt-2.1.1"></a>
 
-### Server descriptor format
+# Server descriptor format
 
 Server descriptors consist of the following items.
 
diff --git a/spec/dir-spec/serving-bandwidth-list-files.md b/spec/dir-spec/serving-bandwidth-list-files.md
index 2680eb8..6860a6b 100644
--- a/spec/dir-spec/serving-bandwidth-list-files.md
+++ b/spec/dir-spec/serving-bandwidth-list-files.md
@@ -1,6 +1,6 @@
 <a id="dir-spec.txt-3.4.3"></a>
 
-### Serving bandwidth list files { #serving-bwlist }
+# Serving bandwidth list files { #serving-bwlist }
 
 If an authority has used a bandwidth list file to generate a vote
 document it SHOULD make it available at
diff --git a/spec/dir-spec/uploading-relay-documents.md b/spec/dir-spec/uploading-relay-documents.md
index d354068..da34943 100644
--- a/spec/dir-spec/uploading-relay-documents.md
+++ b/spec/dir-spec/uploading-relay-documents.md
@@ -1,6 +1,6 @@
 <a id="dir-spec.txt-2.1"></a>
 
-## Uploading server descriptors and extra-info documents
+# Uploading server descriptors and extra-info documents
 
 ORs SHOULD generate a new server descriptor and a new extra-info
 document whenever any of the following events have occurred:
diff --git a/spec/path-spec/cannibalizing-circuits.md b/spec/path-spec/cannibalizing-circuits.md
index 2d15175..3987839 100644
--- a/spec/path-spec/cannibalizing-circuits.md
+++ b/spec/path-spec/cannibalizing-circuits.md
@@ -1,6 +1,6 @@
 <a id="path-spec.txt-2.3"></a>
 
-## Cannibalizing circuits
+# Cannibalizing circuits
 
 If we need a circuit and have a clean one already established, in
 some cases we can adapt the clean circuit for our new
diff --git a/spec/path-spec/handling-failure.md b/spec/path-spec/handling-failure.md
index a05fc58..27bad6a 100644
--- a/spec/path-spec/handling-failure.md
+++ b/spec/path-spec/handling-failure.md
@@ -1,6 +1,6 @@
 <a id="path-spec.txt-2.5"></a>
 
-## Handling failure
+# Handling failure
 
 If an attempt to extend a circuit fails (either because the first create
 failed or a subsequent extend failed) then the circuit is torn down and is
diff --git a/spec/path-spec/learning-timeouts.md b/spec/path-spec/learning-timeouts.md
index e53ab66..3685274 100644
--- a/spec/path-spec/learning-timeouts.md
+++ b/spec/path-spec/learning-timeouts.md
@@ -1,13 +1,13 @@
 <a id="path-spec.txt-2.4"></a>
 
-## Learning when to give up ("timeout") on circuit construction {#timing-out}
+# Learning when to give up ("timeout") on circuit construction {#timing-out}
 
 Since version 0.2.2.8-alpha, Tor clients attempt to learn when to give
 up on circuits based on network conditions.
 
 <a id="path-spec.txt-2.4.1"></a>
 
-### Distribution choice
+## Distribution choice
 
 Based on studies of build times, we found that the distribution of
 circuit build times appears to be a Frechet distribution (and a multi-modal
@@ -19,7 +19,7 @@ distribution with a single Pareto curve.
 
 <a id="path-spec.txt-2.4.2"></a>
 
-### How much data to record {#observations}
+## How much data to record {#observations}
 
 From our observations, the minimum number of circuit build times for a
 reasonable fit appears to be on the order of 100. However, to keep a
@@ -48,7 +48,7 @@ that build time binning is still needed for parameter estimation.
 
 <a id="path-spec.txt-2.4.3"></a>
 
-### Parameter estimation
+## Parameter estimation
 
 Once 'cbtmincircs' build times are recorded, Tor clients update the
 distribution parameters and recompute the timeout every circuit completion
@@ -122,7 +122,7 @@ but at least 60 seconds:
 
 <a id="path-spec.txt-2.4.3"></a>
 
-### Calculating timeouts thresholds for circuits of different lengths {#different-lengths}
+## Calculating timeouts thresholds for circuits of different lengths {#different-lengths}
 
 The timeout_ms and close_ms estimates above are good only for 3-hop
 circuits, since only 3-hop circuits are recorded in the list of build
@@ -145,7 +145,7 @@ required with the Xth hop.
 
 <a id="path-spec.txt-2.4.4"></a>
 
-### How to record timeouts {#recording-timeouts}
+## How to record timeouts {#recording-timeouts}
 
 Pareto estimators begin to lose their accuracy if the tail is omitted.
 Hence, Tor clients actually calculate two timeouts: a usage timeout, and a
@@ -166,7 +166,7 @@ offline.
 
 <a id="path-spec.txt-2.4.5"></a>
 
-### Detecting Changing Network Conditions {#changes-in-network}
+## Detecting Changing Network Conditions {#changes-in-network}
 
 Tor clients attempt to detect both network connectivity loss and drastic
 changes in the timeout characteristics.
@@ -187,7 +187,7 @@ we start with a new, empty state.
 
 <a id="path-spec.txt-2.4.6"></a>
 
-### Consensus parameters governing behavior {#parameters}
+## Consensus parameters governing behavior {#parameters}
 
 Clients that implement circuit build timeout learning should obey the
 following consensus parameters that govern behavior, in order to allow
diff --git a/spec/path-spec/path-selection-constraints.md b/spec/path-spec/path-selection-constraints.md
index 694a052..d31e45f 100644
--- a/spec/path-spec/path-selection-constraints.md
+++ b/spec/path-spec/path-selection-constraints.md
@@ -1,6 +1,6 @@
 <a id="path-spec.txt-2.2"></a>
 
-## Path selection and constraints
+# Path selection and constraints
 
 We choose the path for each new circuit before we build it.  We choose the
 exit node first, followed by the other nodes in the circuit, front to
@@ -88,7 +88,7 @@ mind.  Each kind of request puts certain constraints on paths:
 
 <a id="path-spec.txt-2.2.1"></a>
 
-### Choosing an exit
+## Choosing an exit
 
 If we know what IP address we want to connect to or resolve, we can
 trivially tell whether a given router will support it by simulating
@@ -107,7 +107,7 @@ themselves as listing bad exits.
 
 <a id="path-spec.txt-2.2.2"></a>
 
-### User configuration
+## User configuration
 
 Users can alter the default behavior for path selection with configuration
 options.
diff --git a/spec/path-spec/when-we-build.md b/spec/path-spec/when-we-build.md
index ca9b704..cbcf7da 100644
--- a/spec/path-spec/when-we-build.md
+++ b/spec/path-spec/when-we-build.md
@@ -1,10 +1,10 @@
 <a id="path-spec.txt-2.1"></a>
 
-## When we build
+# When we build
 
 <a id="path-spec.txt-2.1.0"></a>
 
-### We don't build circuits until we have enough directory info
+## We don't build circuits until we have enough directory info
 
 There's a class of possible attacks where our directory servers
 only give us information about the relays that they would like us
@@ -59,7 +59,7 @@ fraction of middle relays.
 
 <a id="path-spec.txt-2.1.1"></a>
 
-### Clients build circuits preemptively
+## Clients build circuits preemptively
 
 When running as a client, Tor tries to maintain at least a certain
 number of clean circuits, so that new streams can be handled
@@ -94,7 +94,7 @@ persistent medium.
 
 <a id="path-spec.txt-2.1.2"></a>
 
-### Clients build circuits on demand
+## Clients build circuits on demand
 
 Additionally, when a client request exists that no circuit (built or
 pending) might support, we create a new circuit to support the request.
@@ -114,7 +114,7 @@ clean; see Section 2.3 (cannibalizing circuits) for details.
 
 <a id="path-spec.txt-2.1.3"></a>
 
-### Relays build circuits for testing reachability and bandwidth
+## Relays build circuits for testing reachability and bandwidth
 
 Tor relays test reachability of their ORPort once they have
 successfully built a circuit (on startup and whenever their IP address
@@ -137,13 +137,13 @@ this purpose.
 
 <a id="path-spec.txt-2.1.4"></a>
 
-### Hidden-service circuits
+## Hidden-service circuits
 
 See section 4 below.
 
 <a id="path-spec.txt-2.1.5"></a>
 
-### Rate limiting of failed circuits
+## Rate limiting of failed circuits
 
 If we fail to build a circuit N times in a X second period (see Section
 2.3 for how this works), we stop building circuits until the X seconds
@@ -152,7 +152,7 @@ XXXX
 
 <a id="path-spec.txt-2.1.6"></a>
 
-### When to tear down circuits
+## When to tear down circuits
 
 Clients should tear down circuits (in general) only when those circuits
 have no streams on them.  Additionally, clients should tear-down
diff --git a/spec/pt-spec/configuration-environment.md b/spec/pt-spec/configuration-environment.md
index 767c37b..f2f0eb5 100644
--- a/spec/pt-spec/configuration-environment.md
+++ b/spec/pt-spec/configuration-environment.md
@@ -1,6 +1,6 @@
 <a id="pt-spec.txt-3.2"></a>
 
-## Pluggable Transport Configuration Environment Variables {#envvars}
+# Pluggable Transport Configuration Environment Variables {#envvars}
 
 All Pluggable Transport proxy instances are configured by their
 parent process at launch time via a set of well defined
@@ -12,7 +12,7 @@ specification.
 
 <a id="pt-spec.txt-3.2.1"></a>
 
-### Common Environment Variables {#common}
+## Common Environment Variables {#common}
 
 When launching either a client or server Pluggable Transport proxy,
 the following common environment variables MUST be set.
@@ -102,7 +102,7 @@ TOR_PT_OUTBOUND_BIND_ADDRESS_V6=\[2001:db8::4\]
 
 <a id="pt-spec.txt-3.2.2"></a>
 
-### Pluggable Transport Client Environment Variables {#client}
+## Pluggable Transport Client Environment Variables {#client}
 
 Client-side Pluggable Transport forward proxies are configured
 via the following environment variables.
@@ -143,7 +143,7 @@ Examples:
 
 <a id="pt-spec.txt-3.2.3"></a>
 
-### Pluggable Transport Server Environment Variables {#server}
+## Pluggable Transport Server Environment Variables {#server}
 
 Server-side Pluggable Transport reverse proxies are configured
 via the following environment variables.
diff --git a/spec/pt-spec/ipc.md b/spec/pt-spec/ipc.md
index 8c5d001..d419fba 100644
--- a/spec/pt-spec/ipc.md
+++ b/spec/pt-spec/ipc.md
@@ -1,6 +1,6 @@
 <a id="pt-spec.txt-3.3"></a>
 
-## Pluggable Transport To Parent Process Communication
+# Pluggable Transport To Parent Process Communication
 
 All Pluggable Transport Proxies communicate to the parent process
 via writing NL-terminated lines to stdout.  The line metaformat is:
@@ -21,7 +21,7 @@ unknown keywords.
 
 <a id="pt-spec.txt-3.3.1"></a>
 
-### Common Messages
+## Common Messages
 
 When a PT proxy first starts up, it must determine which version
 of the Pluggable Transports Specification to use to configure
@@ -96,7 +96,7 @@ ENV-ERROR No TOR_PT_AUTH_COOKIE_FILE when TOR_PT_EXTENDED_SERVER_PORT set
 
 <a id="pt-spec.txt-3.3.2"></a>
 
-### Pluggable Transport Client Messages {#client-messages}
+## Pluggable Transport Client Messages {#client-messages}
 
 After negotiating the Pluggable Transport Specification version,
 PT client proxies MUST first validate "TOR_PT_PROXY" (3.2.2) if
@@ -178,7 +178,7 @@ Notes:
 
 <a id="pt-spec.txt-3.3.3"></a>
 
-### Pluggable Transport Server Messages {#server-messages}
+## Pluggable Transport Server Messages {#server-messages}
 
 PT server reverse proxies iterate over the requested transports
 in "TOR_PT_CLIENT_TRANSPORTS" and initialize the listeners.
@@ -245,7 +245,7 @@ initialization is complete.
 
 <a id="pt-spec.txt-3.3.4"></a>
 
-### Pluggable Transport Log Message {#log-messages}
+## Pluggable Transport Log Message {#log-messages}
 
 This message is for a client or server PT to be able to signal back to the
 parent process via stdout or stderr any log messages.
@@ -276,7 +276,7 @@ Example:
 
 <a id="pt-spec.txt-3.3.5"></a>
 
-### Pluggable Transport Status Message {#status-messages}
+## Pluggable Transport Status Message {#status-messages}
 
 This message is for a client or server PT to be able to signal back to the
 parent process via stdout or stderr any status messages.
diff --git a/spec/pt-spec/naming.md b/spec/pt-spec/naming.md
index 394b420..f86c5e3 100644
--- a/spec/pt-spec/naming.md
+++ b/spec/pt-spec/naming.md
@@ -1,6 +1,6 @@
 <a id="pt-spec.txt-3.1"></a>
 
-## Pluggable Transport Naming
+# Pluggable Transport Naming
 
 Pluggable Transport names serve as unique identifiers, and every
 PT MUST have a unique name.
diff --git a/spec/pt-spec/per-connection-args.md b/spec/pt-spec/per-connection-args.md
index 90becab..e1a133a 100644
--- a/spec/pt-spec/per-connection-args.md
+++ b/spec/pt-spec/per-connection-args.md
@@ -1,6 +1,6 @@
 <a id="pt-spec.txt-3.5"></a>
 
-## Pluggable Transport Client Per-Connection Arguments
+# Pluggable Transport Client Per-Connection Arguments
 
 Certain PT transport protocols require that the client provides
 per-connection arguments when making outgoing connections.  On
diff --git a/spec/pt-spec/shutdown.md b/spec/pt-spec/shutdown.md
index cd826d9..aeba498 100644
--- a/spec/pt-spec/shutdown.md
+++ b/spec/pt-spec/shutdown.md
@@ -1,6 +1,6 @@
 <a id="pt-spec.txt-3.4"></a>
 
-## Pluggable Transport Shutdown
+# Pluggable Transport Shutdown
 
 The recommended way for Pluggable Transport using applications and
 Pluggable Transports to handle graceful shutdown is as follows.
diff --git a/spec/rend-spec/deriving-keys.md b/spec/rend-spec/deriving-keys.md
index cbf62fe..e3cca79 100644
--- a/spec/rend-spec/deriving-keys.md
+++ b/spec/rend-spec/deriving-keys.md
@@ -1,6 +1,6 @@
 <a id="rend-spec-v3.txt-2.1"></a>
 
-## Deriving blinded keys and subcredentials {#SUBCRED}
+# Deriving blinded keys and subcredentials {#SUBCRED}
 
 In each time period (see \[TIME-PERIODS\] for a definition of time
 periods), a hidden service host uses a different blinded private key
@@ -58,7 +58,7 @@ Which Tor servers hosts a hidden service depends on:
 
 <a id="rend-spec-v3.txt-2.2.1"></a>
 
-### Dividing time into periods {#TIME-PERIODS}
+## Dividing time into periods {#TIME-PERIODS}
 
 To prevent a single set of hidden service directory from becoming a
 target by adversaries looking to permanently censor a hidden service,
@@ -90,7 +90,7 @@ after the epoch, at 2016-04-12 12:00 UTC, and ended at 16904*1440*60 +
 
 <a id="rend-spec-v3.txt-2.2.2"></a>
 
-### When to publish a hidden service descriptor {#WHEN-HSDESC}
+## When to publish a hidden service descriptor {#WHEN-HSDESC}
 
 Hidden services periodically publish their descriptor to the responsible
 HSDirs. The set of responsible HSDirs is determined as specified in
@@ -104,7 +104,7 @@ descriptor again to the responsible HSDirs for that time period.
 
 <a id="rend-spec-v3.txt-2.2.2.1"></a>
 
-#### Overlapping descriptors {#OVERLAPPING-DESCS}
+### Overlapping descriptors {#OVERLAPPING-DESCS}
 
 Hidden services need to upload multiple descriptors so that they can be
 reachable to clients with older or newer consensuses than them. Services
@@ -125,7 +125,7 @@ achieved.
 
 <a id="rend-spec-v3.txt-2.2.3"></a>
 
-### Where to publish a hidden service descriptor {#WHERE-HSDESC}
+## Where to publish a hidden service descriptor {#WHERE-HSDESC}
 
 This section specifies how the HSDir hash ring is formed at any given
 time. Whenever a time value is needed (e.g. to get the current time period
@@ -190,7 +190,7 @@ choosing the spread for a replica.
 
 <a id="rend-spec-v3.txt-2.2.4"></a>
 
-### Using time periods and SRVs to fetch/upload HS descriptors {#FETCHUPLOADDESC}
+## Using time periods and SRVs to fetch/upload HS descriptors {#FETCHUPLOADDESC}
 
 Hidden services and clients need to make correct use of time periods (TP)
 and shared random values (SRVs) to successfully fetch and upload
@@ -228,7 +228,7 @@ Let's start with an illustration of the system:
 
 <a id="rend-spec-v3.txt-2.2.4.1"></a>
 
-#### Client behavior for fetching descriptors {#CLIENTFETCH}
+### Client behavior for fetching descriptors {#CLIENTFETCH}
 
 And here is how clients use TPs and SRVs to fetch descriptors:
 
@@ -258,7 +258,7 @@ after SRV#2, it will still use TP#1 and SRV#1.
 
 <a id="rend-spec-v3.txt-2.2.4.2"></a>
 
-#### Service behavior for uploading descriptors {#SERVICEUPLOAD}
+### Service behavior for uploading descriptors {#SERVICEUPLOAD}
 
 As discussed above, services maintain two active descriptors at any time. We
 call these the "first" and "second" service descriptors. Services rotate
@@ -272,7 +272,7 @@ values based on their position in the graph above. Here is the logic:
 
 <a id="rend-spec-v3.txt-2.2.4.2.1"></a>
 
-##### First descriptor upload logic {#FIRSTDESCUPLOAD}
+#### First descriptor upload logic {#FIRSTDESCUPLOAD}
 
 Here is the service logic for uploading its first descriptor:
 
@@ -308,7 +308,7 @@ first descriptor using TP#1 and SRV#1.
 
 <a id="rend-spec-v3.txt-2.2.4.2.2"></a>
 
-##### Second descriptor upload logic {#SECONDDESCUPLOAD}
+#### Second descriptor upload logic {#SECONDDESCUPLOAD}
 
 Here is the service logic for uploading its second descriptor:
 
@@ -342,7 +342,7 @@ second descriptor using TP#2 and SRV#2.
 
 <a id="rend-spec-v3.txt-2.2.4.3"></a>
 
-#### Directory behavior for handling descriptor uploads \[DIRUPLOAD\]
+### Directory behavior for handling descriptor uploads \[DIRUPLOAD\]
 
 Upon receiving a hidden service descriptor publish request, directories MUST
 check the following:
@@ -368,7 +368,7 @@ necessary client credentials (for decrypting the second layer).
 
 <a id="rend-spec-v3.txt-2.2.5"></a>
 
-### Expiring hidden service descriptors {#EXPIRE-DESC}
+## Expiring hidden service descriptors {#EXPIRE-DESC}
 
 Hidden services set their descriptor's "descriptor-lifetime" field to 180
 minutes (3 hours). Hidden services ensure that their descriptor will remain
@@ -381,7 +381,7 @@ the time period has changed).
 
 <a id="rend-spec-v3.txt-2.2.6"></a>
 
-### URLs for anonymous uploading and downloading {#urls}
+## URLs for anonymous uploading and downloading {#urls}
 
 Hidden service descriptors conforming to this specification are uploaded
 with an HTTP POST request to the URL `/tor/hs/<version>/publish` relative to
@@ -395,7 +395,7 @@ anything else.
 
 <a id="rend-spec-v3.txt-2.2.7"></a>
 
-### Client-side validation of onion addresses {#addr-validation}
+## Client-side validation of onion addresses {#addr-validation}
 
 When a Tor client receives a prop224 onion address from the user, it
 MUST first validate the onion address before attempting to connect or
diff --git a/spec/rend-spec/hsdesc-encrypt.md b/spec/rend-spec/hsdesc-encrypt.md
index 10a7d77..06713a2 100644
--- a/spec/rend-spec/hsdesc-encrypt.md
+++ b/spec/rend-spec/hsdesc-encrypt.md
@@ -1,6 +1,6 @@
 <a id="rend-spec-v3.txt-2.5"></a>
 
-## Hidden service descriptors: encryption format {#HS-DESC-ENC}
+# Hidden service descriptors: encryption format {#HS-DESC-ENC}
 
 Hidden service descriptors are protected by two layers of encryption.
 Clients need to decrypt both layers to connect to the hidden service.
@@ -12,7 +12,7 @@ and protects against entities that do not possess valid client credentials.
 
 <a id="rend-spec-v3.txt-2.5.1"></a>
 
-### First layer of encryption {#HS-DESC-FIRST-LAYER}
+## First layer of encryption {#HS-DESC-FIRST-LAYER}
 
 The first layer of HS descriptor encryption is designed to protect
 descriptor confidentiality against entities who don't know the public
@@ -20,7 +20,7 @@ identity key of the hidden service.
 
 <a id="rend-spec-v3.txt-2.5.1.1"></a>
 
-#### First layer encryption logic {#first-layer-logic}
+### First layer encryption logic {#first-layer-logic}
 
 The encryption keys and format for the first layer of encryption are
 generated as specified in \[HS-DESC-ENCRYPTION-KEYS\] with customization
@@ -43,7 +43,7 @@ multiple of 10k bytes.
 
 <a id="rend-spec-v3.txt-2.5.1.2"></a>
 
-#### First layer plaintext format {#first-layer-plaintext}
+### First layer plaintext format {#first-layer-plaintext}
 
 After clients decrypt the first layer of encryption, they need to parse the
 plaintext to get to the second layer ciphertext which is contained in the
@@ -138,7 +138,7 @@ Here are all the supported fields:
 
 <a id="rend-spec-v3.txt-2.5.1.3"></a>
 
-#### Client behavior {#FIRST-LAYER-CLIENT-BEHAVIOR}
+### Client behavior {#FIRST-LAYER-CLIENT-BEHAVIOR}
 
 ```text
     The goal of clients at this stage is to decrypt the "encrypted" field as
@@ -160,7 +160,7 @@ Here are all the supported fields:
 
 <a id="rend-spec-v3.txt-2.5.1.4"></a>
 
-#### Hiding client authorization data {#hiding-client-auth}
+### Hiding client authorization data {#hiding-client-auth}
 
 ```text
     Hidden services should avoid leaking whether client authorization is
@@ -183,7 +183,7 @@ Here are all the supported fields:
 
 <a id="rend-spec-v3.txt-2.5.2"></a>
 
-### Second layer of encryption {#HS-DESC-SECOND-LAYER}
+## Second layer of encryption {#HS-DESC-SECOND-LAYER}
 
 The second layer of descriptor encryption is designed to protect descriptor
 confidentiality against unauthorized clients. If client authorization is
@@ -196,7 +196,7 @@ does not offer any additional security, but is still used.
 
 <a id="rend-spec-v3.txt-2.5.2.1"></a>
 
-#### Second layer encryption keys {#second-layer-keys}
+### Second layer encryption keys {#second-layer-keys}
 
 The encryption keys and format for the second layer of encryption are
 generated as specified in \[HS-DESC-ENCRYPTION-KEYS\] with customization
@@ -213,7 +213,7 @@ parameters as follows:
 
 <a id="rend-spec-v3.txt-2.5.2.2"></a>
 
-#### Second layer plaintext format {#second-layer-plaintext}
+### Second layer plaintext format {#second-layer-plaintext}
 
 After decrypting the second layer ciphertext, clients can finally learn the
 list of intro points etc. The plaintext has the following format:
@@ -396,7 +396,7 @@ newline.
 
 <a id="rend-spec-v3.txt-2.5.3"></a>
 
-### Deriving hidden service descriptor encryption keys {#HS-DESC-ENCRYPTION-KEYS}
+## Deriving hidden service descriptor encryption keys {#HS-DESC-ENCRYPTION-KEYS}
 
 In this section we present the generic encryption format for hidden service
 descriptors. We use the same encryption format in both encryption layers,
@@ -439,7 +439,7 @@ Here is the key generation logic:
 
 <a id="rend-spec-v3.txt-2.5.4"></a>
 
-### Number of introduction points {#NUM_INTRO_POINT}
+## Number of introduction points {#NUM_INTRO_POINT}
 
 This section defines how many introduction points an hidden service
 descriptor can have at minimum, by default and the maximum:
diff --git a/spec/rend-spec/hsdesc-outer.md b/spec/rend-spec/hsdesc-outer.md
index 5f4b5de..ea623b8 100644
--- a/spec/rend-spec/hsdesc-outer.md
+++ b/spec/rend-spec/hsdesc-outer.md
@@ -1,6 +1,6 @@
 <a id="rend-spec-v3.txt-2.4"></a>
 
-## Hidden service descriptors: outer wrapper \[DESC-OUTER\]
+# Hidden service descriptors: outer wrapper \[DESC-OUTER\]
 
 The format for a hidden service descriptor is as follows, using the
 meta-format from dir-spec.txt.
diff --git a/spec/rend-spec/shared-random.md b/spec/rend-spec/shared-random.md
index b06558f..e6b2452 100644
--- a/spec/rend-spec/shared-random.md
+++ b/spec/rend-spec/shared-random.md
@@ -1,6 +1,6 @@
 <a id="rend-spec-v3.txt-2.3"></a>
 
-## Publishing shared random values {#PUB-SHAREDRANDOM}
+# Publishing shared random values {#PUB-SHAREDRANDOM}
 
 Our design for limiting the predictability of HSDir upload locations
 relies on a shared random value (SRV) that isn't predictable in advance or
@@ -19,7 +19,7 @@ According to proposal 250, we add two new lines in consensuses:
 
 <a id="rend-spec-v3.txt-2.3.1"></a>
 
-### Client behavior in the absence of shared random values {#client-disaster}
+## Client behavior in the absence of shared random values {#client-disaster}
 
 If the previous or current shared random value cannot be found in a
 consensus, then Tor clients and services need to generate their own random
@@ -36,7 +36,7 @@ found originally.
 
 <a id="rend-spec-v3.txt-2.3.2"></a>
 
-### Hidden services and changing shared random values {#service-problems}
+## Hidden services and changing shared random values {#service-problems}
 
 It's theoretically possible that the consensus shared random values will
 change or disappear in the middle of a time period because of directory
diff --git a/spec/tor-spec/closing-streams.md b/spec/tor-spec/closing-streams.md
index 5fa84a8..7182f48 100644
--- a/spec/tor-spec/closing-streams.md
+++ b/spec/tor-spec/closing-streams.md
@@ -1,6 +1,6 @@
 <a id="tor-spec.txt-6.3"></a>
 
-## Closing streams
+# Closing streams
 
 When an anonymized TCP connection is closed, or an edge node
 encounters error on any stream, it sends a 'RELAY_END' cell along the
diff --git a/spec/tor-spec/create-created-cells.md b/spec/tor-spec/create-created-cells.md
index 2cc5f9d..d182f48 100644
--- a/spec/tor-spec/create-created-cells.md
+++ b/spec/tor-spec/create-created-cells.md
@@ -1,6 +1,6 @@
 <a id="tor-spec.txt-5.1"></a>
 
-## CREATE and CREATED cells
+# CREATE and CREATED cells
 
 Users set up circuits incrementally, one hop at a time. To create a
 new circuit, OPs send a CREATE/CREATE2 cell to the first node, with
@@ -71,7 +71,7 @@ DESTROY cell to tear down the circuit.
 
 <a id="tor-spec.txt-5.1.1"></a>
 
-### Choosing circuit IDs in create cells {#choosing-circid}
+## Choosing circuit IDs in create cells {#choosing-circid}
 
 The CircID for a CREATE/CREATE2 cell is a nonzero integer, selected
 by the node (OP or OR) that sends the CREATE/CREATED2 cell.
@@ -105,7 +105,7 @@ randomly chosen CircID values are all in use (today's Tor stops after 64).
 
 <a id="tor-spec.txt-5.1.2"></a>
 
-### EXTEND and EXTENDED cells
+## EXTEND and EXTENDED cells
 
 To extend an existing circuit, the client sends an EXTEND or EXTEND2
 RELAY_EARLY cell to the last node in the circuit.
@@ -206,7 +206,7 @@ use the format with 'client handshake type tag'.
 
 <a id="tor-spec.txt-5.1.3"></a>
 
-### The "TAP" handshake {#TAP}
+## The "TAP" handshake {#TAP}
 
 This handshake uses Diffie-Hellman in Z_p and RSA to compute a set of
 shared keys which the client knows are shared only with a particular
@@ -260,7 +260,7 @@ and 'derivative key data' value via the KDF-TOR function in 5.2.1.
 
 <a id="tor-spec.txt-5.1.4"></a>
 
-### The "ntor" handshake {#ntor}
+## The "ntor" handshake {#ntor}
 
 This handshake uses a set of DH handshakes to compute a set of
 shared keys which the client knows are shared only with a particular
@@ -339,7 +339,7 @@ described in 5.2.2 and the tag m_expand.
 
 <a id="tor-spec.txt-5.1.4.1"></a>
 
-#### The "ntor-v3" handshake {#ntor-v3}
+### The "ntor-v3" handshake {#ntor-v3}
 
 This handshake extends the ntor handshake to include support
 for extra data transmitted as part of the handshake.  Both
@@ -495,7 +495,7 @@ their circuit keys.
 
 <a id="tor-spec.txt-5.1.5"></a>
 
-### CREATE_FAST/CREATED_FAST cells {#create_fast}
+## CREATE_FAST/CREATED_FAST cells {#create_fast}
 
 When initializing the first hop of a circuit, the OP has already
 established the OR's identity and negotiated a secret key using TLS.
@@ -529,7 +529,7 @@ networkstatus parameter as described in dir-spec.txt.
 
 <a id="tor-spec.txt-5.1.6"></a>
 
-### Additional data in CREATE/CREATED cells {#additional-data}
+## Additional data in CREATE/CREATED cells {#additional-data}
 
 Some handshakes (currently ntor-v3 defined above) allow the client or the
 relay to send additional data as part of the handshake.  When used in a
diff --git a/spec/tor-spec/creating-circuits.md b/spec/tor-spec/creating-circuits.md
index c69d2cf..23e5a83 100644
--- a/spec/tor-spec/creating-circuits.md
+++ b/spec/tor-spec/creating-circuits.md
@@ -1,6 +1,6 @@
 <a id="tor-spec.txt-5.3"></a>
 
-## Creating circuits
+# Creating circuits
 
 When creating a circuit through the network, the circuit creator
 (OP) performs the following steps:
@@ -81,7 +81,7 @@ network latency too greatly.)
 
 <a id="tor-spec.txt-5.3.1"></a>
 
-### Canonical connections
+## Canonical connections
 
 It is possible for an attacker to launch a man-in-the-middle attack
 against a connection by telling OR Alice to extend to OR Bob at some
diff --git a/spec/tor-spec/opening-streams.md b/spec/tor-spec/opening-streams.md
index 956e2c8..5c264cb 100644
--- a/spec/tor-spec/opening-streams.md
+++ b/spec/tor-spec/opening-streams.md
@@ -1,6 +1,6 @@
 <a id="tor-spec.txt-6.2"></a>
 
-## Opening streams and transferring data
+# Opening streams and transferring data
 
 To open a new anonymized TCP connection, the OP chooses an open
 circuit to an exit that may be able to connect to the destination
@@ -90,7 +90,7 @@ a cell, the OR or OP must drop it.
 
 <a id="tor-spec.txt-6.2.1"></a>
 
-### Opening a directory stream
+## Opening a directory stream
 
 If a Tor relay is a directory server, it should respond to a
 RELAY_BEGIN_DIR cell as if it had received a BEGIN cell requesting a
diff --git a/spec/tor-spec/relay-cells.md b/spec/tor-spec/relay-cells.md
index a40f06a..b827d0f 100644
--- a/spec/tor-spec/relay-cells.md
+++ b/spec/tor-spec/relay-cells.md
@@ -1,6 +1,6 @@
 <a id="tor-spec.txt-6.1"></a>
 
-## Relay cells
+# Relay cells
 
 Within a circuit, the OP and the end node use the contents of
 RELAY packets to tunnel end-to-end commands and TCP connections
@@ -116,7 +116,7 @@ still count with respect to the digests and flow control windows, though.
 
 <a id="tor-spec.txt-6.1.1"></a>
 
-### Calculating the 'Digest' field {#digest-field}
+## Calculating the 'Digest' field {#digest-field}
 
 The 'Digest' field itself serves the purpose to check if a cell has been
 fully decrypted, that is, all onion layers have been removed.  Having a
diff --git a/spec/tor-spec/relay-early.md b/spec/tor-spec/relay-early.md
index 2517dcc..cefa790 100644
--- a/spec/tor-spec/relay-early.md
+++ b/spec/tor-spec/relay-early.md
@@ -1,6 +1,6 @@
 <a id="tor-spec.txt-5.6"></a>
 
-## Handling relay_early cells
+# Handling relay_early cells
 
 A RELAY_EARLY cell is designed to limit the length any circuit can reach.
 When an OR receives a RELAY_EARLY cell, and the next node in the circuit
diff --git a/spec/tor-spec/remote-hostname-lookup.md b/spec/tor-spec/remote-hostname-lookup.md
index ba78cf1..8482660 100644
--- a/spec/tor-spec/remote-hostname-lookup.md
+++ b/spec/tor-spec/remote-hostname-lookup.md
@@ -1,6 +1,6 @@
 <a id="tor-spec.txt-6.4"></a>
 
-## Remote hostname lookup
+# Remote hostname lookup
 
 To find the address associated with a hostname, the OP sends a
 RELAY_RESOLVE cell containing the hostname to be resolved with a NUL
diff --git a/spec/tor-spec/routing-relay-cells.md b/spec/tor-spec/routing-relay-cells.md
index e2c784c..07057b0 100644
--- a/spec/tor-spec/routing-relay-cells.md
+++ b/spec/tor-spec/routing-relay-cells.md
@@ -1,10 +1,10 @@
 <a id="tor-spec.txt-5.5"></a>
 
-## Routing relay cells
+# Routing relay cells
 
 <a id="tor-spec.txt-5.5.1"></a>
 
-### Circuit ID Checks
+## Circuit ID Checks
 
 When a node wants to send a RELAY or RELAY_EARLY cell, it checks the cell's
 circID and determines whether the corresponding circuit along that
@@ -16,14 +16,14 @@ that connection. If not, the node drops the cell.
 
 <a id="tor-spec.txt-5.5.2"></a>
 
-### Forward Direction
+## Forward Direction
 
 The forward direction is the direction that CREATE/CREATE2 cells
 are sent.
 
 <a id="tor-spec.txt-5.5.2.1"></a>
 
-#### Routing from the Origin
+### Routing from the Origin
 
 When a relay cell is sent from an OP, the OP encrypts the payload
 with the stream cipher as follows:
@@ -37,7 +37,7 @@ with the stream cipher as follows:
 
 <a id="tor-spec.txt-5.5.2.2"></a>
 
-#### Relaying Forward at Onion Routers
+### Relaying Forward at Onion Routers
 
 When a forward relay cell is received by an OR, it decrypts the payload
 with the stream cipher, as follows:
@@ -59,14 +59,14 @@ For more information, see section 6 below.
 
 <a id="tor-spec.txt-5.5.3"></a>
 
-### Backward Direction
+## Backward Direction
 
 The backward direction is the opposite direction from
 CREATE/CREATE2 cells.
 
 <a id="tor-spec.txt-5.5.3.1"></a>
 
-#### Relaying Backward at Onion Routers
+### Relaying Backward at Onion Routers
 
 When a backward relay cell is received by an OR, it encrypts the payload
 with the stream cipher, as follows:
@@ -78,7 +78,7 @@ with the stream cipher, as follows:
 
 <a id="tor-spec.txt-5.5.3"></a>
 
-### Routing to the Origin
+## Routing to the Origin
 
 When a relay cell arrives at an OP, the OP decrypts the payload
 with the stream cipher as follows:
diff --git a/spec/tor-spec/setting-circuit-keys.md b/spec/tor-spec/setting-circuit-keys.md
index f299f81..95a5b27 100644
--- a/spec/tor-spec/setting-circuit-keys.md
+++ b/spec/tor-spec/setting-circuit-keys.md
@@ -1,10 +1,10 @@
 <a id="tor-spec.txt-5.2"></a>
 
-## Setting circuit keys
+# Setting circuit keys
 
 <a id="tor-spec.txt-5.2.1"></a>
 
-### KDF-TOR
+## KDF-TOR
 
 This key derivation function is used by the TAP and CREATE_FAST
 handshakes, and in the current hidden service protocol. It shouldn't
@@ -36,7 +36,7 @@ Kb is used to encrypt the stream of data going from the OR to the OP.
 
 <a id="tor-spec.txt-5.2.2"></a>
 
-### KDF-RFC5869
+## KDF-RFC5869
 
 For newer KDF needs, Tor uses the key derivation function HKDF from
 RFC5869, instantiated with SHA256.  (This is due to a construction
diff --git a/spec/tor-spec/tearing-down-circuits.md b/spec/tor-spec/tearing-down-circuits.md
index f06b231..66e71bd 100644
--- a/spec/tor-spec/tearing-down-circuits.md
+++ b/spec/tor-spec/tearing-down-circuits.md
@@ -1,6 +1,6 @@
 <a id="tor-spec.txt-5.4"></a>
 
-## Tearing down circuits
+# Tearing down circuits
 
 Circuits are torn down when an unrecoverable error occurs along
 the circuit, or when all streams on a circuit are closed and the