Gigo

We are going to generate a website with Gigo by using the tags:

<gigo-include file=* />
<gigo-include-in file=* />

1) Install Gigo

Make sure you have Go installed.

Install Gigo by running the following command locally:

go install github.com/reactive-tech/gigo@latest

The command above will install the executable "gigo" in the folder $(go env GOPATH)/bin. You may need to add that directory to your $PATH in order to access to the binary "gigo" from anywhere on your computer.

2) Folder structure

Gigo does not impose any folder structure. The only rule to be aware of is, the urls and include-paths that you are using in the html files are relative to your project's root folder where your website resides. For this example, the website resides in the folder "website-example". It is therefore the root folder for this project and all paths are relative to that root folder.

We placed the following files in this project's:

-> website-example
    -> index.html
    -> about-us.html
    -> css
        -> main.css
    -> includes
        -> header.html
        -> header-title.html
        -> main-template.html

Our aim is to generate a static website with 2 pages: "index.html" and "about-us.html".

We have a folder "includes" containing the HTML files that we will include to compose "index.html" and "about-us.html".

Note that, the folder "includes" is not mandatory as Gigo does not impose any folder structure. You can locate the files to include anywhere in your root folder and they do not have to be in the same folder. For this example, we aimed to simplify the documentation by placing the files to include in the same folder.

3) Using the tag "gigo-include"

The tag <gigo-include file=* /> allows including an external HTML page to a current HTML page.

A page can contains one or many tags <gigo-include file=* />.

Let's illustrate an example, with the contents below of the file containing only the website's title.

includes/header-title.html:

<title>Gigo in action</title>

Let's include that page in "header.html":

includes/header.html:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <link rel="stylesheet" type="text/css" href="../css/main.css">
        <gigo-include file="includes/header-title.html" />
    </head>
    <body>

And finally, we have a footer page and a css file.

includes/footer.html:

    </body>
</html>

css/main.css:

body{
    border:1px solid #ccc;
    text-align:center;
}

Now we defined the header and footer, and css pages, we can use them to assemble the 2 pages: "index.html" and "about-us.html".

4) Using the tag "gigo-include-in"

The tag <gigo-include-in file=* /> allows an HTML page to be generated by being included in a target HTML file. Its contents will be placed in the tag <gigo-include-in-content /> of the target HTML file.

A page can only contain one tag <gigo-include-in file=* /> and the target page can only contain one tag <gigo-include-in-content />.

This tag is very handy when you have a website with many pages. It prevents duplicating the inclusion statements for header and footer in each page to generate.

In our example, the website has 2 pages: "index.html" and "about-us.html". These 2 HTML pages have the same structure with a header and body and a footer. We have created a template file "main-template.html" which centralise this structure.

includes/main-template.html:

<gigo-include file="includes/header.html" />

<gigo-include-in-content />

<gigo-include file="includes/footer.html" />

Above, <gigo-include-in-content /> is where the pages using <gigo-include-in file="includes/footer.html" /> will be included.

Finally let's assemble the 2 pages that we want to generate.

index.html:

<gigo-include-in file="includes/main-template.html" />

<h1>Home page</h1>
<p>Contents of home page ...</p>

<p>Menu: <a href="about-us.html">About us</a></p>

about-us.html:

<gigo-include-in file="includes/main-template.html" />

<h1>About us</h1>
<p>Contents of about-us page ...</p>

<p>Menu: <a href="index.html">Home</a></p>

The codes above use the tag <gigo-include-in ... /> asking Gigo to generate the pages by being included in the target HTML file "includes/main-template.html" where the tag <gigo-include-in-content /> resides.

5) Generate the static website

Assuming the binary "gigo" is in your $PATH, we run the command line:

~/website-example$ gigo

Gigo generates the static website in the folder "output", as follows:

-> website-example
    -> index.html
    -> about-us.html
    -> css
        -> main.css
    -> includes
        -> header.html
        -> header-title.html
        -> main-template.html
    
    -> output
        -> css
            -> main.css
        -> about-us.html
        -> index.html

By default, a generated website is copied in the folder "output". You can change Gigo's default behaviour as explained in Configure.

The generated "index.html" page:

<!DOCTYPE html>
<html lang="en">

    <head>
        <meta charset="UTF-8">
        <link rel="stylesheet" type="text/css" href="../css/main.css">
        <title>Gigo in action</title>
    </head>

    <body>
        <h1>Home page</h1>
        <p>Contents of about us home page ...</p>
        <p>Menu: <a href="about-us.html">About us</a></p>
    </body>
</html>

The generated "about-us.html" page:

<!DOCTYPE html>
<html lang="en">

    <head>
        <meta charset="UTF-8">
        <link rel="stylesheet" type="text/css" href="../css/main.css">
        <title>Gigo in action</title>
    </head>

    <body>
        <h1>About us</h1>
        <p>Contents of about-us page ...</p>
        <p>Menu: <a href="index.html">Home</a></p>
    </body>
</html>

It is possible to specify custom configuration file when running gigo, as detailed here.

Additional source code examples are available, please see the websites using Gigo.

13 April 2021