diff --git a/.markdownlint.yaml b/.markdownlint.yaml
new file mode 100644
index 0000000..b3d9dd0
--- /dev/null
+++ b/.markdownlint.yaml
@@ -0,0 +1,6 @@
+default: true
+MD013: false
+MD024:
+    siblings_only: true
+MD033:
+    allowed_elements: ["br", "sub", "sup", "table", "tr", "th", "td"]
diff --git a/Documentation/mboxd.md b/Documentation/mboxd.md
index 69a6b39..d6c0781 100644
--- a/Documentation/mboxd.md
+++ b/Documentation/mboxd.md
@@ -1,10 +1,12 @@
+# mboxd
+
 Copyright 2017,2018 IBM
 
 Licensed under the Apache License, Version 2.0 (the "License"); you may not use
 this file except in compliance with the License. You may obtain a copy of the
 License at
 
-http://www.apache.org/licenses/LICENSE-2.0
+<http://www.apache.org/licenses/LICENSE-2.0>
 
 Unless required by applicable law or agreed to in writing, software distributed
 under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
@@ -21,7 +23,7 @@
 The main mailbox daemon is implemented in mboxd.c. This file uses helper
 functions from the various mboxd\_\*.c files.
 
-```
+```text
 dbus.c -    Contains the handlers for the D-Bus commands which the daemon can
                   receive.
 flash.c -   Contains the functions for performing flash access including
@@ -37,7 +39,7 @@
 
 The daemon is a state machine with 5 valid states:
 
-```
+```text
 UNINITIALISED -         The daemon is still in the initialisation phase and
                         will not respond
 ACTIVE_MAPS_FLASH -     The daemon is polling for incoming commands, is not
@@ -61,7 +63,7 @@
 
 ### State Transitions
 
-```
+```text
 UNINITIALISED -> ACTIVE_MAPS_FLASH -      Uninitiated: Occurs when the daemon is
                                           finished initialising.
 ACTIVE_MAPS_FLASH -> SUSPEND_MAPS_FLASH - Suspend command received over
@@ -105,7 +107,7 @@
 
 The daemon is invoked on the command line with a few parameters:
 
