docs/faq.md: entries on formatting issues
And add back the title that was dropped by accident.
Updates golang/vscode-go#2268
Updates golang/vscode-go#1815
Updates golang/vscode-go#1805
Change-Id: Iea464b1e54f0eb5d421d28c7bea40a86e49dc517
Reviewed-on: https://go-review.googlesource.com/c/vscode-go/+/412054
Reviewed-by: Jamal Carvalho <jamal@golang.org>
diff --git a/docs/_Sidebar.md b/docs/_Sidebar.md
deleted file mode 100644
index d859891..0000000
--- a/docs/_Sidebar.md
+++ /dev/null
@@ -1,21 +0,0 @@
-**For Users**
-* [[features]]
-* [[commands]]
-* [[settings]]
-* [[debugging]]
-* [[tasks]]
-* [[tools]]
-* [[ui]]
-* [[faq]]
-* [[troubleshooting]]
-* [[advanced]]
-* [[nightly]]
-* [[contributing]]
-
-**For Developers**
-* [[release_plan]]
-* [[smoke test]]
-* [[test explorer]]
-* [[debug adapter]]
-* [Go Language Server](https://go.dev/s/gopls)
-* [Delve DAP](https://github.com/go-delve/delve/tree/master/Documentation/api/dap)
diff --git a/docs/faq.md b/docs/faq.md
index fb90dfb..204e117 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -1,3 +1,8 @@
+# Frequently Asked Questions
+
+**NOTE: [Debugging](debugging.md#faqs) has its own FAQ documentation.**
+
+## Syntax highlighting doesn't seem to work.
The default syntax highlighting for Go files is provided by a
[TextMate rule](https://github.com/jeff-hykin/better-go-syntax) embedded in VS Code,
@@ -11,6 +16,43 @@
"gopls": { "ui.semanticTokens": true }
```
+## Code formatting by this extension doesn't seem to work.
+
+When you have multiple formatter extensions, be sure to set this
+extension as the default formatter for go language.
+```json5
+"[go]": {
+ "editor.defaultFormatter": "golang.go"
+}
+```
+
+## How can I stop the extension from formatting files on save?
+
+Formatting and organizing imports for Go are enabled by default. This is implemented
+by setting the [language-specific editor settings](https://code.visualstudio.com/docs/getstarted/settings#_languagespecific-editor-settings), that take precedence
+over user/workspace editor settings.
+
+You can choose to disable them by configuring the following settings.
+
+```json5
+"[go]": {
+ "editor.formatOnSave": false,
+ "editor.codeActionsOnSave": {
+ "source.organizeImports": false
+ }
+}
+```
+
+This decision was made a while ago to help users follow the best practice,
+and to detect broken code early (e.g. unused imports causes compile errors in Go).
+Unfortunately, these language-specific editor settings overriden by the
+extension is not easily visible from the settings UI, and confuses users new to Go.
+In the following issues, we are discussing and collecting ideas to improve
+the situation without interrupting existing users.
+
+ * [`editor.formatOnSave` and `editor.codeActionsOnSave`](https://github.com/golang/vscode-go/issues/1815)
+ * [`editor.suggest.snippetsPreventQuickSuggestions`](https://github.com/golang/vscode-go/issues/1805)
+
<!-- Topics
* The extension deletes my code on save?
* Help! The extension does not find 'go'.
