docs: improve plugins page (#4494)

Author: ldez

docs/src/config/sidebar.yml

@@ -49,7 +49,7 @@
 - label: Plugins
   items:
     - label: Module Plugin System
-      link: /contributing/new-linters/
+      link: /plugins/module-plugins/
     - label: Go Plugin System
-      link: /contributing/private-linters/
+      link: /plugins/go-plugins/
 

docs/src/docs/plugins/module-plugins.mdx

@@ -69,3 +69,11 @@ linters:
   enable:
     - foo
 ```
+
+## Reference
+
+The configuration file can be validated with the JSON Schema: https://golangci-lint.run/jsonschema/custom-gcl.jsonschema.json
+
+```yml
+{ .CustomGCLReference }
+```

scripts/website/expand_templates/linters.go

@@ -2,6 +2,7 @@ package main
 
 import (
 	"fmt"
+	"os"
 	"path/filepath"
 	"reflect"
 	"sort"
@@ -17,6 +18,20 @@ import (
 
 const listItemPrefix = "list-item-"
 
+func getExampleSnippets() (*SettingSnippets, error) {
+	reference, err := os.ReadFile(".golangci.reference.yml")
+	if err != nil {
+		return nil, fmt.Errorf("can't read .golangci.reference.yml: %w", err)
+	}
+
+	snippets, err := extractExampleSnippets(reference)
+	if err != nil {
+		return nil, fmt.Errorf("can't extract example snippets from .golangci.reference.yml: %w", err)
+	}
+
+	return snippets, nil
+}
+
 func getLintersListMarkdown(enabled bool) string {
 	linters, err := readJSONFile[[]*types.LinterWrapper](filepath.Join("assets", "linters-info.json"))
 	if err != nil {

scripts/website/expand_templates/main.go

@@ -119,14 +119,14 @@ func getLatestVersion() (string, error) {
 }
 
 func buildTemplateContext() (map[string]string, error) {
-	golangciYamlExample, err := os.ReadFile(".golangci.reference.yml")
+	snippets, err := getExampleSnippets()
 	if err != nil {
-		return nil, fmt.Errorf("can't read .golangci.reference.yml: %w", err)
+		return nil, err
 	}
 
-	snippets, err := extractExampleSnippets(golangciYamlExample)
+	pluginReference, err := getPluginReference()
 	if err != nil {
-		return nil, fmt.Errorf("can't read .golangci.reference.yml: %w", err)
+		return nil, fmt.Errorf("failed to read plugin reference file: %w", err)
 	}
 
 	helps, err := readJSONFile[types.CLIHelp](filepath.Join("assets", "cli-help.json"))
@@ -150,7 +150,7 @@ func buildTemplateContext() (map[string]string, error) {
 	}
 
 	return map[string]string{
-		"LintersExample":                   snippets.LintersSettings,
+		"CustomGCLReference":               pluginReference,
 		"ConfigurationExample":             snippets.ConfigurationFile,
 		"LintersCommandOutputEnabledOnly":  helps.Enable,
 		"LintersCommandOutputDisabledOnly": helps.Disable,

scripts/website/expand_templates/plugins.go

@@ -0,0 +1,15 @@
+package main
+
+import (
+	"fmt"
+	"os"
+)
+
+func getPluginReference() (string, error) {
+	reference, err := os.ReadFile(".custom-gcl.reference.yml")
+	if err != nil {
+		return "", fmt.Errorf("can't read .custom-gcl.reference.yml: %w", err)
+	}
+
+	return string(reference), nil
+}