docs: upgrade theme and minor fixes (#245)

* docs: upgrade theme and minor fixes * docs: update default settings for highlight * docs: refactoring :) * Fixes "go to top" link in updated relearn theme * docs: add setcap draft * docs: final tweaks --------- Co-authored-by: jkellerer <[email protected]>
creativeprojects · Aug 11, 2023 · 1024189 · 1024189
1 parent 9c05157
commit 1024189
Show file tree

Hide file tree

Showing 41 changed files with 479 additions and 431 deletions.
diff --git a/Makefile b/Makefile
@@ -264,7 +264,7 @@ generate-config-reference: build
 	LAYOUT_NOTICE_END="{{% /notice %}}" \
 	LAYOUT_HINT_START="{{% notice hint %}}" \
 	LAYOUT_HINT_END="{{% /notice %}}" \
-	LAYOUT_UPLINK="[go to top](#topbar)" \
+	LAYOUT_UPLINK="[go to top](#reference)" \
 	$(abspath $(BINARY)) generate --config-reference > $(CONFIG_REFERENCE_DIR)/index.md
 
 syslog:

diff --git a/docs/config.toml b/docs/config.toml
@@ -7,7 +7,7 @@ publishdir = "../public/"
 
 # For search functionality
 [outputs]
-  home = [ "HTML", "RSS", "JSON"]
+  home = [ "HTML", "RSS", "SEARCH", "SEARCHPAGE"]
 
 [params]
   # Change default color scheme with a variant one.
@@ -30,3 +30,22 @@ publishdir = "../public/"
   identifier = "resticdoc"
   url = "https://restic.readthedocs.io/"
   weight = 30
