docs: refactoring and cleanup (#1658)

.github/workflows/documentation.yml

@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-latest
     env:
       GO_VERSION: 1.18
-      HUGO_VERSION: 0.54.0
+      HUGO_VERSION: 0.101.0
       CGO_ENABLED: 0
 
     steps:

docs/.gitignore

@@ -1,2 +1,3 @@
 themes/
 public/
+.hugo_build.lock

docs/config.toml

@@ -45,6 +45,7 @@ pygmentsUseClasses = true
 #  ordersectionsby = "weight"
   # Change default color scheme with a variant one. Can be "red", "blue", "green".
   themeVariant = "blue"
+  custom_css = ["css/theme-custom.css"]
   disableLandingPageButton = true
 
 [Languages]
@@ -64,5 +65,10 @@ pygmentsUseClasses = true
   url = "https://github.com/go-acme/lego/issues"
   weight = 11
 
+[[Languages.en.menu.shortcuts]]
+  name = "<i class='fas fa-fw fa-comments'></i> Discussions"
+  url = "https://github.com/go-acme/lego/discussions"
+  weight = 12
+
 [outputs]
   home = [ "HTML", "RSS", "JSON"]

docs/content/_index.md

@@ -20,11 +20,12 @@ Let's Encrypt client and ACME library written in Go.
   - DNS (dns-01)
   - TLS (tls-alpn-01)
 - SAN certificate support
-- Comes with multiple optional [DNS providers](dns)
-- [Custom challenge solvers](usage/library/writing-a-challenge-solver/)
+- Comes with multiple optional [DNS providers]({{< ref "dns" >}})
+- [Custom challenge solvers]({{< ref "usage/library/Writing-a-Challenge-Solver" >}})
 - Certificate bundling
 - OCSP helper function
 
 
-lego introduced support for ACME v2 in [v1.0.0](https://github.com/go-acme/lego/releases/tag/v1.0.0).  
+lego introduced support for ACME v2 in [v1.0.0](https://github.com/go-acme/lego/releases/tag/v1.0.0).
+
 If you still need to utilize ACME v1, you can do so by using the [v0.5.0](https://github.com/go-acme/lego/releases/tag/v0.5.0) version.

docs/content/dns/_index.md

@@ -15,10 +15,10 @@ The environment variables can reference a value.
 
 Here is an example bash command using the Cloudflare DNS provider:
 
-```bash
-$ CLOUDFLARE_EMAIL=foo@bar.com \
-CLOUDFLARE_API_KEY=b9841238feb177a84330febba8a83208921177bffe733 \
-lego --dns cloudflare --domains www.example.com --email me@bar.com run
+```console
+$ CLOUDFLARE_EMAIL=you@example.com \
+  CLOUDFLARE_API_KEY=b9841238feb177a84330febba8a83208921177bffe733 \
+  lego --dns cloudflare --domains www.example.com --email you@example.com run
 ```
 
 ### Environment Variables: File
@@ -33,16 +33,16 @@ The file must contain only the value.
 
 Here is an example bash command using the CloudFlare DNS provider:
 
-```bash
+```console
 $ cat /the/path/to/my/key
 b9841238feb177a84330febba8a83208921177bffe733
 
 $ cat /the/path/to/my/email
-foo@bar.com
+you@example.com
 
 $ CLOUDFLARE_EMAIL_FILE=/the/path/to/my/email \
-CLOUDFLARE_API_KEY_FILE=/the/path/to/my/key \
-lego --dns cloudflare --domains www.example.com --email me@bar.com run
+  CLOUDFLARE_API_KEY_FILE=/the/path/to/my/key \
+  lego --dns cloudflare --domains www.example.com --email you@example.com run
 ```
 
 ## Experimental Features
@@ -52,4 +52,4 @@ set `LEGO_EXPERIMENTAL_CNAME_SUPPORT` to `true`.
 
 ## DNS Providers
 
-{{%children style="h2" description="true" %}}
+{{% tableofdnsproviders %}}

docs/content/dns/manual.md

@@ -3,6 +3,10 @@ title: "Manual"
 date: 2019-03-03T16:39:46+01:00
 draft: false
 slug: manual
+dnsprovider:
+  since: v0.3.0
+  code: manual
+  url:
 ---
 
 Solving the DNS-01 challenge using CLI prompt.
@@ -11,49 +15,58 @@ Solving the DNS-01 challenge using CLI prompt.
 
 ## Example
 
-```txt
-Do you accept the TOS? Y/n
+To start using the CLI prompt "provider", start lego with `--dns manual`:
 
-[INFO] acme: Registering account for test@test.com
-!!!! HEADS UP !!!!
+```console
+$ lego --email "you@example.com" --domains="example.com" --dns "manual" run
+```
 
-    Your account credentials have been saved in your Let's Encrypt
-    configuration directory at "~/.lego/accounts".
-    You should make a secure backup of this folder now. This
-    configuration directory will also contain certificates and
-    private keys obtained from Let's Encrypt so making regular
-    backups of this folder is ideal.
-    
-[INFO] [test.com] acme: Obtaining bundled SAN certificate
-[INFO] [test.com] AuthURL: https://acme-v02.api.letsencrypt.org/acme/authz/lornkZmVYjsh5wLHpxdQcZDPekGf_TYUM-MTJk3-yrA
-[INFO] [test.com] acme: Could not find solver for: tls-alpn-01
-[INFO] [test.com] acme: Could not find solver for: http-01
-[INFO] [test.com] acme: use dns-01 solver
-[INFO] [test.com] acme: Preparing to solve DNS-01
-lego: Please create the following TXT record in your test.com. zone:
-_acme-challenge.test.com. 120 IN TXT "VP-dby1RBuUOnDZg1n9sF-cwicLsognMzJb0Vx8ttAI"
-lego: Press 'Enter' when you are done
+What follows are a few log print outs, interspersed with some prompts, asking for you to do perform some actions:
 
+```txt
+No key found for account you@example.com. Generating a P256 key.
+Saved key to ./.lego/accounts/acme-v02.api.letsencrypt.org/you@example.com/keys/you@example.com.key
+Please review the TOS at https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf
 Do you accept the TOS? Y/n
+```
+
+If you accept the linked Terms of Service, hit `Enter`.
 
-[INFO] acme: Registering account for test@test.com
+```txt
+[INFO] acme: Registering account for you@example.com
 !!!! HEADS UP !!!!
 
     Your account credentials have been saved in your Let's Encrypt
-    configuration directory at "~/.lego/accounts".
+    configuration directory at "./.lego/accounts".
+
     You should make a secure backup of this folder now. This
     configuration directory will also contain certificates and
     private keys obtained from Let's Encrypt so making regular
     backups of this folder is ideal.
-
-[INFO] [test.com] acme: Obtaining bundled SAN certificate
-[INFO] [test.com] AuthURL: https://acme-v02.api.letsencrypt.org/acme/authz/lornkZmVYjsh5wLHpxdQcZDPekGf_TYUM-MTJk3-yrA
-[INFO] [test.com] acme: Could not find solver for: tls-alpn-01
-[INFO] [test.com] acme: Could not find solver for: http-01
-[INFO] [test.com] acme: use dns-01 solver
-[INFO] [test.com] acme: Preparing to solve DNS-01
-lego: Please create the following TXT record in your test.com. zone:
-_acme-challenge.test.com. 120 IN TXT "VP-dby1RBuUOnDZg1n9sF-cwicLsognMzJb0Vx8ttAI"
+[INFO] [example.com] acme: Obtaining bundled SAN certificate
+[INFO] [example.com] AuthURL: https://acme-v02.api.letsencrypt.org/acme/authz-v3/2345678901
+[INFO] [example.com] acme: Could not find solver for: tls-alpn-01
+[INFO] [example.com] acme: Could not find solver for: http-01
+[INFO] [example.com] acme: use dns-01 solver
+[INFO] [example.com] acme: Preparing to solve DNS-01
+lego: Please create the following TXT record in your example.com. zone:
+_acme-challenge.example.com. 120 IN TXT "hX0dPkG6Gfs9hUvBAchQclkyyoEKbShbpvJ9mY5q2JQ"
 lego: Press 'Enter' when you are done
+```
+
+Do as instructed, and create the TXT records, and hit `Enter`.
+
+```txt
+[INFO] [example.com] acme: Trying to solve DNS-01
+[INFO] [example.com] acme: Checking DNS record propagation using [192.168.8.1:53]
+[INFO] Wait for propagation [timeout: 1m0s, interval: 2s]
+[INFO] [example.com] acme: Waiting for DNS record propagation.
+[INFO] [example.com] The server validated our request
+[INFO] [example.com] acme: Cleaning DNS-01 challenge
+lego: You can now remove this TXT record from your example.com. zone:
+_acme-challenge.example.com. 120 IN TXT "hX0dPkG6Gfs9hUvBAchQclkyyoEKbShbpvJ9mY5q2JQ"
+[INFO] [example.com] acme: Validations succeeded; requesting certificates
+[INFO] [example.com] Server responded with a certificate.
+```
 
-```
+As mentioned, you can now remove the TXT record again.

docs/content/dns/zz_gen_acme-dns.md

@@ -3,27 +3,32 @@ title: "Joohoi's ACME-DNS"
 date: 2019-03-03T16:39:46+01:00
 draft: false
 slug: acme-dns
+dnsprovider:
+  since:    "v1.1.0"
+  code:     "acme-dns"
+  url:      "https://github.com/joohoi/acme-dns"
 ---
 
 <!-- THIS DOCUMENTATION IS AUTO-GENERATED. PLEASE DO NOT EDIT. -->
 <!-- providers/dns/acmedns/acmedns.toml -->
 <!-- THIS DOCUMENTATION IS AUTO-GENERATED. PLEASE DO NOT EDIT. -->
 
-Since: v1.1.0
 
 Configuration for [Joohoi's ACME-DNS](https://github.com/joohoi/acme-dns).
 
 
 <!--more-->
 
 - Code: `acme-dns`
+- Since: v1.1.0
+
 
 Here is an example bash command using the Joohoi's ACME-DNS provider:
 
 ```bash
 ACME_DNS_API_BASE=http://10.0.0.8:4443 \
 ACME_DNS_STORAGE_PATH=/root/.lego-acme-dns-accounts.json \
-lego --email myemail@example.com --dns acme-dns --domains my.example.org run
+lego --email you@example.com --dns acme-dns --domains my.example.org run
 ```
 
 
@@ -37,7 +42,7 @@ lego --email myemail@example.com --dns acme-dns --domains my.example.org run
 | `ACME_DNS_STORAGE_PATH` | The ACME-DNS JSON account data file. A per-domain account will be registered/persisted to this file and used for TXT updates. |
 
 The environment variable names can be suffixed by `_FILE` to reference a file instead of a value.
-More information [here](/lego/dns/#configuration-and-credentials).
+More information [here]({{< ref "dns#configuration-and-credentials" >}}).
 
 
 

docs/content/dns/zz_gen_alidns.md

@@ -3,33 +3,38 @@ title: "Alibaba Cloud DNS"
 date: 2019-03-03T16:39:46+01:00
 draft: false
 slug: alidns
+dnsprovider:
+  since:    "v1.1.0"
+  code:     "alidns"
+  url:      "https://www.alibabacloud.com/product/dns"
 ---
 
 <!-- THIS DOCUMENTATION IS AUTO-GENERATED. PLEASE DO NOT EDIT. -->
 <!-- providers/dns/alidns/alidns.toml -->
 <!-- THIS DOCUMENTATION IS AUTO-GENERATED. PLEASE DO NOT EDIT. -->
 
-Since: v1.1.0
 
 Configuration for [Alibaba Cloud DNS](https://www.alibabacloud.com/product/dns).
 
 
 <!--more-->
 
 - Code: `alidns`
+- Since: v1.1.0
+
 
 Here is an example bash command using the Alibaba Cloud DNS provider:
 
 ```bash
 # Setup using instance RAM role
 ALICLOUD_RAM_ROLE=lego \
-lego --email myemail@example.com --dns alidns --domains my.example.org run
+lego --email you@example.com --dns alidns --domains my.example.org run
 
 # Or, using credentials
 ALICLOUD_ACCESS_KEY=abcdefghijklmnopqrstuvwx \
 ALICLOUD_SECRET_KEY=your-secret-key \
 ALICLOUD_SECURITY_TOKEN=your-sts-token \
-lego --email myemail@example.com --dns alidns --domains my.example.org run
+lego --email you@example.com --dns alidns --domains my.example.org run
 ```
 
 
@@ -45,7 +50,7 @@ lego --email myemail@example.com --dns alidns --domains my.example.org run
 | `ALICLOUD_SECURITY_TOKEN` | STS Security Token (optional) |
 
 The environment variable names can be suffixed by `_FILE` to reference a file instead of a value.
-More information [here](/lego/dns/#configuration-and-credentials).
+More information [here]({{< ref "dns#configuration-and-credentials" >}}).
 
 
 ## Additional Configuration
@@ -58,7 +63,7 @@ More information [here](/lego/dns/#configuration-and-credentials).
 | `ALICLOUD_TTL` | The TTL of the TXT record used for the DNS challenge |
 
 The environment variable names can be suffixed by `_FILE` to reference a file instead of a value.
-More information [here](/lego/dns/#configuration-and-credentials).
+More information [here]({{< ref "dns#configuration-and-credentials" >}}).
 
 
 

docs/content/dns/zz_gen_allinkl.md

@@ -3,27 +3,32 @@ title: "all-inkl"
 date: 2019-03-03T16:39:46+01:00
 draft: false
 slug: allinkl
+dnsprovider:
+  since:    "v4.5.0"
+  code:     "allinkl"
+  url:      "https://all-inkl.com"
 ---
 
 <!-- THIS DOCUMENTATION IS AUTO-GENERATED. PLEASE DO NOT EDIT. -->
 <!-- providers/dns/allinkl/allinkl.toml -->
 <!-- THIS DOCUMENTATION IS AUTO-GENERATED. PLEASE DO NOT EDIT. -->
 
-Since: v4.5.0
 
 Configuration for [all-inkl](https://all-inkl.com).
 
 
 <!--more-->
 
 - Code: `allinkl`
+- Since: v4.5.0
+
 
 Here is an example bash command using the all-inkl provider:
 
 ```bash
 ALL_INKL_LOGIN=xxxxxxxxxxxxxxxxxxxxxxxxxx \
 ALL_INKL_PASSWORD=yyyyyyyyyyyyyyyyyyyyyyyyyy \
-lego --email myemail@example.com --dns allinkl --domains my.example.org run
+lego --email you@example.com --dns allinkl --domains my.example.org run
 ```
 
 
@@ -37,7 +42,7 @@ lego --email myemail@example.com --dns allinkl --domains my.example.org run
 | `ALL_INKL_PASSWORD` | KAS password |
 
 The environment variable names can be suffixed by `_FILE` to reference a file instead of a value.
-More information [here](/lego/dns/#configuration-and-credentials).
+More information [here]({{< ref "dns#configuration-and-credentials" >}}).
 
 
 ## Additional Configuration
@@ -49,7 +54,7 @@ More information [here](/lego/dns/#configuration-and-credentials).
 | `ALL_INKL_PROPAGATION_TIMEOUT` | Maximum waiting time for DNS propagation |
 
 The environment variable names can be suffixed by `_FILE` to reference a file instead of a value.
-More information [here](/lego/dns/#configuration-and-credentials).
+More information [here]({{< ref "dns#configuration-and-credentials" >}}).