From d54b48d03b97001863cf9bc5404a67420c9a805f Mon Sep 17 00:00:00 2001
From: Jorge Orpinel Perez <jorge@orpinel.com>
Date: Sat, 11 Mar 2023 15:26:45 -0600
Subject: [PATCH] guide: refinements

per https://github.com/iterative/dvc.org/pull/4379#pullrequestreview-1335822748
and https://github.com/iterative/dvc.org/pull/4379#discussion_r1133141390
---
 content/docs/command-reference/config.md      |  2 +-
 .../project-structure/configuration.md        | 64 ++++++++++++++-----
 2 files changed, 49 insertions(+), 17 deletions(-)

diff --git a/content/docs/command-reference/config.md b/content/docs/command-reference/config.md
index c62305f91e..2101771901 100644
--- a/content/docs/command-reference/config.md
+++ b/content/docs/command-reference/config.md
@@ -37,7 +37,7 @@ to the project-level config file by default (`.dvc/config`). Options `--system`,
 <admon type="warn">
 
 `.dvc/config` is meant to be tracked by Git and should not contain sensitive
-info or secrets (passwords, keys, etc). Use `--local` when in doubt.
+user info or secrets (passwords, SSH keys, etc). Use `--local` when in doubt.
 
 </admon>
 
diff --git a/content/docs/user-guide/project-structure/configuration.md b/content/docs/user-guide/project-structure/configuration.md
index ccd95d39ca..4ab4545c32 100644
--- a/content/docs/user-guide/project-structure/configuration.md
+++ b/content/docs/user-guide/project-structure/configuration.md
@@ -4,22 +4,20 @@ Once initialized in a <abbr>project</abbr>, DVC populates its installation
 directory with [internal files], which include `.dvc/config`, the default
 configuration file.
 
+Config files can be composed manually (or programmatically), or managed with the
+helper command `dvc config`.
+
 [internal files]: /doc/user-guide/project-structure/internal-files
 
+## Config file locations
+
 <admon type="warn">
 
 `.dvc/config` is meant to be tracked by Git and should not contain sensitive
-info or secrets (passwords, keys, etc).
-[Config file locations](#config-file-locations) outside the repo can be used as
-well.
+user info or secrets (passwords, SHH keys, etc).
 
 </admon>
 
-Config files can be composed manually (or programmatically), or managed with the
-helper command `dvc config`.
-
-## Config file locations
-
 DVC supports saving configuration outside of the <abbr>repository</abbr>, either
 in a Git-ignored file alongside the regular config file or in other places in
 your file system. These locations and their loading priority are detailed below:
@@ -78,7 +76,9 @@ within:
   /doc/user-guide/project-structure/dvcyaml-files#dictionary-unpacking
 [internals]: /doc/user-guide/project-structure/internal-files
 
-### core
+<details>
+
+## core
 
 - [`core.remote`](#remote) - name of the default remote storage
 
@@ -113,7 +113,11 @@ within:
   <abbr>DVC files</abbr> created or modified by DVC commands. The files will not
   be committed. Accepts values `true` and `false` (default).
 
-### remote
+</details>
+
+<details>
+
+## remote
 
 Unlike most other sections, configuration files may have more than one
 `'remote'`. All of them require a unique `"name"` and a `url` value. They can
@@ -140,7 +144,11 @@ section):
     remote = temp
 ```
 
-### cache
+</details>
+
+<details>
+
+## cache
 
 - `cache.dir` - set/unset cache directory location. A correct value is either an
   absolute path, or a path **relative to the config file location**. The default
@@ -235,7 +243,11 @@ is the way that can be done.
 [local remote]:
   /doc/user-guide/data-management/remote-storage#file-systems-local-remotes
 
-### exp
+</details>
+
+<details>
+
+## exp
 
 Sets the default paths assumed by `dvc exp init`. This can help avoid overriding
 them repeatedly with that command's options, for example if all of your
@@ -256,6 +268,8 @@ experiments or projects use a similar structure.
 
 - `exp.live` - path to your [DVCLive](/doc/dvclive) output logs.
 
+</details>
+
 ### hydra
 
 Sets the defaults for <abbr>experiment</abbr> configuration via [Hydra
@@ -273,7 +287,11 @@ Composition].
   https://hydra.cc/docs/tutorials/basic/your_first_app/config_groups/
 [defaults list]: https://hydra.cc/docs/tutorials/basic/your_first_app/defaults/
 
-### parsing
+</details>
+
+<details>
+
+## parsing
 
 - `parsing.bool` - Controls the templating syntax for boolean values when used
   in [dictionary unpacking].
@@ -345,7 +363,11 @@ Composition].
 [python `argparse` actions]:
   https://docs.python.org/3/library/argparse.html#action
 
-### plots
+</details>
+
+<details>
+
+## plots
 
 - `plots.auto_open` - if `true`, DVC will automatically open the HTML file
   generated by `dvc plots` commands in a browser. `false` by default
@@ -357,7 +379,11 @@ Composition].
 - `plots.out_dir` - changes the default value for `dvc plots show --out` and
   `dvc plots diff --out`. The original default value is `dvc_plots`.
 
-### state
+</details>
+
+<details>
+
+## state
 
 - `state.row_limit` - maximum number of entries in state databases. This affects
   the physical size of the state files, as well as the performance of certain
@@ -373,8 +399,14 @@ Composition].
   using DVC on NFS or other mounted volumes where SQLite encounters file
   permission errors.
 
-### index
+</details>
+
+<details>
+
+## index
 
 - `index.dir` - specify a custom location for the directory where remote index
   files will be stored, by default in `.dvc/tmp/index`. This may be necessary
   when using DVC on NFS or other mounted volumes.
+
+</details>