Merge branch 'main' into updateFontAwesome

Author: Yasir

CHANGELOG.md

@@ -8,10 +8,17 @@ For a list of issues targeted for the next release, see the [22Q2][] milestone.
 
 For a full list of the changes to this release, see the [release notes][0.5.0].
 
+**New**:
+
+- Projects can now install and use [Docsy as an NPM package][].
+
 **Breaking changes**:
 
 - ...
 
+[docsy as an npm package]:
+  https://www.docsy.dev/docs/get-started/other-options/#option-3-docsy-as-an-npm-package
+
 ## [0.4.0][]
 
 For a full list of the changes to this release, see the [release notes][0.4.0].
@@ -25,62 +32,64 @@ For a full list of the changes to this release, see the [release notes][0.4.0].
   and FontAwesome. Migrate your site by following these steps (execute commands
   from your project's root directory):
 
-   1. Update Docsy to 0.4.0.
-   2. Delete obsolete Docsy Git submodules:
+  1.  Update Docsy to 0.4.0.
+  2.  Delete obsolete Docsy Git submodules:
       ```console
       $ rm -Rf themes/docsy/assets/vendor
       ```
-   3. Get Docsy dependencies:
+  3.  Get Docsy dependencies:
       ```console
       $ (cd themes/docsy && npm install)
       ```
-   4. (Optional) If your site project uses NPM, consider getting Docsy
-      dependencies via a `prepare` script, for example:
+  4.  (Optional) If your site uses NPM, consider getting Docsy dependencies via
+      a [prepare][] script as follows:
       ```json
       {
         "name": "my-website",
         "scripts": {
-          "get:submodule": "git submodule update --init --depth 1",
-          "_prepare:docsy": "cd themes/docsy && npm install",
-          "prepare": "npm run get:submodule && npm run _prepare:docsy",
+          "prepare": "cd themes/docsy && npm install",
           "...": "..."
         },
         "...": "..."
       }
       ```
-   5. Proceed as usual to build or serve your site.
+  5.  Proceed as usual to build or serve your site.
 
-[Hugo Modules]: https://www.docsy.dev/docs/get-started/docsy-as-module/
-[other Docsy setups]: https://www.docsy.dev/docs/get-started/other-options/
+[hugo modules]: https://www.docsy.dev/docs/get-started/docsy-as-module/
+[other docsy setups]: https://www.docsy.dev/docs/get-started/other-options/
+[prepare]:
+  https://docs.npmjs.com/cli/v8/using-npm/scripts#prepare-and-prepublish
 
 ## [0.3.0][]
 
 For a full list of the changes to this release, see the [release notes][0.3.0].
 
 **Breaking changes**:
 
-- Upgrade to [Algolia DocSearch
-  v3](https://docsearch.algolia.com/docs/DocSearch-v3). If your site uses the
-  deprecated DocSearch v2, you must [update your DocSearch
-  code](https://docsearch.algolia.com/docs/migrating-from-v2).
+- Upgrade to
+  [Algolia DocSearch v3](https://docsearch.algolia.com/docs/DocSearch-v3). If
+  your site uses the deprecated DocSearch v2, you must
+  [update your DocSearch code](https://docsearch.algolia.com/docs/migrating-from-v2).
 
 ## [0.2.0][]
 
 **New**:
 
-- Add official Docsy support for [Hugo modules][]. Many thanks to the dedicated and
-  patient efforts of [@deining][], who researched, experimented, and implemented
-  this feature. Thanks to [@deining][] and [@LisaFC][] for the doc updates.
+- Add official Docsy support for [Hugo modules][]. Many thanks to the dedicated
+  and patient efforts of [@deining][], who researched, experimented, and
+  implemented this feature. Thanks to [@deining][] and [@LisaFC][] for the doc
+  updates.
 
-  For details, see [Migrate to Hugo Modules](https://www.docsy.dev/docs/updating/convert-site-to-module/).
+  For details, see
+  [Migrate to Hugo Modules](https://www.docsy.dev/docs/updating/convert-site-to-module/).
 
 **Details**:
 
 - For a full list of the changes to this release, see the [release notes][0.2.0]
 
 ## [0.X.Y][] - next planned release (unpublished yet)
 
-For a full list of the changes to this release, see the [release notes][0.X.Y].
+For a full list of the changes to this release, see the [release notes][0.x.y].
 
 **Breaking changes**:
 
@@ -92,7 +101,7 @@ For a full list of the changes to this release, see the [release notes][0.X.Y].
 [0.3.0]: https://github.com/google/docsy/releases/v0.3.0
 [0.4.0]: https://github.com/google/docsy/releases/v0.4.0
 [0.5.0]: https://github.com/google/docsy/releases/v0.5.0
-[0.X.Y]: #
+[0.x.y]: #
 [22q2]: https://github.com/google/docsy/milestone/3
 [hugo modules]: https://gohugo.io/hugo-modules/
 [latest]: https://github.com/google/docsy/releases/latest

CONTRIBUTING.md

@@ -1,3 +1,5 @@
+<!-- cSpell:ignore docsy userguide -->
+
 # How to Contribute
 
 We'd love to accept your patches and contributions to this project. There are
@@ -29,35 +31,37 @@ This project follows
 
 ## How to contribute
 
-See the [contribution
-guidelines](https://www.docsy.dev/docs/contribution-guidelines/)
-in the Docsy user guide.
+See the [contribution guidelines][] in the Docsy user guide.
 
 ## Publishing a release
 
 These notes are WIP for creating a release (v0.X.Y) from a local copy of the
 repo.
 
-1.  Change directory to your local Docsy repo and ensure that you're on a branch
-    and at the commit that you want to tag as the next release (usually
-    `@HEAD`).
+1.  Change directory to your local Docsy repo.
 2.  Ensure that the [CHANGELOG](CHANGELOG.md) has a release summary entry for
     v0.X.Y. If not, create one with a brief summary of breaking changes using
     the section template at the end of the file. (Note that change details are
     autogenerated by GitHub in a later step.)
-3.  Update the Hugo module versions to v0.X.Y.
-4.  Update the NPM package version in [package.json](package.json) to 0.X.Y.
+3.  Update module and package versions:
+    - Update the version of `docsy/dependencies` in [go.mod](go.mod) to v0.X.Y.
+    - Update the NPM package version in [package.json](package.json) to 0.X.Y.
+4.  Update the Docsy `version` in [userguide/config.toml][] to 0.X.Y.
 5.  Commit your changes, usually as a PR entitled "Release v0.X.Y preparation".
     Once the PR is approved and merged, proceed with the remaining steps.
-6.  Create the tags for v0.X.Y (we currently need two):
+6.  Ensure that you're:
+    - On the default branch
+    - At the commit that you want to tag as the next release (usually `@HEAD`).
+7.  Create the tags for v0.X.Y (we currently need two):
 
     ```sh
     REL=v0.X.Y
     git tag $REL
     git tag dependencies/$REL
     ```
 
-7.  Push the new tags to the main repo (which is named `upstream` in my setup):
+8.  Push the new tags to the main repo (which is named `upstream` in the
+    following setup):
 
     ```console
     $ git push upstream $REL && git push upstream dependencies/$REL
@@ -66,28 +70,30 @@ repo.
     * [new tag]         dependencies/v0.X.Y -> dependencies/v0.X.Y
     ```
 
-8.  Use the GitHub [Draft a new release][] feature, filling in the fields as
+9.  Use the GitHub [Draft a new release][] feature, filling in the fields as
     follows:
 
-    -   From the **release/tag dropdown**: Select the new release tag that you just
-        pushed, v0.X.Y.
-    -   Set the **release title** to the release number (without the "v").
-    -   Click "auto-generate release notes" to get the release details.
-    -   Replace the auto-generated "## What's Changed" heading by the following:
+    - From the **release/tag dropdown**: Select the new release tag that you
+      just pushed, v0.X.Y.
+    - Set the **release title** to the release number (without the "v").
+    - Click "auto-generate release notes" to get the release details.
+    - Replace the auto-generated "## What's Changed" heading by the following:
 
-        ```markdown
-        ## Release summary
+      ```markdown
+      ## Release summary
 
-        See, https://github.com/google/docsy/blob/main/CHANGELOG.md#0XY
+      See, https://github.com/google/docsy/blob/main/CHANGELOG.md#0XY
 
-        ## Commit details
-        ```
+      ## Commit details
+      ```
 
-    -   Replace the `0XY` anchor target above with a target appropriate for this
-        release.
-    -   Remove the "New contributors" autogenerated text (if present) since we
-        don't publish that as part of our release notes.
-    -   Select **Create a discussion for this release**.
-    -   Click **Publish release**.
+    - Replace the `0XY` anchor target above with a target appropriate for this
+      release.
+    - Remove the "New contributors" autogenerated text (if present) since we
+      don't publish that as part of our release notes.
+    - Select **Create a discussion for this release**.
+    - Click **Publish release**.
 
-[draft a new release]: https://github.com/google/docsy/releases/new
+[contribution guidelines]: https://www.docsy.dev/docs/contribution-guidelines/
+[Draft a new release]: https://github.com/google/docsy/releases/new
+[userguide/config.toml]: userguide/config.toml

assets/js/offline-search.js

@@ -188,13 +188,8 @@
                 });
             });
 
-            // Enable inline styles in popover.
-            const whiteList = $.fn.tooltip.Constructor.Default.whiteList;
-            whiteList['*'].push('style');
-
             $targetSearchInput
                 .data('content', $html[0].outerHTML)
-                .popover({ whiteList: whiteList })
                 .popover('show');
         };
     });

assets/scss/_main-container.scss

@@ -22,13 +22,11 @@
 
 .td-main {
     flex-grow: 1;
+}
 
-    main {
-        @include media-breakpoint-up(md) {
-            padding-top: 5.5rem;
-        }
-
-
-        padding-bottom: 2rem;
-    }
+.td-404 main,
+.td-main main {
+  padding-top: 1.5rem;
+  padding-bottom: 2rem;
+  @include media-breakpoint-up(md) { padding-top: 5.5rem; }
 }

config.toml

@@ -48,3 +48,11 @@ min = "0.73.0"
   [[module.mounts]]
     source = 'static'
     target = 'static'
+  # Mounts for projects using Docsy as an NPM package. The source path prefix
+  # "../.." moves out of themes/docsy so that Docsy can find its dependencies.
+  [[module.mounts]]
+    source = '../../node_modules/bootstrap'
+    target = 'assets/vendor/bootstrap'
+  [[module.mounts]]
+    source = '../../node_modules/@fortawesome/fontawesome-free'
+    target = 'assets/vendor/Font-Awesome'

layouts/404.html

@@ -1,8 +1,6 @@
-{{ define "main"}}
-    <main id="main">
-      <div>
-       <h1 id="title">Not found</h1>
-          <p>Oops! This page doesn't exist. Try going back to our <a href="{{ "/" | relURL }}">home page</a>.</p>
-      </div>
-    </main>
-{{ end }}
+{{ define "main" -}}
+<div class="td-content">
+  <h1>Not found</h1>
+  <p>Oops! This page doesn't exist. Try going back to the <a href="{{ "" | relURL }}">home page</a>.</p>
+</div>
+{{- end }}

layouts/blog/list.html

@@ -1,5 +1,5 @@
 {{ define "main" }}
-{{ if .Parent.IsHome }}
+{{ if (and .Parent .Parent.IsHome) }}
 {{ $.Scratch.Set "blog-pages" (where .Site.RegularPages "Section" .Section) }}
 {{ else }}
 {{$.Scratch.Set "blog-pages" .Pages }}

layouts/partials/head.html

@@ -38,7 +38,7 @@
 {{ end -}}
 
 {{ if .Site.Params.prism_syntax_highlighting -}}
-<link rel="stylesheet" href="{{ "/css/prism.css" | relURL }}"/>
+<link rel="stylesheet" href="{{ "css/prism.css" | relURL }}"/>
 {{ end -}}
 
 {{ partial "hooks/head-end.html" . -}}

layouts/partials/scripts.html

@@ -6,7 +6,7 @@
     crossorigin="anonymous"></script>
 
 {{ if .Site.Params.mermaid.enable }}
-<script src="https://cdn.jsdelivr.net/npm/mermaid@8.13.4/dist/mermaid.min.js" integrity="sha512-JERecFUBbsm75UpkVheAuDOE8NdHjQBrPACfEQYPwvPG+fjgCpHAz1Jw2ci9EXmd3DdfiWth3O3CQvcfEg8gsA==" crossorigin="anonymous"></script>
+<script src="https://cdn.jsdelivr.net/npm/mermaid@9.1.3/dist/mermaid.min.js" integrity="sha512-E/owfVh8/U1xwhvIT4HSI064DRc1Eo/xf7AYax84rt9gVqA8tc/JNH/lvTl1tuw9PUHQIMGUtObkjYkgRjFqAA==" crossorigin="anonymous"></script>
 {{ end }}
 
 {{ if .Site.Params.markmap.enable }}
@@ -24,11 +24,11 @@
 <script src="https://cdn.jsdelivr.net/npm/markmap-autoloader"></script>
 {{ end }}
 
-<script src='{{ "/js/tabpane-persist.js" | relURL }}'></script>
+<script src='{{ "js/tabpane-persist.js" | relURL }}'></script>
 
 <!-- load the deflate.js for plantuml support -->
 {{ if .Site.Params.plantuml.enable }}
-<script src='{{ "/js/deflate.js" | relURL }}'></script>
+<script src='{{ "js/deflate.js" | relURL }}'></script>
 {{ end }}
 
 <!-- load stylesheet and scripts for KaTeX support -->
@@ -48,7 +48,7 @@
 {{ end }}
 <!-- To automatically render math in text elements, include the auto-render extension: -->
 <script defer src='https://cdn.jsdelivr.net/npm/katex@0.15.1/dist/contrib/auto-render.min.js'
-    integrity='sha512-ZA/RPrAo88DlwRnnoNVqKINnQNcWERzRK03PDaA4GIJiVZvGFIWQbdWCsUebMZfkWohnfngsDjXzU6PokO4jGw==' crossorigin='anonymous' 
+    integrity='sha512-ZA/RPrAo88DlwRnnoNVqKINnQNcWERzRK03PDaA4GIJiVZvGFIWQbdWCsUebMZfkWohnfngsDjXzU6PokO4jGw==' crossorigin='anonymous'
     {{ printf "onload='renderMathInElement(%s, %s);'" (( .Site.Params.katex.html_dom_element | default "document.body" ) | safeJS ) ( printf "%s" ( $.Site.Params.katex.options | jsonify )) | safeHTMLAttr }}></script>
 {{ end }}
 
@@ -71,6 +71,6 @@
 {{ end }}
 {{ if .Site.Params.prism_syntax_highlighting }}
 <!-- scripts for prism -->
-<script src='{{ "/js/prism.js" | relURL }}'></script>
+<script src='{{ "js/prism.js" | relURL }}'></script>
 {{ end }}
 {{ partial "hooks/body-end.html" . }}

layouts/swagger/baseof.html

@@ -3,7 +3,7 @@
   <head>
     {{ partial "head.html" . }}
     <title>{{ if .IsHome }}{{ .Site.Title }}{{ else }}{{ with .Title }}{{ . }} | {{ end }}{{ .Site.Title }}{{ end }}</title>
-    <link rel="stylesheet" type="text/css" href="{{ "/css/swagger-ui.css" | relURL }}">
+    <link rel="stylesheet" type="text/css" href="{{ "css/swagger-ui.css" | relURL }}">
   </head>
   <body class="td-{{ .Kind }}">
     <header>
@@ -22,8 +22,8 @@
           </aside>
           <main class="col-12 col-md-9 col-xl-8 pl-md-5" role="main">
             {{ if not .Site.Params.ui.breadcrumb_disable }}{{ partial "breadcrumb.html" . }}{{ end }}
-            <script src="{{ "/js/swagger-ui-bundle.js" | relURL }}"></script>
-            <script src="{{ "/js/swagger-ui-standalone-preset.js" | relURL }}"></script>
+            <script src="{{ "js/swagger-ui-bundle.js" | relURL }}"></script>
+            <script src="{{ "js/swagger-ui-standalone-preset.js" | relURL }}"></script>
             {{ block "main" . }}{{ end }}
           </main>
         </div>