Switch to "Hugo Relearn" theme (contao#1501)

Author: fritzmg

.github/workflows/build_and_deploy.yaml

@@ -17,7 +17,7 @@ jobs:
             - name: Setup Hugo
               uses: peaceiris/actions-hugo@v2
               with:
-                  hugo-version: '0.135.0'
+                  hugo-version: '0.144.2'
             - name: Build user manual
               run: make build-manual
             - name: Build developer manual

.gitmodules

@@ -1,3 +1,3 @@
-[submodule "page/themes/hugo-theme-learn"]
-	path = page/themes/hugo-theme-learn
-	url = https://github.com/matcornic/hugo-theme-learn
+[submodule "page/themes/hugo-theme-relearn"]
+	path = page/themes/hugo-theme-relearn
+	url = https://github.com/McShelby/hugo-theme-relearn

CONTRIBUTING.md

@@ -9,8 +9,8 @@ Only major versions are documented (e.g. Contao 4 and later on Contao 5).
 ## General rules
 
 * Only use ATX style headlines (e.g. `# H1` or `### H3`).
-* See [learn.netlify.app/en/cont/markdown/](https://learn.netlify.app/en/cont/markdown/) 
-  and [learn.netlify.app/en/shortcodes/](https://learn.netlify.app/en/shortcodes/) 
+* See [mcshelby.github.io/hugo-theme-relearn/authoring/markdown/](https://mcshelby.github.io/hugo-theme-relearn/authoring/markdown/index.html) 
+  and [mcshelby.github.io/hugo-theme-relearn/shortcodes/](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/index.html) 
   for available markdown and shortcode syntax.
 * Always add two empty lines above each headline.
 * Add line breaks after 140 characters in paragraphs.
@@ -71,13 +71,13 @@ The short code tabs allows you to group content. Very handy for providing code s
 providing configuration in different formats.
 
 ```
-{{< tabs groupId="Example">}}
+{{< tabs groupid="Example" style="code" >}}
 
-{{% tab name="PHP" %}}
+{{% tab title="PHP" %}}
 Lorem ipsum dolor sit amet ...
 {{% /tab %}}
 
-{{% tab name="Twig" %}}
+{{% tab title="Twig" %}}
 Lorem ipsum dolor sit amet ...
 {{% /tab %}}
 
@@ -118,6 +118,9 @@ Lorem ipsum dolor sit amet ...
 {{% /faq %}}
 ```
 
+_Note:_ only use this for actual FAQs - otherwise use the [`expand`](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/expand/index.html)
+shortcode.
+
 
 ## New features
 

README.md

@@ -8,7 +8,7 @@ If you just want to contribute content, read the [CONTRIBUTING](CONTRIBUTING.md)
 
 ## Cloning
 
-The project installs the Hugo Learn theme as a git submodule. Thus when cloning
+The project installs the [Hugo Relearn Theme](https://mcshelby.github.io/hugo-theme-relearn/) as a git submodule. Thus when cloning
 the repository, you need to use the `--recurse-submodules` parameter:
 
 ```bash
@@ -23,12 +23,20 @@ git clone --recurse-submodules https://github.com/contao/docs.git
 
 ## Updating the Theme
 
-To update the theme after cloning, simply run the following command:
+Due to the switch of the theme from Hugo Learn to Hugo Relearn, you will need to execute
 
 ```bash
-git submodule foreach git pull origin master
+git submodule sync
+git submodule update
 ```
 
+once, if you had already checked out the repository before the switch.
+
+To update the theme after cloning - or after the theme switch, run the following command:
+
+```bash
+git submodule foreach git pull origin main
+```
 
 ## Build
 

docs/dev/_index.md

@@ -1,5 +1,6 @@
 ---
-title: "Contao Developer Documentation"
+title: Contao Developer Documentation
+type: home
 ---
 
 

docs/dev/framework/content-elements.md

@@ -128,7 +128,7 @@ As mentioned previously a content element is registered by registering a control
 | Option   | Type      | Description                                                                                                                               |
 | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------|
 | name     | `string`  | Must be `contao.content_element`.                                                                                                         |
-| type     | `string`  | _Optional:_ The *type* mentioned in [Type]({{< ref "#type" >}}) can be customized.                                                        |
+| type     | `string`  | _Optional:_ The *type* mentioned in [Type]({{% ref "#type" %}}) can be customized.                                                        |
 | category | `string`  | Defines in which option group this content element will be placed in the content element selector.                                        |
 | template | `string`  | _Optional:_ Override the generated template name.                                                                                         |
 | renderer | `string`  | _Optional:_ The renderer can be changed to `inline` or `esi`. Defaults to `forward`. See [Caching Fragments][fragments] for more details. |
@@ -137,9 +137,9 @@ As mentioned previously a content element is registered by registering a control
 
 Applying the service tag can either be done via PHP attributes, annotations or via the YAML configuration.
 
-{{< tabs groupId="attribute-annotation-yaml" >}}
+{{< tabs groupid="attribute-annotation-yaml" style="code" >}}
 
-{{% tab name="Attribute" %}}
+{{% tab title="Attribute" %}}
 {{< version-tag "4.13" >}} A content element can be registered using the `AsContentElement` PHP attribute.
 
 ```php
@@ -190,7 +190,7 @@ class ExampleElementController extends AbstractContentElementController
 However, it is recommended to only define what you need and otherwise leave the defaults.
 {{% /tab %}}
 
-{{% tab name="Annotation" %}}
+{{% tab title="Annotation" %}}
 {{< version-tag "4.8" >}} A content element can be registered using the `ContentElement` annotation. The annotation can be used on the class of the content element,
 if the class is invokable (has an `__invoke` method) or extends from the `AbstractContentElementController`. Otherwise the annotation can be 
 used on the method that will deliver the response.
@@ -247,7 +247,7 @@ class ExampleElementController extends AbstractContentElementController
 However, it is recommended to only define what you need and otherwise leave the defaults.
 {{% /tab %}}
 
-{{% tab name="YAML" %}}
+{{% tab title="YAML" %}}
 {{< version-tag "4.8" >}} A content element can be registered using the `contao.content_element` service tag.
 
 ```yaml
@@ -415,9 +415,9 @@ article of a page.
 
 Allowing nested fragments for your content element works via the `nestedFragments` option in the service tag:
 
-{{< tabs groupId="attribute-annotation-yaml" >}}
+{{< tabs groupid="attribute-annotation-yaml" style="code" >}}
 
-{{% tab name="Attribute" %}}
+{{% tab title="Attribute" %}}
 ```php
 #[AsContentElement(nestedFragments: true)]
 class ExampleElementController extends AbstractContentElementController
@@ -430,7 +430,7 @@ class ExampleElementController extends AbstractContentElementController
 ```
 {{% /tab %}}
 
-{{% tab name="Annotation" %}}
+{{% tab title="Annotation" %}}
 ```php
 /**
  * @ContentElement(category="miscellaneous", nestedFragments=true)
@@ -445,7 +445,7 @@ class ExampleElementController extends AbstractContentElementController
 ```
 {{% /tab %}}
 
-{{% tab name="YAML" %}}
+{{% tab title="YAML" %}}
 ```yaml
 services:
     App\Controller\ContentElement\ExampleElementController:
@@ -463,9 +463,9 @@ want to implement a specific slider content element which should only allow imag
 instead of defining `true` for the tag's `nestedFragments` option you can instead pass an additional option called
 `allowedTypes`:
 
-{{< tabs groupId="attribute-annotation-yaml" >}}
+{{< tabs groupid="attribute-annotation-yaml" style="code" >}}
 
-{{% tab name="Attribute" %}}
+{{% tab title="Attribute" %}}
 ```php
 #[AsContentElement(nestedFragments: ['allowedTypes' => ['image', 'video']])]
 class ExampleElementController extends AbstractContentElementController
@@ -478,7 +478,7 @@ class ExampleElementController extends AbstractContentElementController
 ```
 {{% /tab %}}
 
-{{% tab name="Annotation" %}}
+{{% tab title="Annotation" %}}
 ```php
 /**
  * @ContentElement(category="miscellaneous", nestedFragments={"allowedTypes" = {"image", "video"}})
@@ -493,7 +493,7 @@ class ExampleElementController extends AbstractContentElementController
 ```
 {{% /tab %}}
 
-{{% tab name="YAML" %}}
+{{% tab title="YAML" %}}
 ```yaml
 services:
     App\Controller\ContentElement\ExampleElementController:

docs/dev/framework/cron.md

@@ -134,8 +134,8 @@ Generally cron jobs can be registered through the `contao.cronjob` service tag.
 | `interval` | Can be `minutely`, `hourly`, `daily`, `weekly`, `monthly`, `yearly` or a full CRON expression, like `*/5 * * * *`. |
 | `method` | Will default to `__invoke` or `onMinutely` etc. when a named interval is used. Otherwise a method name has to be defined. |
 
-{{< tabs groupId="attribute-annotation-yaml-php" >}}
-{{% tab name="Attribute" %}}
+{{< tabs groupid="attribute-annotation-yaml-php" style="code" >}}
+{{% tab title="Attribute" %}}
 {{< version-tag "4.13" >}} Contao implements [PHP attributes](https://www.php.net/manual/en/language.attributes.overview.php) (available 
 since **PHP 8**) with which you can tag your service to be registered as a cron job.
 
@@ -159,7 +159,7 @@ In this case the cron job is executed once per hour. As mentioned before this pa
 `*/5 * * * *` for "every 5 minutes".
 {{% /tab %}}
 
-{{% tab name="Annotation" %}}
+{{% tab title="Annotation" %}}
 {{< version-tag "4.9" >}} Contao also supports its own annotation formats via the [Service Annotation Bundle](https://github.com/terminal42/service-annotation-bundle).
 
 ```php
@@ -189,7 +189,7 @@ with `\`, since `*/` would close the PHP comment.
 {{% /notice %}}
 {{% /tab %}}
 
-{{% tab name="YAML" %}}
+{{% tab title="YAML" %}}
 {{< version-tag "4.9" >}} As mentioned before you can manually add the `contao.cronjob` service tag in your service configuration.
 
 ```yaml
@@ -216,7 +216,7 @@ Only the `interval` parameter is required. In this case the cron job is executed
 be a full CRON expression, e.g. `*/5 * * * *` for "every 5 minutes".
 {{% /tab %}}
 
-{{% tab name="PHP" %}}
+{{% tab title="PHP" %}}
 
 {{% notice "info" %}}
 This method is deprecated since Contao **4.13** and does not work in Contao **5** anymore.

docs/dev/framework/csp.md

@@ -60,18 +60,18 @@ to an external source - e.g. via an `<iframe>` or `<script src="…">` etc. - th
 browser. However, your application might deliberately want to include external resources and thus it is necessary to 
 allow this resource specifically (or at least the domain of that resource). This can be done via the `addSource` method:
 
-{{< tabs groupId="csp-methods" >}}
-{{% tab name="PHP" %}}
+{{< tabs groupid="csp-methods" style="code" >}}
+{{% tab title="PHP" %}}
 ```php
 $cspHandler->addSource('frame-src', 'https://www.youtube.com/embed/foobar123');
 ```
 {{% /tab %}}
-{{% tab name="Twig" %}}
+{{% tab title="Twig" %}}
 ```twig
 {% do csp_source('frame-src', 'https://www.youtube.com/embed/foobar123') %}
 ```
 {{% /tab %}}
-{{% tab name="PHP Template" %}}
+{{% tab title="PHP Template" %}}
 ```php
 <?php $this->addCspSource('frame-src', 'https://www.youtube.com/embed/foobar123') ?>
 ```
@@ -93,18 +93,18 @@ without having to resort to allowing `'unsafe-inline'` in your directives. Conta
 instance still use inline JavaScript and thus will add a nonce when used. You can retrieve a nonce for `script-src` or 
 `style-src` like this:
 
-{{< tabs groupId="csp-methods" >}}
-{{% tab name="PHP" %}}
+{{< tabs groupid="csp-methods" style="code" >}}
+{{% tab title="PHP" %}}
 ```php
 $nonce = $cspHandler->getNonce('script-src');
 ```
 {{% /tab %}}
-{{% tab name="Twig" %}}
+{{% tab title="Twig" %}}
 ```twig
 <script{{ attrs().setIfExists('nonce', csp_nonce('script-src')) }}>
 ```
 {{% /tab %}}
-{{% tab name="PHP Template" %}}
+{{% tab title="PHP Template" %}}
 ```php
 <script<?= $this->attr()->setIfExists('nonce', $this->nonce('script-src')) ?>>
 ```
@@ -127,19 +127,19 @@ inline scripts or inline styles. This also includes inline scripts via HTML attr
 this is not possible such inline scripts can still be allowed through [hashes][CSPHash]. A hash can be generated and
 added to a directive for a specific inline script or style like this:
 
-{{< tabs groupId="csp-methods" >}}
-{{% tab name="PHP" %}}
+{{< tabs groupid="csp-methods" style="code" >}}
+{{% tab title="PHP" %}}
 ```php
 $cspHandler->addHash('style-src', 'display:none');
 ```
 {{% /tab %}}
-{{% tab name="Twig" %}}
+{{% tab title="Twig" %}}
 ```twig
 {% do csp_hash('display:none') %}
 <div style="display:none">
 ```
 {{% /tab %}}
-{{% tab name="PHP Template" %}}
+{{% tab title="PHP Template" %}}
 ```php
 <div style="<?= $this->cspInlineStyle('display:none') ?>">
 ```
@@ -166,8 +166,8 @@ and then their hashes are added via the `CspHandler`. The allowed inline style p
 
 The `'unsafe-hashes'` directive will also be added automatically by the template helpers for CSP Level 3 compliance.
 
-{{< tabs groupId="csp-methods" >}}
-{{% tab name="PHP" %}}
+{{< tabs groupid="csp-methods" style="code" >}}
+{{% tab title="PHP" %}}
 You can use the `WysiwygStyleProcessor` directly in your services if you want to. Though typically you will likely only
 need it in your templates (see other methods).
 
@@ -211,13 +211,13 @@ class ExampleService
 }
 ```
 {{% /tab %}}
-{{% tab name="Twig" %}}
+{{% tab title="Twig" %}}
 In Twig you can use the filter `csp_inline_styles`. See the following example from Contao's `text.html.twig` template:
 ```twig
 {{ text|csp_inline_styles|insert_tag|encode_email|raw }}
 ```
 {{% /tab %}}
-{{% tab name="PHP Template" %}}
+{{% tab title="PHP Template" %}}
 ```php
 <?= $this->cspInlineStyles($this->text) ?>
 ```