Learn how to get started with Docsy by using the theme as a Hugo Module.
As you saw in our introduction, Docsy is a Hugo theme, which means that if you want to use Docsy, you need to set up your website source so that the Hugo static site generator can find and use the Docsy theme files when building your site. The simplest way to do this is to copy and edit our example site, though we also provide instructions for adding the Docsy theme manually to new or existing sites.
If you want to build and test your site locally you also need to be able to run Hugo itself, either by installing it and any other required dependencies, or by using our provided Docker container.
This page describes Docsy’s installation options and helps you choose the appropriate setup guide to get started.
Hugo offers multiple options for using themes, all of which are supported by Docsy.
- Adding the theme as a Hugo Module: Hugo Modules are the simplest and latest way to use Hugo themes. Hugo uses the modules mechanism to pull in the theme files from the main Docsy repo at your chosen revision, and it’s easy to keep the theme up to date in your site. Our example site uses Docsy as a Hugo Module.
- Adding the theme as a Git submodule: Adding the theme as a Git submodule also lets Hugo use the theme files from their own 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.
- Cloning the theme files: 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.
Migration and backward compatibility
If you have an existing site that uses Docsy as a Git submodule, and you would like to update it to use Hugo Modules, follow our migration guide. If you’re not ready to migrate yet, don’t worry! Your site will continue to work as usual.
Follow the setup guide for your chosen approach. If you’re new to Docsy and not sure which guide to follow, we recommend following the Use Docsy as a Hugo Module guide as a simple and easily maintained option.
Create a new Docsy site with Docsy as a Git submodule or cloned theme
Instructions on how to setup and run a local Docsy site with Docker.
Basic configuration for new Docsy sites.
Known issues when installing Docsy theme.
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.