+
+[markup]
+  [markup.highlight]
+    # line numbers in a table layout will shift if code is wrapping, so better
+    # use inline; besides that visually both layouts have the same look and behavior
+    lineNumbersInTable = false
+
+    # if `guessSyntax = true`, there will be no unstyled code even if no language
+    # was given BUT Mermaid and Math codefences will not work anymore! So this is a
+    # mandatory setting for your site if you want to use Mermaid or Math codefences
+    guessSyntax = false
+
+    # the shipped variants come with their own modified chroma syntax highlightning
+    # style which is imported in theme-relearn-light.css, theme-relearn-dark.css, etc.;
+    # if you want to use a predefined style instead:
+    # - remove `noClasses` or set `noClasses = true`
+    # - set `style` to a predefined style name
+    noClasses = false
+    # style = "tango"
diff --git a/docs/content/_index.md b/docs/content/_index.md
@@ -1,3 +1,6 @@
+---
+archetype: "home"
+---
 
 # resticprofile
 Configuration profiles manager for [restic backup](https://restic.net/)

diff --git a/docs/content/configuration/_index.md b/docs/content/configuration/_index.md
@@ -1,20 +1,18 @@
 +++
-chapter = true
+archetype = "chapter"
 pre = "<b>2. </b>"
-title = "Configuration"
-weight = 10
+title = "Configuration file"
+weight = 2
 +++
 
 
-# Configuration file
-
 * A configuration is a set of _profiles_.
 * Each profile is in a new section that has the name of the profile.
 * Inside each profile, you can specify different flags for each command.
 * A command definition is in a subsection of the name of the command.
 
-{{< tabs groupId="config-with-json" >}}
-{{% tab name="toml" %}}
+{{< tabs groupid="config-with-json" >}}
+{{% tab title="toml" %}}
 
 ```toml
 [profile_name]
@@ -24,7 +22,7 @@ weight = 10
 ```
 
 {{% /tab %}}
-{{% tab name="yaml" %}}
+{{% tab title="yaml" %}}
 
 ```yaml
 profile_name:
@@ -34,7 +32,7 @@ profile_name:
 ```
 
 {{% /tab %}}
-{{% tab name="hcl" %}}
+{{% tab title="hcl" %}}
 
 ```hcl
 profile_name {
@@ -46,7 +44,7 @@ profile_name {
 ```
 
 {{% /tab %}}
-{{% tab name="json" %}}
+{{% tab title="json" %}}
 
 ```json
 {
@@ -72,13 +70,13 @@ There's **one exception**: the flag `--repo` is named `repository` in the config
 So let's say you normally use this simple command:
 
 ```shell
-$ restic --repo "local:/backup" --password-file "password.txt" --verbose backup /home
+restic --repo "local:/backup" --password-file "password.txt" --verbose backup /home
 ```
 
 For resticprofile to generate this command automatically for you, here's the configuration file:
 
-{{< tabs groupId="config-with-json" >}}
-{{% tab name="toml" %}}
+{{< tabs groupid="config-with-json" >}}
+{{% tab title="toml" %}}
 
 ```toml
 # indentation is not needed but it makes it easier to read ;)
@@ -95,7 +93,7 @@ version = "1"
 ```
 
 {{% /tab %}}
-{{% tab name="yaml" %}}
+{{% tab title="yaml" %}}
 
 ```yaml
 version: "1"
@@ -111,7 +109,7 @@ default:
 ```
 
 {{% /tab %}}
-{{% tab name="hcl" %}}
+{{% tab title="hcl" %}}
 
 ```hcl
 default {
@@ -126,7 +124,7 @@ default {
 ```
 
 {{% /tab %}}
-{{% tab name="json" %}}
+{{% tab title="json" %}}
 
 ```json
 {
@@ -153,15 +151,15 @@ You may have noticed the `source` flag is accepting an array of values (inside b
 Now, assuming this configuration file is named `profiles.conf` in the current folder (it's the default config file name), you can simply run
 
 ```shell
-$ resticprofile backup
+resticprofile backup
 ```
 
 and resticprofile will do its magic and generate the command line for you.
 
 If you have any doubt on what it's running, you can try a `--dry-run`:
 
 ```shell
-$ resticprofile --dry-run backup
+resticprofile --dry-run backup
 2022/05/18 17:14:07 profile 'default': starting 'backup'
 2022/05/18 17:14:07 dry-run: /usr/bin/restic backup --password-file password.txt --repo local:/backup --verbose /home
 2022/05/18 17:14:07 profile 'default': finished 'backup'

diff --git a/docs/content/configuration/copy/index.md b/docs/content/configuration/copy/index.md
@@ -11,8 +11,8 @@ weight: 17
 The copy command needs two repositories (and quite likely 2 different set of keys). You can configure a `copy` section like this:
 
 
-{{< tabs groupId="config-with-hcl" >}}
-{{% tab name="toml" %}}
+{{< tabs groupid="config-with-hcl" >}}
+{{% tab title="toml" %}}
 
 ```toml
 version = "1"
@@ -29,7 +29,7 @@ version = "1"
 ```
 
 {{% /tab %}}
-{{% tab name="yaml" %}}
+{{% tab title="yaml" %}}
 
 ```yaml
 version: "1"
@@ -45,7 +45,7 @@ default:
 ```
 
 {{% /tab %}}
-{{% tab name="hcl" %}}
+{{% tab title="hcl" %}}
 
 
 ```hcl
@@ -72,8 +72,8 @@ You will note that the secondary repository doesn't need to have a `2` behind it
 If you want to initialize the *copy* repository using the `copy-chunker-params` flag, it needs to be called `initialize-copy-chunker-params` instead. As such, this flag does not exist on the `copy` target which is why we need to prefix it.
 
 
-{{< tabs groupId="config-with-hcl" >}}
-{{% tab name="toml" %}}
+{{< tabs groupid="config-with-hcl" >}}
+{{% tab title="toml" %}}
 
 ```toml
 version = "1"
@@ -91,7 +91,7 @@ version = "1"
 ```
 
 {{% /tab %}}
-{{% tab name="yaml" %}}
+{{% tab title="yaml" %}}
 
 ```yaml
 version: "1"
@@ -108,7 +108,7 @@ profile:
 ```
 
 {{% /tab %}}
-{{% tab name="hcl" %}}
+{{% tab title="hcl" %}}
 
 
 ```hcl

diff --git a/docs/content/configuration/examples/_index.md b/docs/content/configuration/examples/_index.md
@@ -8,8 +8,8 @@ weight: 5
 
 Here's a simple configuration file using a Microsoft Azure backend. You will notice that the `env` section lets you define environment variables:
 
-{{< tabs groupId="config-with-hcl" >}}
-{{% tab name="toml" %}}
+{{< tabs groupid="config-with-hcl" >}}
+{{% tab title="toml" %}}
 
 ```toml
 version = "1"
@@ -31,7 +31,7 @@ version = "1"
     source = [ "/", "/var" ]
 ```
 {{% /tab %}}
-{{% tab name="yaml" %}}
+{{% tab title="yaml" %}}
 
 ```yaml
 version: "1"
@@ -57,7 +57,7 @@ default:
 ```
 
 {{% /tab %}}
-{{% tab name="hcl" %}}
+{{% tab title="hcl" %}}
 
 ```hcl
 default {
@@ -87,8 +87,8 @@ default {
 
 Here's a more complex configuration file showing profile inheritance and two backup profiles using the same repository:
 
-{{< tabs groupId="config-with-hcl" >}}
-{{% tab name="toml" %}}
+{{< tabs groupid="config-with-hcl" >}}
+{{% tab title="toml" %}}
 
 ```toml
 version = "1"
@@ -213,7 +213,7 @@ version = "1"
 ```
 
 {{% /tab %}}
-{{% tab name="yaml" %}}
+{{% tab title="yaml" %}}
 
 ```yaml
 version: "1"
@@ -347,7 +347,7 @@ src:
 ```
 
 {{% /tab %}}
-{{% tab name="hcl" %}}
+{{% tab title="hcl" %}}
 
 ```hcl
 global {
@@ -428,8 +428,8 @@ self {
 ## Configuration example for Windows
 
 
-{{< tabs groupId="config-with-hcl" >}}
-{{% tab name="toml" %}}
+{{< tabs groupid="config-with-hcl" >}}
+{{% tab title="toml" %}}
 
 ```toml
 version = "1"
@@ -463,7 +463,7 @@ version = "1"
 ```
 
 {{% /tab %}}
-{{% tab name="yaml" %}}
+{{% tab title="yaml" %}}
 
 ```yaml
 version: "1"
@@ -499,7 +499,7 @@ test:
 ```
 
 {{% /tab %}}
-{{% tab name="hcl" %}}
+{{% tab title="hcl" %}}
 
 ```hcl
 global {
@@ -535,8 +535,8 @@ test {
 
 Simple example sending a file via stdin
 
-{{< tabs groupId="config-with-hcl" >}}
-{{% tab name="toml" %}}
+{{< tabs groupid="config-with-hcl" >}}
+{{% tab title="toml" %}}
 
 ```toml
 version = "1"
@@ -561,7 +561,7 @@ version = "1"
 ```
 
 {{% /tab %}}
-{{% tab name="yaml" %}}
+{{% tab title="yaml" %}}
 
 ```yaml
 version: "1"
@@ -586,7 +586,7 @@ mysql:
 ```
 
 {{% /tab %}}
-{{% tab name="hcl" %}}
+{{% tab title="hcl" %}}
 
 ```hcl
 # sending stream through stdin