Commit 6f37c179 authored by Jacek Lebioda's avatar Jacek Lebioda
Browse files

Merge remote-tracking branch 'origin/master'

# Conflicts:
#	index.md
parents e3735af4 9ffe74eb
Pipeline #8875 passed with stage
in 1 minute and 12 seconds
![Build Status](https://gitlab.com/pages/jekyll/badges/master/build.svg) # Gitlab pages
Welcome to an example page!
--- Below you will find a detailed instruction on how to set-up your own gitlab website.
For a better view, please go to the following website: [https://core-services.pages.uni.lu/pages-jekyll-lcsb-template/](https://core-services.pages.uni.lu/pages-jekyll-lcsb-template/)
Example [Jekyll] website using GitLab Pages. View it live at https://pages.gitlab.io/jekyll
Sources for this page are [available in Gitlab](https://git-r3lab.uni.lu/core-services/pages-jekyll-lcsb-template).
[Learn more about GitLab Pages](https://pages.gitlab.io) or read the the [official GitLab Pages documentation](https://docs.gitlab.com/ce/user/project/pages/). Additionally, you can also navigate to the [repository for theme](https://git-r3lab.uni.lu/core-services/jekyll-theme-lcsb-default).
--- # Setting up your web page
<!-- START doctoc generated TOC please keep comment here to allow auto update --> ## The process
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> 0. Make sure that you have access to [gitlab](https://git-r3lab.uni.lu/). If you ever cloned a repository or set-up a new one there, then you should be fine.
**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* 1. [Create an empty repository in gitlab](https://git-r3lab.uni.lu/projects/new). Please bear in mind, that the both names of the namespace and the project influence
final address of the page - it will follow the `https://<namespace>.pages.uni.lu/<project_name>` convention.
- [Getting Started](#getting-started) 2. Clone this very repository: `git clone ssh://git@git-r3lab-server.uni.lu:8022/core-services/pages-jekyll-lcsb-template.git`.
- [Start by forking this repository](#start-by-forking-this-repository) 3. Once cloned, remove the _remote_ (so that every time you push to your repository, you don't push to this very repository):
- [Start from a local Jekyll project](#start-from-a-local-jekyll-project) `cd project_name; git remote rm origin`, and add _remote_ to your new repository (you can find the correct remote address and the appropriate command in Gitlab, in your new repository page) **TODO: add screenshot**.
- [GitLab CI](#gitlab-ci) 4. Modify site's settings (`_config.yml`) to match your needs. Refer to the next section for help.
- [Using Jekyll locally](#using-jekyll-locally) 5. Modify the index page. Modify (or delete) help and about pages. Add your own content.
- [GitLab User or Group Pages](#gitlab-user-or-group-pages) 6. Commit and push to the repository.
- [Did you fork this project?](#did-you-fork-this-project) 7. If you want to have your page publicly available, make a ticket to SIU.
- [Other examples](#other-examples) 8. Your page is published! Go to `https://<namespace>.pages.uni.lu/name-of-repository` in your favourite browser, or the URL you specified in the SIU ticket.
- [Troubleshooting](#troubleshooting) 9. (optional) In gitlab, go to **Settings** (under left-hand menu) > **General** > **Advanced** (hit `Expand` button) > **Remove fork relationship** (red button), then follow the instructions from the pop-up.
<!-- END doctoc generated TOC please keep comment here to allow auto update --> ## What should you change in settings file?
Mandatory:
## Getting Started * `baseurl` - this is very important. Set it to the name of the project (i.e. repository name). Here it's `pages-jekyll-lcsb-template`
* `url` - this is equally important. Please set it to `https://gitlab-namespace-name.pages.uni.lu`. For example - if your project is inside `core-services` namespace, it should be: `url: "https://core-services.pages.uni.lu"`. For `minerva`, it would be: `url: "https://minerva.pages.uni.lu"`.
You can get started with GitLab Pages using Jekyll easily by either forking this repository or by uploading a new/existing Jekyll project.
Optional:
Remember you need to wait for your site to build before you will be able to see your changes. You can track the build on the **Pipelines** tab. * `title` field
* `e-mail` field
### Start by forking this repository * `description` field
* `date` field
1. Fork this repository. * `banner` field - if you want to have your own banner (the text next to _uni.lu_ logo), please send us an email (`lcsb-sysadmins (at) uni.lu`).
1. **IMPORTANT:** Remove the fork relationship.
Go to **Settings (⚙)** > **Edit Project** and click the **"Remove fork relationship"** button. ## Testing the web page locally
1. Enable Shared Runners. You can test your website locally (on your machine).
Go to **Settings (⚙)** > **Pipelines** and click the **"Enable shared Runners"** button.
1. Rename the repository to match the name you want for your site. * First, make sure that you have Ruby installed. If not - please [install it](https://www.ruby-lang.org/en/downloads/).
1. Edit your website through GitLab or clone the repository and push your changes. * Then, install _bundler_ - `gem install bundler`.
* Next, initialize the site: `bundle install`.
### Start from a local Jekyll project * Finally, run the site: `bundle exec jekyll serve`.
1. [Install][] Jekyll.
1. Use `jekyll new` to create a new Jekyll Project. ## Common problems
1. Add [this `.gitlab-ci.yml`](.gitlab-ci.yml) to the root of your project. ### *The website looks broken! There are no images, no colors etc.*
1. Push your repository and changes to GitLab. You probably didn't configure `baseurl` parameter in the settings. Please take a look on `_settings.yml` file.
## GitLab CI ### *The links in the menu are not working (they point to "404: Not found").*
You probably didn't add `permalink` attribute. Or the post has `published: false` or `draft: true` set. Please take a look on the post file.
This project's static Pages are built by [GitLab CI][ci], following the steps
defined in [`.gitlab-ci.yml`](.gitlab-ci.yml): ### Other problems?
Please send us an email! (`lcsb-sysadmins (at) uni.lu`)
``` \ No newline at end of file
image: ruby:2.5
variables:
JEKYLL_ENV: production
pages:
script:
- bundle install
- bundle exec jekyll build -d public
artifacts:
paths:
- public
only:
- master
```
## Configuration
You have some variables that you need to override in the `_config.yaml` file.
## Using Jekyll locally
To work locally with this project, you'll have to follow the steps below:
1. Fork, clone or download this project
1. [Install][] Jekyll
1. Download dependencies: `bundle`
1. Build and preview: `bundle exec jekyll serve`
1. Add content
The above commands should be executed from the root directory of this project.
Read more at Jekyll's [documentation][].
## GitLab User or Group Pages
To use this project as your user/group website, you will need one additional
step: just rename your project to `namespace.gitlab.io`, where `namespace` is
your `username` or `groupname`. This can be done by navigating to your
project's **Settings**.
Read more about [user/group Pages][userpages] and [project Pages][projpages].
## Did you fork this project?
If you forked this project for your own use, please go to your project's
**Settings** and remove the forking relationship, which won't be necessary
unless you want to contribute back to the upstream project.
## Other examples
* [jekyll-branched](https://gitlab.com/pages/jekyll-branched) demonstrates how you can keep your GitLab Pages site in one branch and your project's source code in another.
* The [jekyll-themes](https://gitlab.com/groups/jekyll-themes) group contains a collection of example projects you can fork (like this one) having different visual styles.
## Enabling and configuring pagination
The template includes `jekyll-paginate-v2` plugin by default, but it's turned off.
To use it, configure the pagination following instructions from the next paragraph, go to `pagination.md` file and change `enabled: false` to `enabled: true`, and `published: false` to `published: true`. Later, create a directory called `_posts` in the project root directory and fill it with posts.
You may also need to disable showing `index.md`, by setting `published: false` in its contents.
There are two sections in `_config.yml`, that refer to pagination: first, ` - jekyll-paginate-v2` line in plugins section, and then the configuration dictionary:
```
pagination:
enabled: true # Note, that setting it to disabled does not disable it completely, as it has to be also set to false in `pagination.md` file
title: ':title - page :num of :max' # Customize the text
per_page: 8 # How many posts should be displayed on one page
permalink: '/page/:num/' # The URL to the index of pagination
limit: 0
sort_field: 'date' # How the posts should be sorted. can also be: `title` or any page attribute
sort_reverse: true
trail: # How many pages should be shown in paginator.
before: 2 # Show 2 before the current one, e.g. `< 5 6 CURRENT ...`
after: 2 # Show 2 after the current one, e.g. `... CURRENT 6 7 >`
```
To disable it completely, set `enabled` to `false`, remove the aforementioned sections from the configuration, and `gem "jekyll-paginate-v2", "~> 1.7"` from `Gemfile` (from the project's root), and remove `pagination.md` file from project's root directory.
Refer to its [documentation](https://github.com/sverrirs/jekyll-paginate-v2/blob/master/README-GENERATOR.md) for more detailed instructions.
## Troubleshooting
1. CSS is missing! That means two things:
* Either that you have wrongly set up the CSS URL in your templates, or
* your static generator has a configuration option that needs to be explicitly
set in order to serve static assets under a relative URL.
[ci]: https://about.gitlab.com/gitlab-ci/
[Jekyll]: http://jekyllrb.com/
[install]: https://jekyllrb.com/docs/installation/
[documentation]: https://jekyllrb.com/docs/home/
[userpages]: https://docs.gitlab.com/ce/user/project/pages/introduction.html#user-or-group-pages
[projpages]: https://docs.gitlab.com/ce/user/project/pages/introduction.html#project-pages
![Build Status](https://gitlab.com/pages/jekyll/badges/master/build.svg)
---
Example [Jekyll] website using GitLab Pages. View it live at https://pages.gitlab.io/jekyll
[Learn more about GitLab Pages](https://pages.gitlab.io) or read the the [official GitLab Pages documentation](https://docs.gitlab.com/ce/user/project/pages/).
---
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
- [Getting Started](#getting-started)
- [Start by forking this repository](#start-by-forking-this-repository)
- [Start from a local Jekyll project](#start-from-a-local-jekyll-project)
- [GitLab CI](#gitlab-ci)
- [Using Jekyll locally](#using-jekyll-locally)
- [GitLab User or Group Pages](#gitlab-user-or-group-pages)
- [Did you fork this project?](#did-you-fork-this-project)
- [Other examples](#other-examples)
- [Troubleshooting](#troubleshooting)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
## Getting Started
You can get started with GitLab Pages using Jekyll easily by either forking this repository or by uploading a new/existing Jekyll project.
Remember you need to wait for your site to build before you will be able to see your changes. You can track the build on the **Pipelines** tab.
### Start by forking this repository
1. Fork this repository.
1. **IMPORTANT:** Remove the fork relationship.
Go to **Settings (⚙)** > **Edit Project** and click the **"Remove fork relationship"** button.
1. Enable Shared Runners.
Go to **Settings (⚙)** > **Pipelines** and click the **"Enable shared Runners"** button.
1. Rename the repository to match the name you want for your site.
1. Edit your website through GitLab or clone the repository and push your changes.
### Start from a local Jekyll project
1. [Install][] Jekyll.
1. Use `jekyll new` to create a new Jekyll Project.
1. Add [this `.gitlab-ci.yml`](.gitlab-ci.yml) to the root of your project.
1. Push your repository and changes to GitLab.
## GitLab CI
This project's static Pages are built by [GitLab CI][ci], following the steps
defined in [`.gitlab-ci.yml`](.gitlab-ci.yml):
```
image: ruby:2.5
variables:
JEKYLL_ENV: production
pages:
script:
- bundle install
- bundle exec jekyll build -d public
artifacts:
paths:
- public
only:
- master
```
## Configuration
You have some variables that you need to override in the `_config.yaml` file.
## Using Jekyll locally
To work locally with this project, you'll have to follow the steps below:
1. Fork, clone or download this project
1. [Install][] Jekyll
1. Download dependencies: `bundle`
1. Build and preview: `bundle exec jekyll serve`
1. Add content
The above commands should be executed from the root directory of this project.
Read more at Jekyll's [documentation][].
## GitLab User or Group Pages
To use this project as your user/group website, you will need one additional
step: just rename your project to `namespace.gitlab.io`, where `namespace` is
your `username` or `groupname`. This can be done by navigating to your
project's **Settings**.
Read more about [user/group Pages][userpages] and [project Pages][projpages].
## Did you fork this project?
If you forked this project for your own use, please go to your project's
**Settings** and remove the forking relationship, which won't be necessary
unless you want to contribute back to the upstream project.
## Other examples
* [jekyll-branched](https://gitlab.com/pages/jekyll-branched) demonstrates how you can keep your GitLab Pages site in one branch and your project's source code in another.
* The [jekyll-themes](https://gitlab.com/groups/jekyll-themes) group contains a collection of example projects you can fork (like this one) having different visual styles.
## Enabling and configuring pagination
The template includes `jekyll-paginate-v2` plugin by default, but it's turned off.
To use it, configure the pagination following instructions from the next paragraph, go to `pagination.md` file and change `enabled: false` to `enabled: true`, and `published: false` to `published: true`. Later, create a directory called `_posts` in the project root directory and fill it with posts.
You may also need to disable showing `index.md`, by setting `published: false` in its contents.
There are two sections in `_config.yml`, that refer to pagination: first, ` - jekyll-paginate-v2` line in plugins section, and then the configuration dictionary:
```
pagination:
enabled: true # Note, that setting it to disabled does not disable it completely, as it has to be also set to false in `pagination.md` file
title: ':title - page :num of :max' # Customize the text
per_page: 8 # How many posts should be displayed on one page
permalink: '/page/:num/' # The URL to the index of pagination
limit: 0
sort_field: 'date' # How the posts should be sorted. can also be: `title` or any page attribute
sort_reverse: true
trail: # How many pages should be shown in paginator.
before: 2 # Show 2 before the current one, e.g. `< 5 6 CURRENT ...`
after: 2 # Show 2 after the current one, e.g. `... CURRENT 6 7 >`
```
To disable it completely, set `enabled` to `false`, remove the aforementioned sections from the configuration, and `gem "jekyll-paginate-v2", "~> 1.7"` from `Gemfile` (from the project's root), and remove `pagination.md` file from project's root directory.
Refer to its [documentation](https://github.com/sverrirs/jekyll-paginate-v2/blob/master/README-GENERATOR.md) for more detailed instructions.
## Troubleshooting
1. CSS is missing! That means two things:
* Either that you have wrongly set up the CSS URL in your templates, or
* your static generator has a configuration option that needs to be explicitly
set in order to serve static assets under a relative URL.
[ci]: https://about.gitlab.com/gitlab-ci/
[Jekyll]: http://jekyllrb.com/
[install]: https://jekyllrb.com/docs/installation/
[documentation]: https://jekyllrb.com/docs/home/
[userpages]: https://docs.gitlab.com/ce/user/project/pages/introduction.html#user-or-group-pages
[projpages]: https://docs.gitlab.com/ce/user/project/pages/introduction.html#project-pages
# Welcome to Jekyll! # This config file is meant to be edited once, before the site is deployed.
# # After that, new edits are rarely needed.
# This config file is meant for settings that affect your whole blog, values
# which you are expected to set up once and rarely edit after that. If you find # Usually, you need only to change `title`, `email`, `description`, `baseurl`, `url` and `date`.
# yourself editing this file very often, consider using Jekyll's data files # To see complete guide, please take a look into `readme.md` file.
# feature for the data you need to update frequently.
#
# For technical reasons, this file is *NOT* reloaded automatically when you use # For technical reasons, this file is *NOT* reloaded automatically when you use
# 'bundle exec jekyll serve'. If you change this file, please restart the server process. # 'bundle exec jekyll serve'. If you change this file, please restart the server process.
...@@ -19,24 +18,21 @@ description: >- # this means to ignore newlines until "baseurl:" ...@@ -19,24 +18,21 @@ description: >- # this means to ignore newlines until "baseurl:"
Write an awesome description for your new site here. You can edit this Write an awesome description for your new site here. You can edit this
line in _config.yml. It will appear in your document head meta (for line in _config.yml. It will appear in your document head meta (for
Google search results) and in your feed.xml site description. Google search results) and in your feed.xml site description.
baseurl: "/pages-jekyll-lcsb-template" # the subpath of your site, e.g. /blog
url: "" # the base hostname & protocol for your site, e.g. http://example.com
# URL settings (the most difficult part, please refer to the guide)
baseurl: "/pages-jekyll-lcsb-template" # the subpath of your site, e.g. /gitlab-repository-name
url: "" # the base hostname & protocol for your site, e.g. http://gitlab-namespace-name.pages.uni.lu/
# Banner settings
banner: default # When you have custom images, change this setting's value to the name of the folder containing them banner: default # When you have custom images, change this setting's value to the name of the folder containing them
logo: small # Change to "big" (without quotas) in case of having broad logo logo: small # Change to "big" (without quotas) in case of having broad logo
date: "2018" date: "2018"
# Social media icon settings
twitter_username: uni_lu twitter_username: uni_lu
facebook_username: uni.lu facebook_username: uni.lu
linkedin_schoolname: university-of-luxembourg linkedin_schoolname: university-of-luxembourg
# Build settings
markdown: kramdown
theme: jekyll-theme-lcsb-default
plugins:
- jekyll-feed
- jekyll-paginate-v2
# Produces a cleaner folder structure when using categories # Produces a cleaner folder structure when using categories
permalink: /:year/:month/:title.html permalink: /:year/:month/:title.html
...@@ -53,7 +49,14 @@ pagination: ...@@ -53,7 +49,14 @@ pagination:
before: 2 before: 2
after: 2 after: 2
# Exclude from processing. # Build settings (no need to touch these)
markdown: kramdown
theme: jekyll-theme-lcsb-default
plugins:
- jekyll-feed
- jekyll-paginate-v2
# Exclude from processing. (no need to touch these)
# The following items will not be processed, by default. Create a custom list # The following items will not be processed, by default. Create a custom list
# to override the default setting. # to override the default setting.
# exclude: # exclude:
......
--- ---
# You don't need to edit this file, it's empty on purpose.
# Edit theme's home layout instead if you wanna make some changes
# See: https://jekyllrb.com/docs/themes/#overriding-theme-defaults
layout: default layout: default
title: Index title: Index
order: 1 order: 1
--- ---
# Gitlab pages # Gitlab pages
Welcome to an example page! Welcome to an example page! Below you will find a detailed instruction on how to set-up your own gitlab website.
Below you will find a detailed instruction on how to set-up your own gitlab website.
Sources for this page are [available in Gitlab](https://git-r3lab.uni.lu/core-services/pages-jekyll-lcsb-template). Sources for this page are [available in Gitlab](https://git-r3lab.uni.lu/core-services/pages-jekyll-lcsb-template).
Additionally, you can also navigate to the [repository for theme](https://git-r3lab.uni.lu/core-services/jekyll-theme-lcsb-default). Additionally, you can also navigate to the [repository for theme](https://git-r3lab.uni.lu/core-services/jekyll-theme-lcsb-default).
...@@ -30,17 +26,19 @@ Additionally, you can also navigate to the [repository for theme](https://git-r3 ...@@ -30,17 +26,19 @@ Additionally, you can also navigate to the [repository for theme](https://git-r3
6. Add your changes (`git add .`), commit (`git commit -m "Initial commit"`) and push (`git push --set-upstream master`) to the repository. 6. Add your changes (`git add .`), commit (`git commit -m "Initial commit"`) and push (`git push --set-upstream master`) to the repository.
7. If you want to have your page publicly available, make a ticket to SIU. 7. If you want to have your page publicly available, make a ticket to SIU.
8. Your page is published! Go to `https://<namespace>.pages.uni.lu/name-of-repository` in your favourite browser, or the URL you specified in the SIU ticket. 8. Your page is published! Go to `https://<namespace>.pages.uni.lu/name-of-repository` in your favourite browser, or the URL you specified in the SIU ticket.
9. (optional) In gitlab, go to **Settings** (under left-hand menu) > **General** > **Advanced** (hit `Expand` button) > **Remove fork relationship** (red button), then follow the instructions from the pop-up.
## What should you change in settings file? ## What should you change in settings file?
Mandatory: Mandatory:
* `baseurl` - this is very important. Set it to the name of the project (i.e. repository name). Here it's `pages-jekyll-lcsb-template` * `baseurl` - this is very important. Set it to the name of the project (i.e. repository name). Here it's `pages-jekyll-lcsb-template`
* `url` - this is equally important. Please set it to `https://gitlab-namespace-name.pages.uni.lu`. For example - if your project is inside `core-services` namespace, it should be: `url: "https://core-services.pages.uni.lu"`. For `minerva`, it would be: `url: "https://minerva.pages.uni.lu"`.
Optional: Optional:
* `title` field * `title` field
* `e-mail` field * `e-mail` field
* `description` field * `description` field
* `date` field * `date` field
* `banner` field - if you want to have your own banner (the text next to _uni.lu_ logo), send us an email. * `banner` field - if you want to have your own banner (the text next to _uni.lu_ logo), please send us an email (`lcsb-sysadmins (at) uni.lu`).
## Testing the web page locally ## Testing the web page locally
You can test your website locally (on your machine). You can test your website locally (on your machine).
...@@ -51,10 +49,12 @@ You can test your website locally (on your machine). ...@@ -51,10 +49,12 @@ You can test your website locally (on your machine).
* Finally, run the site: `bundle exec jekyll serve`. * Finally, run the site: `bundle exec jekyll serve`.
## Common problems ## Common problems
### *The website looks broken! There are no images, no colors etc.* ### *The website looks broken! There are no images, no colors etc.*
You probably didn't configure `baseurl` parameter in the settings. Please take a look on `_settings.yml` file. You probably didn't configure `baseurl` parameter in the settings. Please take a look on `_settings.yml` file.
### *The links in the menu are not working (they point to "404: Not found").* ### *The links in the menu are not working (they point to "404: Not found").*
You probably didn't add `permalink` attribute. Or the post has `published: false` or `draft: true` set. Please take a look on the post file. You probably didn't add `permalink` attribute. Or the post has `published: false` or `draft: true` set. Please take a look on the post file.
\ No newline at end of file
### Other problems?
Please send us an email! (`lcsb-sysadmins (at) uni.lu`)
\ No newline at end of file
...@@ -4,11 +4,8 @@ ...@@ -4,11 +4,8 @@
# pagination: # pagination:
# enabled: true # enabled: true
# And inside index.md, add `published: false` # And inside `index.md` header (e.g. after `title: index`), add `published: false`
# You don't need to edit this file, it's empty on purpose.
# Edit theme's home layout instead if you wanna make some changes
# See: https://jekyllrb.com/docs/themes/#overriding-theme-defaults
title: index title: index
layout: paginated_index layout: paginated_index
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment