<commit_before>---
layout: post
title: "SSGs Part 3: Build any SSG site with GitLab Pages"
date: 2016-06-17
comments: true
categories: technical overview
author: <NAME>
author_twitter: virtuacreative
image_title: '/images/blogimages/ssg-gitlab-pages-series/ssg-overview-gitlab-pages-part-3-cover.jpg'
---

Which **Static Site Generators** (SSGs) can I use with **GitLab Pages**? How to setup GitLab CI to build my SSG site? Where can I find some examples?

If these questions ring a bell, this **series of posts** is for you! We prepared three articles around the same theme "**Static Site Generators (SSGs)**".

This is **Part 3: Build any SSG site with GitLab Pages**, where we'll show you some examples of SSGs using distinct GitLab CI configurations, so you can understand it and adjust it to your needs.

Read through the previous posts:

- [**Part 1: Dynamic vs Static Websites**][part-1]
- [**Part 2: Modern Static Site Generators**][part-2]

**Note:** For this series, we assume you are familiar with web development, curious about Static Site Generators, and excited to see your site getting deployed with GitLab Pages.
{: .note}

<!-- more -->

----------

### What's in this page?
{:.no_toc}

- TOC
{: toc}

----

## Build any SSG site with GitLab Pages

Along the previous articles of this series on Static Site Generators, we explained the difference between [static and dynamic websites][part-1], and provided a general [overview on Modern SSGs][part-2]. Now let's understand how can we use them with [GitLab Pages][pages].

