Climate Change

With the site created and the theme installed, it’s time to run the server and create content.

Starting & building the site

Development server

To start the site for development mode, execute the following command while in your /docs folder:

hugo server

For more Hugo commands visit https://gohugo.io/commands/

Building for production

To build the site for your production environment, as in, to serve it to your users through a web server, execute the following command. This will create a folder /docs/public with all the necessary files, compiled to HTML.

Be sure the site’s configuration in config.toml is complete, including the baseURL = “https://yourdomain.com/” value to properly load stylesheets and other resources.

hugo

Creating content

Markdown

Pages are written in Markdown and files defining pages should end with .md. For more information on how to use Markdown, search for tutorials on the internet or use this cheatsheet.

File structure

Ace looks at your file structure and automatically turns it into a menu. The structure looks as follows:

/content
├── _index.md
├── page-top.md
└── /level-one
    ├── _index.md
    ├── page-1-one.md
    ├── page-1-two.md
    └── /level-two
        ├── _index.md
        ├── page-2-one.md
        ├── page-2-two.md
        └── /level-three
            ├── _index.md
            ├── page-3-one.md
            ├── page-3-two.md
            └── /level-four
                ├── page-4-one.md
                └── page-4-two.md

Your ‘homepage’ for every level is the _index.md file. Subpages (like page-1-one.md) are automatically added as child pages in the menu.

An exception exists for the top level files. /content/_index.md is your homepage, and any other page files in the /content folder are not automatically added in the menu. Instead, they can be accessed manually through their URL (yourdomain.com/page-title).

File contents

Every file should start by defining the title and weight of the page. This can be done by adding the following text to the top of your page file.

+++
title = "Usage"
description = ""
weight = 2
+++

After that you may write the content you desire with Markdown. You may use shortcodes to add some more ‘advanced’ layout features to the page, such as code highlighting, a ‘lead’ style paragraph, images, video’s, and more.

Navigation bar menu

While the left sidebar navigation is automatically populated by the file structure described above, and the right ‘table of contents’ sidebar menu is automatically populated by the headings defined on a page, the top navigation bar needs to be configured manually.
This can be done in the config.toml file, by adding the following lines:

[[menu.shortcuts]]
name = "<i class='fab fa-github'></i>"
url = "https://github.com/vantagedesign/ace-documentation"
weight = 10

This example will create a GitHub icon that links to that URL. Instead of an icon, you may also use text, or both.