dev: new way to fill the documentation

.github/workflows/deploy-documentation.yml

@@ -31,19 +31,8 @@ jobs:
           wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
           && sudo dpkg -i ${{ runner.temp }}/hugo.deb
 
-      - name: Build Documentation assets
-        run: make website_copy_jsonschema website_expand_templates
-
       - name: Build Documentation
-        env:
-          # For maximum backward compatibility with Hugo modules
-          HUGO_ENVIRONMENT: production
-          HUGO_ENV: production
-        working-directory: ./docs
-        run: |
-          hugo \
-            --gc --minify \
-            --baseURL "https://golangci-lint.run/"
+        run: make docs_build
 
       - name: Deploy to GitHub Pages
         uses: peaceiris/actions-gh-pages@v4

.github/workflows/pr-documentation.yml

@@ -31,12 +31,4 @@ jobs:
           && sudo dpkg -i ${{ runner.temp }}/hugo.deb
 
       - name: Build Documentation
-        env:
-          # For maximum backward compatibility with Hugo modules
-          HUGO_ENVIRONMENT: production
-          HUGO_ENV: production
-        working-directory: ./docs
-        run: |
-          hugo \
-            --gc --minify \
-            --baseURL "https://golangci-lint.run/"
+        run: make docs_build

CHANGELOG.md