-```
+```text
 (*) - required
 (#) - optional but recommended
 (~) - optional
@@ -162,7 +164,7 @@
 When an event occurs on this file descriptor the signal received is determined
 and processed as follows:
 
-```
+```text
 SIGINT -  Terminate the daemon
 SIGTERM - Terminate the daemon
 SIGHUP -  Clear the window cache and point the LPC bus mapping back to
diff --git a/Documentation/protocol.md b/Documentation/protocol.md
index 14eb195..76c12ac 100644
--- a/Documentation/protocol.md
+++ b/Documentation/protocol.md
@@ -1,17 +1,19 @@
+# Protocol
+
 Copyright 2018 IBM
 
 Licensed under the Apache License, Version 2.0 (the "License"); you may not use
 this file except in compliance with the License. You may obtain a copy of the
 License at
 
-http://www.apache.org/licenses/LICENSE-2.0
+<http://www.apache.org/licenses/LICENSE-2.0>
 
 Unless required by applicable law or agreed to in writing, software distributed
 under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
 CONDITIONS OF ANY KIND, either express or implied. See the License for the
 specific language governing permissions and limitations under the License.
 
-# Introduction
+## Introduction
 
 This document defines a protocol and several transports for flash access
 mediation between the host and the Baseboard Management Controller (BMC).
@@ -33,7 +35,7 @@
 flash data in the LPC firmware space, communicated via functions in the LPC IO
 space.
 
-# Scope
+## Scope
 
 The scope of the document is limited to defining the protocol and its
 transports, and does not cover the content or structure of the data read or
@@ -42,7 +44,7 @@
 The definition of transport-specific parameters, for example selection of IPMI
 `(NetFn, Command)` pairs, is also beyond the scope of the document.
 
-# Background, Design and Constraints
+## Background, Design and Constraints
 
 The protocol was developed to meet requirements on OpenPOWER systems based
 around the ASPEED BMC System-on-Chips such as the AST2400 and AST2500. The
@@ -70,7 +72,7 @@
 same as write, just that the dirty and flush commands are not legal on such
 windows.
 
-## Historic and Future Naming
+### Historic and Future Naming
 
 The original transport for the protocol was the ASPEED BMC LPC mailbox
 interface, and previous revisions of the protocol documentation referred to the
@@ -82,7 +84,7 @@
 "hiomap". This is a reflection of its true purpose - to control the host's view
 of data exposed from the BMC.
 
-# Protocol Overview
+## Protocol Overview
 
 The primary flow of the protocol is for the host to send requests to the BMC,
 which adjusts the mapping of the LPC firmware space as requested and returns a
@@ -94,7 +96,7 @@
 daemon implementing the protocol must notify the host that its requests will be
 denied until further notice.
 
-## Protocol Versioning
+### Protocol Versioning
 
 To enable evolution of the command and event interfaces, incremental changes to
 the behaviour are defined in new versions of the protocol. The descriptions and
@@ -102,7 +104,7 @@
 
 The highest currently specified protocol version is version 3.
 
-## Table of Commands
+### Table of Commands
 
 | ID  | Name                                                  | v1  | v2  | v3  | Description                                                              |
 | --- | ----------------------------------------------------- | --- | --- | --- | ------------------------------------------------------------------------ |
@@ -119,7 +121,7 @@
 | 11  | [`GET_FLASH_NAME`](#get_flash_name-command)           |     |     | ✓   | Retrieve the name of an indexed flash device                             |
 | 12  | [`LOCK`](#lock-command)                               |     |     | ✓   | Mark a region of the current flash window as immutable                   |
 
-## Table of Events
+### Table of Events
 
 | ID  | Name                                              | v1  | v2  | v3  | Description                                                                                 |
 | --- | ------------------------------------------------- | --- | --- | --- | ------------------------------------------------------------------------------------------- |
@@ -128,7 +130,7 @@
 | 6   | [`FLASH_CONTROL_LOST`](#flash_control_lost-event) |     | ✓   | ✓   | The host should suspend access requests                                                     |
 | 7   | [`DAEMON_READY`](#daemon_ready-event)             |     | ✓   | ✓   | The daemon is active and can accept commands                                                |
 
-## List of Transports
+### List of Transports
 
 An essential feature of the protocol is that its behaviour is independent of the
 host-BMC transport. The command and event interfaces of each transport
@@ -154,7 +156,7 @@
 can be used to separate a host-interface transport from the protocol
 implementation.
 
-## Protocol Flow
+### Protocol Flow
 
 The high-level protocol flow is that the host first issues a `GET_INFO` command
 to negotiate the protocol version and acquire parameters fundamental to
@@ -181,7 +183,7 @@
 that large regions should be set to the erased state. This optimisation saves
 the associated LPC firmware cycles to write the regions into the erased state.
 
-## Version Negotiation
+### Version Negotiation
 
 When invoking `GET_INFO` the host must provide the BMC its highest supported
 version of the protocol. The BMC must respond with a protocol version less than
@@ -192,7 +194,7 @@
 host may at a future point request a change in protocol version by issuing a
 subsequent `GET_INFO` command.
 
-### Unversioned Commands
+#### Unversioned Commands
 
 In some circumstances it is necessary for bootstrap or optimisation purposes to
 support unversioned commands. The protocol supports three unversioned commands:
@@ -218,7 +220,7 @@
 Defining `ACK` as unversioned ensures host firmware that has minimal protocol
 support can silence interrupts from the BMC as required.
 
-## Sequence Numbers
+### Sequence Numbers
 
 Sequence numbers are included in messages for correlation of commands and
 responses. v1, v2 and v3 of the protocol permit either zero or one commands to
@@ -238,7 +240,7 @@
 in-progress commands to have failed. The host may retry the affected command(s)
 after generating a suitable sequence number.
 
-## Window Management
+### Window Management
 
 There is only ever one active window which is the window created by the most
 recent `CREATE_READ_WINDOW` or `CREATE_WRITE_WINDOW` call which succeeded. Even
@@ -260,7 +262,7 @@
 the active window. The host must not use write management functions (see below)
 if the active window is a read window or if there is no active window.
 
-## Command Parameter Types
+### Command Parameter Types
 
 It is common in the protocol definition for command parameters to be represented
 in terms of a block size. This block size may refer to e.g. the size of the
@@ -277,7 +279,7 @@
 Finally, conversion between blocks and bytes is achieved by respectively
 dividing or multiplying the quantity by the negotiated block-size.
 
-# Transport Overview
+## Transport Overview
 
 Several transports are defined for the protocol and are outlined below. The key
 features of transport support are the wire-format, delivery mechanisms of
@@ -287,7 +289,7 @@
 command index or a sequence number; these two elements are handled by the
 properties of DBus itself.
 
-## Mailbox Transport
+### Mailbox Transport
 
 - Multi-byte quantity endianness: Little-endian
 - Command length encoding: Assumed from negotiated protocol version
@@ -306,7 +308,7 @@
 the ABI is defined as follows, where the bytes in the range [2, 12] are
 available for command parameters and are defined on a per-command basis.
 
-```
+```text
     0        7         15                    31
    +----------+----------+---------------------+
  0 | Command  | Sequence |                     |
@@ -322,7 +324,7 @@
 
 Command status response codes are as follows:
 
-### Status Codes
+#### Status Codes
 
 | ID  | Name           | v1  | v2  | v3  | Description                                          |
 | --- | -------------- | --- | --- | --- | ---------------------------------------------------- |
@@ -336,7 +338,7 @@
 | 8   | `SEQ_ERROR`    |     | ✓   | ✓   | Invalid sequence number supplied with command        |
 | 9   | `LOCKED_ERROR` |     |     | ✓   | Erased or dirtied region intersected a locked region |
 
-## IPMI Transport
+### IPMI Transport
 
 - Multi-byte quantity endianness: Little-endian
 - Command length encoding: Assumed from negotiated protocol version
@@ -354,14 +356,14 @@
 2. The sequence number is the second value and is encoded in one byte
 3. Parameters required by the (version, command) pair follow
 
-```
+```text
     0        7         15                     N
    +----------+----------+---------     -------+
  0 | Command  | Sequence |          ...        |
    +----------+----------+---------     -------+
 ```
 
-## DBus Transport
+### DBus Transport
 
 - Multi-byte quantity endianness: Transport encoded
 - Command length encoding: Transport encoded
@@ -390,7 +392,7 @@
 type signature and parameter ordering are described in the relevant command
 definition.
 
-# Command Definitions
+## Command Definitions
 
 The command identifier values and command-response parameter formats are
 described in tables under headers for each command. The order of the parameters
@@ -403,13 +405,13 @@
 appropriate
 [type signature](https://dbus.freedesktop.org/doc/dbus-specification.html#basic-types).
 
-## `RESET` Command
+### `RESET` Command
 
 | v1  | v2  | v3  | M   | I   | D     |
 | --- | --- | --- | --- | --- | ----- |
 | ✓   | ✓   | ✓   | 1   | 1   | Reset |
 
-### v1 Parameters
+#### v1 Parameters
 
 <table>
 <tr>
@@ -431,7 +433,7 @@
 </tr>
 </table>
 
-### v2 Parameters
+#### v2 Parameters
 
 <table>
 <tr>
@@ -453,7 +455,7 @@
 </tr>
 </table>
 
-### v3 Parameters
+#### v3 Parameters
 
 <table>
 <tr>
@@ -475,18 +477,18 @@
 </tr>
 </table>
 
-### Description
+#### Description
 
 Requests the BMC return the LPC firmware space to a state ready for host
 firmware bootstrap.
 
-## `GET_INFO` Command
+### `GET_INFO` Command
 
 | v1  | v2  | v3  | M   | I   | D       |
 | --- | --- | --- | --- | --- | ------- |
 | ✓   | ✓   | ✓   | 2   | 2   | GetInfo |
 
-### v1 Parameters
+#### v1 Parameters
 
 <table>
 <tr>
@@ -512,7 +514,7 @@
 </tr>
 </table>
 
-### v2 Parameters
+#### v2 Parameters
 
 <table>
 <tr>
@@ -538,7 +540,7 @@
 </tr>
 </table>
 
-### v3 Parameters
+#### v3 Parameters
 
 <table>
 <tr>
@@ -566,7 +568,7 @@
 </tr>
 </table>
 
-### Description
+#### Description
 
 The suggested timeout is a hint to the host as to how long it should wait after
 issuing a command to the BMC before it times out waiting for a response. This is
@@ -580,13 +582,13 @@
 response is the block size which must be used for all further requests until a
 new size is negotiated by another call to `GET_INFO`.
 
-## `GET_FLASH_INFO` Command
+### `GET_FLASH_INFO` Command
 
 | v1  | v2  | v3  | M   | I   | D            |
 | --- | --- | --- | --- | --- | ------------ |
 | ✓   | ✓   | ✓   | 3   | 3   | GetFlashInfo |
 
-### v1 Parameters
+#### v1 Parameters
 
 <table>
 <tr>
@@ -610,7 +612,7 @@
 </tr>
 </table>
 
-### v2 Parameters
+#### v2 Parameters
 
 <table>
 <tr>
@@ -634,7 +636,7 @@
 </tr>
 </table>
 
-### v3 Parameters
+#### v3 Parameters
 
 <table>
 <tr>
@@ -659,13 +661,13 @@
 </tr>
 </table>
 
-## `CREATE_READ_WINDOW` Command
+### `CREATE_READ_WINDOW` Command
 
 | v1  | v2  | v3  | M   | I   | D                |
 | --- | --- | --- | --- | --- | ---------------- |
 | ✓   | ✓   | ✓   | 4   | 4   | CreateReadWindow |
 
-### v1 Parameters
+#### v1 Parameters
 
 <table>
 <tr>
@@ -689,7 +691,7 @@
 </tr>
 </table>
 
-### v2 Parameters
+#### v2 Parameters
 
 <table>
 <tr>
@@ -716,7 +718,7 @@
 </tr>
 </table>
 
-### v3 Parameters
+#### v3 Parameters
 
 <table>
 <tr>
@@ -744,7 +746,7 @@
 </tr>
 </table>
 
-### Description
+#### Description
 
 The flash offset which the host requests access to is always taken from the
 start of flash - that is it is an absolute offset into flash.
@@ -770,13 +772,13 @@
 If this command returns successfully then the created window is the active
 window. If it fails then there is no active window.
 
-## `CLOSE` Command
+### `CLOSE` Command
 
 | v1  | v2  | v3  | M   | I   | D     |
 | --- | --- | --- | --- | --- | ----- |
 | ✓   | ✓   | ✓   | 5   | 5   | Close |
 
-### v1 Parameters
+#### v1 Parameters
 
 <table>
 <tr>
@@ -798,7 +800,7 @@
 </tr>
 </table>
 
-### v2 Parameters
+#### v2 Parameters
 
 <table>
 <tr>
@@ -821,7 +823,7 @@
 </tr>
 </table>
 
-### v3 Parameters
+#### v3 Parameters
 
 <table>
 <tr>
@@ -844,7 +846,7 @@
 </tr>
 </table>
 
-### Description
+#### Description
 
 Closes the active window. Any further access to the LPC bus address specified to
 address the previously active window will have undefined effects. If the active
@@ -853,7 +855,7 @@
 The Flags argument allows the host to provide some hints to the BMC. Defined
 values are:
 
-```
+```text
 0x01 - Short Lifetime:
        The window is unlikely to be accessed anytime again in the near future.
        The effect of this will depend on BMC implementation. In the event that
@@ -861,13 +863,13 @@
        in a window closed with this flag as first to be evicted from the cache.
 ```
 
-## `CREATE_WRITE_WINDOW` Command
+### `CREATE_WRITE_WINDOW` Command
 
 | v1  | v2  | v3  | M   | I   | D                 |
 | --- | --- | --- | --- | --- | ----------------- |
 | ✓   | ✓   | ✓   | 6   | 6   | CreateWriteWindow |
 
-### v1 Parameters
+#### v1 Parameters
 
 <table>
 <tr>
@@ -891,7 +893,7 @@
 </tr>
 </table>
 
-### v2 Parameters
+#### v2 Parameters
 
 <table>
 <tr>
@@ -918,7 +920,7 @@
 </tr>
 </table>
 
-### v3 Parameters
+#### v3 Parameters
 
 <table>
 <tr>
@@ -946,7 +948,7 @@
 </tr>
 </table>
 
-### Description
+#### Description
 
 The flash offset which the host requests access to is always taken from the
 start of flash - that is it is an absolute offset into flash.
@@ -972,13 +974,13 @@
 If this command returns successfully then the created window is the active
 window. If it fails then there is no active window.
 
-## `MARK_DIRTY` Command
+### `MARK_DIRTY` Command
 
 | v1  | v2  | v3  | M   | I   | D         |
 | --- | --- | --- | --- | --- | --------- |
 | ✓   | ✓   | ✓   | 7   | 7   | MarkDirty |
 
-### v1 Parameters
+#### v1 Parameters
 
 <table>
 <tr>
@@ -1002,7 +1004,7 @@
 </tr>
 </table>
 
-### v2 Parameters
+#### v2 Parameters
 
 <table>
 <tr>
@@ -1026,7 +1028,7 @@
 </tr>
 </table>
 
-### v3 Parameters
+#### v3 Parameters
 
 <table>
 <tr>
@@ -1051,7 +1053,7 @@
 </tr>
 </table>
 
-### Description
+#### Description
 
 The BMC has no method for intercepting writes that occur over the LPC bus. The
 host must explicitly notify the daemon of where and when a write has occurred so
@@ -1067,13 +1069,13 @@
 erase it before hand. This can be used if the host knows that a large area has
 already been erased for example but then wants to perform many small writes.
 
-## `FLUSH` Command
+### `FLUSH` Command
 
 | v1  | v2  | v3  | M   | I   | D     |
 | --- | --- | --- | --- | --- | ----- |
 | ✓   | ✓   | ✓   | 8   | 8   | Flush |
 
-### v1 Parameters
+#### v1 Parameters
 
 <table>
 <tr>
@@ -1097,7 +1099,7 @@
 </tr>
 </table>
 
-### v2 Parameters
+#### v2 Parameters
 
 <table>
 <tr>
@@ -1119,7 +1121,7 @@
 </tr>
 </table>
 
-### v3 Parameters
+#### v3 Parameters
 
 <table>
 <tr>
@@ -1141,7 +1143,7 @@
 </tr>
 </table>
 
-### Description
+#### Description
 
 Flushes any dirty/erased blocks in the active window to the backing storage.
 
@@ -1150,13 +1152,13 @@
 to flush since there are no longer any arguments. If the offset + length exceeds
 the size of the active window then the command must not succeed.
 
-## `ACK` Command
+### `ACK` Command
 
 | v1  | v2  | v3  | M   | I   | D   |
 | --- | --- | --- | --- | --- | --- |
 | ✓   | ✓   | ✓   | 9   | 9   | Ack |
 
-### v1 Parameters
+#### v1 Parameters
 
 <table>
 <tr>
@@ -1179,7 +1181,7 @@
 </tr>
 </table>
 
-### v2 Parameters
+#### v2 Parameters
 
 <table>
 <tr>
@@ -1202,7 +1204,7 @@
 </tr>
 </table>
 
-### v3 Parameters
+#### v3 Parameters
 
 <table>
 <tr>
@@ -1225,18 +1227,18 @@
 </tr>
 </table>
 
-### Description
+#### Description
 
 The host should use this command to acknowledge BMC events propagated to the
 host.
 
-## `ERASE` Command
+### `ERASE` Command
 
 | v1  | v2  | v3  | M   | I   | D     |
 | --- | --- | --- | --- | --- | ----- |
 |     | ✓   | ✓   | 10  | 10  | Erase |
 
-### v2 Parameters
+#### v2 Parameters
 
 <table>
 <tr>
@@ -1260,7 +1262,7 @@
 </tr>
 </table>
 
-### v3 Parameters
+#### v3 Parameters
 
 <table>
 <tr>
@@ -1284,7 +1286,7 @@
 </tr>
 </table>
 
-### Description
+#### Description
 
 This command allows the host to erase a large area without the need to
 individually write 0xFF repetitively.
@@ -1294,13 +1296,13 @@
 the active window to erase starting at offset. If the offset + number exceeds
 the size of the active window then the command must not succeed.
 
-## `GET_FLASH_NAME` Command
+### `GET_FLASH_NAME` Command
 
 | v1  | v2  | v3  | M   | I   | D            |
 | --- | --- | --- | --- | --- | ------------ |
 |     |     | ✓   | 11  | 11  | GetFlashName |
 
-### v3 Parameters
+#### v3 Parameters
 
 <table>
 <tr>
@@ -1325,7 +1327,7 @@
 </tr>
 </table>
 
-### Description
+#### Description
 
 Describes a flash with some kind of identifier useful to the host system.
 
@@ -1335,13 +1337,13 @@
 Note that DBus encodes the string length in its string type, so the explicit
 length is omitted from the DBus message.
 
-## `LOCK` Command
+### `LOCK` Command
 
 | v1  | v2  | v3  | M   | I   | D    |
 | --- | --- | --- | --- | --- | ---- |
 |     |     | ✓   | 12  | 12  | Lock |
 
-### v3 Parameters
+#### v3 Parameters
 
 <table>
 <tr>
@@ -1366,13 +1368,13 @@
 </tr>
 </table>
 
-### Description
+#### Description
 
 Lock an area of flash so that the host can't mark it dirty or erased. If the
 requested area is within the current window and that area is currently marked
 dirty or erased then this command must fail.
 
-# Event Definitions
+## Event Definitions
 
 The M, I, and D columns represent the Mailbox, IPMI and DBus transports
 respectively. The values in the M, I or D columns represent the events' bit
@@ -1383,39 +1385,39 @@
 whether they should be acknowledged or not as part of the protocol. This ensures
 that state changes can be published atomically.
 
-## `PROTOCOL_RESET` Event
+### `PROTOCOL_RESET` Event
 
 | v1  | v2  | v3  | M   | I   | D             |
 | --- | --- | --- | --- | --- | ------------- |
 | ✓   | ✓   | ✓   | 0   | 0   | ProtocolReset |
 
-### Description
+#### Description
 
 Used to inform the host that a protocol reset has occurred, likely due to
 restarting the daemon. The host must perform protocol version negotiation again
 and must assume it has no active window. The host must also assume that any
 in-flight commands have failed.
 
-## `WINDOW_RESET` Event
+### `WINDOW_RESET` Event
 
 | v1  | v2  | v3  | M   | I   | D           |
 | --- | --- | --- | --- | --- | ----------- |
 |     | ✓   | ✓   | 1   | 1   | WindowReset |
 
-### Description
+#### Description
 
 The host must assume that its active window has been closed and that it no
 longer has an active window. The host is not required to perform protocol
 version negotiation again. The host must assume that any in-flight commands have
 failed.
 
-## `FLASH_CONTROL_LOST` Event
+### `FLASH_CONTROL_LOST` Event
 
 | v1  | v2  | v3  | M   | I   | D                |
 | --- | --- | --- | --- | --- | ---------------- |
 |     | ✓   | ✓   | 6   | 6   | FlashControlLost |
 
-### Description
+#### Description
 
 The BMC daemon has been suspended and thus no longer controls access to the
 flash (most likely because some other process on the BMC required direct access
@@ -1427,13 +1429,13 @@
 The host must not assume that the contents of the active window correctly
 reflect the contents of flash while this bit is set.
 
-## `DAEMON_READY` Event
+### `DAEMON_READY` Event
 
 | v1  | v2  | v3  | M   | I   | D           |
 | --- | --- | --- | --- | --- | ----------- |
 |     | ✓   | ✓   | 7   | 7   | DaemonReady |
 
-### Description
+#### Description
 
 Used to inform the host that the BMC daemon is ready to accept command requests.
 The host isn't able to clear this bit through an acknowledge command, the BMC
diff --git a/README.md b/README.md
index 88888ea..77bdce2 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@
 'the mailbox interface' in contexts that aren't completely sensible. It's
 unfortunate, but it's our current reality.
 
-# Building
+## Building
 
 The build system is a standard autotools setup. `bootstrap.sh` runs all the jobs
 necessary to initialise autotools.
@@ -21,11 +21,11 @@
 If you are hacking on the reference implementation it's recommended to run
 `bootstrap.sh` with the `dev` argument:
 
-```
-$ ./bootstrap.sh dev
-$ ./configure
-$ make
-$ make check
+```shell
+./bootstrap.sh dev
+./configure
+make
+make check
 ```
 
 This will turn on several of the compiler's sanitizers to help find bad memory
@@ -33,11 +33,11 @@
 
 Otherwise, build with:
 
-```
-$ ./bootstrap.sh
-$ ./configure
-$ make
-$ make check
+```shell
+./bootstrap.sh
+./configure
+make
+make check
 ```
 
 Through the virtual PNOR feature the daemon's role as a flash abstraction can be
@@ -46,16 +46,16 @@
 `configure` time. If you do not have a C++ compiler for your target, set
 `CXX=cc`.
 
-```
-$ ./bootstrap.sh
-$ ./configure CXX=cc --disable-virtual-pnor
-$ make
-$ make check
+```shell
+./bootstrap.sh
+./configure CXX=cc --disable-virtual-pnor
+make
+make check
 ```
 
-# Coding Style Guide
+## Coding Style Guide
 
-## Preamble
+### Preamble
 
 For not particularly good reasons the codebase is a mix of C and C++. This is an
 ugly split: message logging and error handling can be vastly different inside
@@ -71,7 +71,7 @@
 
 So:
 
-## Rules
+### Rules
 
 1. Message logging MUST be done to stdout or stderr, and MUST NOT be done
    directly via journal APIs or wrappers of the journal APIs.
@@ -99,7 +99,7 @@
    Note: This section specifically targets the use of phosphor-logging's
    `log<T>()`. It does not prevent the use of `elog<T>()`.
 
-# License and Copyright
+## License and Copyright
 
 Copyright 2017 IBM
 
@@ -107,7 +107,7 @@
 this file except in compliance with the License. You may obtain a copy of the
 License at
 
-http://www.apache.org/licenses/LICENSE-2.0
+<http://www.apache.org/licenses/LICENSE-2.0>
 
 Unless required by applicable law or agreed to in writing, software distributed
 under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
diff --git a/vpnor/README.md b/vpnor/README.md
index 2fac3cf..9e103ce 100644
--- a/vpnor/README.md
+++ b/vpnor/README.md
@@ -25,18 +25,18 @@
 
 ## Implementation Behavioural Properties
 
-1.  The FFS ToC defines the set of valid access ranges in terms of partitions
-2.  The read-only property of partitions is enforced
-3.  The ToC is considered read-only
-4.  Read access to valid ranges must be granted
-5.  Write access to valid ranges may be granted
-6.  Access ranges that are valid may map into a backing file associated with the
-    partition
-7.  A read of a valid access range that maps into the backing file will render
-    the data held in the backing file at the appropriate offset
-8.  A read of a valid access range that does not map into the backing file will
-    appear erased
-9.  A read of an invalid access range will appear erased
+1. The FFS ToC defines the set of valid access ranges in terms of partitions
+2. The read-only property of partitions is enforced
+3. The ToC is considered read-only
+4. Read access to valid ranges must be granted
+5. Write access to valid ranges may be granted
+6. Access ranges that are valid may map into a backing file associated with the
+   partition
+7. A read of a valid access range that maps into the backing file will render
+   the data held in the backing file at the appropriate offset
+8. A read of a valid access range that does not map into the backing file will
+   appear erased
+9. A read of an invalid access range will appear erased
 10. A write to a valid access range that maps into the backing file will update
     the data in the file at the appropriate offset
 11. A write to a valid access range that does not map into the backing file will