4 Building a documentation site

 

This chapter covers

  • Understanding the needs of a typical documentation site
  • Choosing a headless CMS for managing documentation
  • Choosing a static site generator for a documentation site
  • Installing and configuring Hugo
  • Setting up Netlify CMS open editing and modeling
  • Configuring Netlify and GitHub for user authentication
  • Editing content in Netlify CMS

The Jamstack has always excelled at content-focused sites, even from the early days of static site generators. Static HTML and CSS is perfect for displaying content quickly and efficiently; thus, content sites lend themselves to pre-rendering using Jamstack tools. This is why documentation sites have been one of the most obvious use cases for the Jamstack.

Documentation sites have always generally had additional advantages to using the Jamstack:

  • The ability to version file-based content easily via source control
  • A means of accepting contributions and corrections via processes like a GitHub pull request
  • The fact that, in many cases, the authors were technically adept with these sorts of development tools

4.1 Requirements of a documentation site

4.1.1 The example site requirements

4.2 Choosing the right tools

4.2.1 What is a headless CMS?

4.2.2 Headless CMS options

4.2.3 Why Netlify CMS?

4.2.4 Static site generator (SSG) options

4.2.5 Why Hugo?

4.3 Building the example site

4.3.1 Installing Hugo

4.3.2 Creating a new Hugo site

4.3.3 Setting up the Hugo Book theme