polishing

README.md

@@ -4,16 +4,26 @@ draft = false
 title = 'Kyleguy Inception'
 +++
 
-# kyleguy
-There are a few things that need to be setup to have a website.  One needs a domain.  This is just a name that people use to identify something.  Google owns many domains, for example: `www.google.com`, `google.com`, `gmail.com`.  These domains have various meanings to different people, but to you `google.com` probably means a website where one can find other websites, products, services, etc on the Internet.  We need a domain.  We need a place for our website to exist, we are going to host our website at `pebbleguy.com`.  We also need a way to edit our site.  These three things are really all that we need, each might abstract some difficulties, but nothing is too complex.  For example to have a domain we need to manage the Domain Name System, it is easy albeit esoteric.
+# README.md
+What could be more helpful than a guide that is more interested in a party trick than attempting solve its stated purpose?  Well, a guide that does both.  That does not make sense but it's staying because my keyboard doesn't do deletes.  My "trick" is that this `README.md` was used to create the site that this `README.md` is being displayed on.  If you don't think about it too much it is indeed pretty cool.  We are showing off static webpages.  These are the fastest websites, but still maintain much of the flexibility developers are used to with dynamic pages.
 
-## prerequisites - a thing that is the same as something that is required
-This guide was primarily written for a single person and looks complex with a a bunch of tools and screenshots and clicks and stuff, but the overall process can be accomplished under a variety of environments.  A couple tools that have binaries pre-compiled for Windows are needed because by default Windows does not provide any aid.  Thankfully there are many Windows users that have stepped in and are helpping provide the necessary solutions.  To give a brief overview of what is described in this guide here is a Debian version of this guide:
+ - [x] 1. [prerequisites](#prelude)
+ - [x]   a. a domain
+ - [x]   b. a webhost
+ - [x]   b. developer tools/environment
 
+## <a name="prelude" id="prelude"></a>prerequisites
+We will be installing and maintaining a website therefore we need a domain.  You will already need to have registered a domain for your use, this is not something this guide covers.  You should prioritize the [instructions](#configureRegistrarDns) early due to the inherent delays in DNS propagation.  You will also need access to Dan's server pebbleguy.com.  Pebbleguy.com will serve as a location to store our files and it will host our website.  Websites are forever changing it makes sense that a requirement would be that we need a place edit our site, we won't directly solve that problem but at times we will make an effort and will need both git and an interactive developer environment.  These three things are really all that we need, each might hide difficulties, but nothing we cannot handle.
+
+This guide was primarily written to support someone with a Windows computer.  Things may look and feel complex due to a bunch of tools, screenshots, button clicks and stuff but if you look at the [Debian](#brief) guide one can see we are't actually accomplishing that much.  We can also see that goals of this guide could be completed in a number of different environments.  There are a number of tools that fill in where Windows is lacking features or where a solid Microsoft application is not yet developed.  These tools are pre-compiled for us and provided by their authors to Windows users at-large.  This guide would not be possible without their contributions.  I say this to clear up inevitable misunderstandings caused by us bringing diverse softwares together.
+
+**klossary**
+> domain - *This is just a name that people use to identify something.  Google owns many, for example: `www.google.com`, `google.com`, `gmail.com` are all domains.  On the internet one 'owns' a name by registering with Internet Corporation for Assigned Names and Numbers (ICANN).*
+
+## <a name="brief" id="brief"></a>A Debian guide shows the road ahead
 ```
-: "you need to add a DNS record for the domain kyleguy.rome7.com on your domain registrar"
-# --
 # Debian version of static site using Hugo
+# --
 sudo apt install hugo;
 # setup NginX configs for our webserver
 git clone https://git.pebbleguy.com/Dan/pebbleguy.com
@@ -31,6 +41,7 @@ sudo ln -s /mnt/external/projects/kyleguy/web/public/ /mnt/external/websites/kyl
 git add --all && git commit -m'added a static site with hugo'
 git remote add origin http://git.pebbleguy.com/kyle/kyleguy.git
 git push -u origin master
+: "you need to add a DNS record for the domain kyleguy.rome7.com on your domain registrar"
 ```
 
 What we can see is that the user made sure that they had a DNS record for `kyleguy.rome7.com` then installed `hugo`.  They pulled a copy of the `pebbleguy.com` repository so that they could execute the `certbot-wrapper.sh` to setup a webserver with a certificate signed by a certificate authority.  They then setup a webroot and added a theme to their static site.  Lastly they committed their site contained in a new `git` repository to `git.pebbleguy.com`.  This is basically what we are going to do in this guide but we need some extra things.  We are going to assume that the Windows user already has `git` setup and they know how to use it.  They are going to need to connect to a remote server because Windows lacks several basic API calls needed for a reliable server.  Idk is reliable is the right word.  They lack the `epoll` API and do not support `select` or `poll` and would rely on a third party [tools](https://www.cygwin.com/).  That is what I actually mean by 'reliable'.  I was saying they need to connect to a remote server which means one needs to be careful and run some commands on the Windows host and some using `SecureShell` on a remote host.  In addition files need to be synced between the local and remote side which means we need a few more tools and configs.  The installation of `Hugo` is the tiniest bit more complex, due to the differences between `Windows Powershell` the end-of-the-road 'powershell' that is installed on Windows, and `Powershell` the [actively developed](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows) but not installed on any version of Windows.  The guide tries to be a little on the verbose side, both becuase I lack clarity, also because this is just a guide hopefully details are useful, but when you fall off a cliff the guide can't catch you, it's just going to watch your inevitible tumble down the mountainside.
@@ -291,7 +302,8 @@ emma-kac  gogs-webhooks  KingsAndChaos  kyleguy.rome7.com  shootGame  www.pebble
 
 ## repository setup
 
-**Configure the your domain registrar's DNS**
+
+<a name="configureRegistrarDns" id="configureRegistrarDns"></a>**Configure the your domain registrar's DNS**
 
 This assumes you are using the DNS provided by your domain registrar.  Some common registrars are Cloudflare, SquareSpace, Wix, GoDaddy, Gandi, Namecheap, and [others](https://www.icann.org/en/accredited-registrars).  FYI, I listed some bad and some good ones, not a review just blasting.
 

web/hugo.toml

@@ -1,8 +1,9 @@
 baseURL = 'https://kyleguy.rome7.com/'
 languageCode = 'en-us'
-title = 'kyleguy'
+title = "Kyle's Website"
 theme = 'ananke'
 
+# this is a workaround for [Issue 11556](https://github.com/gohugoio/hugo/issues/11556)
 [module]
   [[module.mounts]]
     source = "content"
@@ -11,7 +12,16 @@ theme = 'ananke'
     source = "/mnt/external/projects/kyleguy/README.md"
     target = "content/posts/kyleguy-inception.md"
     lang = "en"
+  # This is probably not needed
   [[module.mounts]]
     source = "/mnt/external/projects/kyleguy/images"
     target = "content/posts/kyleguy-inception/images"
     lang = "en"
+
+# In my README.md I use HTML - this should probably be in a config file for just this page but I do not know how to do it
+# Hugo uses Goldmark to render Markdown, Goldmark is worried about HTML being unsafe
+[markup]
+  [markup.goldmark]
+    [markup.goldmark.renderer]
+      # this is a weird way to say this, but to enable html in markdown you say: I want it to be unsafe (true)
+      unsafe = true