Update README

Added instructions to build custom image sizes
Convert to adoc for automatic toc

README.md → README.adoc

@@ -1,25 +1,23 @@
 # BlueSCSI
+:toc: macro
 
 BlueSCSI & ArdSCSino are hardware that reproduces SCSI devices (hard disks) with an Arduino STM32F103C (aka Blue Pill.)
 
-`BlueSCSI` created by [erichelgeson](https://github.com/erichelgeson) is a fork of `ArdSCSino-stm32` which adds:
+`BlueSCSI` created by https://github.com/erichelgeson[erichelgeson] is a fork of `ArdSCSino-stm32` which adds:
+
 * Mac specific functionality
 * Passive SCSI termination
 * An alternative power source if not able to be powered by the SCSI bus
 
-`ArdSCSino-stm32` created by [ztto](https://github.com/ztto/ArdSCSino-stm32) is the STM32 version of `ArdSCSino`
-
-`ArdSCSino` created by [Tambo (TNB Seisakusho)](https://twitter.com/h_koma2)
-
-# Purchase a Kit or Fully Assembled
+`ArdSCSino-stm32` created by https://github.com/ztto/ArdSCSino-stm32[ztto] is the STM32 version of `ArdSCSino`
+`ArdSCSino` created by https://twitter.com/h_koma2[Tambo (TNB Seisakusho)]
 
-https://gum.co/bluescsi-1b
+image::docs/buynow.png[link=https://gum.co/bluescsi-1b, 150]
+image::docs/discordbanner.png[https://discord.gg/GKcvtgU7P9, 150]
 
-# Questions?
+Join us in #bluescsi on https://discord.gg/GKcvtgU7P9[Discord] or open an issue on this repo.
 
-Join us in #bluescsi on [Discord](https://discord.gg/GKcvtgU7P9)
-
-Or open an issue on this repo.
+toc::[]
 
 ## Compatibility
 
@@ -33,7 +31,7 @@ SE, SE/30, Classic, Classic II, Color Classic, LC I/II/III, LC 475, LC 575
 
 #### Reported by others
 
-[IIcx](https://68kmla.org/forums/topic/61045-arduino-scsi-device-work-in-progress/?do=findComment&comment=663077), [PowerBook 100 (with custom adapter)](https://68kmla.org/forums/topic/61045-arduino-scsi-device-work-in-progress/?do=findComment&comment=664446)
+https://68kmla.org/forums/topic/61045-arduino-scsi-device-work-in-progress/?do=findComment&comment=663077[IIcx], https://68kmla.org/forums/topic/61045-arduino-scsi-device-work-in-progress/?do=findComment&comment=664446[PowerBook 100 (with custom adapter)]
 
 ### Incompatible 
 
@@ -41,7 +39,7 @@ Plus, PowerPC (SCSI-2?)
 
 ## Performance
 
-Tested on a Color Classic with [SCSI Director Pro 4](https://macintoshgarden.org/apps/scsi-director-pro-40)
+Tested on a Color Classic with https://macintoshgarden.org/apps/scsi-director-pro-40[SCSI Director Pro 4]
 ```
 1024KB/Sec Write
 900KB/Sec Read
@@ -50,7 +48,7 @@ Tested on a Color Classic with [SCSI Director Pro 4](https://macintoshgarden.org
 
 ## Assembly
 
-See [Assembly.md](docs/assembly.md)
+See <<Assembly.md,Assembly.md>>
 
 ## Usage
 
@@ -79,12 +77,27 @@ If no image files are found PC13 will pulse on and off. Check the log file for a
 
 ### Blanks & Premade Images
 
-Any blank raw file will do. They are easy to come by as they are used in other devices and emulators such as Basilisk II.
+Any blank raw file will do. They are easy to come by as they are used in other devices and emulators such as https://www.emaculation.com/doku.php/basiliskii_osx_setup[Basilisk II].
 
 * Blanks of various sizes from gryphel.com - https://www.gryphel.com/c/minivmac/extras/blanks/
 * Premade from savagetaylor.com - https://www.savagetaylor.com/downloads/downloads-macintosh/ 
 * Premade from RaSCSI - http://macintoshgarden.org/apps/rascsi-68kmla-edition
 
+### Custom Disk Images
+
+This technique is useful when you would like a disk image larger than the pre-built images in the previous section.
+
+The following instructions demonstrates the process using https://ss64.com/osx/dd.html[dd] on a modern Mac:
+
+1. Open terminal.
+2. The following command will create a blank disk image. You can modify the command to suit your use.
+   * `dd if=/dev/zero of=example.hda bs=1m count=500`
+   * The `count` field defines the number of megabytes (`bs=1m`) the total disk image should be.
+   * The output file from the command is "example.hda". This can be changed in the `of=example.hda` field.
+3. Place the new blank disk image in the root directory of your SD card.
+4. If you do not already have a tool to format SCSI drives, https://macintoshgarden.org/apps/lido-756[download LIDO]. You can use an emulator such as https://www.emaculation.com/doku.php/basiliskii_osx_setup[Basilisk II] to move files to the image to prepare your installation.
+5. After booting into your target machine with the working Mac OS disk image on your BlueSCSI from step 3, format the blank disk.
+
 ### Termination
 
 To enable termination place the two jumpers on the TERM block. Termination should be enabled if it is the last device in the chain - which is normally how it is used.
@@ -97,36 +110,20 @@ If your device is not working - check the `LOG.txt` in the root of the SD card.
 
 ### Verify you are not using a fake
 
-How to tell if your STM32 is fake: https://github.com/keirf/Greaseweazle/wiki/STM32-Fakes
+https://github.com/keirf/Greaseweazle/wiki/STM32-Fakes[How to tell if your STM32 is fake]
 
 ### Performance is slower than expected
 
 Try a different SD card. Cheap/old SD cards can affect performance.
 
-# Development
+## Development
 
 Below is for users who wish to edit or develop on the BluePill - normal users should not need to worry about this.
 
-## PlatformIO
+### Setup PlatformIO
 
 Open the project in [PlatformIO](https://platformio.org/) and everything is pre-configured.
 
-## Setup Arduino IDE (Depricated, Do Not Use)
-
-You only need to setup the Arduino IDE if you are planning on developing and contributing to the project. Otherwise flash a provided `.bin` file.
-
-1. Install `Arduino IDE` version `1.8.x` - https://www.arduino.cc/en/software
-    1. Instructions may require extra steps to allow for serial/usb access depending on your OS. Read all instructions carefully.
-1. Follow these instructions _**carefully**_ as well - https://github.com/rogerclarkmelbourne/Arduino_STM32/wiki/Installation
-    1. **Use the 1.0.0 core** - not the master - https://github.com/rogerclarkmelbourne/Arduino_STM32/releases/tag/v1.0.0
-    1. Note I used the `Arduino SAM Boards (32-bits ARM) Cortext-M3)` version `1.6.12`
-    1. Additional Help https://sites.google.com/site/ericmklaus/projects-1/stm32f103-minimum-system-development-board/arduino-ide-for-stm32103-board
-    1. Some additional hints here - https://github.com/ztto/ArdSCSino-stm32/issues/5
-    1. If you get a warning about an unsigned binary - open the System Preferences -> Security -> allow stm32...
-1. Install SdFat - Tools -> Manage Libraries -> `SdFat by Bill Greiman` version `2.0.2`
-1. Make sure the correct board is selected `Generic STM32F103C series` - Copy the latest `.ino` file into a sketch and compile.
-1. Flash using your preferred method.
-
 ## Flashing
 
 When flashing you have two options:
@@ -137,33 +134,33 @@ You may also flash the `.bin` file directly from STM32CubeProgrammer. If you are
 
 ### Using STLink v2 (prefered)
 
-0. Remove SD Card
-0. Make sure the STLink is up to date - [Latest Firmware](https://my.st.com/content/my_st_com/en/products/development-tools/software-development-tools/stm32-software-development-tools/stm32-programmers/stsw-link007.license=1610785194992.product=STSW-LINK007.version=2.37.26.html)
-1. Connect pins `SWDIO`(2), `GND`(4), `SWCLK`(6), and `3.3v`(8) from the programmer to the Blue Pill. NOTE: These are not the same as Serial ports.
-1. Using Arduino Studio Select Tools -> Upload Method -> STLink.
-1. You should see the LED PC_13 flashing indicating no SD Card detected.
-1. Insert SD Card, boot on your favorite Mac!
+1. Remove SD Card
+2. Make sure the STLink is up to date - https://my.st.com/content/my_st_com/en/products/development-tools/software-development-tools/stm32-software-development-tools/stm32-programmers/stsw-link007.license=1610785194992.product=STSW-LINK007.version=2.37.26.html[Latest Firmware]
+3. Connect pins `SWDIO`(2), `GND`(4), `SWCLK`(6), and `3.3v`(8) from the programmer to the Blue Pill. NOTE: These are not the same as Serial ports.
+4. Using Arduino Studio Select Tools -> Upload Method -> STLink.
+5. You should see the LED `PC_13` flashing indicating no SD Card detected.
+6. Insert SD Card, boot on your favorite Mac!
 
 #### Trouble Shooting
 
 If the device is not detected you may need to hold reset, click program, once it is detected release reset.
 
-If you are unable to get the device in DFU mode for programming you may need to use [STM32CubeProgrammer](https://www.st.com/en/development-tools/stm32cubeprog.html) to erase the chip.
+If you are unable to get the device in DFU mode for programming you may need to use https://www.st.com/en/development-tools/stm32cubeprog.html[STM32CubeProgrammer] to erase the chip.
 
 ### Using UART Serial
 
 I used these - but any USB->TTL device should work https://www.amazon.com/gp/product/B07D6LLX19/
 
-0. Remove SD Card if you have one installed.
-1. Set the BOOT0 jumper to 1
-1. Connect to your UART flashing device via the debug pins, then connect to your computer.
-1. Click the reset button on the BluePill to reset and enter programming mode.
-1. In Arduino Studio click Upload
+1. Remove SD Card if you have one installed.
+2. Set the BOOT0 jumper to 1
+3. Connect to your UART flashing device via the debug pins, then connect to your computer.
+4. Click the reset button on the BluePill to reset and enter programming mode.
+5. In Arduino Studio click Upload
     - Note you may have to click Upload more than once, or try restarting more than once.
-1. You should see the LED flashing if you have no SD Card.
-1. Unplug UART device.
-1. Set the BOOT0 jumper to 0
-1. Insert SD Card, boot on your favorite Mac!
+6. You should see the LED flashing if you have no SD Card.
+7. Unplug UART device.
+8. Set the BOOT0 jumper to 0
+9. Insert SD Card, boot on your favorite Mac!
 
 ### Using USB HID