DOCS: GitBook styling for style guide (#2235)

Co-authored-by: Tom Limoncelli <tlimoncelli@stackoverflow.com>

documentation/styleguide.md

@@ -2,7 +2,7 @@
 
 # Use the Google Go Style Guide
 
-https://google.github.io/styleguide/go/
+<https://google.github.io/styleguide/go/>
 
 
 # Always favor simplicity
@@ -11,13 +11,16 @@ This is a community project. The code you write today will be maintained by
 someone in the future that may not be a professional developer or one that is
 as experienced as you.
 
-Remember what Brian Kernighan wrote: "Debugging is twice as hard as writing the
-code in the first place. Therefore, if you write the code as cleverly as
-possible, you are, by definition, not smart enough to debug it."
+Remember what Brian Kernighan wrote:
 
-Remember the [John Woods](http://wiki.c2.com/?CodeForTheMaintainer) quote,
-"Always code as if the guy who ends up maintaining your code will be a violent
-psychopath who knows where you live."
+> "Debugging is twice as hard as writing the
+code in the first place. Therefore, if you write the code as cleverly as
+possible, you are, by definition, not smart enough to debug it." — _Brian Kernighan_
+
+Remember the [John Woods](http://wiki.c2.com/?CodeForTheMaintainer) quote:
+
+> "Always code as if the guy who ends up maintaining your code will be a violent
+psychopath who knows where you live." — _[John Woods](http://wiki.c2.com/?CodeForTheMaintainer)_
 
 Don't code for today-you.  Write code for six-months-from-now-you.  Have you
 met six-months-from-now-you? Oh, you should. Fine individual. They are
@@ -33,11 +36,13 @@ write code that six-months-from-now-you can understand.
 
 These are the filenames to use:
 
-(NOTE: This is a new standard. Old providers are not yet compliant.)
+{% hint style="info" %}
+**NOTE**: This is a new standard. Old providers are not yet compliant.
+{% endhint %}
 
 * `providers/foo/fooProvider.go` -- The main file.
-* `providers/foo/records.go` -- Get/Correct the records of a DNS zone: GetZoneRecords() and GetZoneRecordsCorrections(), plus any helper functions.
-* `providers/foo/convert.go` -- Convert between RecordConfig and the native API's format: toRc() and toNative()
+* `providers/foo/records.go` -- Get/Correct the records of a DNS zone: `GetZoneRecords()` and `GetZoneRecordsCorrections()`, plus any helper functions.
+* `providers/foo/convert.go` -- Convert between RecordConfig and the native API's format: `toRc()` and `toNative()`
 * `providers/foo/auditrecords.go` -- The AuditRecords function and helpers
 * `providers/foo/api.go` -- Code that talks to the API, preferably through a public library.
 * `providers/foo/listzones.go` -- Code for listing and creating DNS zones and domains
@@ -46,13 +51,15 @@ These are the filenames to use:
 
 # Don't conditionally add/remove trailing dots
 
-(The "trailing dot" is the "." at the end of "example.com." which indicates the string is a FQDN.)
+{% hint style="info" %}
+The "trailing dot" is the "." at the end of "example.com." which indicates the string is a FQDN.
+{% endhint %}
 
 DO NOT conditionally add or remove the trailing dot from a string to future-proof code. Either add it or remove it. (This applies to data received from an API call.)
 
-DO call panic() if a protocol changes unexpectedly.
+DO call Go's `panic()` function if a protocol changes unexpectedly.
 
-Why?
+### Why?
 
 It seems like future-proofing to only add a "." if the dot doesn't already exist.  It is the opposite.
 
@@ -64,11 +71,11 @@ Writing code for a situation that doesn't exist means you're writing code that n
 
 Therefore, if your code looks like, "add dot, but not if one exists" or "remove dot if it exists", your code is broken.  Yes, that's fine while exploring the API but once your code works, remove such conditionals.  Try the integration tests both ways: leaving the field untouched and always adding (or removing) the ".".  Only keep the way that works.
 
-Q: But isn't future-proofing good? What if the API changes?
+### But isn't future-proofing good? What if the API changes?
 
 The protocol won't change.  That would break all their other users that didn't future-proof their code. Why would they make a random change like that?  A breaking change like that would (by semvar rules) require a new protocol version, which would trigger code changes in DNSControl.
 
-Q: But what if it changes anway?
+### But what if it changes anway?
 
 If the protocol does change, how do you know your future-proofed code is doing the right thing?
 
@@ -76,7 +83,7 @@ Let's suppose the API started sending a "." when previously they didn't.  They m
 
 Let's suppose the API no longer adds a "." when it previously did. Was the change to save a byte of bandwidth or does the lack of a "." mean this is a shortname and we need to add a "." and add the domain too?  We have no way of knowing and there's a good chance we've done the wrong thing.
 
-Q: What should we do instead?
+### What should we do instead?
 
 Option 1: Write code that assumes it won't change.  If you need to add a dot,
 it is safe to just `s = s + "."`   The code will be readable by any Go