How to run Hugo locally
The Microsoft 365 Community blog uses Hugo, a static site generator.
If you're not familiar with the term: It's a tool that can generate a website by converting markdown files and combining them with a template. Using a static site generator means you don't need a Content Management System, a database or a webserver with all kinds of requirements. You can just write files in Markdown and host your files anywhere. Static sites load very fast, and it's a great experience writing content in easy-to learn Markdown.
Now Markdown looks nice, but you never know for sure how it will be transformed without seeing it for yourself. If you want to know, you need to install and run Hugo locally.
To install Hugo you can follow the guidance in the Hugo docs. There are a few things to take note of:
-
Hugo extended: Make sure that you install Hugo extended. The PnP blog uses scss/css compilation, which is only available in extended.
-
Hugo Version: It's also best if you align with the version of Hugo that we use on the PnP blog. You can find the current version in the
.devcontainer/devcontainer.jsonfile in the GitHub repository. (You'll find more info on the devcontainer further down this page.) At the time of writing we're at version0.100.2.
Taking the above into account, the following script can be used to install Hugo with PowerShell on Windows. (using the Chocolatey package manager)
# Installs chocolatey if you don't have it
Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))
# Installs hugo
choco install hugo-extended --version=0.100.2If you already have Hugo installed, you can check the version running hugo version. It should print something like this:
hugo v0.100.2-d25cb2943fd94ecf781412aeff9682d5dc62e284+extended linux/amd64 BuildDate=2022-06-08T10:25:57Z VendorInfo=gohugoioThis string contains the version number and whether you've got the extended version: (look for the +extended string)
Installing Hugo on your system is OK if you don't mind. But maybe you have your own Hugo development going on, with separate versions of Hugo. Or maybe you don't like to install more programs, cluttering your system. It is possible to separate your contributions from the other stuff going on in your PC. This can be done using Docker. Using Docker is like running a VM on your PC, and being able to clean it up instantly if you're done. It's an advanced subject, but for the matter at hand you need three things:
Once you have them all installed and Docker running, open a new VS Code window, open the Command Palette using Ctrl + Shift + P and search for the command Clone repository in Container Volume:
The command will ask for a git URL, and you can copy/paste our git url there: https://github.com/pnp/blog.git. Following the prompts and hitting enter will start cloning the repository on your machine in a completely separated docker volume. It will also install Hugo, so you'll not need to do anything else after.
This is a VERY condensed way to explain it. If you're interested in finding out a bit more, you can read up on remote containers or follow the tutorial.
Open a terminal in the root directory of your blog and run the following command:
hugo serverWhat this will do is build the site and start a server that will allow you to view the site using the URL http://localhost:1313/blog/. It will also configure a watcher, so any changes you make to md-files are instantly compiled. No need to hit F5 after, your browser window will be refreshed for you as well.
Please see this note if your local builds are timing out: https://github.com/pnp/blog/wiki#%EF%B8%8F-note-on-hugo-build-times-and-timeouts-
Contact us! We'll help in any way we can.