Navbar-brand: define classes for the logo and name (#1190)

6 files changed, 54 insertions, 44 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a6bedd0..6cb616b 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 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
   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 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/assets/scss/_nav.scss b/assets/scss/_nav.scss
index 2b82c04..87bda33 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 054b942..331964a 100644
--- a/layouts/partials/navbar.html
+++ b/layouts/partials/navbar.html
@@ -3,19 +3,19 @@
     (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">
-      {{- if .Site.Params.ui.navbar_logo -}}
+    <span class="navbar-brand__logo navbar-logo">
+      {{- if ne .Site.Params.ui.navbar_logo false -}}
         {{ with resources.Get "icons/logo.svg" -}}
           {{ ( . | minify).Content | safeHTML -}}
         {{ end -}}
       {{ end -}}
     </span>
     {{- /**/ -}}
-    <span class="font-weight-bold">
+    <span class="navbar-brand__name">
       {{- .Site.Title -}}
     </span>
     {{- /**/ -}}
diff --git a/userguide/config.yaml b/userguide/config.yaml
index 75e1640..dd3ba61 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 4310b7f..563b39f 100644
--- a/userguide/content/en/docs/adding-content/iconsimages.md
+++ b/userguide/content/en/docs/adding-content/iconsimages.md
@@ -1,15 +1,18 @@
 ---
-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`:
+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 >}}
 {{< tab header="Configuration file:" disabled=true />}}
@@ -26,35 +29,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`:
-
-{{< 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;
-}
-```
+For information about styling your logo, see [Styling your project logo and
+name][].
 
-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 project logo and name]: /docs/adding-content/lookandfeel/#styling-your-project-logo-and-name
 
 ## Add your favicons
 
@@ -70,7 +48,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 30a4d1f..671a943 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,34 @@ site's [configuration file][].
 [configuration file]: https://gohugo.io/getting-started/configuration/#configuration-file
 [primary color]: #site-colors
 
+### Styling your project logo and name
 
+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
+    `.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 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 {
+      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