@@ -6,6 +6,8 @@ If you value it, consider supporting us, we appreciate it!
 
 [![Donate](https://img.shields.io/badge/Donate-❤️-blue?style=for-the-badge)](https://donate.golangci.org)
 
+<!-- START --->
+
 ### v2.3.1
 
 1. Linters bug fixes

Makefile

@@ -101,18 +101,18 @@ go.sum: go.mod
 
 # Documentation
 
-docs_serve:
+docs_serve: website_expand_templates
 	@make -C ./docs serve
 .PHONY: docs_serve
 
-docs_reset:
-	@make -C ./docs reset
-.PHONY: docs_reset
-
 docs_clean:
 	@make -C ./docs clean
 .PHONY: docs_clean
 
+docs_build: website_copy_jsonschema website_expand_templates
+	@make -C ./docs build
+.PHONY: docs_build
+
 docs/static/demo.gif: FORCE
 	vhs docs/golangci-lint.tape
 

docs/.gitignore

@@ -1,4 +1,9 @@
+# Hugo files
 .hugo_build.lock
 public/
-/static/jsonschema/
 resources/
+
+# Generated files
+/static/jsonschema/
+data/version.json
+.tmp/

docs/Makefile

@@ -1,12 +1,17 @@
-.PHONY: default clean reset serve
+.PHONY: default clean serve build
 
 default: clean serve
 
 clean:
 	rm -rf public/
 
-reset:
-	git checkout HEAD content/
-
 serve: clean
-	hugo server --disableFastRender --buildDrafts --enableGitInfo --watch --source .
+	hugo server --disableFastRender --buildDrafts --enableGitInfo
+
+# IMPORTANT used by the CI to deploy documentation
+build: clean
+	HUGO_ENVIRONMENT=production \
+	HUGO_ENV=production \
+	hugo \
+		--gc --minify \
+		--baseURL "https://golangci-lint.run/"

docs/assets/css/custom.css

@@ -8,3 +8,11 @@
 .hx-line-clamp-3.hextra-card-subtitle {
   -webkit-line-clamp: 30;
 }
+
+.author-cards {
+    grid-template-columns: repeat(auto-fill, minmax(max(150px, calc((100% - 1rem * 4) / var(--hextra-cards-grid-cols))), 1fr));
+}
+
+.gl-hidden {
+    display: none;
+}

docs/content/docs/_index.md

@@ -33,8 +33,7 @@ Golangci-lint is a free and open-source project built by volunteers.
 
 If you value it, consider supporting us, we appreciate it!
 
-<div class="hx-mb-6"></div>
-<div class="hx-mb-6">
+<div class="hx-mt-6 hx-mb-6">
 {{< hextra/hero-button text="Donate ❤️" link="https://donate.golangci.org" >}}
 </div>
 

docs/content/docs/configuration/cli.md

@@ -3,10 +3,7 @@ title: Command-Line
 weight: 1
 ---
 
-```console
-$ golangci-lint -h
-{.CmdRootHelpText}
-```
+{{% cli-output %}}
 
 ## `run`
 
@@ -16,10 +13,7 @@ $ golangci-lint -h
     {{< card link="/docs/linters/configuration/" title="Linter Settings" icon="adjustments" >}}
 {{< /cards >}}
 
-```console
-$ golangci-lint run -h
-{.CmdRunHelpText}
-```
+{{% cli-output cmd="run" %}}
 
 When the `--cpu-profile-path` or `--mem-profile-path` arguments are specified,
 golangci-lint writes runtime profiling data in the format expected by the [pprof](https://github.com/google/pprof) visualization tool.
@@ -35,38 +29,23 @@ the `go tool trace` command and visualization tool.
 {{< card link="/docs/formatters/configuration/" title="Formatter Settings" icon="adjustments" >}}
 {{< /cards >}}
 
-```console
-$ golangci-lint fmt -h
-{.CmdFmtHelpText}
-```
+{{% cli-output cmd="fmt" %}}
 
 ## `migrate`
 
-```console
-$ golangci-lint migrate -h
-{.CmdMigrateHelpText}
-```
+{{% cli-output cmd="migrate" %}}
 
 ## `formatters`
 
-```console
-$ golangci-lint formatters -h
-{.CmdFormattersHelpText}
-```
+{{% cli-output cmd="formatters" %}}
 
 ## `help`
 
-```console
-$ golangci-lint help -h
-{.CmdHelpText}
-```
+{{% cli-output cmd="help" %}}
 
 ## `linters`
 
-```console
-$ golangci-lint linters -h
-{.CmdLintersHelpText}
-```
+{{% cli-output cmd="linters" %}}
 
 ## `cache`
 
@@ -76,35 +55,20 @@ You can override the default cache directory with the environment variable `GOLA
 
 The cache is only used by `golangci-lint run` (linters).
 
-```console
-$ golangci-lint cache -h
-{.CmdCacheHelpText}
-```
+{{% cli-output cmd="cache" %}}
 
 ## `config`
 
-```console
-$ golangci-lint config -h
-{.CmdConfigHelpText}
-```
+{{% cli-output cmd="config" %}}
 
 ## `custom`
 
-```console
-$ golangci-lint custom -h
-{.CmdCustomHelpText}
-```
+{{% cli-output cmd="custom" %}}
 
 ## `version`
 
-```console
-$ golangci-lint version -h
-{.CmdVersionHelpText}
-```
+{{% cli-output cmd="version" %}}
 
 ## `completion`
 
-```console
-$ golangci-lint completion -h
-{.CmdCompletionHelpText}
-```
+{{% cli-output cmd="completion" %}}

docs/content/docs/configuration/file.md

@@ -18,8 +18,47 @@ Config options inside the file are identical to command-line options.
 You can configure specific linters' options only within the config file (not the command-line).
 
 There is a [`.golangci.reference.yml`](https://github.com/golangci/golangci-lint/blob/HEAD/.golangci.reference.yml) file with all supported options, their descriptions, and default values.
-This file is neither a working example nor a recommended configuration, it's just a reference to display all the configuration options.
+This file is neither a working example nor a recommended configuration,
+it's just a reference to display all the configuration options used to generate the documentation.
 
 The configuration file can be validated with the JSON Schema: [golangci.jsonschema.json](https://golangci-lint.run/jsonschema/golangci.jsonschema.json)
 
-{ .ConfigurationExample }
+{{% configuration-file-snippet section="root" %}}
+
+## `version` configuration
+
+{{% configuration-file-snippet section="version" %}}
+
+## `linters` configuration
+
+{{< cards  cols=2 >}}
+{{< card link="/docs/linters" title="Linters Overview" icon="collection" >}}
+{{< card link="/docs/linters/configuration" title="Linters  Settings" icon="adjustments" >}}
+{{< /cards >}}
+
+{{% configuration-file-snippet section="linters" %}}
+
+## `formatters` configuration
+
+{{< cards  cols=2 >}}
+{{< card link="/docs/formatters" title="Formatters Overview" icon="collection" >}}
+{{< card link="/docs/formatters/configuration" title="Formatters  Settings" icon="adjustments" >}}
+{{< /cards >}}
+
+{{% configuration-file-snippet section="formatters" %}}
+
+## `issues` configuration
+
+{{% configuration-file-snippet section="issues" %}}
+
+## `output` configuration
+
+{{% configuration-file-snippet section="output" %}}
+
+## `run` configuration
+
+{{% configuration-file-snippet section="run" %}}
+
+## `severity` configuration
+
+{{% configuration-file-snippet section="severity" %}}