From b5037f5487812901926d49899288091085ebcc72 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Tue, 26 Jul 2022 14:40:18 -0400 Subject: [PATCH 1/3] Document use of Docsy as an NPM package --- .../en/docs/get-started/other-options.md | 73 ++++++++++++++----- 1 file changed, 53 insertions(+), 20 deletions(-) diff --git a/userguide/content/en/docs/get-started/other-options.md b/userguide/content/en/docs/get-started/other-options.md index ce4ebec33f..565a25fc24 100644 --- a/userguide/content/en/docs/get-started/other-options.md +++ b/userguide/content/en/docs/get-started/other-options.md @@ -1,9 +1,9 @@ --- title: Other setup options +description: Create a new Docsy site with Docsy using Git or NPM date: 2021-12-08T09:22:27+01:00 +spelling: cSpell:ignore docsy gohugo hugo myproject weight: 2 -description: - Create a new Docsy site with Docsy as a Git submodule or cloned theme --- If you don't want to use @@ -23,10 +23,13 @@ of the theme directly, or your deployment choice requires you to include a copy of the theme in your repository), you can **clone the files directly into your site source**. -This guide provides instructions for both these options, along with common +Finally, you can install +[Docsy as an NPM package](#option-3-docsy-as-an-npm-package). + +This guide provides instructions for all of these options, along with common prerequisites. -## Prerequisites and installation +## Prerequisites ### Install Hugo @@ -81,20 +84,16 @@ The following shows you how to install Hugo from the release page: Install Hugo using [Brew](https://gohugo.io/getting-started/installing/#homebrew-macos). -#### As an `npm` module +#### As an NPM module -You can install Hugo as an `npm` module using -[`hugo-bin`](https://www.npmjs.com/package/hugo-bin). This adds `hugo-bin` to -your `node_modules` folder and adds the dependency to your `package.json` file. -To install the extended version of Hugo: +You can install Hugo as an NPM module using +[hugo-extended](https://www.npmjs.com/package/hugo-extended). To install the +extended version of Hugo: ``` npm install hugo-extended --save-dev ``` -See the [`hugo-bin` documentation](https://www.npmjs.com/package/hugo-bin) for -usage details. - ### Node: Get the latest LTS release Install or upgrade your version of Node to the active [LTS release][]. We @@ -105,10 +104,6 @@ shown): $ nvm install --lts ``` -[lts release]: https://nodejs.org/en/about/releases/ -[nvm]: - https://github.com/nvm-sh/nvm/blob/master/README.md#installing-and-updating - ### Install PostCSS {{% alert title="IMPORTANT: Check your Node version" color="warning" %}} @@ -129,8 +124,7 @@ default `npm` installs tools under the directory where you run [`npm install`](https://docs.npmjs.com/cli/v6/commands/npm-install#description): ``` -npm install -D autoprefixer -npm install -D postcss-cli +npm install -D autoprefixer postcss-cli ``` Starting in @@ -209,11 +203,46 @@ For more information, see [Theme Components](https://gohugo.io/hugo-modules/theme-components/) on the [Hugo](https://gohugo.io) site. +## Option 3: Docsy as an NPM package + +You can use Docsy as an NPM module as follows. + +1. Create your site and specify Docsy as the site theme: + + ```sh + hugo new site myproject + cd myproject + echo 'theme = "docsy"' >> config.toml + ``` + +2. Install Docsy, and postCSS (as [instructed earlier](#install-postcss)): + + ```sh + npm install --save-dev google/docsy autoprefixer postcss-cli postcss + ``` + +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: + + ```console + $ hugo --themesDir node_modules + Start building sites … + ... + Total in 1890 ms + ``` + + You can drop the `--themesDir ...` flag by adding the themes directory to + your site's configuration file: + + ```sh + echo 'themesDir = "node_modules"' >> config.toml + ``` + ## Preview your site -To build and preview your site locally: +To preview your site locally: -``` +```sh cd myproject hugo server ``` @@ -237,3 +266,7 @@ from scratch as it provides defaults for many required configuration parameters. [Example Site](https://github.com/google/docsy-example) and other [Examples](/docs/examples/). - [Publish your site](/docs/deployment/). + +[lts release]: https://nodejs.org/en/about/releases/ +[nvm]: + https://github.com/nvm-sh/nvm/blob/master/README.md#installing-and-updating From 4c63b698c6c49f3621f409d2f8875c7adc1de8b7 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Tue, 26 Jul 2022 15:03:41 -0400 Subject: [PATCH 2/3] Describe symlink option --- .../content/en/docs/get-started/other-options.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/userguide/content/en/docs/get-started/other-options.md b/userguide/content/en/docs/get-started/other-options.md index 565a25fc24..40b77d4f3a 100644 --- a/userguide/content/en/docs/get-started/other-options.md +++ b/userguide/content/en/docs/get-started/other-options.md @@ -238,6 +238,17 @@ You can use Docsy as an NPM module as follows. echo 'themesDir = "node_modules"' >> config.toml ``` +As an alternative to specifying a `themesDir`, on some platforms, you can +instead create a symbolic link to the Docsy theme directory as follows (Linux +commands shown, executed from the site root folder): + +```sh +mkdir -p theme +pushd theme +ln -s ../node_modules/docsy +popd +``` + ## Preview your site To preview your site locally: From c87d970524c41751408b94f9adf7a2a28fa4a39b Mon Sep 17 00:00:00 2001 From: LisaFC Date: Wed, 27 Jul 2022 10:17:54 +0100 Subject: [PATCH 3/3] Update other-options.md --- userguide/content/en/docs/get-started/other-options.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/userguide/content/en/docs/get-started/other-options.md b/userguide/content/en/docs/get-started/other-options.md index 40b77d4f3a..84fd275b33 100644 --- a/userguide/content/en/docs/get-started/other-options.md +++ b/userguide/content/en/docs/get-started/other-options.md @@ -23,8 +23,8 @@ of the theme directly, or your deployment choice requires you to include a copy of the theme in your repository), you can **clone the files directly into your site source**. -Finally, you can install -[Docsy as an NPM package](#option-3-docsy-as-an-npm-package). +Finally, you can **install +[Docsy as an NPM package](#option-3-docsy-as-an-npm-package)**. This guide provides instructions for all of these options, along with common prerequisites. @@ -205,7 +205,7 @@ For more information, see ## Option 3: Docsy as an NPM package -You can use Docsy as an NPM module as follows. +You can use Docsy as an NPM module as follows: 1. Create your site and specify Docsy as the site theme: