Skip to content
Snippets Groups Projects
Commit 87a6fe7e authored by Nicholas Bodvin Sellevåg's avatar Nicholas Bodvin Sellevåg
Browse files

Update README.md

parent 5359b3f0
No related branches found
No related tags found
No related merge requests found
Show whitespace changes
Inline Side-by-side
Showing
with 39 additions and 51 deletions
README.md
+ 39
− 51
View file @ 87a6fe7e
# Git da gitt # Background information
This repository consists of all code developt during the bachelor thesis "Exploring possibilities for Gitlab as a Learning Management System" in the bachelor program Digital Infrastructure and Cyber Security (2019 - 2022). This repository consists of all code developt during the bachelor thesis "Exploring possibilities for Gitlab as a Learning Management System" in the bachelor program Digital Infrastructure and Cyber Security (2019 - 2022).
The aim of this thesis was to explore to which degree alternative systems available at NTNU could solve the main challenges of a learning Management System (LMS). The aim of this thesis was to explore to which degree alternative systems available at NTNU could solve the main challenges of a learning Management System (LMS).
...@@ -18,8 +18,8 @@ Fabian Kongelf <br> ...@@ -18,8 +18,8 @@ Fabian Kongelf <br>
Yan Senko <br> Yan Senko <br>
| yans@stud.ntnu.no | yans@stud.ntnu.no
## Installation ## What is contained within the repository?
The repository contains several projects that are effectively independent projects serving different functionalities of the developed system in relation to the thesis. For example, this repository transforms markdown documents into websites with Gitlab Pages automations. The folders "cypress_gitlab_pages", "auto-git-structure" and "webpage-accessebility-test" are all respectively their own repository and can be interconnected with CI/CD pipelines ad downstream and upstream projects. As a result, proper installation of the coherent system developed begins with configuring the "Gitlab pages" repository. Afterwards each other project should be created seperately. The repository contains several projects that are effectively independent projects serving different functionalities of the developed system in relation to the thesis. For example, this repository transforms markdown documents into websites with Gitlab Pages automations. The folders "cypress_gitlab_pages", "auto-git-structure" and "webpage-accessebility-test" are all respectively their own repository and can be interconnected with CI/CD pipelines ad downstream and upstream projects. As a result, proper installation of the coherent system developed begins with configuring the "Gitlab pages" repository. Afterwards each other project should be created seperately. Excluding the mentioned seperate projects all other files and folders are related to the configurable Gitlab Pages system.
Group members recommend creating an overarching group, then add each project within that group. Group members recommend creating an overarching group, then add each project within that group.
See the other projects repository/folder for their installation guide. See the other projects repository/folder for their installation guide.
...@@ -29,12 +29,26 @@ The original repository and working example can be viewed at [Department of Comp ...@@ -29,12 +29,26 @@ The original repository and working example can be viewed at [Department of Comp
### Installation of the GitLab Pages ### Installation of the GitLab Pages
The gitlab pages are almost able to function out of the box, however an administrator have to configure the _config.yml file for the website to have it's intended functions. The gitlab pages project require a small amount of configuration before working as intended.
When the changes to _config.yml is commited, the .gitlab-ci.yml file is executed in CI/CD and created the resulting website (the ci/cd is executed every time a commit is made to a project containing .gitlab-ci file). 1. Configure _config.yml file for the Static Site Generator Jekyll Service
Variables including baseurl, title and description affect the generated pages. Other variables such as "announcement_webhook" affect integrations with Teams.
### CI/CD It is notewhorty that most of the configuration is done beforehand and does not need changing. Therefore the required changes for users are marked with REQUIRED in the comment section.
2. Configure .gitlab-ci.yml for Gitlab CI/CD pipelines
There are five stages created by group members and can be interchanged or removed completely depending on the users wishes.
The possible stages are as follows in .gitlab-ci.yml file:
- test #Code-quality testing on Gitlab pages repository
- vuln-scan #Snyk dependency scanning of repository
- deploy #Gitlab Pages
- web-testing #Pre defined cypress tests against Gitlab Pages
- web-accessibility-report #accessibility testing of Gitlab Pages
- notification #Send web request to defined Teams webhook for publishing changes in repository
For example, users are free to remove the stages from the YAML file. On the other hand, to work as intended the Gitlab Pages project should triggers two downstream projects for running Web Unit tests with Cypress JavaScripted framework and WCAG testing as Gitlab's own feature. One could make all stages part of this repository through combining the different .gitlab-ci.yml and overwriting the stages from YAML file in each project folder into this repository's version.
To solely have Gitlab Pages transform markdown documents into websites simply remove all other stages than deploy in this repository's .gitlab-ci.yml file.
### Other projects ### Other projects
The following folder are thier own projects: The following folder are thier own projects:
...@@ -57,7 +71,23 @@ In a teminal at the root of the project, do the following commands: ...@@ -57,7 +71,23 @@ In a teminal at the root of the project, do the following commands:
- bundle exec jekyll serve //Run Jekyll and host _site localt, the output is the local URL of the website - bundle exec jekyll serve //Run Jekyll and host _site localt, the output is the local URL of the website
## Dependencies ## Dependencies
Jekyll Static Site Generator
[Jekyll Ruby plugin](https://rubygems.org/gems/jekyll)
Create automated table of contents from headings in markdown documents
[Jekyll-toc Ruby plugin](https://rubygems.org/gems/jekyll-toc)
Access environment variables using Liquid tags with Jekyll
[Jekyll-environment-variables Ruby plugin](https://rubygems.org/gems/jekyll-environment-variables)
A Jekyll plugin to generate an Atom feed of your Jekyll posts. In practice RSS generation.
[Jekyll-feed Ruby plugin](https://rubygems.org/gems/jekyll-feed)
Time Date of posts
[Tzinfo-data Ruby plugin](https://rubygems.org/gems/tzinfo-data)
This plugin takes any file that is in posts folders, and copy them to the folder in which the post HTML page will be created.
[Jekyll-postfiles Ruby plugin](https://rubygems.org/gems/jekyll-postfiles)
# How the website works # How the website works
...@@ -75,10 +105,6 @@ Added to the top of a markdown post to set certain specifications. Most of the t ...@@ -75,10 +105,6 @@ Added to the top of a markdown post to set certain specifications. Most of the t
Defines the layout to use for a post. For now all posts should use the standard layout "post", as seen in *_layouts/post.html*. Defines the layout to use for a post. For now all posts should use the standard layout "post", as seen in *_layouts/post.html*.
In practice, layouts are templates with some basic html that includes the content of a given page, in addition a standarized footer and header all available in the "/webpage/_includes" folder. In practice, layouts are templates with some basic html that includes the content of a given page, in addition a standarized footer and header all available in the "/webpage/_includes" folder.
## Naming conventions
Jekyll treats dates in the beginning of file names specially, but our solution does not support this. In order to avoid uncertain behaviours, avoid starting file names with dates in a YYYY-MM-DD format.
## Table of Contents ## Table of Contents
Posts will automatically generate a table of contents based on headings present in the source markdown file. Tocs are enabled by default, but can be disabled for a single post by adding the following line to the front matter of the post: Posts will automatically generate a table of contents based on headings present in the source markdown file. Tocs are enabled by default, but can be disabled for a single post by adding the following line to the front matter of the post:
...@@ -105,11 +131,6 @@ To render a code block with syntax highlighting, surround your code as follows: ...@@ -105,11 +131,6 @@ To render a code block with syntax highlighting, surround your code as follows:
The argument to the highlight tag (C in the example above) is the language identifier. You can view a list of all supported languages and their identifiers [here](https://github.com/rouge-ruby/rouge/blob/master/docs/Languages.md). The argument to the highlight tag (C in the example above) is the language identifier. You can view a list of all supported languages and their identifiers [here](https://github.com/rouge-ruby/rouge/blob/master/docs/Languages.md).
## Naming convention
Markdown files to become websites needs to be named ".md" as of now because of "datoBeGone" plugin as it only looks for ".md" extension.
TODO: make markdown extension all encompassing
## Directory/folder structure ## Directory/folder structure
All documents to become websites and relating images should be created inside the "content" folder in its own subfolder. This subfolder will automatically be made into a category by Jekyll. All documents to become websites and relating images should be created inside the "content" folder in its own subfolder. This subfolder will automatically be made into a category by Jekyll.
...@@ -128,7 +149,7 @@ content/ ...@@ -128,7 +149,7 @@ content/
-> imageToWebsite2.pdf -> imageToWebsite2.pdf
``` ```
This is not in and of itself a valid Jekyll structure, but script.sh will take the contents of the "content" folder and copy it into a temp folder "webpage/content", rearranging into a proper structure in the process. Should you as a user want to define the entire structure manually, simply adding the required _posts folders to the original "content" folder will stop the script from making any changes. This is not in and of itself a valid Jekyll structure, but deploy.sh will take the contents of the "content" folder and copy it into a temp folder "webpage/content", rearranging into a proper structure in the process. Should you as a user want to define the entire structure manually, simply adding the required _posts folders to the original "content" folder will stop the script from making any changes.
``` ```
content/ content/
...@@ -153,42 +174,9 @@ As long as an image or pdf is in the same folder as a markdown file, you can ref ...@@ -153,42 +174,9 @@ As long as an image or pdf is in the same folder as a markdown file, you can ref
If you want one or more assets to be accessed by several markdown files in several different folders, we recommend adding it to the "assets" folder. Referencing files from this folder requires using the absolute path starting at the baseurl: If you want one or more assets to be accessed by several markdown files in several different folders, we recommend adding it to the "assets" folder. Referencing files from this folder requires using the absolute path starting at the baseurl:
``` ```
![My image](/bachelor/webpage/assets/image.png) ![My image](/nameOfRepo/webpage/assets/image.png)
``` ```
## Notes for ourselves
### Liquid expressions
Link to jekyll-liquid documentation: https://jekyllrb.com/docs/liquid/
Link to liqud documentation: https://shopify.github.io/liquid/
Jekyll uses the Liquid templating language to process templates.
Generally in Liquid you output content using two curly braces e.g. `{{ variable }}` and perform logic statements by surrounding them in a curly brace percentage sign e.g. `{% if statement %}`.
In practice, we have used liquid to dynamically create the content listing on our index/home page. It serves the purpose of mapping our folder structure into the webpage and have links to all posts created for the site.
### Syntax highlighting
To change individual styles, for example colorschemes on variables and functions, change the css inside:
_syntax-highlighting.scss
Changing color for a specific language would probably involve:
Make a code snippet, highlight in browser which class names the ruby identifier used in the converted html
change the class css in _syntax-highlighting.scss.
For example, changing color of functions:
.n { color ....} //n stands for name
.nf { color ...} //nf stands for named function
NB! _base.scss has some base css for code highlighting. for example background color
### Performance testing
Link: https://docs.gitlab.com/ee/user/project/merge_requests/browser_performance_testing.html
NB! Check whether NTNU uses kubernetes cluster or not for Gitlab, metrics attained from website will depend on setup
### Plugins ### Plugins
DO NOT REMOVE THE _plugins FOLDER! It might be empty, but plugins won't work without it! DO NOT REMOVE THE _plugins FOLDER! It might be empty, but plugins won't work without it!
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment