docs: clean up .title-refs

docs/architecture.md

@@ -65,7 +65,7 @@ signer, and returns the encoded signature back to the client.
 The authentication/authorization model is probably the most complex part
 of the autograph core. Clients are required to provide a Hawk
 authorization with payload signature issued by a user trusted by
-autograph. The [authorization]{.title-ref} section of the autograph.yaml
+autograph. The `authorization` section of the autograph.yaml
 configuration lists permitted users, along with the signers each is
 allowed to use.
 
@@ -76,7 +76,7 @@ authenticated user is permitted to use the requested signer. Should all
 these steps succeed, the signing request is passed along to a signer.
 
 Signers are separate Go packages defined under the
-[github.com/mozilla-services/autograph/signer/\...]{.title-ref} package.
+`github.com/mozilla-services/autograph/signer/\...` package.
 Each signer implements a specific type of signing, for example:
 
 -   **github.com/mozilla-services/autograph/signer/contentsignature**
@@ -95,10 +95,10 @@ Each signer implements a specific type of signing, for example:
     implementation in Autograph is described in the [xpi signer\'s
     README](https://github.com/mozilla-services/autograph/blob/main/signer/xpi/README.md).
 
-Signers can implement three interfaces: [FileSigner]{.title-ref},
-[DataSigner]{.title-ref} and [HashSigner]{.title-ref}, which correspond
-to the endpoints [/sign/file]{.title-ref}, [/sign/data]{.title-ref} and
-[/sign/hash]{.title-ref} respectively. When a signing request is
+Signers can implement three interfaces: `FileSigner`,
+`DataSigner` and `HashSigner`, which correspond
+to the endpoints `/sign/file`, `/sign/data` and
+`/sign/hash` respectively. When a signing request is
 received, autograph checks if the requested signer implements the
 interface for the type of signature requested. If the requested signer
 doesn\'t support a given mode (eg. the xpi signer doesn\'t support the

docs/configuration.md

@@ -1,9 +1,8 @@
 # Configuration
 
-
-The configuration lives in [autograph.yaml]{.title-ref} and is expected
-in [/etc/autograph/autograph.yaml]{.title-ref} (use flag
-[-c]{.title-ref} to provide an alternate location).
+The configuration lives in `autograph.yaml` at the default path
+`/etc/autograph/autograph.yaml` (use the flag `-c` to provide an
+alternate path).
 
 ## Server
 
@@ -19,7 +18,7 @@ server:
     writetimeout: 60s
 ```
 
-Use flag [-p]{.title-ref} to provide an alternate port and override any
+Use flag `-p` to provide an alternate port and override any
 port specified in the config.
 
 ## Statsd
@@ -59,7 +58,7 @@ heartbeat:
     dbchecktimeout: 15ms
 ```
 
-[heartbeat.dbchecktimeout]{.title-ref} is how long the heartbeat handler
+`heartbeat.dbchecktimeout` is how long the heartbeat handler
 should wait for the DB to return a response before erroring.
 
 ## Hardware Security Module (HSM)
@@ -84,7 +83,7 @@ heartbeat:
 Refer to each signer\'s configuration doc to know how they each make use
 of the HSM.
 
-[heartbeat.hsmchecktimeout]{.title-ref} is how long the heartbeat
+`heartbeat.hsmchecktimeout` is how long the heartbeat
 handler should wait for the HSM to return a response before erroring.
 
 ## Signers
@@ -94,10 +93,10 @@ respective README under the
 [autograph/signer/](https://github.com/mozilla-services/autograph/tree/main/signer)
 directory.
 
-All signers share the common field [id]{.title-ref}, which is a name
-unique to the installation to identify each signer. The [id]{.title-ref}
+All signers share the common field `id`, which is a name
+unique to the installation to identify each signer. The `id`
 is used in the authorization configurations for both
-[autograph]{.title-ref} and [autograph edge]{.title-ref}.
+autograph and autograph edge.
 
 ``` yaml
 signer:
@@ -110,8 +109,8 @@ signer:
 
 Authorizations map an arbitrary username and key to a list of signers.
 The key does not need to be generated in any special way. You can use
-[openssl]{.title-ref} or the tool in
-[tools/maketoken/main.go]{.title-ref} to obtain a random 256bits string:
+`openssl` or the tool in `tools/maketoken/main.go` to obtain a random
+256-bit string:
 
 ``` bash
 $ openssl rand -hex 32
@@ -137,18 +136,17 @@ authorizations:
           - appkey2
 ```
 
-The configuration above allows [alice]{.title-ref} to request signatures
-from both [appkey1]{.title-ref} and [appkey2]{.title-ref}, while
-[bob]{.title-ref} is only allowed to request signatures from
-[appkey2]{.title-ref}.
+The configuration above allows `alice` to request signatures from both
+`appkey1` and `appkey2`, while `bob` is only allowed to request
+signatures from `appkey2`.
 
-Note that, when a user is allowed to sign with more than one signer, and
-no specific signer key id is provided in the signing request, autograph
-will use the first signer in the list. For example, if alice requests a
-signature without providing a key id, the private key from
-[appkey1]{.title-ref} will be used to sign her request.
+Note that, when a user is allowed to sign with more than one signer,
+and no specific signer key id is provided in the signing request,
+autograph will use the first signer in the list. For example, if alice
+requests a signature without providing a key id, the private key from
+`appkey1` will be used to sign her request.
 
-The optional key [hawktimestampvalidity]{.title-ref} maps to a string
+The optional key `hawktimestampvalidity` maps to a string
 [parsed as a time.Duration](https://golang.org/pkg/time/#ParseDuration)
 and allows for different HAWK timestamp skews than the default of 1
 minute.
@@ -166,7 +164,7 @@ Build the autograph binary using make:
 $ make install
 ```
 
-The binary is located in [\$GOPATH/bin/autograph]{.title-ref} and can be
+The binary is located in `$GOPATH/bin/autograph` and can be
 started with the configuration file:
 
 ``` bash
@@ -183,7 +181,7 @@ ohai
 
 ## Test Key/Cert
 
-For dev and testing purposes, the private key [appkey1]{.title-ref} can
+For dev and testing purposes, the private key `appkey1` can
 be used with the following self-signed certificate:
 
 >     -----BEGIN CERTIFICATE-----

docs/endpoints.md

@@ -1,9 +1,9 @@
 # API Endpoints
 
 Authorization: All API calls require a
-[hawk](https://github.com/hueniverse/hawk) Authorization header with
-payload signature enabled. Example code can be found in the
-[tools]{.title-ref} directory.
+[hawk](https://github.com/mozilla/hawk) Authorization header with
+payload signature enabled. Example code can be found in the `tools`
+directory.
 
 ## /sign/data
 
@@ -47,7 +47,7 @@ Authorization: Hawk id="dh37fgj492je", ts="1353832234", nonce="j4h3g2", ext="som
 
 ### Response
 
-A successful request return a [201 Created]{.title-ref} with a response
+A successful request return a `201 Created` with a response
 body containing signature elements encoded in JSON. The ordering of the
 response array is identical to the request array, such that signing
 request 0 maps to signing response 0, etc.
@@ -70,15 +70,15 @@ Below is an example signing response for a content-signature request:
 
 Each signature response contains the following fields:
 
--   [ref]{.title-ref} is a random string that acts as a reference number
+-   `ref` is a random string that acts as a reference number
     for logging and tracking.
--   [type]{.title-ref} is the type of signer that issued the signature
--   [signer_id]{.title-ref} is ID of the signer in configuration.
--   [public_key]{.title-ref} is the DER encoded public key that maps to
+-   `type` is the type of signer that issued the signature
+-   `signer_id` is ID of the signer in configuration.
+-   `public_key` is the DER encoded public key that maps to
     the signing key used to generate the signature. This value can be
     used by clients to verify signatures. The DER format is supported by
     OpenSSL and most libraries.
--   [signature]{.title-ref} is the signature encoded in the proper
+-   `signature` is the signature encoded in the proper
     format. Each signer uses a different format, so refer to their
     documentation for more information.
 
@@ -124,16 +124,16 @@ Authorization: Hawk id="alice", mac="756lSgQEYLoc6V0Uv2wS8pRg/h+4WFUVKWQynCFvY8Y
 
 ### Response
 
-A successful request return a [201 Created]{.title-ref} with a response
+A successful request return a `201 Created` with a response
 body containing all signed files encoded in JSON. The ordering of the
 response array is identical to the request array, such that signing
 request 0 maps to signing response 0, etc.
 
-The response format is the same as [/sign/data]{.title-ref} except
-instead of the [signature]{.title-ref} field autograph returns the
+The response format is the same as `/sign/data` except
+instead of the `signature` field autograph returns the
 field:
 
--   [signed_file]{.title-ref} is the base64 encoded signed file data.
+-   `signed_file` is the base64 encoded signed file data.
     Each signer uses a different format, so refer to their documentation
     for more information.
 
@@ -169,30 +169,30 @@ Body format: The request body is a json array where each entry of the
 array is an object to sign. The parameters are:
 
 -   input: base64 encoded hash to sign
--   keyid: see [/sign/data]{.title-ref}
--   options: see [/sign/data]{.title-ref}
+-   keyid: see `/sign/data`
+-   options: see `/sign/data`
 
 ### Response
 
-See [/sign/data]{.title-ref}, the response format is identical.
+See `/sign/data`, the response format is identical.
 
 ### Response
 
-A successful request return a [201 Created]{.title-ref} with a response
+A successful request return a `201 Created` with a response
 body containing an S/MIME detached signature encoded with Base 64.
 
 ## /\_\_monitor\_\_
 
 This is a special endpoint designed to monitor the status of all signers
 without granting signing privileges to a monitoring client. It requires
-a special user named [monitor]{.title-ref} that can request a signature
-of the string [AUTOGRAPH MONITORING]{.title-ref} by all active signers.
+a special user named `monitor` that can request a signature
+of the string `AUTOGRAPH MONITORING` by all active signers.
 
 ### Request
 
 The endpoint accepts a GET request without query parameter or request
-body. The [Hawk]{.title-ref} authorization of the user named
-[monitor]{.title-ref} is required.
+body. The `Hawk` authorization of the user named
+`monitor` is required.
 
 ``` bash
 GET /__monitor__
@@ -206,7 +206,7 @@ Authorization: Hawk id="dh37fgj492je", ts="1353832234", nonce="j4h3g2", ext="som
 
 One signing response per active signer is returned. The format follows
 the standard signing response format described in
-[/sign/data]{.title-ref}.
+`/sign/data`.
 
 The monitoring client should verify the signature returned with each
 response. If X5U values are provided, the monitoring client should

docs/hsm.md

@@ -6,9 +6,9 @@ PKCS11 operations. Crypto11 wraps [Miekg\'s
 PKCS11](https://github.com/miekg/pkcs11/) package, which itself wraps
 the C library that talks to the HSM.
 
-PKCS11 depends on [ltdl]{.title-ref}. On Ubuntu, that\'s installed from
-[libltdl-dev]{.title-ref}. On Archlinux, use
-[libtool-ltdl-devel]{.title-ref}.
+PKCS11 depends on `ltdl`. On Ubuntu, that\'s installed from
+`libltdl-dev`. On Archlinux, use
+`libtool-ltdl-devel`.
 
 ## Setting up CloudHSM
 
@@ -53,17 +53,16 @@ it will be located under /opt/cloudhsm/lib/libcloudhsm_pkcs11.so
 
 ## Setting up SoftHSM
 
--   On Ubuntu Xenial, install [softhsm2]{.title-ref} and create [mkdir
-    /var/lib/softhsm/tokens]{.title-ref}
--   On ArchLinux, install [softhsm]{.title-ref} from AUR
--   Then create a token with [\$ softhsm2-util \--init-token \--slot 0
-    \--label test \--pin 0000 \--so-pin 0000]{.title-ref}
+-   On Ubuntu Xenial, install `softhsm2` and create `mkdir /var/lib/softhsm/tokens`
+-   On ArchLinux, install `softhsm` from AUR
+-   Then create a token with `$ softhsm2-util --init-token --slot 0 --label test --pin 0000 --so-pin 0000`
 
 ### PKCS11 SoftHSM client
 
-The SO library is installed with the softhsm package and located: \*
-Ubuntu: [/usr/lib/softhsm/libsofthsm2.so]{.title-ref} \* ArchLinux:
-[/usr/lib/libsofthsm2.so]{.title-ref}
+The SO library is installed with the softhsm package and located:
+
+* Ubuntu: `/usr/lib/softhsm/libsofthsm2.so`
+* ArchLinux: `/usr/lib/libsofthsm2.so`
 
 ## Configuring Autograph
 
@@ -94,5 +93,5 @@ signers:
 
 Note that autograph does not generate slots or keys, this must be
 handled separately. For a full working example, take a look at
-[autograph.softhsm.yaml]{.title-ref} and how it is used by CircleCI in
-[.circleci/config.yaml]{.title-ref}.
+`autograph.softhsm.yaml` and how it is used by CircleCI in
+`.circleci/config.yaml`.

docs/troubleshooting.md

@@ -11,10 +11,9 @@ These procedures assume that:
 
 Collect the following information from reporter:
 
--   Autograph [key_id]{.title-ref} (if different from Hawk
-    [key_id]{.title-ref})
--   Hawk [key_id]{.title-ref}
--   Has this [key_id]{.title-ref} ever worked before?
+-   Autograph `key_id` (if different from Hawk `key_id`)
+-   Hawk `key_id`
+-   Has this `key_id` ever worked before?
 -   Time range error occurred.
 -   Client location (Taskcluster or not)
 
@@ -24,10 +23,10 @@ Process:
     logs](https://console.cloud.google.com/logs/viewer?project=aws-aws-autograph-p-1535037642&organizationId=442341870013&minLogLevel=0&expandAll=false&timestamp=2019-11-22T14%3A29%3A11.008000000Z&customFacets&limitCustomFacetWidth=true&dateRangeStart=2019-11-21T14%3A29%3A11.258Z&dateRangeEnd=2019-11-22T14%3A29%3A11.258Z&interval=P1D&resource=aws_ec2_instance&scrollTimestamp=2019-11-21T23%3A58%3A48.000000000Z&advancedFilter=resource.type%3D%22aws_ec2_instance%22%0AjsonPayload.code%3D%22401%22).
     If no such entries, problem exists outside of Autograph.
 2.  [Verify credentials work](#verify-credentials-work) for the specific
-    [key_id]{.title-ref}. If so, client isn\'t submitting credentials
+    [key_id`. If so, client isn\'t submitting credentials
     properly.
 3.  [Verify signing works](#verify-signing-works) for the specific
-    [key_id]{.title-ref}. If not, likely configuration error.
+    `key_id`. If not, likely configuration error.
 
 ## Procedures
 
@@ -39,9 +38,8 @@ allocated to you following the [standard
 procedure](https://mana.mozilla.org/wiki/pages/viewpage.action?pageId=87365053#OnlineHSM(AWS)-get_prod_box_for_hsm_work).
 
 1.  Log into the production instance
-2.  Clone the Autgraph repo via https: [git clone \--depth 1
-    https://github.com/mozilla-services/autograph.git]{.title-ref}
-3.  Restart autograph via [sudo systemctl start docker-app]{.title-ref}.
+2.  Clone the Autgraph repo via https: `git clone --depth 1 https://github.com/mozilla-services/autograph.git`
+3.  Restart autograph via `sudo systemctl start docker-app`.
     (The box will not take production traffic, as it has been removed
     from the load balancing pool.)
 4.  Extract the Hawk secret from your laptop.
@@ -65,4 +63,4 @@ go run client.go \
 Use the same setup as for [Verify Credentials
 Work](#verify-credentials-work), but ensure you provide the correct
 input file format. A correct same should be available in the
-[../../signer]{.title-ref} subtree.
+`../../signer` subtree.