chapter four

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

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 such as:

  • 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 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

4.3.4  Installing Netlify CMS

4.3.5  Modeling Content in Netlify CMS

4.3.6  Deploying to Netlify

4.3.7  Configuring GitHub for Authentication

4.3.8  Configuring Netlify for Authentication

4.3.9  Editing Content as an Admin

4.3.10  The Open Authoring Workflow

4.3.11  Simplifying the Open Authoring Workflow

4.4  What’s Next

4.5  Summary