diff --git a/CHANGELOG.md b/CHANGELOG.md index 7994e5c36..2e20aa016 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -24,6 +24,10 @@ For the full list of changes, see the [release][0.8.0] notes. **Breaking changes**: +- Docsy is packaged as a **single Hugo module** ([#1120]). + - For details, see [Use Docsy as a Hugo Module]. +- **Important**: non-Hugo-module projects should read the [Docsy NPM install + side-effect] note. - **Page feedback**, or [User feedback]: - In support of projects configuring analytics outside of Docsy, feedback functionality is enabled regardless of whether @@ -41,10 +45,15 @@ For the full list of changes, see the [release][0.8.0] notes. **Other changes**: +[#1120]: https://github.com/google/docsy/issues/1120 [#1385]: https://github.com/google/docsy/issues/1385 [#1726]: https://github.com/google/docsy/pull/1726 [#1727]: https://github.com/google/docsy/pull/1727 [0.8.0]: https://github.com/google/docsy/releases/v0.8.0/#FIXME +[Docsy NPM install side-effect]: + https://docsy.dev/docs/get-started/other-options/#docsy-npm-install-side-effect +[Use Docsy as a Hugo Module]: + https://www.docsy.dev/docs/get-started/docsy-as-module/ [User feedback]: https://www.docsy.dev/docs/adding-content/feedback/#user-feedback diff --git a/userguide/content/en/docs/get-started/docsy-as-module/installation-prerequisites.md b/userguide/content/en/docs/get-started/docsy-as-module/installation-prerequisites.md index 29f388e55..e3c69a525 100644 --- a/userguide/content/en/docs/get-started/docsy-as-module/installation-prerequisites.md +++ b/userguide/content/en/docs/get-started/docsy-as-module/installation-prerequisites.md @@ -10,7 +10,7 @@ This page describes the prerequisites for building a site that uses Docsy as a H ## Install Hugo -You need a [recent **extended** version](https://github.com/gohugoio/hugo/releases) (we recommend version 0.73.0 or later) of [Hugo](https://gohugo.io/) to do local builds and previews of sites (like this one) that use Docsy. If you install from the release page, make sure to get the `extended` Hugo version, which supports [SCSS](https://sass-lang.com/documentation/file.SCSS_FOR_SASS_USERS.html); you may need to scroll down the list of releases to see it. +You need a [recent **extended** version](https://github.com/gohugoio/hugo/releases) (version 0.110.0 or later) of [Hugo](https://gohugo.io/) to do local builds and previews of sites (like this one) that use Docsy. If you install from the release page, make sure to get the `extended` Hugo version, which supports [SCSS](https://sass-lang.com/documentation/file.SCSS_FOR_SASS_USERS.html); you may need to scroll down the list of releases to see it. For comprehensive Hugo documentation, see [gohugo.io](https://gohugo.io). @@ -24,7 +24,7 @@ If you've already installed Hugo, check your version: hugo version ``` -If the result is `v0.73` or earlier, or if you don't see `Extended`, you'll need to install the latest version. You can see a complete list of Linux installation options in [Install Hugo](https://gohugo.io/getting-started/installing/#linux). The following shows you how to install Hugo from the release page: +If the result is `v0.109.0` or earlier, or if you don't see `Extended`, you'll need to install the latest version. You can see a complete list of Linux installation options in [Install Hugo](https://gohugo.io/getting-started/installing/#linux). The following shows you how to install Hugo from the release page: 1. Go to the [Hugo releases](https://github.com/gohugoio/hugo/releases) page. 2. In the most recent release, scroll down until you find a list of @@ -70,7 +70,7 @@ Hugo's commands for module management require that the Go programming language i ```console $ go version -go version go1.20.5 +go version go1.21.4 ``` Ensure that you are using version 1.12 or higher. @@ -84,7 +84,7 @@ Hugo's commands for module management require that the `git` client is installed ```console $ git version -git version 2.41.0 +git version 2.42.1 ``` If no `git` client is installed on your system yet, go to the [Git website](https://git-scm.com/), download the installer for your system architecture and execute it. Afterwards, check for a successful installation. @@ -138,11 +138,11 @@ You can check your current Node.js version by running `node -v`. If you need to ```bash # Using Ubuntu - curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - + curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs # Using Debian, as root - curl -fsSL https://deb.nodesource.com/setup_18.x | bash - + curl -fsSL https://deb.nodesource.com/setup_20.x | bash - apt-get install -y nodejs ``` @@ -152,10 +152,10 @@ You can check your current Node.js version by running `node -v`. If you need to ```bash # As root - curl -fsSL https://rpm.nodesource.com/setup_18.x | bash - + curl -fsSL https://rpm.nodesource.com/setup_20.x | bash - # No root privileges - curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash - + curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash - ``` diff --git a/userguide/content/en/docs/get-started/docsy-as-module/start-from-scratch.md b/userguide/content/en/docs/get-started/docsy-as-module/start-from-scratch.md index 0562ea22c..2f8f23838 100644 --- a/userguide/content/en/docs/get-started/docsy-as-module/start-from-scratch.md +++ b/userguide/content/en/docs/get-started/docsy-as-module/start-from-scratch.md @@ -27,8 +27,6 @@ cat >> hugo.toml <}} @@ -43,11 +41,7 @@ proxy = "direct"^ [[module.imports]]^ -path = "github.com/google/docsy"^ - -[[module.imports]]^ - -path = "github.com/google/docsy/dependencies")>>hugo.toml +path = "github.com/google/docsy" hugo server {{< /tab >}} {{< /tabpane >}} @@ -110,9 +104,6 @@ Add the settings in the following snippet at the end of your site's [configurati [[module.imports]] path = "github.com/google/docsy" disable = false - [[module.imports]] - path = "github.com/google/docsy/dependencies" - disable = false {{< /tab >}} {{< tab header="hugo.yaml" lang="yaml" >}} module: @@ -123,8 +114,6 @@ module: imports: - path: github.com/google/docsy disable: false - - path: github.com/google/docsy/dependencies - disable: false {{< /tab >}} {{< tab header="hugo.json" lang="json" >}} { @@ -138,10 +127,6 @@ module: { "path": "github.com/google/docsy", "disable": false - }, - { - "path": "github.com/google/docsy/dependencies", - "disable": false } ] } diff --git a/userguide/content/en/docs/get-started/other-options.md b/userguide/content/en/docs/get-started/other-options.md index 5489b9f67..7a055f3bd 100644 --- a/userguide/content/en/docs/get-started/other-options.md +++ b/userguide/content/en/docs/get-started/other-options.md @@ -131,7 +131,7 @@ release][latest-lts]. From your project root, run this command: ``` -npm install --save-dev autoprefixer postcss-cli postcss +npm install --save-dev autoprefixer postcss-cli ``` ## Option 1: Docsy as a Git submodule @@ -190,6 +190,8 @@ If you are using hugo 0.110 or above, consider renaming your `config.toml` to `h (cd themes/docsy && npm install) ``` + > **Important**: read the [Docsy NPM install side-effect] note. + 4. (Optional but recommended) To avoid having to repeat the previous step every time you update Docsy, consider adding [NPM scripts][] like the following to your project's `package.json` file: @@ -234,6 +236,8 @@ cd docsy npm install ``` +> **Important**: read the [Docsy NPM install side-effect] note. + To work from the development version of Docsy (not recommended unless, for example, you plan to upstream changes to Docsy), omit the `-b v{{% param version %}}` argument from the clone command above. @@ -259,9 +263,11 @@ You can use Docsy as an NPM module as follows: 2. Install Docsy, and postCSS (as [instructed earlier](#install-postcss)): ```console - npm install --save-dev google/docsy#semver:{{% param version %}} autoprefixer postcss-cli postcss + npm install --save-dev google/docsy#semver:{{% param version %}} autoprefixer postcss-cli ``` + > **Important**: read the [Docsy NPM install side-effect] note. + 3. Build or serve your new site using the usual Hugo commands, specifying the path to the Docsy theme files. For example, build your site as follows: @@ -290,6 +296,29 @@ ln -s ../node_modules/docsy popd ``` +## Docsy NPM install side-effect + +{{% alert title="Important" color=warning %}} + +As of Docsy version [0.8.0], running `npm install` inside the Docsy theme +directory will create a sibling folder named `github.com`, for example: + +```console +$ ls themes +docsy github.com +``` + +This is a workaround necessary to support Docsy's use as a single [Hugo module] +([#1120]). + +[#1120]: https://github.com/google/docsy/issues/1120 +[0.8.0]: https://github.com/google/docsy/blob/main/CHANGELOG.md/#080 +[hugo module]: /docs/get-started/docsy-as-module/ + +{{% /alert %}} + +[Docsy NPM install side-effect]: #docsy-npm-install-side-effect + ## Preview your site To preview your site locally: diff --git a/userguide/content/en/docs/updating/convert-site-to-module.md b/userguide/content/en/docs/updating/convert-site-to-module.md index 5d8e36329..8b0bc3dfc 100644 --- a/userguide/content/en/docs/updating/convert-site-to-module.md +++ b/userguide/content/en/docs/updating/convert-site-to-module.md @@ -23,8 +23,6 @@ cat >> hugo.toml <}} @@ -39,11 +37,7 @@ proxy = "direct"^ [[module.imports]]^ -path = "github.com/google/docsy"^ - -[[module.imports]]^ - -path = "github.com/google/docsy/dependencies")>>hugo.toml +path = "github.com/google/docsy")>>hugo.toml hugo server {{< /tab >}} {{< /tabpane >}} @@ -97,17 +91,15 @@ Change this line to: {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} -theme = ["github.com/google/docsy", "github.com/google/docsy/dependencies"] +theme = ["github.com/google/docsy"] {{< /tab >}} {{< tab header="config.yaml" lang="yaml" >}} theme: - github.com/google/docsy - - github.com/google/docsy/dependencies {{< /tab >}} {{< tab header="hugo.json" lang="json" >}} "theme": [ - "github.com/google/docsy", - "github.com/google/docsy/dependencies" + "github.com/google/docsy" ] {{< /tab >}} {{< /tabpane >}} @@ -127,9 +119,6 @@ Alternatively, you can omit this line altogether and replace it with the setting [[module.imports]] path = "github.com/google/docsy" disable = false - [[module.imports]] - path = "github.com/google/docsy/dependencies" - disable = false {{< /tab >}} {{< tab header="hugo.yaml" lang="yaml" >}} module: @@ -186,9 +175,8 @@ To make sure that your configuration settings are correct, run the command `hugo hugo mod graph hugo: collected modules in 1092 ms github.com/me/my-existing-site github.com/google/docsy@v{{% param "version" %}} -github.com/me/my-existing-site github.com/google/docsy/dependencies@v{{% param "version" %}} -github.com/google/docsy/dependencies@v{{% param "version" %}} github.com/twbs/bootstrap@v5.2.3+incompatible -github.com/google/docsy/dependencies@v{{% param "version" %}} github.com/FortAwesome/Font-Awesome@v0.0.0-20230327165841-0698449d50f2 +github.com/google/docsy@v{{% param "version" %}} github.com/twbs/bootstrap@v5.2.3+incompatible +github.com/google/docsy@v{{% param "version" %}} github.com/FortAwesome/Font-Awesome@v0.0.0-20230327165841-0698449d50f2 ``` Make sure that three lines with dependencies `docsy`, `bootstrap` and `Font-Awesome` are listed. If not, please double check your config settings. @@ -201,7 +189,6 @@ hugo mod clean hugo: collected modules in 995 ms hugo: cleaned module cache for "github.com/FortAwesome/Font-Awesome" hugo: cleaned module cache for "github.com/google/docsy" -hugo: cleaned module cache for "github.com/google/docsy/dependencies" hugo: cleaned module cache for "github.com/twbs/bootstrap" ``` {{% /alert %}}