google
/
docsy
mirror of https://github.com/google/docsy.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
docsy/userguide/content/en/docs/get-started/other-options.md

12 KiB
Raw Permalink Blame History

title description date cSpell:ignore weight
Other setup options Create a new Docsy site with Docsy using Git or NPM 2021-12-08T09:22:27+01:00 docsy gohugo hugo myproject 2

If you don't want to use Docsy as a Hugo Module (for example if you do not want to install Go) but still don't want to copy the theme files into your own repo, you can use Docsy as a Git submodule. Using submodules also lets Hugo use the theme files from Docsy repo, though is more complicated to maintain than the Hugo Modules approach. This is the approach used in older versions of the Docsy example site, and is still supported. If you are using Docsy as a submodule but would like to migrate to Hugo Modules, see our migration guide.

Alternatively if you don’t want Hugo to have to get the theme files from an external repo (for example, if you want to customize and maintain your own copy 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.

This guide provides instructions for all of these options, along with common prerequisites.

Prerequisites

Install Hugo

You need a recent extended version (we recommend version 0.73.0 or later) of Hugo 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; you may need to scroll down the list of releases to see it.

For comprehensive Hugo documentation, see gohugo.io.

On Linux

Be careful using sudo apt-get install hugo, as it doesn't get you the extended version for all Debian/Ubuntu versions, and may not be up-to-date with the most recent Hugo version.

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. The following shows you how to install Hugo from the release page:

  1. Go to the Hugo releases page.

  2. In the most recent release, scroll down until you find a list of Extended versions.

  3. Download the latest extended version (hugo_extended_0.9X_Linux-64bit.tar.gz).

  4. Create a new directory:

    mkdir hugo

  5. Extract the files you downloaded to hugo.

  6. Switch to your new directory:

    cd hugo

  7. Install Hugo:

    sudo install hugo /usr/bin

On macOS

Install Hugo using Brew.

Hugo-extended NPM package

You can install Hugo as an NPM module using hugo-extended:

npm install hugo-extended --save-dev

Node: Get the latest LTS release

If you have Node installed already, check your version of Node. For example:

node -v

Install or upgrade your version of Node to the active LTS release. We recommend using nvm to manage your Node installation (Linux command shown):

nvm install --lts

Install PostCSS

To build or update your site's CSS resources, you'll also need PostCSS. Install it using the Node package manager, npm.

{{% alert title="IMPORTANT: Check your Node version" color="warning" %}}

The PostCSS package installed by some older versions of Node is incompatible with Docsy. Check your version of Node against the active LTS release and upgrade, if necessary. For details, see Node: Get the latest LTS release.

{{% /alert %}}

From your project root, run this command:

npm install --save-dev autoprefixer postcss-cli

Option 1: Docsy as a Git submodule

For a new site

To create a new site and add the Docsy theme as a Git submodule, run the following commands:

  1. Create the site:

    hugo new site myproject
cd myproject
git init

  2. Install postCSS as instructed earlier.

  3. Follow the instructions below for an existing site.

For an existing site

To add the Docsy theme to an existing site, run the following commands from your project's root directory:

  1. Install Docsy as a Git submodule:

    git submodule add https://github.com/google/docsy.git themes/docsy
cd themes/docsy
git checkout v{{% param version %}}

    To work from the development version of Docsy (not recommended), run the following command instead:

    git submodule add --depth 1 https://github.com/google/docsy.git themes/docsy

  2. Add Docsy as a theme, for example:

    echo 'theme: docsy' >> hugo.yaml

    {{% alert title="Tip" %}}As of Hugo 0.110.0, the default config base filename was changed to hugo.* from config.*. If you are using hugo 0.110 or above, consider renaming your config.* to hugo.*. {{% /alert %}}

  3. Get Docsy dependencies:

    (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:

    {
  "...": "...",
  "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",
    "...": "..."
  },
  "...": "..."
}

    Every time you run npm install from your project root, the prepare script will fetch the latest version of Docsy and its dependencies.

From this point on, build and serve your site using the usual Hugo commands, for example:

hugo serve

Option 2: Clone the Docsy theme

If you don't want to use a submodules (for example, if you want to customize and maintain your own copy of the theme directly, or your deployment choice requires you to include a copy of the theme in your repository), you can clone the theme into your project's themes subdirectory.

To clone Docsy at v{{% param version %}} into your project's theme folder, run the following commands from your project's root directory:

cd themes
git clone -b v{{% param version %}} https://github.com/google/docsy
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.

Then consider setting up an NPM prepare script, as documented in Option 1.

For more information, see Theme Components on the Hugo 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:

    hugo new site --format yaml myproject
cd myproject
echo "theme: docsy\nthemesDir: node_modules" >> hugo.yaml

  2. Install Docsy, and postCSS as instructed earlier:

    npm init -y
npm install --save-dev autoprefixer postcss-cli
npm install --save-dev google/docsy#semver:{{% param version %}} --omit=peer

    {{% alert title="Hugo-module compatibility" color="warning" %}} Installing Docsy using NPM creates an empty github.com sibling folder. For details, see Docsy NPM install side-effect. {{% /alert %}}

    {{% alert title="Hugo install tip" color="info" %}} You can install Docsy's officially supported version of Hugo using NPM at the same time as Docsy. Just omit the --omit flag from the command above. {{% /alert %}}

  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:

    $ hugo
Start building sites …
...

    {{% alert title="Error: failed to load modules" color="warning" %}}

If Hugo reports the following error when building your site (#2116):

Error: failed to load modules: module "github.com/FortAwesome/Font-Awesome" not found in ".../myproject/node_modules/github.com/FortAwesome/Font-Awesome" ...

Then run the following command and try again:

npm rebuild

{{% /alert %}}

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):

mkdir -p themes
pushd themes
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:

$ ls themes
docsy                   github.com

This is a workaround necessary to support Docsy's use as a single Hugo module (#1120) in the context of projects not using Hugo modules. The github.com folder is created via Docsy's postinstall script. To disable this behavior, set the environment variable DOCSY_MKDIR_HUGO_MOD_SKIP=1 before running NPM install.

{{% /alert %}}

Preview your site

To preview your site locally:

cd myproject
hugo server

By default, your site will be available at http://localhost:1313. See the known issues on MacOS.

You may get Hugo errors for missing parameters and values when you try to build your site. This is usually because you’re missing default values for some configuration settings that Docsy uses - once you add them your site should build correctly. You can find out how to add configuration in Basic site configuration - we recommend copying the example site configuration even if you’re creating a site from scratch as it provides defaults for many required configuration parameters.

What's next?