docs: organize sections and pages (#4493)

Author: ldez

docs/src/config/sidebar.yml

@@ -2,32 +2,36 @@
 
 - label: "Introduction"
   link: "/"
-- label: Usage
+- label: Welcome
   items:
     - label: "Install"
-      link: "/usage/install/"
+      link: "/welcome/install/"
     - label: "Quick Start"
-      link: "/usage/quick-start/"
+      link: "/welcome/quick-start/"
     - label: "Integrations"
-      link: "/usage/integrations/"
-    - label: "Linters"
-      link: "/usage/linters/"
+      link: "/welcome/integrations/"
+    - label: "FAQ"
+      link: "/welcome/faq/"
+- label: Usage
+  items:
     - label: "Configuration"
       link: "/usage/configuration/"
+    - label: "Linters"
+      link: "/usage/linters/"
     - label: "False Positives"
       link: "/usage/false-positives/"
-    - label: "Performance"
-      link: "/usage/performance/"
-    - label: "FAQ"
-      link: "/usage/faq/"
 - label: Product
   items:
-    - label: "Roadmap"
-      link: "/product/roadmap/"
     - label: "Thanks"
       link: "/product/thanks/"
     - label: "Trusted By"
       link: "/product/trusted-by/"
+    - label: "Changelog"
+      link: "/product/changelog/"
+    - label: "Roadmap"
+      link: "/product/roadmap/"
+    - label: "Performance"
+      link: "/product/performance/"
     - label: "GitHub"
       link: "https://github.com/golangci/golangci-lint"
 - label: Contributing

docs/src/docs/product/changelog.mdx

@@ -0,0 +1,7 @@
+---
+title: Changelog
+---
+
+## Changelog
+
+{.ChangeLog}

docs/src/docs/usage/performance.mdx renamed to docs/src/docs/product/performance.mdx

@@ -14,9 +14,55 @@ Please file an issue for bugs, missing documentation, or unexpected behavior.
 
 [See Bugs](https://github.com/golangci/golangci-lint/issues?utf8=✓&q=is%3Aissue+is%3Aopen+label%3A%22bug%22+sort%3Acreated-desc)
 
-## Changelog
+## Versioning Policy
 
-{.ChangeLog}
+`golangci-lint` follows [semantic versioning](https://semver.org). However, due to the nature of `golangci-lint` as a code quality tool,
+it's not always clear when a minor or major version bump occurs. To help clarify this for everyone, we've defined the following semantic versioning policy:
+
+- Patch release (intended to not break your lint build)
+- A patch version update in a specific linter that results in `golangci-lint` reporting fewer errors.
+- A bug fix to the CLI or core (packages loading, runner, postprocessors, etc).
+- Improvements to documentation.
+- Non-user-facing changes such as refactoring code, adding, deleting, or modifying tests, and increasing test coverage.
+- Re-releasing after a failed release (i.e., publishing a release that doesn't work for anyone).
+- Minor release (might break your lint build because of newly found issues)
+- A major or minor version update of a specific linter that results in `golangci-lint` reporting more errors.
+- A new linter is added.
+- An existing configuration option or linter is deprecated.
+- A new CLI command is created.
+- Backward incompatible change of configuration with extremely low impact, e.g. adding validation of a list of enabled `go-critic` checkers.
+- Major release (likely to break your lint build)
+- Backward incompatible change of configuration with huge impact, e.g. removing excluding issues about missed comments from `golint` by default.
+- A linter is removed.
+
+According to our policy, any minor update may report more errors than the previous release (ex: from a bug fix).
+As such, we recommend using the fixed minor version and fixed or the latest patch version to guarantee the results of your builds.
+
+For example, in our [GitHub Action](https://github.com/golangci/golangci-lint-action) we require users to explicitly set the minor version of `golangci-lint`
+and we always use the latest patch version.
+
+## Linter Deprecation Cycle
+
+A linter can be deprecated for various reasons, e.g. the linter stops working with a newer version of Go or the author has abandoned its linter.
+
+The deprecation of a linter will follow 3 phases:
+
+1. **Display of a warning message**: The linter can still be used (unless it's completely non-functional), but it's recommended to remove it from your configuration.
+2. **Display of an error message**: At this point, you should remove the linter. The original implementation is replaced by a placeholder that does nothing.
+3. **Removal of the linter** from golangci-lint.
+
+Each phase corresponds to a minor version:
+
+- v1.0.0 -> warning message
+- v1.1.0 -> error message
+- v1.2.0 -> linter removed
+
+The deprecated linters are removed from presets immediately when they are deprecated (phase 1).
+
+We will provide clear information about those changes on different supports: changelog, logs, social network, etc.
+
+We consider the removal of a linter as non-breaking changes for golangci-lint itself.
+No major version will be created when a linter is removed.
 
 ## Future Plans
 

docs/src/docs/product/roadmap.mdx

@@ -31,6 +31,8 @@ You can configure specific linters' options only within the config file (not the
 There is a [`.golangci.reference.yml`](https://github.com/golangci/golangci-lint/blob/master/.golangci.reference.yml) file with all supported options, their description, 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.
 
+The configuration file can be validated with the JSON Schema: https://golangci-lint.run/jsonschema/golangci.jsonschema.json
+
 { .ConfigurationExample }
 
 ## Command-Line Options

docs/src/docs/usage/configuration.mdx

@@ -2,55 +2,22 @@
 title: FAQ
 ---
 
-## How do you add a custom linter?
-
-You can integrate it yourself, see this [manual](/contributing/new-linters/).
-Or you can create a [GitHub Issue](https://github.com/golangci/golangci-lint/issues/new) and we will integrate when time permits.
-
-## How to integrate `golangci-lint` into large project with thousands of issues
-
-We are sure that every project can easily integrate `golangci-lint`, even the large one.
-
-The idea is to not fix all existing issues. Fix only newly added issue: issues in new code.
-To do this setup CI to run `golangci-lint` with option `--new-from-rev=HEAD~1`.
-
-Also, take a look at option `--new`, but consider that CI scripts that generate unstaged files will make `--new` only point out issues in those files and not in the last commit.
-In that regard `--new-from-rev=HEAD~1` is safer.
-
-By doing this you won't create new issues in your code and can choose fix existing issues (or not).
-
-## Why `--new-from-rev` or `--new-from-patch` don't seem to be working in some cases?
-
-The options `--new-from-rev` and `--new-from-patch` work by comparing `git diff` output and issues.
-
-If an issue is not reported as the same line as the changes then the issue will be skipped.
-This is the line of the issue is not inside the lines changed.
+## Which Go versions are supported
 
-To fix that you have to use the option `--whole-files`.
-
-The side effect is the issues inside file that contains changes but not directly related to the changes themselves will be reported.
+The same as the Go team (the 2 latest minor versions).
 
 ## How to use `golangci-lint` in CI
 
 Run `golangci-lint` in CI and check the exit code. If it's non-zero - fail the build.
 
 See [how to properly install `golangci-lint` in CI](/usage/install#ci-installation)
 
-## Which Go versions are supported
-
-The same as the Go team (the 2 last minor versions)
-
 ## `golangci-lint` doesn't work
 
 1. Please, ensure you are using the latest binary release.
 2. Run it with `-v` option and check the output.
 3. If it doesn't help create a [GitHub issue](https://github.com/golangci/golangci-lint/issues/new) with the output from the error and #2 above.
 
-## Why running with `--fast` is slow on the first run
-
-Because the first run caches type information. All subsequent runs will be fast.
-Usually this options is used during development on local machine and compilation was already performed.
-
 ## Why do you have `typecheck` errors?
 
 `typecheck` is like a front-end for the Go compiler errors.
@@ -77,3 +44,36 @@ How to troubleshoot:
 - [ ] Ensure building works with `go run ./...`/`go build ./...` - whole package.
 - [ ] Ensure you are not running an analysis on code that depends on files/packages outside the scope of the analyzed elements.
 - [ ] If using CGO, ensure all require system libraries are installed.
+
+## Why running with `--fast` is slow on the first run
+
+Because the first run caches type information. All subsequent runs will be fast.
+Usually this options is used during development on local machine and compilation was already performed.
+
+## How do you add a custom linter?
+
+You can integrate it yourself, see this [manual](/contributing/new-linters/).
+Or you can create a [GitHub Issue](https://github.com/golangci/golangci-lint/issues/new) and we will integrate when time permits.
+
+## How to integrate `golangci-lint` into large project with thousands of issues
+
+We are sure that every project can easily integrate `golangci-lint`, even the large one.
+
+The idea is to not fix all existing issues. Fix only newly added issue: issues in new code.
+To do this setup CI to run `golangci-lint` with option `--new-from-rev=HEAD~1`.
+
+Also, take a look at option `--new`, but consider that CI scripts that generate unstaged files will make `--new` only point out issues in those files and not in the last commit.
+In that regard `--new-from-rev=HEAD~1` is safer.
+
+By doing this you won't create new issues in your code and can choose fix existing issues (or not).
+
+## Why `--new-from-rev` or `--new-from-patch` don't seem to be working in some cases?
+
+The options `--new-from-rev` and `--new-from-patch` work by comparing `git diff` output and issues.
+
+If an issue is not reported as the same line as the changes then the issue will be skipped.
+This is the line of the issue is not inside the lines changed.
+
+To fix that you have to use the option `--whole-files`.
+
+The side effect is the issues inside file that contains changes but not directly related to the changes themselves will be reported.

docs/src/docs/usage/install/annotations.png renamed to docs/src/docs/welcome/annotations.png

@@ -124,56 +124,6 @@ go install github.com/golangci/golangci-lint/cmd/golangci-lint@{.LatestVersion}
 
 </div>
 
-## Versioning Policy
-
-`golangci-lint` follows [semantic versioning](https://semver.org). However, due to the nature of `golangci-lint` as a code quality tool,
-it's not always clear when a minor or major version bump occurs. To help clarify this for everyone, we've defined the following semantic versioning policy:
-
-- Patch release (intended to not break your lint build)
-  - A patch version update in a specific linter that results in `golangci-lint` reporting fewer errors.
-  - A bug fix to the CLI or core (packages loading, runner, postprocessors, etc).
-  - Improvements to documentation.
-  - Non-user-facing changes such as refactoring code, adding, deleting, or modifying tests, and increasing test coverage.
-  - Re-releasing after a failed release (i.e., publishing a release that doesn't work for anyone).
-- Minor release (might break your lint build because of newly found issues)
-  - A major or minor version update of a specific linter that results in `golangci-lint` reporting more errors.
-  - A new linter is added.
-  - An existing configuration option or linter is deprecated.
-  - A new CLI command is created.
-  - Backward incompatible change of configuration with extremely low impact, e.g. adding validation of a list of enabled `go-critic` checkers.
-- Major release (likely to break your lint build)
-  - Backward incompatible change of configuration with huge impact, e.g. removing excluding issues about missed comments from `golint` by default.
-  - A linter is removed.
-
-According to our policy, any minor update may report more errors than the previous release (ex: from a bug fix).
-As such, we recommend using the fixed minor version and fixed or the latest patch version to guarantee the results of your builds.
-
-For example, in our [GitHub Action](https://github.com/golangci/golangci-lint-action) we require users to explicitly set the minor version of `golangci-lint`
-and we always use the latest patch version.
-
-## Linter Deprecation Cycle
-
-A linter can be deprecated for various reasons, e.g. the linter stops working with a newer version of Go or the author has abandoned its linter.
-
-The deprecation of a linter will follow 3 phases:
-
-1. **Display of a warning message**: The linter can still be used (unless it's completely non-functional), but it's recommended to remove it from your configuration.
-2. **Display of an error message**: At this point, you should remove the linter. The original implementation is replaced by a placeholder that does nothing.
-3. **Removal of the linter** from golangci-lint.
-
-Each phase corresponds to a minor version:
-
-- v1.0.0 -> warning message
-- v1.1.0 -> error message
-- v1.2.0 -> linter removed
-
-The deprecated linters are removed from presets immediately when they are deprecated (phase 1).
-
-We will provide clear information about those changes on different supports: changelog, logs, social network, etc.
-
-We consider the removal of a linter as non-breaking changes for golangci-lint itself.
-No major version will be created when a linter is removed.
-
 ## Next
 
 [Quick Start: how to use `golangci-lint`](/usage/quick-start).

docs/src/docs/usage/faq.mdx renamed to docs/src/docs/welcome/faq.mdx

@@ -22,23 +22,17 @@ golangci-lint run dir1 dir2/... dir3/file1.go
 
 Directories are NOT analyzed recursively. To analyze them recursively append `/...` to their path.
 
-GolangCI-Lint can be used with zero configuration. By default the following linters are enabled:
+GolangCI-Lint can be used with zero configuration. By default, the following linters are enabled:
 
 ```sh
 $ golangci-lint help linters
 {.LintersCommandOutputEnabledOnly}
 ```
 
-and the following linters are disabled by default:
-
-```sh
-$ golangci-lint help linters
-...
-{.LintersCommandOutputDisabledOnly}
-```
-
 Pass `-E/--enable` to enable linter and `-D/--disable` to disable:
 
 ```sh
 golangci-lint run --disable-all -E errcheck
 ```
+
+More information about available linters can be found in the [linters page](/usage/linters/).

docs/src/docs/usage/install/index.mdx renamed to docs/src/docs/welcome/install.mdx

@@ -105,9 +105,8 @@ func saveCLIHelp(dst string) error {
 	shortHelp := bytes.Join(helpLines[2:], []byte("\n"))
 
 	data := types.CLIHelp{
-		Enable:  string(lintersOutParts[0]),
-		Disable: string(lintersOutParts[1]),
-		Help:    string(shortHelp),
+		Enable: string(lintersOutParts[0]),
+		Help:   string(shortHelp),
 	}
 
 	return saveToJSONFile(dst, data)

docs/src/docs/usage/integrations.mdx renamed to docs/src/docs/welcome/integrations.mdx

@@ -161,18 +161,17 @@ func buildTemplateContext() (map[string]string, error) {
 	}
 
 	return map[string]string{
-		"CustomGCLReference":               pluginReference,
-		"LintersExample":                   snippets.LintersSettings,
-		"ConfigurationExample":             snippets.ConfigurationFile,
-		"LintersCommandOutputEnabledOnly":  helps.Enable,
-		"LintersCommandOutputDisabledOnly": helps.Disable,
-		"EnabledByDefaultLinters":          getLintersListMarkdown(true),
-		"DisabledByDefaultLinters":         getLintersListMarkdown(false),
-		"DefaultExclusions":                exclusions,
-		"ThanksList":                       getThanksList(),
-		"RunHelpText":                      helps.Help,
-		"ChangeLog":                        string(changeLog),
-		"LatestVersion":                    latestVersion,
+		"CustomGCLReference":              pluginReference,
+		"LintersExample":                  snippets.LintersSettings,
+		"ConfigurationExample":            snippets.ConfigurationFile,
+		"LintersCommandOutputEnabledOnly": helps.Enable,
+		"EnabledByDefaultLinters":         getLintersListMarkdown(true),
+		"DisabledByDefaultLinters":        getLintersListMarkdown(false),
+		"DefaultExclusions":               exclusions,
+		"ThanksList":                      getThanksList(),
+		"RunHelpText":                     helps.Help,
+		"ChangeLog":                       string(changeLog),
+		"LatestVersion":                   latestVersion,
 	}, nil
 }
 

docs/src/docs/usage/quick-start.mdx renamed to docs/src/docs/welcome/quick-start.mdx

@@ -5,9 +5,8 @@ import (
 )
 
 type CLIHelp struct {
-	Enable  string `json:"enable"`
-	Disable string `json:"disable"`
-	Help    string `json:"help"`
+	Enable string `json:"enable"`
+	Help   string `json:"help"`
 }
 
 type ExcludePattern struct {