This the multi-page printable view of this section. Click here to print.
One of the best ways to see what Docsy can do, and learn how to configure a site with it, is to see some real projects. In addition to our provided Docsy Example Project, there are several live sites already using the theme. Please add your own examples once you’ve got a production site up and running with Docsy!
Example sites that have low to no customization:
Example sites that include a moderate to high amount of customization:
We provide a Docker image that you can use to run and test your Docsy site locally, without having to install all Docsy’s dependencies.
You can see how to get started with this approach by following our Docker Quickstart tutorial. If you don’t want to use Docker, follow the instructions below to install Hugo and PostCSS.
You need a recent extended version (we recommend version 0.75.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.
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.75 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:
Go to the Hugo releases page.
In the most recent release, scroll down until you find a list of Extended versions.
Download the latest extended version (hugo_extended_0.5X_Linux-64bit.tar.gz).
Create a new directory:
mkdir hugo
Extract the files you downloaded to hugo.
Switch to your new directory:
cd hugo
Install Hugo:
sudo install hugo /usr/bin
Install Hugo using Brew.
npm moduleYou can install Hugo as an npm module using 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:
npm install hugo-extended --save-dev
See the hugo-bin documentation for usage details.
To build or update your site’s CSS resources, you also need PostCSS to create the final assets. If you need to install it, you must have a recent version of NodeJS installed on your machine so you can use npm, the Node package manager. By default npm installs tools under the directory where you run npm install:
sudo npm install -D autoprefixer
sudo npm install -D postcss-cli
Starting in version 8 of postcss-cli, you must also separately install postcss:
sudo npm install -D postcss
Note that versions of PostCSS later than 5.0.1 will not load autoprefixer if installed globally, you must use a local install.
To use the Docsy Hugo theme, you have a couple of options:
The Example Site gives you a good starting point for building your docs site and is pre-configured to use the Docsy theme as a Git submodule. You can copy the Example Site either by:
This is the simplest approach, as the Docsy example site repo is a template repository. To create your own copy of the Docsy example site repo:
Go to the repo page and click Use this template.
Type your chosen name for your new repository in the Repository name field. You can also add an optional Description.
Click Create repository from template to create your new repository. Congratulations, you now have a Docsy site repo!
To test your copied site locally with Hugo, or make local edits, you’ll also need to make a local copy of your new repository. To do this, use git clone, replacing https://github.com/my/example.git with your repo’s web URL (don’t forget to use --recurse-submodules or you won’t pull down some of the code you need to generate a working site):
git clone --recurse-submodules --depth 1 https://github.com/my/example.git
You can now edit your local versions of the site’s source files. To preview your site, go to your site root directory and run hugo server (see the known issues on MacOS). By default, your site will be available at http://localhost:1313/. To push changes to your new repo, go to your site root directory and use git push.
To copy the example site:
Make a local working copy of the example site directly using git clone:
git clone https://github.com/google/docsy-example.git
Switch to the root of the cloned project, for example:
cd docsy-example
Get local copies of the project submodules so you can build and run your site locally:
git submodule update --init --recursive
Build your site:
hugo server
Preview your site in your browser at: http://localhost:1313/. You can use Ctrl + c to stop the Hugo server whenever you like.
See the known issues on MacOS.
Now that you have a site running, you can push it to a new repository:
Create a new repository in GitHub
for your site with your chosen repo name. For clarity you may also want to rename the root
directory (docsy-example) of your working copy to match, though everything will still
work even if you don’t.
Configure
origin
in your project. From your site’s root directory, set the URL for origin to your new
repo (otherwise you’ll be trying to push changes to google/docsy rather than to your repo):
git remote set-url origin https://github.com/MY-SITE/EXAMPLE.git
Verify that your remote is configured correctly by running:
git remote -v
Push your Docsy site to your repository:
git push -u origin master
Specify the Docsy theme like any other Hugo theme when creating or updating your site. This gives you all the theme-y goodness but you’ll need to specify your own site structure. You can either use the theme as a submodule (our recommended approach for easy updates), or just clone the theme into your project’s themes subdirectory.
Whichever approach you use, for simplicity we recommend copying and editing our example site configuration for your project, or you may get Hugo errors for missing parameters and values when you try to build your site.
Adding Docsy as a Git submodule is our recommended approach for using the theme, as it means your project always refers to the Docsy repo version at your chosen revision, rather than you having your own copy in your repo that may result in merge conflicts when you try to update it. This is the approach used by our example project.
To create a new Hugo site project and then add the Docs theme as a submodule, run the following commands from your project’s root directory.
hugo new site myproject
cd myproject
git init
git submodule add https://github.com/google/docsy.git themes/docsy
echo 'theme = "docsy"' >> config.toml
git submodule update --init --recursive
To add the Docsy theme to an existing site, run the following commands from your project’s root directory:
git submodule add https://github.com/google/docsy.git themes/docsy
echo 'theme = "docsy"' >> config.toml
git submodule update --init --recursive
themes subdirectoryIf 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.
To clone Docsy into your project’s theme folder, run the following commands from your project’s root directory:
cd themes
git clone https://github.com/google/docsy
If you want to build and/or serve your site locally, you also need to get local copies of the theme’s own submodules:
git submodule update --init --recursive
For more information, see Theme Components on the Hugo site.
To build and 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.
Site-wide configuration details and parameters are defined in your project’s config.toml file. These include your chosen Hugo theme (Docsy, of course!), project name, community links, Google Analytics configuration, and Markdown parser parameters. See the examples with comments in config.toml in the example project for how to add this information. We recommend copying this config.toml and editing it even if you’re just using the theme and not copying the entire Docsy example site.
The Docsy example site comes with some defaults you may want to remove or customize straight away:
The Docsy example site supports content in English and Norwegian. You can find out more about how Docsy supports multi-language content in Multi-language support.
If you don’t intend to translate your site to Norwegian, you can remove the language switcher by removing the following lines from config.toml:
[languages.no]
title = "Docsy"
description = "Docsy er operativsystem for skyen"
languageName ="Norsk"
contentDir = "content/no"
To remove the translated source files, delete the docsy-example/content/no directory.
By default, the Docsy example site uses its own Google Custom Search Engine. To disable this site search, delete or comment out the following lines:
# Google Custom Search Engine ID. Remove or comment out to disable search.
gcs_engine_id = "011737558837375720776:fsdu1nryfng"
To use your own Custom Search Engine, replace the value in the gcs_engine_id with the ID of your own search engine. Or choose another search option.
too many open files or fatal error: pipe failedBy default, MacOS permits a small number of open File Descriptors. For larger sites, or when you’re simultaneously running multiple applications,
you might receive one of the following errors when you run hugo server to preview your site locally:
POSTCSS v7 and earlier:
ERROR 2020/04/14 12:37:16 Error: listen tcp 127.0.0.1:1313: socket: too many open files
POSTCSS v8 and later:
fatal error: pipe failed
To temporarily allow more open files:
View your current settings by running:
sudo launchctl limit maxfiles
Increase the limit to 65535 files by running the following commands. If your site has fewer files, you can set choose to set lower soft (65535) and
hard (200000) limits.
sudo launchctl limit maxfiles 65535 200000
ulimit -n 65535
sudo sysctl -w kern.maxfiles=200000
sudo sysctl -w kern.maxfilesperproc=65535
Note that you might need to set these limits for each new shell. Learn more about these limits and how to make them permanent.
We provide a Docker image that you can use to run and test your Docsy site locally, without having to install all Docsy’s dependencies.
You can see how to get started with this approach by following our Docker Quickstart tutorial. If you don’t want to use Docker, follow the instructions below to install Hugo and PostCSS.
You need a recent extended version (we recommend version 0.75.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.
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.75 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:
Go to the Hugo releases page.
In the most recent release, scroll down until you find a list of Extended versions.
Download the latest extended version (hugo_extended_0.5X_Linux-64bit.tar.gz).
Create a new directory:
mkdir hugo
Extract the files you downloaded to hugo.
Switch to your new directory:
cd hugo
Install Hugo:
sudo install hugo /usr/bin
Install Hugo using Brew.
npm moduleYou can install Hugo as an npm module using 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:
npm install hugo-extended --save-dev
See the hugo-bin documentation for usage details.
To build or update your site’s CSS resources, you also need PostCSS to create the final assets. If you need to install it, you must have a recent version of NodeJS installed on your machine so you can use npm, the Node package manager. By default npm installs tools under the directory where you run npm install:
sudo npm install -D autoprefixer
sudo npm install -D postcss-cli
Starting in version 8 of postcss-cli, you must also separately install postcss:
sudo npm install -D postcss
Note that versions of PostCSS later than 5.0.1 will not load autoprefixer if installed globally, you must use a local install.
To use the Docsy Hugo theme, you have a couple of options:
The Example Site gives you a good starting point for building your docs site and is pre-configured to use the Docsy theme as a Git submodule. You can copy the Example Site either by:
This is the simplest approach, as the Docsy example site repo is a template repository. To create your own copy of the Docsy example site repo:
Go to the repo page and click Use this template.
Type your chosen name for your new repository in the Repository name field. You can also add an optional Description.
Click Create repository from template to create your new repository. Congratulations, you now have a Docsy site repo!
To test your copied site locally with Hugo, or make local edits, you’ll also need to make a local copy of your new repository. To do this, use git clone, replacing https://github.com/my/example.git with your repo’s web URL (don’t forget to use --recurse-submodules or you won’t pull down some of the code you need to generate a working site):
git clone --recurse-submodules --depth 1 https://github.com/my/example.git
You can now edit your local versions of the site’s source files. To preview your site, go to your site root directory and run hugo server (see the known issues on MacOS). By default, your site will be available at http://localhost:1313/. To push changes to your new repo, go to your site root directory and use git push.
To copy the example site:
Make a local working copy of the example site directly using git clone:
git clone https://github.com/google/docsy-example.git
Switch to the root of the cloned project, for example:
cd docsy-example
Get local copies of the project submodules so you can build and run your site locally:
git submodule update --init --recursive
Build your site:
hugo server
Preview your site in your browser at: http://localhost:1313/. You can use Ctrl + c to stop the Hugo server whenever you like.
See the known issues on MacOS.
Now that you have a site running, you can push it to a new repository:
Create a new repository in GitHub
for your site with your chosen repo name. For clarity you may also want to rename the root
directory (docsy-example) of your working copy to match, though everything will still
work even if you don’t.
Configure
origin
in your project. From your site’s root directory, set the URL for origin to your new
repo (otherwise you’ll be trying to push changes to google/docsy rather than to your repo):
git remote set-url origin https://github.com/MY-SITE/EXAMPLE.git
Verify that your remote is configured correctly by running:
git remote -v
Push your Docsy site to your repository:
git push -u origin master
Specify the Docsy theme like any other Hugo theme when creating or updating your site. This gives you all the theme-y goodness but you’ll need to specify your own site structure. You can either use the theme as a submodule (our recommended approach for easy updates), or just clone the theme into your project’s themes subdirectory.
Whichever approach you use, for simplicity we recommend copying and editing our example site configuration for your project, or you may get Hugo errors for missing parameters and values when you try to build your site.
Adding Docsy as a Git submodule is our recommended approach for using the theme, as it means your project always refers to the Docsy repo version at your chosen revision, rather than you having your own copy in your repo that may result in merge conflicts when you try to update it. This is the approach used by our example project.
To create a new Hugo site project and then add the Docs theme as a submodule, run the following commands from your project’s root directory.
hugo new site myproject
cd myproject
git init
git submodule add https://github.com/google/docsy.git themes/docsy
echo 'theme = "docsy"' >> config.toml
git submodule update --init --recursive
To add the Docsy theme to an existing site, run the following commands from your project’s root directory:
git submodule add https://github.com/google/docsy.git themes/docsy
echo 'theme = "docsy"' >> config.toml
git submodule update --init --recursive
themes subdirectoryIf 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.
To clone Docsy into your project’s theme folder, run the following commands from your project’s root directory:
cd themes
git clone https://github.com/google/docsy
If you want to build and/or serve your site locally, you also need to get local copies of the theme’s own submodules:
git submodule update --init --recursive
For more information, see Theme Components on the Hugo site.
To build and 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.
Site-wide configuration details and parameters are defined in your project’s config.toml file. These include your chosen Hugo theme (Docsy, of course!), project name, community links, Google Analytics configuration, and Markdown parser parameters. See the examples with comments in config.toml in the example project for how to add this information. We recommend copying this config.toml and editing it even if you’re just using the theme and not copying the entire Docsy example site.
The Docsy example site comes with some defaults you may want to remove or customize straight away:
The Docsy example site supports content in English and Norwegian. You can find out more about how Docsy supports multi-language content in Multi-language support.
If you don’t intend to translate your site to Norwegian, you can remove the language switcher by removing the following lines from config.toml:
[languages.no]
title = "Docsy"
description = "Docsy er operativsystem for skyen"
languageName ="Norsk"
contentDir = "content/no"
To remove the translated source files, delete the docsy-example/content/no directory.
By default, the Docsy example site uses its own Google Custom Search Engine. To disable this site search, delete or comment out the following lines:
# Google Custom Search Engine ID. Remove or comment out to disable search.
gcs_engine_id = "011737558837375720776:fsdu1nryfng"
To use your own Custom Search Engine, replace the value in the gcs_engine_id with the ID of your own search engine. Or choose another search option.
too many open files or fatal error: pipe failedBy default, MacOS permits a small number of open File Descriptors. For larger sites, or when you’re simultaneously running multiple applications,
you might receive one of the following errors when you run hugo server to preview your site locally:
POSTCSS v7 and earlier:
ERROR 2020/04/14 12:37:16 Error: listen tcp 127.0.0.1:1313: socket: too many open files
POSTCSS v8 and later:
fatal error: pipe failed
To temporarily allow more open files:
View your current settings by running:
sudo launchctl limit maxfiles
Increase the limit to 65535 files by running the following commands. If your site has fewer files, you can set choose to set lower soft (65535) and
hard (200000) limits.
sudo launchctl limit maxfiles 65535 200000
ulimit -n 65535
sudo sysctl -w kern.maxfiles=200000
sudo sysctl -w kern.maxfilesperproc=65535
Note that you might need to set these limits for each new shell. Learn more about these limits and how to make them permanent.
On Mac and Windows, download and install Docker Desktop. On Linux, install Docker engine and Docker compose.
The installation may require you to reboot your computer for the changes to take effect.
The docsy-example repository provides a basic site structure that you can use as starting point to create your own documentation.
Use the docsy-example template to create your own repository.
Download the code to your local machine by cloning your newly created repository.
Change your working directory to the newly created folder:
cd docsy-example
The docsy-example repository includes a Dockerfile that you can use to run your site.
Build the docker image:
docker-compose build
Run the built image:
docker-compose up
Open the address http://localhost:1313 in your web browser to load the
docsy-example homepage. You can now make changes to the source files, those
changes will be live-reloaded in your browser.
To cleanup your system and delete the container image follow the next steps.
Stop Docker Compose with Ctrl + C.
Remove the produced images
docker-compose rm
On Mac and Windows, download and install Docker Desktop. On Linux, install Docker engine and Docker compose.
The installation may require you to reboot your computer for the changes to take effect.
The docsy-example repository provides a basic site structure that you can use as starting point to create your own documentation.
Use the docsy-example template to create your own repository.
Download the code to your local machine by cloning your newly created repository.
Change your working directory to the newly created folder:
cd docsy-example
The docsy-example repository includes a Dockerfile that you can use to run your site.
Build the docker image:
docker-compose build
Run the built image:
docker-compose up
Open the address http://localhost:1313 in your web browser to load the
docsy-example homepage. You can now make changes to the source files, those
changes will be live-reloaded in your browser.
To cleanup your system and delete the container image follow the next steps.
Stop Docker Compose with Ctrl + C.
Remove the produced images
docker-compose rm
If you’d like to provide site content in multiple languages, the Docsy theme and Hugo make it easy to both add your translated content and for your users to navigate between language versions.
To add content in multiple languages, you first need to define the available languages in a languages section in your site configuration. Each language can have its own language-specific configuration. For example, the Docsy Example Site config specifies that it provides content in English and Norwegian, and that the language version visitors will see by default is English:
contentDir = "content/en"
defaultContentLanguage = "en"
defaultContentLanguageInSubdir = false
...
[languages]
[languages.en]
title = "Docsy"
description = "Docsy does docs"
languageName ="English"
# Weight used for sorting.
weight = 1
[languages.no]
title = "Docsy"
description = "Docsy er operativsystem for skyen"
languageName ="Norsk"
contentDir = "content/no"
time_format_default = "02.01.2006"
time_format_blog = "02.01.2006"
Any setting not defined in a [languages] block will fall back to the global value for that setting: so, for example, the content directory used for the site above will be content/en unless the user selects the Norwegian language option.
Once you’ve updated your site config, you create a content root directory for each language version in your source repo, such as content/en for English text, and add your content as usual. See the Hugo Docs on multi-language support for more information.
For adding multiple language versions of other site elements such as button text, see the internationalization bundles section below.
If you configure more than one language in config.toml, the Docsy theme adds a language selector drop down to the top-level menu. Selecting a language takes the user to the translated version of the current page, or the home page for the given language.
All UI strings (text for buttons etc.) are bundled inside /i18n in the theme, with a .toml file for each language.
If your chosen language isn’t currently in the theme and you create your own .toml file for all the common UI strings (for example, if you translate the UI text into Japanese and create a copy of en.toml called jp.toml), we recommend you do this in the theme rather than in your own project, so it can be reused by others. Any additional strings or overridden values can be added to your project’s /i18n folder.
hugo server --i18n-warnings when doing translation work, as it will give you warnings on what strings are missing.
If you’d like to provide site content in multiple languages, the Docsy theme and Hugo make it easy to both add your translated content and for your users to navigate between language versions.
To add content in multiple languages, you first need to define the available languages in a languages section in your site configuration. Each language can have its own language-specific configuration. For example, the Docsy Example Site config specifies that it provides content in English and Norwegian, and that the language version visitors will see by default is English:
contentDir = "content/en"
defaultContentLanguage = "en"
defaultContentLanguageInSubdir = false
...
[languages]
[languages.en]
title = "Docsy"
description = "Docsy does docs"
languageName ="English"
# Weight used for sorting.
weight = 1
[languages.no]
title = "Docsy"
description = "Docsy er operativsystem for skyen"
languageName ="Norsk"
contentDir = "content/no"
time_format_default = "02.01.2006"
time_format_blog = "02.01.2006"
Any setting not defined in a [languages] block will fall back to the global value for that setting: so, for example, the content directory used for the site above will be content/en unless the user selects the Norwegian language option.
Once you’ve updated your site config, you create a content root directory for each language version in your source repo, such as content/en for English text, and add your content as usual. See the Hugo Docs on multi-language support for more information.
For adding multiple language versions of other site elements such as button text, see the internationalization bundles section below.
If you configure more than one language in config.toml, the Docsy theme adds a language selector drop down to the top-level menu. Selecting a language takes the user to the translated version of the current page, or the home page for the given language.
All UI strings (text for buttons etc.) are bundled inside /i18n in the theme, with a .toml file for each language.
If your chosen language isn’t currently in the theme and you create your own .toml file for all the common UI strings (for example, if you translate the UI text into Japanese and create a copy of en.toml called jp.toml), we recommend you do this in the theme rather than in your own project, so it can be reused by others. Any additional strings or overridden values can be added to your project’s /i18n folder.
hugo server --i18n-warnings when doing translation work, as it will give you warnings on what strings are missing.
If you’d like to provide site content in multiple languages, the Docsy theme and Hugo make it easy to both add your translated content and for your users to navigate between language versions.
To add content in multiple languages, you first need to define the available languages in a languages section in your site configuration. Each language can have its own language-specific configuration. For example, the Docsy Example Site config specifies that it provides content in English and Norwegian, and that the language version visitors will see by default is English:
contentDir = "content/en"
defaultContentLanguage = "en"
defaultContentLanguageInSubdir = false
...
[languages]
[languages.en]
title = "Docsy"
description = "Docsy does docs"
languageName ="English"
# Weight used for sorting.
weight = 1
[languages.no]
title = "Docsy"
description = "Docsy er operativsystem for skyen"
languageName ="Norsk"
contentDir = "content/no"
time_format_default = "02.01.2006"
time_format_blog = "02.01.2006"
Any setting not defined in a [languages] block will fall back to the global value for that setting: so, for example, the content directory used for the site above will be content/en unless the user selects the Norwegian language option.
Once you’ve updated your site config, you create a content root directory for each language version in your source repo, such as content/en for English text, and add your content as usual. See the Hugo Docs on multi-language support for more information.
For adding multiple language versions of other site elements such as button text, see the internationalization bundles section below.
If you configure more than one language in config.toml, the Docsy theme adds a language selector drop down to the top-level menu. Selecting a language takes the user to the translated version of the current page, or the home page for the given language.
All UI strings (text for buttons etc.) are bundled inside /i18n in the theme, with a .toml file for each language.
If your chosen language isn’t currently in the theme and you create your own .toml file for all the common UI strings (for example, if you translate the UI text into Japanese and create a copy of en.toml called jp.toml), we recommend you do this in the theme rather than in your own project, so it can be reused by others. Any additional strings or overridden values can be added to your project’s /i18n folder.
hugo server --i18n-warnings when doing translation work, as it will give you warnings on what strings are missing.
There are multiple possible options for deploying a Hugo site, including Netlify, Firebase Hosting, Bitbucket with Aerobatic, and more; you can read about them all in Hosting and Deployment. Hugo also makes it easy to deploy your site locally for quick previews of your content.
Depending on your deployment choice you may want to serve your site locally during development to preview content changes. To serve your site locally:
Ensure you have an up to date local copy of your site files cloned from your repo. Don’t forget to use --recurse-submodules or you won’t pull down some of the code you need to generate a working site.
git clone --recurse-submodules --depth 1 https://github.com/my/example.git
If you’ve just added the theme as a submodule in a local version of your site and haven’t committed it to a repo yet, you must get local copies of the theme’s own submodules before serving your site.
git submodule update --init --recursive
Ensure you have the tools described in Prerequisites and installation installed on your local machine, including postcss-cli (you’ll need it to generate the site resources the first time you run the server).
Run the hugo server command in your site root. By default your site will be available at http://localhost:1313/.
Now that you’re serving your site locally, Hugo will watch for changes to the content and automatically refresh your site. If you have more than one local git branch, when you switch between git branches the local website reflects the files in the current branch.
We recommend using Netlify as a particularly simple way to serve your site from your Git provider (GitHub, GitLab, or BitBucket), with continuous deployment, previews of the generated site when you or your users create pull requests against the doc repo, and more. Netlify is free to use for Open Source projects, with premium tiers if you require greater support.
Before deploying with Netlify, make sure that you’ve pushed your site source to your chosen GitHub (or other provider) repo, following any setup instructions in Using the theme.
Then follow the instructions in Host on Netlify to set up a Netlify account (if you don’t have one already) and authorize access to your GitHub or other Git provider account. Once you’re logged in:
cd themes/docsy && git submodule update -f --init && cd ../.. && hugo. You need to specify this rather than just hugo so that Netlify can use the theme’s submodules.HUGO_VERSION as the Key for the new variable, and 0.53 or later as its Value.HUGO_ENV to production. Do this if you want your site to be indexed by search engines. You must do this if you want to use a Google Custom Search Engine.Netlify uses your site repo’s package.json file to install any JavaScript dependencies (like postcss) before building your site. If you haven’t just copied our example site’s version of this file, make sure that you’ve specified all our prerequisites.
For example, if you want to use a version of postcss-cli later than version 8.0.0, you need to ensure that your package.json also specifies postcss separately:
"devDependencies": {
"autoprefixer": "^9.8.6",
"postcss-cli": "^8.0.0",
"postcss": "^8.0.0"
}
Alternatively, you can follow the same instructions but specify your Deploy settings in a netlify.toml file in your repo rather than in the Deploy settings page. You can see an example of this in the Docsy theme repo (though note that the build command here is a little unusual because the Docsy user guide is inside the theme repo).
If you have an existing deployment you can view and update the relevant information by selecting the site from your list of sites in Netlify, then clicking Site settings - Build and deploy. Ensure that Ubuntu Xenial 16.04 is selected in the Build image selection section - if you’re creating a new deployment this is used by default. You need to use this image to run the extended version of Hugo.
One of the best ways to see what Docsy can do, and learn how to configure a site with it, is to see some real projects. In addition to our provided Docsy Example Project, there are several live sites already using the theme. Please add your own examples once you’ve got a production site up and running with Docsy!
Example sites that have low to no customization:
Example sites that include a moderate to high amount of customization:
Docsy is an open source project and we love getting patches and contributions to make Docsy and its docs even better.
The Docsy theme itself lives in https://github.com/google/docsy.
Contributions to this project must be accompanied by a Contributor License Agreement. You (or your employer) retain the copyright to your contribution; this simply gives us permission to use and redistribute your contributions as part of the project. Head over to https://cla.developers.google.com/ to see your current agreements on file or to sign a new one.
You generally only need to submit a CLA once, so if you’ve already submitted one (even if it was for a different project), you probably don’t need to do it again.
All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult GitHub Help for more information on using pull requests.
As Docsy is a theme rather than a site, you can’t serve the theme directly to check your changes work. Instead use your updated local theme in a local copy of the Docsy example site (copy or make your changes in the themes/docsy directory) and preview from there. Alternatively, clone the Docsy theme repo and test your changes in a local copy of this site, as described below.
This project follows Google’s Open Source Community Guidelines.
Alternatively, if there’s something you’d like to see in Docsy (or if you’ve found something that isn’t working the way you’d expect), but you’re not sure how to fix it yourself, please create an issue.
This user guide is, like our example site, a Docsy site that uses the Hugo static site generator. We welcome updates to the docs!
We use Netlify to manage the deployment of the site and provide previews of doc updates. The instructions here assume you’re familiar with basic GitHub workflows.
userguide subdirectory.If you’ve just spotted something you’d like to change while using the docs, Docsy has a shortcut for you:
If you want to run your own local Hugo server to preview your changes as you work:
Follow the instructions in Getting started to install Hugo and any other tools you need.
Fork the Docsy repo into your own project, then create a local copy using git clone. Don’t forget to use --recurse-submodules or you won’t pull down some of the code you need to generate a working site.
git clone --recurse-submodules --depth 1 https://github.com/google/docsy.git
Change to the userguide directory and run the following Hugo command to build the site and start the Hugo server.
Note that you need the themesDir flag because the site files are inside the theme repo.
cd userguide
hugo server --themesDir ../..
By default your site will be available at http://localhost:1313/. Now that you’re serving your site locally, Hugo will watch for changes to the content and automatically refresh your site.
Continue with the usual GitHub workflow to edit files, commit them, push the changes up to your fork, and create a pull request.
If there’s something you’d like to see in the docs, but you’re not sure how to fix it yourself, please create an issue in this repository. You can also create an issue about a specific page by clicking the Create Issue button in the top right hand corner of the page.