Create a new site: start a new site from scratch

Creating a site from scratch gives you Docsy’s look and feel, navigation, and other features, but you specify your own site structure. These instructions give you a minimum file structure only, so that you build and extend your actual site step by step.

TL;DR: Setup for the impatient expert

Run:

• CLI:
• Unix shell
• Windows command line

hugo new site my-new-site
cd  my-new-site
hugo mod init github.com/me/my-new-site
hugo mod get github.com/google/docsy/theme@v0.17.0
cat >> hugo.toml <<EOL
[module]
proxy = "direct"
[[module.imports]]
path = "github.com/google/docsy/theme"
EOL
npm install --save-exact --save-dev sass-embedded@1.102.0
npm pkg set scripts.hugo=hugo
hugo mod npm pack
npm install
npm run hugo -- server

hugo new site my-new-site
cd  my-new-site
hugo mod init github.com/me/my-new-site
hugo mod get github.com/google/docsy/theme@v0.17.0
(echo [module]^

proxy = "direct"^

[[module.imports]]^

path = "github.com/google/docsy/theme") >> hugo.toml
npm install --save-exact --save-dev sass-embedded@1.102.0
npm pkg set scripts.hugo=hugo
hugo mod npm pack
npm install
npm run hugo -- server

Preview at http://localhost:1313/.

Detailed Setup instructions

Create your new skeleton project

To create a new Hugo site project and then add the Docsy theme as a Hugo module, run the following commands from your project’s root directory.

hugo new site my-new-site
cd  my-new-site

This will create a minimal site structure, containing the folders archetypes, content, data, layouts, static, and themes and a configuration file (default: hugo.toml).

Import the Docsy theme module as a dependency of your site

Only sites that are Hugo Modules themselves can import other modules. To turn your site into a Hugo Module, run the following commands in your newly created site directory:

hugo mod init github.com/me/my-new-site

This creates a go.mod file for your site’s module definitions.

Next declare the Docsy theme module as a dependency for your site.

hugo mod get github.com/google/docsy/theme@v0.17.0

This command adds the docsy theme module to your definition file go.mod and records the module checksums in go.sum.

Add theme module configuration settings

Add the settings in the following snippet at the end of your site’s configuration file (default: hugo.toml) and save the file.

• Configuration file:
• hugo.toml
• hugo.yaml
• hugo.json

[module]
  proxy = "direct"
  # uncomment line below for temporary local development of module
  # replacements = "github.com/google/docsy/theme -> ../../docsy/theme"
  [module.hugoVersion]
    extended = true
    min = "0.160.1"
  [[module.imports]]
    path = "github.com/google/docsy/theme"
    disable = false

module:
  proxy: direct
  hugoVersion:
    extended: true
    min: 0.160.1
  imports:
    - path: github.com/google/docsy/theme
      disable: false

{
  "module": {
    "proxy": "direct",
    "hugoVersion": {
      "extended": true,
      "min": "0.160.1"
    },
    "imports": [
      {
        "path": "github.com/google/docsy/theme",
        "disable": false
      }
    ]
  }
}

You can find details of what these configuration settings do in the Hugo modules documentation. Depending on your environment you may need to tweak them slightly, for example by adding a proxy to use when downloading remote modules.

Install npm dependencies

Install the Dart Sass compiler at the version Docsy is tested with, and define an npm script for running Hugo (see Install Dart Sass). Docsy sources its Bootstrap and Font Awesome assets from npm: generate the theme’s npm-dependency workspace (see Hugo’s Node dependencies) and install it:

npm install --save-exact --save-dev sass-embedded@1.102.0
npm pkg set scripts.hugo=hugo
hugo mod npm pack
npm install

Re-run hugo mod npm pack whenever you update Docsy or otherwise edit package.json; Hugo warns when the dependency set drifts. For background, see Bootstrap and Font Awesome via npm in the 0.16.0 release notes.

Preview your site

To build and preview your site locally, run Hugo through the hugo npm script you defined, which puts the sass CLI on Hugo’s PATH:

npm run hugo -- server

By default, your site will be available at http://localhost:1313. For common issues, such as the build failing with a missing Bootstrap import, see Troubleshooting. If the build fails with missing-parameter errors, add the required defaults per Basic site configuration.

What’s next?

• Add some basic configuration
• Add content and customize your site
• Get some ideas from our Example Site and other Examples and templates.
• Publish your site.