From 5744ead64b363dc740beee9c90d2f2de370b00de Mon Sep 17 00:00:00 2001
From: Patrice Chalin <pchalin@gmail.com>
Date: Thu, 18 Aug 2022 16:19:20 -0400
Subject: [PATCH 1/3] Navbar-brand: define classes for the logo and name

---
 assets/scss/_nav.scss                         |  5 +--
 layouts/partials/navbar.html                  |  8 ++--
 .../en/docs/adding-content/iconsimages.md     | 43 ++++---------------
 .../en/docs/adding-content/lookandfeel.md     | 27 ++++++++++++
 4 files changed, 42 insertions(+), 41 deletions(-)

diff --git a/assets/scss/_nav.scss b/assets/scss/_nav.scss
index 2b82c0440a..87bda33094 100644
--- a/assets/scss/_nav.scss
+++ b/assets/scss/_nav.scss
@@ -41,9 +41,8 @@
         text-transform: none;
         text-align: middle;
 
-        .nav-link {
-            display: inline-block;
-            margin-right: -30px;
+        &__name {
+          font-weight: $font-weight-bold;
         }
 
         svg {
diff --git a/layouts/partials/navbar.html b/layouts/partials/navbar.html
index 054b942e9b..d3e9638f29 100644
--- a/layouts/partials/navbar.html
+++ b/layouts/partials/navbar.html
@@ -3,11 +3,11 @@
     (not .Site.Params.ui.navbar_translucent_over_cover_disable)
 -}}
 
-<nav
-  class="js-navbar-scroll navbar navbar-expand navbar-dark {{ if $cover }}td-navbar-cover{{ end }} flex-column flex-md-row td-navbar">
+<nav class="js-navbar-scroll navbar navbar-expand navbar-dark
+            {{- if $cover }} td-navbar-cover {{- end }} flex-column flex-md-row td-navbar">
   <a class="navbar-brand" href="{{ .Site.Home.RelPermalink }}">
     {{- /**/ -}}
-    <span class="navbar-logo">
+    <span class="navbar-brand__logo navbar-logo">
       {{- if .Site.Params.ui.navbar_logo -}}
         {{ with resources.Get "icons/logo.svg" -}}
           {{ ( . | minify).Content | safeHTML -}}
@@ -15,7 +15,7 @@
       {{ end -}}
     </span>
     {{- /**/ -}}
-    <span class="font-weight-bold">
+    <span class="navbar-brand__name">
       {{- .Site.Title -}}
     </span>
     {{- /**/ -}}
diff --git a/userguide/content/en/docs/adding-content/iconsimages.md b/userguide/content/en/docs/adding-content/iconsimages.md
index 4310b7fe81..969e54e00b 100644
--- a/userguide/content/en/docs/adding-content/iconsimages.md
+++ b/userguide/content/en/docs/adding-content/iconsimages.md
@@ -1,15 +1,15 @@
 ---
-title: "Logos and Images"
-linkTitle: "Logos and Images"
+title: Logos and Images
 date: 2017-01-05
 weight: 6
-description: >
-  Add and customize logos, icons, and images in your project.
+description: Add and customize logos, icons, and images in your project.
 ---
 
 ## Add your logo
 
-Add your project logo as `assets/icons/logo.svg` in your project. This overrides the default Docsy logo in the theme. If you don't want a project logo, set `navbar_logo` to `false` (or delete the variable) in your `config.toml`/`config.yaml`/`config.json`:
+Place your project logo in `assets/icons/logo.svg`. This overrides the default
+Docsy logo in the theme. If you don't want a project logo, set `navbar_logo` to
+`false` in your project's config:
 
 {{< tabpane persistLang=false >}}
 {{< tab header="Configuration file:" disabled=true />}}
@@ -26,35 +26,10 @@ navbar_logo: false
 {{< /tab >}}
 {{< /tabpane >}}
 
-If you decide at a later stage that you'd like to add a logo to your navbar, you can set the parameter to `true`:
+For information about styling your logo, see [Styling your brand logo and
+name][]
 