You can use [GitLab Pages][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**. And that's all **for free**!
If you are not familiar with GitLab Pages, you might want to read the article "[Hosting on GitLab.com with GitLab Pages][post-pages]", where you will find this information and a detailed step-by-step guide to walk you through the process.
See also the [quick start guide][pages] and the [official documentation][pages-ee] for further information.

## SSGs examples

On the following tables you can explore some examples of SSGs sites **built with
GitLab Pages** and hosted by GitLab. Some of them came from contributions from our community. We'll be very happy to have your [contribution] too!

The key for building your site with GitLab Pages is the GitLab CI configuration
file, called `.gitlab-ci.yml`.

In order to make GitLab CI work for this specific purpose is creating a job called `pages`, and generate your compiled site to a `public` folder. Everything else is adjustable to our needs.

On the tables below, there are some examples we've gathered for you, organized by their respective environments.

### 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] |

### 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] |

### 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] |
| [Nikola] | [Default Theme][nikola-prev] | [Source on GitLab][nikola-proj] | [Default][nikola-ci] |

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

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

### More Examples
{: #groups}

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.
{: .note}

## 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.

## 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.

## Conclusion

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

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

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!

<!-- Cover photo: https://unsplash.com/photos/bphc6kyobMg -->

<!-- IDENTIFIERS -->

<!-- SSGs series -->

[part-1]: /2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/
[part-2]: /2016/06/10/ssg-overview-gitlab-pages-part-2/

<!-- GitLab -->

[CTA]: https://docs.google.com/forms/d/1I_0PFB7MFm140hoFro-SfeMpU-VS71QmMfO8_4fj2pM/viewform

[about-gitlab-com]: https://about.gitlab.com/
[contributions]: https://gitlab.com/pages/pages.gitlab.io/blob/master/CONTRIBUTING.md
[get-help]: https://about.gitlab.com/getting-help
[gitlab-com]: https://about.gitlab.com/gitlab-com/
[pages]: https://pages.gitlab.io
[pages-ee]: http://doc.gitlab.com/ee/pages/README.html
[pages-issues]: https://gitlab.com/pages/pages.gitlab.io/issues
[post-pages]: https://about.gitlab.com/2016/04/07/gitlab-pages-setup/
[sign-up]: https://gitlab.com/users/sign_in "Sign Up!"
[twitter]: https://twitter.com/gitlab

<!-- SSGs -->

[blosxom]: http://blosxom.sourceforge.net/
[Brunch]: http://brunch.io/
[GitBook]: https://www.gitbook.com/
[Harp]: http://harpjs.com/
[Hexo]: https://hexo.io/
[Hyde]: http://hyde.github.io/
[Hugo]: https://gohugo.io/
[Jekyll]: https://jekyllrb.com
[Lektor]: https://www.getlektor.com/
[Metalsmith]: http://www.metalsmith.io/
[Middleman]: https://middlemanapp.com/
[Nanoc]: http://nanoc.ws/
[Nikola]: https://getnikola.com/
[Octopress]: http://octopress.org/
[Pelican]: http://blog.getpelican.com/

[hexo-struc]: https://hexo.io/docs/setup.html
[jekyll-struc]: https://jekyllrb.com/docs/structure/
[middle-struc]: https://middlemanapp.com/basics/directory-structure/
<commit_msg>axil's review and a few minor details<commit_after>---
layout: post
title: "SSGs Part 3: Build any SSG site with GitLab Pages"
date: 2016-06-17
comments: true
categories: technical overview
author: <NAME>
author_twitter: virtuacreative
image_title: '/images/blogimages/ssg-gitlab-pages-series/ssg-overview-gitlab-pages-part-3-cover.jpg'
---

Which **Static Site Generators** (SSGs) can I use with **GitLab Pages**? How to setup GitLab CI to build
my SSG site? Where can I find some examples?

If these questions ring a bell, this **series of posts** is for you! We prepared three articles around
the same theme "**Static Site Generators (SSGs)**".

This is **Part 3: Build any SSG site with GitLab Pages**, where we'll show you some examples of SSGs
using distinct GitLab CI configurations, so you can understand it and adjust it to your needs.

Read through the previous posts:

- [**Part 1: Dynamic vs Static Websites**][part-1]
- [**Part 2: Modern Static Site Generators**][part-2]

**Note:** For this series, we assume you are familiar with web development, curious about Static Site Generators,
and excited to see your site getting deployed with GitLab Pages.
{: .note}

<!-- more -->

----------

### What's in this page?
{:.no_toc}

- TOC
{: toc}

----

## Build any SSG site with GitLab Pages

In the previous articles of this series on Static Site Generators, we explained the difference between
[static and dynamic websites][part-1], and provided a general [overview on Modern SSGs][part-2]. Now let's
understand how can we use them with [GitLab Pages][pages].

You can use [GitLab Pages][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**. And that's all **for free** on GitLab.com!
If you are not familiar with GitLab Pages, you might want to read the article "[Hosting on GitLab.com with GitLab Pages][post-pages]",
where you will find this information and a detailed step-by-step guide to walk you through the process.
See also the [quick start guide][pages] and the [official documentation][pages-ee] for further information.

## SSGs examples

On the following tables you can explore some examples of SSGs sites **built with
GitLab Pages** and hosted on GitLab.com. Some of them came from contributions from our community.
We'll be very happy to have [your contribution] too!

The key for [building your site with GitLab Pages][ci-for-pages] is the GitLab CI configuration
file, called `.gitlab-ci.yml`.

To make GitLab CI work for this specific purpose is necessary creating a job called `pages`, and generate your
compiled site to a `public` folder. Everything else is adjustable to your needs.

On the tables below, there are some examples we've gathered for you, organized by their respective environments.

### 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] |

### 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] |

### 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] |
| [Nikola] | [Default Theme][nikola-prev] | [Source on GitLab][nikola-proj] | [Default][nikola-ci] |

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

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

### More Examples
{: #groups}

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.
{: .note}

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

This is a tricky question, and 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, JavaScript, 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.

## 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.

## Conclusion

<!-- TO BE IMPROVED -->

With this post we end up this series on SSGs. Hopefully, we got you inspired to start working with Static Site
Generators, and by now you comprehend what they are and how 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!

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

You are more than welcome 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 on GitLab.com!

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

<!-- Cover photo: https://unsplash.com/photos/bphc6kyobMg -->

<!-- IDENTIFIERS -->

<!-- SSGs series -->

[part-1]: /2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/
[part-2]: /2016/06/10/ssg-overview-gitlab-pages-part-2/

<!-- GitLab -->

[CTA]: https://docs.google.com/forms/d/1I_0PFB7MFm140hoFro-SfeMpU-VS71QmMfO8_4fj2pM/viewform

[about-gitlab-com]: https://about.gitlab.com/
[ci-for-pages]: https://about.gitlab.com/2016/04/07/gitlab-pages-setup/#gitlab-ci
[your contribution]: https://gitlab.com/pages/pages.gitlab.io/blob/master/CONTRIBUTING.md
[get-help]: https://about.gitlab.com/getting-help
[gitlab-com]: https://about.gitlab.com/gitlab-com/
[pages]: https://pages.gitlab.io
[pages-ee]: http://doc.gitlab.com/ee/pages/README.html
[pages-issues]: https://gitlab.com/pages/pages.gitlab.io/issues
[post-pages]: https://about.gitlab.com/2016/04/07/gitlab-pages-setup/
[sign-up]: https://gitlab.com/users/sign_in "Sign Up!"
[twitter]: https://twitter.com/gitlab

<!-- SSGs -->

[blosxom]: http://blosxom.sourceforge.net/
[Brunch]: http://brunch.io/
[GitBook]: https://www.gitbook.com/
[Harp]: http://harpjs.com/
[Hexo]: https://hexo.io/
[Hyde]: http://hyde.github.io/
[Hugo]: https://gohugo.io/
[Jekyll]: https://jekyllrb.com
[Lektor]: https://www.getlektor.com/
[Metalsmith]: http://www.metalsmith.io/
[Middleman]: https://middlemanapp.com/
[Nanoc]: http://nanoc.ws/
[Nikola]: https://getnikola.com/
[Octopress]: http://octopress.org/
[Pelican]: http://blog.getpelican.com/

[hexo-struc]: https://hexo.io/docs/setup.html
[jekyll-struc]: https://jekyllrb.com/docs/structure/
[middle-struc]: https://middlemanapp.com/basics/directory-structure/

{'fraction_non_alphanumeric': 0.15356217973442063, 'fraction_numerical': 0.0073833269050636394, 'mean_word_length': 3.851643945469126, 'pattern_counts': {'":': 0, '<': 21, '<?xml version=': 0, '>': 21, 'https://': 43, 'lorem ipsum': 0, 'www.': 6, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6650092', 'n_tokens_mistral': 6124, 'n_tokens_neox': 5693, 'n_words': 2087}