<commit_before>---
layout: post
title: "Static Site Generators: an overview" # any ideas for a better title?
date: 2016-04-20 20:00:00 # to be replaced
comments: true
categories: technical overview
author: <NAME>
author_twitter: virtuacreative
image_title: '/images/blogimages/ssg-overview-gitlab-pages-cover.jpg'
---

What is a Static Site Generator? What is this for? Why should I use one? Do they have limitations? How can I use them with GitLab Pages?

If these questions ring a bell, this post is for you!

We assume you are familiar with web development and you are curious about Static Site Generators.

<!-- more -->

----------

### What's in this overview?

- [Static and Dynamic Websites](#the-web)
   - [A glance at the history](#web-history)
- [Modern Static Site Generators](#ssgs)
   - [Environment](#environment)
   - [Template engine](#template-engine)
   - [Markdown engine](#markdown-engine)
   - [Preprocessors](#preprocessors)
   - [Directory structure](#directory-structure)
   - [SSGs built-in features](#built-in-features)
   - [Blog-Aware SSGs](#blog-aware)
   - [Supported languages and services](#ssg-support)
   - [Limitations](#limitations)
   - [Overcoming the limitations](#overcoming-limitations)
- [Build an SSG site with GitLab Pages](#ssg-gitlab-pages)
- [SSGs examples](#examples)
   - [Environment: Ruby](#ruby)
   - [Environment: Node JS](#node)
   - [Environment: Python](#python)
   - [Environment: Go-lang](#go)
   - [More Examples](#groups)
- [FAQ: which SSG should I get started with?](#which-ssg-get-started)
- [Getting Help](#getting-help)
- [Conclusions](#conclusions)

----

<a name="the-web"></a>

## Static and Dynamic Websites

<a name="web-history"></a>

### A glance at the history

About 25 years ago, in 1990, [<NAME>][tim-bl] [published][first-site-1990] the [first website in history][first-website]. It was a plain [static webpage] with a few tags and links. Three years later, in 1993, the birth of the [dynamic web] took place, when the [Common Gateway Interface (CGI)][wiki-cgi] was [first introduced][first-cgi]. CGI was a way to let a website run scripts on the web server and display the output. From then on, the evolution was huge.

With the advent of processing server-side scripts, came forward the [Web Content Management Systems (WCMS)][wcms], allowing us to create and maintain databases connected to the internet. Websites with such server-side processing, which provide high-level interactivity with the user, are commonly referred as [web applications][web-apps]. Some notable examples are [WordPress], [Joomla!], [Drupal], [Magento], [Ghost] and [many others][cms-list].

Besides connecting your websites with databases, the dynamic web is an important asset to work with [template systems][template-sys]. By using them, developers write fast, update websites faster, and reduce mistakes (provoked by repetition).

Unfortunately, with the growing popularity of server-side based websites, came together their [vulnerabilities][common-vulnerabilities].  [Security issues] are common among them and there are a lot of [measures][security-web-apps] you need to take to prevent attacks of uncountable natures. You need to protect your users, your site and your server. Everything in between is subjected to hackers attacks.

An intelligent counter-measure for avoiding those security threads and, at the same time, maintaining the benefits of templating systems, was the creation of **Static Site Generators (SSGs)**. With them, you write dynamically and publish statically.

SSGs came out on the early 2000's, with [Blosxom] in 2003, and [WebGen] in 2004. In 2008, [<NAME>][tom-pw] released [Jekyll], by far the [most popular SSG][ssgs-list] up to now. The interest for Static Site Generators have increased considerably in the last few years, as you can see at the chart below, from [Google Trends]:

![Static Site Generators - Google Trends](/images/blogimages/ssg-overview-gitlab-pages-google-trends.png)

<a name="ssgs"></a>

## Modern Static Site Generators

The most fascinating thing of any SSG is the ability to code fast, save money (on web hosting), and incredibly increase the page loading time (compared to server-side dynamic webpages). 

The only thing common to all SSGs is the ability to produce (or _build_) static websites automatically. 

The structure of SSGs is a combination of features to make static sites development faster and less repetitive. Let's take a quick look at the list below, then describe them one by one.

- Environment
- Template engine
- Markdown engine
- Preprocessors
- Directory structure

<a name="environment"></a>

### Environment

The **environment**, also called **platform**, consists essentially on the [programming language] the SSG was written in. It will make difference on the configuration, customization, and performance of the SSG. Examples: [Ruby], [Python], [Node JS][node].

<a name="template-engine"></a>

### Template engine

The **template engine** is very important we understand, since all the dynamic structure of our sites will depend on that. It's essential that we choose an SSG with a [templating system][template-sys] that we can use comfortably. Examples: [Liquid] and [Haml] for Ruby, [Twig] for PHP, [Swig] for JavaScript, [Slim] for HTML.

To give you a picture, let's see an example for an HTML file, in which we are using [Liquid Templating Engine][liquid]:

```html
<!DOCTYPE html>
<html lang="en">
	{% include head.html %}
<body>
	{% include header.html %}
	<main class="content">
		{{ content }}
	</main>
	{% include footer.html %}
</body>
</html>
```

_Advantages over flat HMTL_

- Minimize typography errors ("typos"): all files are considerably reduced, improving readability
- Avoid repetition: every block repeated sitewide would be included to every page, equivalently
- Update faster: if you change something in the file `footer.html`, it will affect the entire site

<a name="markdown-engine"></a>

### Markdown engine

The **markdown engine** is a simplified language we'll use to write our content.  Generally, we are allowed to choose which markdown engine we want to use. It is set up on the site configuration. Examples: [Kramdown], [RDiscount], [Redcarpet], [RedCloth].

A blog **post** or a **page** written in [markdown] will most likely start with a **front matter** section containing information about that page or post, and then comes the content just below it. This is an `example.md` file used in a [Jekyll] site, and also an `example.html.md` file for a [Middleman] site:

```markdown
---
# front matter (between three-dashes block)
title: "Hello World" # post or page title
date: YYYY-MM-DD HH:MM:SS # date and time, e.g. "2016-04-30 11:00:00"
author: "<NAME>" # a common variable to exemplify 
---

# An h1 heading

Some text.
```

<a name="preprocessors"></a>

### Preprocessors

The **preprocessors** are made for speed up our development process too. They simplify the way we code, and then compile their own files into standard ones. Examples: [Sass] and [Stylus] for CSS, [CoffeeScript] for JavaScript.

<a name="directory-structure"></a>

### Directory structure

The **directory structure** is different for each SSG. It's important to study the file tree before we start working with an SSG, otherwise we might face odd build errors, that we won't understand solely because we didn't use its structure accordingly. Examples: [Hexo structure][hexo-struc], [Middleman structure][middle-struc], [Jekyll structure][jekyll-struc].

<a name="built-in-features"></a>

### SSGs built-in features

- Most of SSGs have a pre-installed server for previewing the site locally
- Some of them also contain in their installation package a LiveReload plugin, so we don't need to refresh the page every time we save it
- Most of them provide us with built-in compilers for their supported preprocessors

<a name="blog-aware"></a>

### Blog-Aware SSGs

A blog-aware website generator will create blog-style content, such as lists of content in reverse chronological order, archive lists, and other common blog-style features. How would an SSG do that? With its template engine.

All the posts are archived in a specific directory of the project, depending on the SSG directory's structure. With a `for` loop through the posts, they can be displayed in a single page, as illustrated below (with [Liquid]):

```liquid
  <ul>
    {% for post in site.posts %}
      <li>
        <span>{{ post.date }}</span>
        <h2>
          <a class="post-link" href="{{ post.url }}">{{ post.title }}</a>
        </h2>
      </li>
    {% endfor %}
  </ul>
```

This code means that, **for each post** within the **site posts** (`{% for post in site.posts %}`), all of them would be displayed as items of an unordered list of posts. 

Of course, you can adapt the HTML structure according to your needs.

<a name="ssg-support"></a>

### Supported languages and services

Static servers fully support any language or script interpreted by browsers themselves, known as **client-side** processing. Let's just remember that a static site is essentially composed by three components: the structure (HTML), the layout and styles (CSS) and the behavior (JavaScript).

_Supported languages and file extensions_

- Common file extensions: `.html` / `.css` / `.js` / `.xml` / `.pdf` / `.txt`
- Common media files: [images], [audio], [video], [SVG]

_Supported interactive services (examples)_

- Commenting Systems (e.g., [Disqus], [Facebook Comments], and [many others][comment-systems])
- Live Chat (e.g., [JivoChat], [Tawk.to])
- [PayPal Payments Standard]
- [Facebook Social Plugins]
- [Twitter Kit]
- Google Apps (e.g., [Analytics], [Adwords], [AdSense], etc)
- Site Search Engine (e.g., [Google Search][google-cse], [Swiftype], [Tipue])
- Mailing lists and blog subscriptions (e.g., [MailChimp])

We are also free to add [Schema.org] markup to our static sites, making [search engines][schema-seo] to understand our site content better. This is [one of the numerous SEO][seo] techniques.

<a name="limitations"></a>

### Limitations

We've just described what we **can do** with SSGs. Now let's see what we **cannot**.

- Register users
- Have admin access 
- Send emails via `mail()` function
- Use any server-side language or script

<a name="overcoming-limitations"></a>

### Overcoming the limitations

_Users Authentication_

Despite not having the ability to register users nor having admin access for ourselves, with tools like [Firebase] we can power-up our static site with [user authentication][firebase-user-auth]. Find more [cool stuff][firebase-cool-stuff] here, from the same source.

_Contact Forms_

Yes, we can offer contact forms in our static websites. We can't process the **server-side** script in our static-server, but there are some third-party services we can use for that. For example, you can try [Formspree], [FormKeep], [Wufoo], [FoxyForm], [Google Forms] or any other related service . However, if you want to take control over your mail script, you can try the [parse method with SendGrid][sendgrid-parse].

_JavaScript disabled_

Everything based on JavaScript is allowed to be added to your site. However, if JavaScript is disabled on the user's browser, those scripts will not work. But there is something we can do to minimize this issue. We can add a [`<noscript>`][no-script] tag to our web pages, containing a message that will be displayed only if JavaScript disabled:

```html
<noscript>Please enable JavaScript on your browser for a better experience with this website!</noscript>
```

<a name="ssg-gitlab-pages"></a>

## Build an SSG site with GitLab Pages

You can use GitLab Pages to host and build **any** [SSG][ssgs] available! You can also use custom domains, SSL/TLS certificates, create as many sites as you want, and deploy your site from **private repositories**. That's all for free. On the article "[Hosting on GitLab.com with GitLab Pages][post-pages]" you will find this information and a detailed step-by-step to guide you through. See also the [official documentation][pages-ee] and the [quick start guide][pages] for further information.

<a name="examples"></a>

## SSGs examples

On the following tables you can explore some examples of SSGs sites **built with GitLab Pages** and hosted by GitLab.com. 

The key for building your site with GitLab Pages is the GitLab CI configuration file, called `.gitlab-ci.yml`.  If you are not familiar with GitLab Pages, you can follow through [this tutorial][post-pages] before pushing your site to GitLab.

We have gathered some examples for you, organized by their respective environments.

<a name="ruby"></a>

### Environment: [Ruby]

| SSG | Website URL | Project URL | Configuration |
| --- | ----------- | ----------- | -------------- |  
| [Jekyll] | [Default Theme][j-2-web] | [Source on GitLab][j-2-pro] | [Building Jekyll 3.1.2 with Bundler][j-2-ci] |
| [Middleman] | [Default Theme][middle-prev] | [Source on GitLab][middle-proj] | [Default + Bundler `ENV=PRODUCTION`][middle-ci] |
| [Nanoc] | [Default Theme][nanoc-prev] | [Source on GitLab][nanoc-proj] | [Default][nanoc-ci] |
| [Octopress] | [Default Theme][octo-prev] | [Source on GitLab][octo-proj] | [Default][octo-ci] |

<a name="node"></a>

### Environment: [Node JS][node]

| SSG | Website URL | Project URL | Configuration |
| --- | ----------- | ----------- | -------------- |
| [Hexo] | [Hueman Theme][hexo-prev] | [Source on GitLab][hexo-proj] | [Default + `test` job][hexo-ci] |
| [Brunch] | [Default Skeleton][brunch-prev] | [Source on GitLab][brunch-proj] | [Default][brunch-ci] |
| [Harp] | [Default Theme][harp-prev] | [Source on GitLab][harp-proj] | [Default][harp-ci] |
| [Metalsmith] | [Default Theme][metal-prev] | [Source on GitLab][metal-proj] | [Default][metal-ci] |
| [GitBook] | [Default Theme][book-prev] | [Source on GitLab][book-proj] | [Default][book-ci] |

<a name="python"></a>

### Environment: [Python]

| SSG | Website URL | Project URL | Configuration |
| --- | ----------- | ----------- | -------------- |
| [Pelican] | [Default Theme][pelican-prev] | [Source on GitLab][pelican-proj] | [Default][pelican-ci] |
| [Lektor] | [Default Theme][lektor-prev] | [Source on GitLab][lektor-proj] | [Default][lektor-ci] |
| [Hyde] | [Default Theme][hyde-prev] | [Source on GitLab][hyde-proj] | [Default + `test` job][hyde-ci] |

<a name="go"></a>

### Environment: [Go Lang][go]

| SSG | Website URL | Project URL | Configuration |
| --- | ----------- | ----------- | -------------- |
| [Hugo] | [Lanyon Theme][hugo-prev] (Default) | [Source on GitLab][hugo-proj] | [Default][hugo-ci] |

<a name="groups"></a>

### More Examples

On the following GitLab groups you can find even more examples.

| Group | Environment | SSGs |
| ----- | ----------- | ---- |
| [Pages][ci-examples] (Official) | Ruby, Node, Python, etc. | All SSGs presented on this post |
| [Jekyll Themes][jekyll-examples] | Ruby | Jekyll |
| [Middleman Themes][middle-examples] | Ruby | Middleman |
| [Themes and Templates][themes-templates] | Miscellaneous | Miscellaneous |

_**Note:** these themes, templates and SSGs were casually chosen and listed on this post to provide you with some distinct GitLab CI configurations._


<a name="which-ssg-get-started"></a>

## FAQ: which SSG should I get started with?

This is a tricky question. There is no easy answer for it. Perhaps the best way to choose an SSG is installing three or four of them locally and give them a try. [This list][ssgs-more] might help too. 

However, if you don't know where to start and you never used any Static Site Generator before, I suggest you to get started with **Jekyll**. Why?

- It's very well documented
- If you search the web for information you'll find plenty
- Its template engine is rigid. Meaning, there's no chance to mess up the code
- It is easy to learn

But this was merely a suggestion. There are better ways to choose. For example, if you are a programmer, you could choose the SSG according to the language it's written in (Ruby, Node JS, Python, etc), picking up one you're familiar with. If you are a PHP developer, you might want to choose an SSG with a PHP template engine. And so on.

<a name="getting-help"></a>

## Getting Help

If you need some help regarding GitLab Pages on GitLab.com,
feel free to use one of [our channels][get-help]. You can also open an issue on the [Pages][pages-issues] group.

<a name="conclusions"></a>

## Conclusions

<!-- TO BE IMPROVED -->

Hopefully, we got you inspired to start working with Static Site Generators and you comprehend what they are and how do they work. 

If you already work with an SSG, please [let us know][CTA] which one you prefer. It's a quick survey that will only take a minute, and your participation means a lot to us!

<!-- REVIEWER: PLEASE CHECK THIS GOOGLE FORM! IF WE DECIDE TO USE IT, I WILL NEED TO ADD SOMEONE FROM GITLAB AS COLLABORATOR -->

You are invited to contribute with new SSGs, or with your cool themes and templates, to the [groups](#groups) mentioned earlier.

Don't you have an account on [GitLab.com][sign-up] yet? Let's create one! Remember, we can use GitLab Pages to [build any SSG][post-pages] for us and host it for free!

Follow [@GitLab][twitter] on Twitter and stay tuned for updates!

## About guest author <NAME>

[Marcia] is a back-end developer specialized in WordPress and Jekyll sites at [Virtua Creative],
though she does some front-end too. Her daily work is based on version-controlled systems for almost 15 years.  She is also an experienced technical writer.

<!-- Cover image: https://unsplash.com/photos/6g0KJWnBhxg -->

<!-- IDENTIFIERS --> 

<!-- Alphabetical, miscellaneous -->

[AdSense]: https://support.google.com/adsense/answer/181950
[Adwords]: https://support.google.com/adwords/answer/6331314
[Analytics]: https://developers.google.com/analytics/devguides/collection/analyticsjs/
[audio]: http://www.w3schools.com/html/html5_audio.asp
[cms-list]:  https://en.wikipedia.org/wiki/List_of_content_management_systems
[comment-systems]: http://brianshim.com/webtricks/add-a-comment-wall-to-your-website/
[common-vulnerabilities]:  https://www.toptal.com/security/10-most-common-web-security-vulnerabilities<commit_msg>splitting lines - facilitate reviews<commit_after>---
layout: post
title: "Static Site Generators: an overview" # any ideas for a better title?
date: 2016-04-20 20:00:00 # to be replaced
comments: true
categories: technical overview
author: <NAME>
author_twitter: virtuacreative
image_title: '/images/blogimages/ssg-overview-gitlab-pages-cover.jpg'
---

What is a Static Site Generator? What is this for? Why should I use one? 
Do they have limitations? How can I use them with GitLab Pages?

If these questions ring a bell, this post is for you!

We assume you are familiar with web development and you are curious about 
Static Site Generators.

<!-- more -->

----------

### What's in this overview?

- [Static and Dynamic Websites](#the-web)
   - [A glance at the history](#web-history)
- [Modern Static Site Generators](#ssgs)
   - [Environment](#environment)
   - [Template engine](#template-engine)
   - [Markdown engine](#markdown-engine)
   - [Preprocessors](#preprocessors)
   - [Directory structure](#directory-structure)
   - [SSGs built-in features](#built-in-features)
   - [Blog-Aware SSGs](#blog-aware)
   - [Supported languages and services](#ssg-support)
   - [Limitations](#limitations)
   - [Overcoming the limitations](#overcoming-limitations)
- [Build an SSG site with GitLab Pages](#ssg-gitlab-pages)
- [SSGs examples](#examples)
   - [Environment: Ruby](#ruby)
   - [Environment: Node JS](#node)
   - [Environment: Python](#python)
   - [Environment: Go-lang](#go)
   - [More Examples](#groups)
- [FAQ: which SSG should I get started with?](#which-ssg-get-started)
- [Getting Help](#getting-help)
- [Conclusions](#conclusions)

----

<a name="the-web"></a>

## Static and Dynamic Websites

<a name="web-history"></a>

### A glance at the history

About 25 years ago, in 1990, [<NAME>][tim-bl] [published][first-site-1990] 
the [first website in history][first-website]. It was a plain [static webpage] 
with a few tags and links. Three years later, in 1993, the birth of the [dynamic web] 
took place, when the [Common Gateway Interface (CGI)][wiki-cgi] was [first introduced][first-cgi]. 
CGI was a way to let a website run scripts on the web server and display the output. 
From then on, the evolution was huge.

With the advent of processing server-side scripts, 
came forward the [Web Content Management Systems (WCMS)][wcms], allowing us to 
create and maintain databases connected to the internet. Websites with such server-side processing, 
which provide high-level interactivity with the user, are commonly referred as [web applications][web-apps]. 
Some notable examples are [WordPress], [Joomla!], [Drupal], [Magento], [Ghost] and [many others][cms-list].

Besides connecting your websites with databases, the dynamic web is an important 
asset to work with [template systems][template-sys]. By using them, developers write fast, update websites faster, 
and reduce mistakes (provoked by repetition).

Unfortunately, with the growing popularity of server-side based websites, came together 
their [vulnerabilities][common-vulnerabilities].  [Security issues] are common among them 
and there are a lot of [measures][security-web-apps] you need to take to prevent attacks of uncountable natures. 
You need to protect your users, your site and your server. Everything in between is subjected to hackers attacks.

An intelligent counter-measure for avoiding those security threads and, at the same time, 
maintaining the benefits of templating systems, was the creation of **Static Site Generators (SSGs)**. 
With them, you write dynamically and publish statically.

SSGs came out on the early 2000's, with [Blosxom] in 2003, and [WebGen] in 2004. 
In 2008, [<NAME>][tom-pw] released [Jekyll], by far the [most popular SSG][ssgs-list] up to now. 
The interest for Static Site Generators have increased considerably in the last few years, as you can see at 
the chart below, from [Google Trends]:

![Static Site Generators - Google Trends](/images/blogimages/ssg-overview-gitlab-pages-google-trends.png)

<a name="ssgs"></a>

## Modern Static Site Generators

The most fascinating thing of any SSG is the ability to code fast, save money (on web hosting), 
and incredibly increase the page loading time (compared to server-side dynamic webpages). 

The only thing common to all SSGs is the ability to produce (or _build_) static websites automatically. 

The structure of SSGs is a combination of features to make static sites development faster 
and less repetitive. Let's take a quick look at the list below, then describe them one by one.

- Environment
- Template engine
- Markdown engine
- Preprocessors
- Directory structure

<a name="environment"></a>

### Environment

The **environment**, also called **platform**, consists essentially on the [programming language] 
the SSG was written in. It will make difference on the configuration, customization, and performance of the SSG. 
Examples: [Ruby], [Python], [Node JS][node].

<a name="template-engine"></a>

### Template engine

The **template engine** is very important we understand, since all the dynamic 
structure of our sites will depend on that. It's essential that we choose an SSG 
with a [templating system][template-sys] that we can use comfortably. 
Examples: [Liquid] and [Haml] for Ruby, [Twig] for PHP, [Swig] for JavaScript, [Slim] for HTML.

To give you a picture, let's see an example for an HTML file, in which we are 
using [Liquid Templating Engine][liquid]:

```html
<!DOCTYPE html>
<html lang="en">
	{% include head.html %}
<body>
	{% include header.html %}
	<main class="content">
		{{ content }}
	</main>
	{% include footer.html %}
</body>
</html>
```

_Advantages over flat HMTL_

- Minimize typography errors ("typos"): all files are considerably reduced, improving readability
- Avoid repetition: every block repeated sitewide would be included to every page, equivalently
- Update faster: if you change something in the file `footer.html`, it will affect the entire site

<a name="markdown-engine"></a>

### Markdown engine

The **markdown engine** is a simplified language we'll use to write our content.  
Generally, we are allowed to choose which markdown engine we want to use. 
It is set up on the site configuration. Examples: [Kramdown], [RDiscount], [Redcarpet], [RedCloth].

A blog **post** or a **page** written in [markdown] will most likely start with a **front matter** 
section containing information about that page or post, and then comes the content just below it. 
This is an `example.md` file used in a [Jekyll] site, and also an `example.html.md` file for a [Middleman] site:

```markdown
---
# front matter (between three-dashes block)
title: "Hello World" # post or page title
date: YYYY-MM-DD HH:MM:SS # date and time, e.g. "2016-04-30 11:00:00"
author: "<NAME>" # a common variable to exemplify 
---

# An h1 heading

Some text.
```

<a name="preprocessors"></a>

### Preprocessors

The **preprocessors** are made for speed up our development process too. They simplify 
the way we code, and then compile their own files into standard ones. 
Examples: [Sass] and [Stylus] for CSS, [CoffeeScript] for JavaScript.

<a name="directory-structure"></a>

### Directory structure

The **directory structure** is different for each SSG. It's important to study the 
file tree before we start working with an SSG, otherwise we might face odd build errors, 
that we won't understand solely because we didn't use its structure accordingly. 
Examples: [Hexo structure][hexo-struc], [Middleman structure][middle-struc], [Jekyll structure][jekyll-struc].

<a name="built-in-features"></a>

### SSGs built-in features

- Most of SSGs have a pre-installed server for previewing the site locally
- Some of them also contain in their installation package a LiveReload plugin, 
so we don't need to refresh the page every time we save it
- Most of them provide us with built-in compilers for their supported preprocessors

<a name="blog-aware"></a>

### Blog-Aware SSGs

A blog-aware website generator will create blog-style content, such as lists of 
content in reverse chronological order, archive lists, and other common blog-style features. 
How would an SSG do that? With its template engine.

All the posts are archived in a specific directory of the project, depending on the 
SSG directory's structure. With a `for` loop through the posts, they can be 
displayed in a single page, as illustrated below (with [Liquid]):

```liquid
  <ul>
    {% for post in site.posts %}
      <li>
        <span>{{ post.date }}</span>
        <h2>
          <a class="post-link" href="{{ post.url }}">{{ post.title }}</a>
        </h2>
      </li>
    {% endfor %}
  </ul>
```

This code means that, **for each post** within the **site posts** (`{% for post in site.posts %}`), 
all of them would be displayed as items of an unordered list of posts. 

Of course, you can adapt the HTML structure according to your needs.

<a name="ssg-support"></a>

### Supported languages and services

Static servers fully support any language or script interpreted by browsers, 
known as **client-side** processing. Let's just remember that a static site is 
essentially composed by three components: the structure (HTML), 
the layout and styles (CSS) and the behavior (JavaScript).

_Supported languages and file extensions_

- Common file extensions: `.html` / `.css` / `.js` / `.xml` / `.pdf` / `.txt`
- Common media files: [images], [audio], [video], [SVG]

_Supported interactive services (examples)_

- Commenting Systems (e.g., [Disqus], [Facebook Comments], and [many others][comment-systems])
- Live Chat (e.g., [JivoChat], [Tawk.to])
- [PayPal Payments Standard]
- [Facebook Social Plugins]
- [Twitter Kit]
- Google Apps (e.g., [Analytics], [Adwords], [AdSense], etc)
- Site Search Engine (e.g., [Google Search][google-cse], [Swiftype], [Tipue])
- Mailing lists and blog subscriptions (e.g., [MailChimp])

We are also free to add [Schema.org] markup to our static sites, 
making [search engines][schema-seo] to understand our site content better. 
This is [one of the numerous SEO][seo] techniques.

<a name="limitations"></a>

### Limitations

We've just described what we **can do** with SSGs. Now let's see what we **cannot**.

- Register users
- Have admin access 
- Send emails via `mail()` function
- Use any server-side language or script

<a name="overcoming-limitations"></a>

### Overcoming the limitations

_Users Authentication_

Despite not having the ability to register users nor having admin access for 
ourselves, with tools like [Firebase] we can power-up our static 
site with [user authentication][firebase-user-auth]. Find more [cool stuff][firebase-cool-stuff] here, from the same source.

_Contact Forms_

Yes, we can offer contact forms in our static websites. We can't process the **server-side** 
script in our static-server, but there are some third-party services we can use for that. 
For example, you can try [Formspree], [FormKeep], [Wufoo], [FoxyForm], [Google Forms] or any 
other related service . However, if you want to take control over your mail script, 
you can try the [parse method with SendGrid][sendgrid-parse].

_JavaScript disabled_

Everything based on JavaScript is allowed to be added to your site. However, if 
JavaScript is disabled on the user's browser, those scripts will not work. But there is 
something we can do to minimize this issue. We can add a [`<noscript>`][no-script] tag 
to our web pages, containing a message that will be displayed only if JavaScript disabled:

```html
<noscript>Please enable JavaScript on your browser for a better experience with this website!</noscript>
```

<a name="ssg-gitlab-pages"></a>

## Build an SSG site with GitLab Pages

You can use GitLab Pages to host and build **any** [SSG][ssgs] available! 
You can also use custom domains, SSL/TLS certificates, create as many sites as you want, 
and deploy your site from **private repositories**. That's all for free. 
On the article "[Hosting on GitLab.com with GitLab Pages][post-pages]" you will 
find this information and a detailed step-by-step to guide you through. 
See also the [official documentation][pages-ee] and the [quick start guide][pages] for further information.

<a name="examples"></a>

## SSGs examples

On the following tables you can explore some examples of SSGs sites **built with 
GitLab Pages** and hosted by GitLab.com. 

The key for building your site with GitLab Pages is the GitLab CI configuration 
file, called `.gitlab-ci.yml`.  If you are not familiar with GitLab Pages, you can 
follow through [this tutorial][post-pages] before pushing your site to GitLab.

We have gathered some examples for you, organized by their respective environments.

<a name="ruby"></a>

### Environment: [Ruby]

| SSG | Website URL | Project URL | Configuration |
| --- | ----------- | ----------- | -------------- |  
| [Jekyll] | [Default Theme][j-2-web] | [Source on GitLab][j-2-pro] | [Building Jekyll 3.1.2 with Bundler][j-2-ci] |
| [Middleman] | [Default Theme][middle-prev] | [Source on GitLab][middle-proj] | [Default + Bundler `ENV=PRODUCTION`][middle-ci] |
| [Nanoc] | [Default Theme][nanoc-prev] | [Source on GitLab][nanoc-proj] | [Default][nanoc-ci] |
| [Octopress] | [Default Theme][octo-prev] | [Source on GitLab][octo-proj] | [Default][octo-ci] |

<a name="node"></a>

### Environment: [Node JS][node]

| SSG | Website URL | Project URL | Configuration |
| --- | ----------- | ----------- | -------------- |
| [Hexo] | [Hueman Theme][hexo-prev] | [Source on GitLab][hexo-proj] | [Default + `test` job][hexo-ci] |
| [Brunch] | [Default Skeleton][brunch-prev] | [Source on GitLab][brunch-proj] | [Default][brunch-ci] |
| [Harp] | [Default Theme][harp-prev] | [Source on GitLab][harp-proj] | [Default][harp-ci] |
| [Metalsmith] | [Default Theme][metal-prev] | [Source on GitLab][metal-proj] | [Default][metal-ci] |
| [GitBook] | [Default Theme][book-prev] | [Source on GitLab][book-proj] | [Default][book-ci] |

<a name="python"></a>

### Environment: [Python]

| SSG | Website URL | Project URL | Configuration |
| --- | ----------- | ----------- | -------------- |
| [Pelican] | [Default Theme][pelican-prev] | [Source on GitLab][pelican-proj] | [Default][pelican-ci] |
| [Lektor] | [Default Theme][lektor-prev] | [Source on GitLab][lektor-proj] | [Default][lektor-ci] |
| [Hyde] | [Default Theme][hyde-prev] | [Source on GitLab][hyde-proj] | [Default + `test` job][hyde-ci] |

<a name="go"></a>

### Environment: [Go Lang][go]

| SSG | Website URL | Project URL | Configuration |
| --- | ----------- | ----------- | -------------- |
| [Hugo] | [Lanyon Theme][hugo-prev] (Default) | [Source on GitLab][hugo-proj] | [Default][hugo-ci] |

<a name="groups"></a>

### More Examples

On the following GitLab groups you can find even more examples.

| Group | Environment | SSGs |
| ----- | ----------- | ---- |
| [Pages][ci-examples] (Official) | Ruby, Node, Python, etc. | All SSGs presented on this post |
| [Jekyll Themes][jekyll-examples] | Ruby | Jekyll |
| [Middleman Themes][middle-examples] | Ruby | Middleman |
| [Themes and Templates][themes-templates] | Miscellaneous | Miscellaneous |

_**Note:** these themes, templates and SSGs were casually chosen and listed on 
this post to provide you with some distinct GitLab CI configurations._


<a name="which-ssg-get-started"></a>

## FAQ: which SSG should I get started with?

This is a tricky question. There is no easy answer for it. Perhaps the best way 
to choose an SSG is installing three or four of them locally and give them a try. [This list][ssgs-more] might help too. 

However, if you don't know where to start and you never used any Static Site Generator 
before, I suggest you to get started with **Jekyll**. Why?

- It's very well documented
- If you search the web for information you'll find plenty
- Its template engine is rigid. Meaning, there's no chance to mess up the code
- It is easy to learn

But this was merely a suggestion. There are better ways to choose. For example, 
if you are a programmer, you could choose the SSG according to the language it's 
written in (Ruby, Node JS, Python, etc), picking up one you're familiar with. 
If you are a PHP developer, you might want to choose an SSG with a PHP template engine. And so on.

<a name="getting-help"></a>

## Getting Help

If you need some help regarding GitLab Pages on GitLab.com,
feel free to use one of [our channels][get-help]. You can also 
open an issue on the [Pages][pages-issues] group.

<a name="conclusions"></a>

## Conclusions

<!-- TO BE IMPROVED -->

Hopefully, we got you inspired to start working with Static Site 
Generators and you comprehend what they are and how do they work. 

If you already work with an SSG, please [let us know][CTA] which one you prefer. 
It's a quick survey that will only take a minute, and your participation means a lot to us!

<!-- REVIEWER: PLEASE CHECK THIS GOOGLE FORM! IF WE DECIDE TO USE IT, I WILL NEED TO ADD SOMEONE FROM GITLAB AS COLLABORATOR -->

You are invited to contribute with new SSGs, or with your cool themes and 
templates, to the [groups](#groups) mentioned earlier.

Don't you have an account on [GitLab.com][sign-up] yet? Let's create one! 
Remember, we can use GitLab Pages to [build any SSG][post-pages] for us and host it for free!

Follow [@GitLab][twitter] on Twitter and stay tuned for updates!

## About guest author <NAME>

[Marcia] is a back-end developer specialized in WordPress and Jekyll sites at [Virtua Creative],
though she does some front-end too. Her daily work is based on version-controlled 
systems for almost 15 years.  She is also an experienced technical writer.

<!-- Cover image: https://unsplash.com/photos/6g0KJWnBhxg -->

<!-- IDENTIFIERS --> 

<!-- Alphabetical, miscellaneous -->

[AdSense]: https://support.google.com/adsense/answer/181950
[Adwords]: https://support.google.com/adwords/answer/6331314
[Analytics]: https://developers.google.com/analytics/devguides/collection/analyticsjs/
[audio]: http://www.w3schools.com/html/html5_audio.asp
[cms-list]:  https://en.wikipedia.org/wiki/List_of_content_management_systems
[comment-systems]: http://brianshim.com/webtricks/add-a-comment-wall-to-your-website/
[common-vulnerabilities]:  https://www.toptal.com/security/10-most-common-web-security-vulnerabilities
{'fraction_non_alphanumeric': 0.12265492534048023, 'fraction_numerical': 0.004813214461521632, 'mean_word_length': 4.148106433901169, 'pattern_counts': {'":': 0, '<': 157, '<?xml version=': 0, '>': 157, 'https://': 12, 'lorem ipsum': 0, 'www.': 4, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6343032', 'n_tokens_mistral': 11210, 'n_tokens_neox': 10459, 'n_words': 4589}