-{{< tabpane persistLang=false >}}
-{{< tab header="config.toml" lang="toml" >}}
-navbar_logo = true
-{{< /tab >}}
-{{< tab header="config.yaml" lang="yaml" >}}
-navbar_logo: true
-{{< /tab >}}
-{{< tab header="config.json" lang="json" >}}
-{
-  "navbar_logo": true
-}
-{{< /tab >}}
-{{< /tabpane >}}
-
-{{% alert title="Tip" %}}
-Your logo is included in the default Docsy navbar as an inline SVG with the following CSS styling (from [`_nav.scss`](https://github.com/google/docsy/blob/main/assets/scss/_nav.scss)):
-
-```
-svg {
-    display: inline-block;
-    margin: 0 10px;
-    height: 30px;
-}
-```
-
-To ensure your logo displays correctly, you may want to resize it, ensure it doesn't have height and width attributes so that its size is fully responsive, or override the default styling with your own CSS.
-{{% /alert %}}
+[Styling your brand logo and name]: /docs/adding-content/lookandfeel/#styling-your-brand-logo-and-name
 
 ## Add your favicons
 
@@ -70,7 +45,7 @@ If you have special favicon requirements, you can create your own `layouts/parti
 
 Docsy's [`blocks/cover` shortcode](/docs/adding-content/shortcodes/#blockscover) make it easy to add large cover images to your landing pages. The shortcode looks for an image with the word "background" in the name inside the landing page's [Page Bundle](https://gohugo.io/content-management/page-bundles/) - so, for example, if you've copied the example site, the landing page image in `content/en/_index.html` is `content/en/featured-background.jpg`.
 
-You specify the preferred display height of a cover block container (and hence its image) using the block's `height` parameter.  For a full viewport height, use `full`: 
+You specify the preferred display height of a cover block container (and hence its image) using the block's `height` parameter.  For a full viewport height, use `full`:
 
 ```html
 {{</* blocks/cover title="Welcome to the Docsy Example Project!" image_anchor="top" height="full" color="orange" */>}}
diff --git a/userguide/content/en/docs/adding-content/lookandfeel.md b/userguide/content/en/docs/adding-content/lookandfeel.md
index 30a4d1f987..e06469dbb7 100644
--- a/userguide/content/en/docs/adding-content/lookandfeel.md
+++ b/userguide/content/en/docs/adding-content/lookandfeel.md
@@ -3,6 +3,7 @@ title: Look and Feel
 date: 2017-01-05
 weight: 2
 description: Customize colors, fonts, code highlighting, and more for your site.
+spelling: cSpell:ignore wordmark docsy
 ---
 
 By default, a site using Docsy has the theme's default fonts, colors, and general look and feel. However, if you want your own color scheme (and you probably will!) you can very easily override the theme defaults with your own project-specific values - Hugo will look in your project files first when looking for information to build your site. And because Docsy uses Bootstrap 4 and SCSS for styling, you can override just single values (such as project colors and fonts) in its special SCSS project variables file, or do more serious customization by creating your own styles.
@@ -213,7 +214,33 @@ site's [configuration file][].
 [configuration file]: https://gohugo.io/getting-started/configuration/#configuration-file
 [primary color]: #site-colors
 
+### Styling your brand logo and name
 
+The default Docsy navbar (`.td-navbar`) contains your navbar-brand, consisting
+of the following:
+
+1.  [Your logo][], which is included in the navbar as an inline SVG, styled by
+    `.td-navbar .navbar-brand svg`. For the style details, see [_nav.scss][].
+
+    To ensure your logo displays correctly, you may want to resize it and ensure
+    that it doesn't have height and width attributes so that its size is fully
+    responsive. [Override the default styling][project-styles] of `.td-navbar
+    .navbar-brand svg` or (equivalently) `.td-navbar .navbar-brand__logo` as
+    needed.
+2.  Your brand name, which is the site `title`. If you don't want the brand name
+    to show (for example, because your logo is or contains a [wordmark][]), then
+    add the following custom styling to your [project's styles][project-styles]:
+
+    ```css
+    .td-navbar .navbar-brand__name {
+      display: none;
+    }
+    ```
+
+[_nav.scss]: https://github.com/google/docsy/blob/main/assets/scss/_nav.scss
+[project-styles]: /docs/adding-content/lookandfeel/#project-style-files
+[wordmark]: https://en.wikipedia.org/wiki/Wordmark
+[your logo]: /docs/adding-content/iconsimages/#add-your-logo
 
 ## Customizing templates
 

From 9d31ef80f1a584eebb4a27d77d3017ec44c7b753 Mon Sep 17 00:00:00 2001
From: Patrice Chalin <pchalin@gmail.com>
Date: Thu, 18 Aug 2022 21:08:01 -0400
Subject: [PATCH 2/3] Flip the default to show the logo by default

---
 CHANGELOG.md                                            | 8 +++++++-
 layouts/partials/navbar.html                            | 2 +-
 userguide/config.yaml                                   | 1 -
 userguide/content/en/docs/adding-content/iconsimages.md | 7 +++++--
 4 files changed, 13 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a6bedd0627..709b998ee3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,5 @@
 <!--
-  cSpell:ignore deining docsy gtag
+  cSpell:ignore deining docsy gtag lookandfeel
 -->
 
 # Changelog
@@ -29,6 +29,10 @@ notes][0.5.0]. **BREAKING CHANGES** are documented below.
 - **[Upgraded FontAwesome][]** to v6.1.2 from v5. While many icons were renamed,
   the v5 names will still work. For details about icon renames and more, see
   [What's changed][].
+- **Display logo by default**. Most projects show their logo in the navbar. In
+  support of this majority, Docsy now displays a logo by default. For details on
+  how to hide the logo (or your brand name), see [Styling your brand logo and
+  name][].
 - **Navbar search-box** width is narrower, as a result of the FontAwesome (FA)
   upgrade. You might notice other width changes of elements using FA icons and
   the FA font.
@@ -43,6 +47,8 @@ notes][0.5.0]. **BREAKING CHANGES** are documented below.
 [docsy as an npm package]:
   https://www.docsy.dev/docs/get-started/other-options/#option-3-docsy-as-an-npm-package
 [gtag.js]: https://support.google.com/analytics/answer/10220869
+[styling your brand logo and name]:
+  /docs/adding-content/lookandfeel/#styling-your-brand-logo-and-name
 [upgraded fontawesome]: https://fontawesome.com/docs/web/setup/upgrade/
 [what's changed]: https://fontawesome.com/docs/web/setup/upgrade/whats-changed
 
diff --git a/layouts/partials/navbar.html b/layouts/partials/navbar.html
index d3e9638f29..331964a526 100644
--- a/layouts/partials/navbar.html
+++ b/layouts/partials/navbar.html
@@ -8,7 +8,7 @@
   <a class="navbar-brand" href="{{ .Site.Home.RelPermalink }}">
     {{- /**/ -}}
     <span class="navbar-brand__logo navbar-logo">
-      {{- if .Site.Params.ui.navbar_logo -}}
+      {{- if ne .Site.Params.ui.navbar_logo false -}}
         {{ with resources.Get "icons/logo.svg" -}}
           {{ ( . | minify).Content | safeHTML -}}
         {{ end -}}
diff --git a/userguide/config.yaml b/userguide/config.yaml
index 75e1640128..dd3ba61bca 100644
--- a/userguide/config.yaml
+++ b/userguide/config.yaml
@@ -70,7 +70,6 @@ params:
     sidebar_cache_limit: 10
     breadcrumb_disable: false
     sidebar_search_disable: false
-    navbar_logo: true
     feedback:
       enable: true
       'yes': >-
diff --git a/userguide/content/en/docs/adding-content/iconsimages.md b/userguide/content/en/docs/adding-content/iconsimages.md
index 969e54e00b..b135574d9e 100644
--- a/userguide/content/en/docs/adding-content/iconsimages.md
+++ b/userguide/content/en/docs/adding-content/iconsimages.md
@@ -7,8 +7,11 @@ description: Add and customize logos, icons, and images in your project.
 
 ## Add your logo
 
-Place your project logo in `assets/icons/logo.svg`. This overrides the default
-Docsy logo in the theme. If you don't want a project logo, set `navbar_logo` to
+By default, Docsy shows a site logo at the start of the navbar, that is, at the
+extreme left. Place your project's SVG logo in `assets/icons/logo.svg`. This
+overrides the default Docsy logo in the theme.
+
+If you don't want a logo to appear in the navbar, then set `navbar_logo` to
 `false` in your project's config:
 
 {{< tabpane persistLang=false >}}

From 0e6f643f3329e7ad9fcb604ac9d05470b4d44db0 Mon Sep 17 00:00:00 2001
From: Patrice Chalin <pchalin@gmail.com>
Date: Fri, 7 Oct 2022 12:00:21 -0400
Subject: [PATCH 3/3] Lisa's feedback

---
 CHANGELOG.md                                          |  6 +++---
 .../content/en/docs/adding-content/iconsimages.md     |  6 +++---
 .../content/en/docs/adding-content/lookandfeel.md     | 11 ++++++-----
 3 files changed, 12 insertions(+), 11 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 709b998ee3..6cb616bd00 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -31,7 +31,7 @@ notes][0.5.0]. **BREAKING CHANGES** are documented below.
   [What's changed][].
 - **Display logo by default**. Most projects show their logo in the navbar. In
   support of this majority, Docsy now displays a logo by default. For details on
-  how to hide the logo (or your brand name), see [Styling your brand logo and
+  how to hide the logo (or your brand name), see [Styling your project logo and
   name][].
 - **Navbar search-box** width is narrower, as a result of the FontAwesome (FA)
   upgrade. You might notice other width changes of elements using FA icons and
@@ -47,8 +47,8 @@ notes][0.5.0]. **BREAKING CHANGES** are documented below.
 [docsy as an npm package]:
   https://www.docsy.dev/docs/get-started/other-options/#option-3-docsy-as-an-npm-package
 [gtag.js]: https://support.google.com/analytics/answer/10220869
-[styling your brand logo and name]:
-  /docs/adding-content/lookandfeel/#styling-your-brand-logo-and-name
+[styling your project logo and name]:
+  https://www.docsy.dev/docs/adding-content/lookandfeel/#styling-your-project-logo-and-name
 [upgraded fontawesome]: https://fontawesome.com/docs/web/setup/upgrade/
 [what's changed]: https://fontawesome.com/docs/web/setup/upgrade/whats-changed
 
diff --git a/userguide/content/en/docs/adding-content/iconsimages.md b/userguide/content/en/docs/adding-content/iconsimages.md
index b135574d9e..563b39f411 100644
--- a/userguide/content/en/docs/adding-content/iconsimages.md
+++ b/userguide/content/en/docs/adding-content/iconsimages.md
@@ -29,10 +29,10 @@ navbar_logo: false
 {{< /tab >}}
 {{< /tabpane >}}
 
-For information about styling your logo, see [Styling your brand logo and
-name][]
+For information about styling your logo, see [Styling your project logo and
+name][].
 
-[Styling your brand logo and name]: /docs/adding-content/lookandfeel/#styling-your-brand-logo-and-name
+[Styling your project logo and name]: /docs/adding-content/lookandfeel/#styling-your-project-logo-and-name
 
 ## Add your favicons
 
diff --git a/userguide/content/en/docs/adding-content/lookandfeel.md b/userguide/content/en/docs/adding-content/lookandfeel.md
index e06469dbb7..671a943f65 100644
--- a/userguide/content/en/docs/adding-content/lookandfeel.md
+++ b/userguide/content/en/docs/adding-content/lookandfeel.md
@@ -214,9 +214,9 @@ site's [configuration file][].
 [configuration file]: https://gohugo.io/getting-started/configuration/#configuration-file
 [primary color]: #site-colors
 
-### Styling your brand logo and name
+### Styling your project logo and name
 
-The default Docsy navbar (`.td-navbar`) contains your navbar-brand, consisting
+The default Docsy navbar (`.td-navbar`) displays your site identity, consisting
 of the following:
 
 1.  [Your logo][], which is included in the navbar as an inline SVG, styled by
@@ -227,9 +227,10 @@ of the following:
     responsive. [Override the default styling][project-styles] of `.td-navbar
     .navbar-brand svg` or (equivalently) `.td-navbar .navbar-brand__logo` as
     needed.
-2.  Your brand name, which is the site `title`. If you don't want the brand name
-    to show (for example, because your logo is or contains a [wordmark][]), then
-    add the following custom styling to your [project's styles][project-styles]:
+2.  Your project name, which is the site `title`. If you don't want your project
+    name to appear (for example, because your logo is or contains a
+    [wordmark][]), then add the following custom styling to your [project's
+    styles][project-styles]:
 
     ```css
     .td-navbar .navbar-brand__name {