Merge branch 'master' of git.fmrib.ox.ac.uk:open-science/community/Open-WIN-Community

_config.yml

@@ -84,7 +84,7 @@ nav_sort: case_sensitive # Capital letters sorted before lowercase
 back_to_top: true
 back_to_top_text: "Back to top"
 
-footer_content: "Copyright &copy; 2020, University of Oxford. All rights reserved. Distributed under a <a href=\"https://open.win.ox.ac.uk/pages/open-science/community/Open-WIN-Community/docs/LICENSE\">CC-BY-4.0 license.</a>"
+footer_content: "Copyright &copy; 2022, University of Oxford. All rights reserved. Distributed under a <a href=\"https://open.win.ox.ac.uk/pages/open-science/community/Open-WIN-Community/docs/LICENSE\">CC-BY-4.0 license.</a>"
 
 # Footer last edited timestamp
 last_edit_timestamp: true # show or hide edit time - page must have `last_modified_date` defined in the frontmatter

docs/gitlab/1-2-tools-markdown.md

@@ -20,7 +20,7 @@ Markdown is a simple syntax for formatting text and adding graphics to documenta
 
 Using markdown also supports you to use "heading" identifiers, rather than simply changing the font size. This is because it is so *easy* to use heading syntax and it is comparatively complex to change a font size! This makes for content which is more accessible to screen readers used by individuals with a visual impairment ✌🏻 ✌🏼 ✌🏽 ✌🏾 ✌🏿
 
-Markdown is used by GitHub to translate your text and formatting into webpage (GitHub Pages) content. You will be writing your documentation (maybe in [Atom](1-3-atom.md)) using markdown syntax, and it will automatically be rendered into something beautiful on your Pages site.
+Markdown is used by GitHub to translate your text and formatting into webpage (GitHub Pages) content. You will be writing your documentation (maybe in [Atom](../1-3-tools-atom)) using markdown syntax, and it will automatically be rendered into something beautiful on your Pages site.
 
 There are *many* markdown tutorials online which you can follow. I've listed the syntax I use most commonly below:
 

docs/gitlab/2-3-starting-local-repo.md

@@ -20,9 +20,9 @@ Currently your "test-git-project" exists online and your computer is configured
 
 In your terminal, move to the directory where you would like your local version of the repository to be stored. Enter the "Create a new repository" commands into your terminal, one line at a time.
 
-Note you will be asked for the SSH key password you generated when you [first accessed your gitlab account](2-1-starting-gitlab-account.md).
+Note you will be asked for the SSH key password you generated when you [first accessed your gitlab account](../2-1-starting-gitlab-account).
 
-Below is a brief explanation of what each line is doing. You'll learn more about some of these commands in the [git basics tutorial](2-4-starting-git-basics.md).
+Below is a brief explanation of what each line is doing. You'll learn more about some of these commands in the [git basics tutorial](../2-4-starting-git-basics).
 
 After entering these commands, return to the [gitlab webpage](https://git.fmrib.ox.ac.uk) and refresh your project. You will now see that the instructions for creating a new project have gone and the commit message you just entered is shown on the top.
 

docs/gitlab/2-4-starting-git-basics.md

@@ -27,7 +27,7 @@ In the spirit of inclusivity, I'm going to show you the git commands I know, and
 
 ## Watch and learn
 
-We're not yet going to actually practice doing these things right now. I'd just like you to become familiar with (memorize?!) them. You'll get a chance to use them when you have a go at [contributing to this repository](3-3-play-with-this-page.md),  and again when you [make your pages site](4-2-Make-your-Pages-site.md).
+We're not yet going to actually practice doing these things right now. I'd just like you to become familiar with (memorize?!) them. You'll get a chance to use them when you have a go at [contributing to this repository](../3-3-collaborating-play-with-this-page), and again when you make your [GitLab pages](../4-4-create-gitlab-pages-site) or [GitHub pages](../4-3-you-make-your-pages-site) site.
 
 ## The three(ish) stages of adding to your repository online
 

docs/gitlab/3-2-collaborating-fork-their-repo.md

@@ -63,7 +63,7 @@ First confirm you are working on the new branch with the command below:
 
 Then open your text editor and make and save the changes.
 
-Finally, add, commit and save the changes as described in the earlier [git basics](2-4-git-basics.md)
+Finally, add, commit and save the changes as described in the earlier [git basics](../2-4-starting-git-basics)
 
 Notice the git gave me a helpful error which told me that it din't know where to push my changes  - there was not "upstream branch" - and very kindly told me what commands I need to enter to set the upstream to be this branch on my copy of the repository. Thanks, Git.
 

docs/gitlab/3-3-collaborating-play-with-this-page.md

@@ -30,7 +30,7 @@ Coming soon
 
 Below is a list of numbers. For your first contribution to someone else's documentation, I would like you to write your name, your pronouns, today's date, and your GitHub profile link against one of these numbers. If you don't know your profile link, click your profile icon (top right side) and open 'Your Profile' in a new tab. You can use the URL of that page to build your GitHub profile link. Use the link format: `[Link text here](LINK URL HERE)`. If you want to get jazzy, you can do something more complicated, like add a picture or some formatting! I invite you to freestyle or keep it functional as you wish.
 
-Use the procedure described earlier to [fork, clone, branch, edit, push, and submit a pull request](../3-2-fork-their-repo.md) to update the lines below.
+Use the procedure described earlier to [fork, clone, branch, edit, push, and submit a pull request](../3-2-collaborating-fork-their-repo) to update the lines below.
 
 We're going to assume we're in a "class" setting right now, and I'm expecting your pull requests to come in. I'll accept them as soon as I can! If we're not in an active tutorial, I'll still aim to get to them as soon as I can, but please accept my apologies if it is not instantaneous. Often collaboration is asynchronous!
 

docs/gitlab/4-3-you-make-your-pages-site.md

 ---
 layout: default
-title: 4.3 Making your pages site
+title: 4.3 Create a GitHub Pages site
 parent: Tutorials
 grand_parent: Git and GitLab
 has_children: false
@@ -16,13 +16,14 @@ Use the magic of Jekyll to transform markdown pages into a website
 
 ---
 
-Coming soon
-{: .label .label-yellow }
-**This documentation needs to be updated for GitLab**
+> **Note**
+>
+> This guide describes how to publish your repo with **GitHub** Pages. If you are planning to publish a GitLab project, see the [GitLab Pages Guide](../4-4-create-gitlab-pages-site) instead!
+
 
 ## 1. Turn your repo into a GitHub Pages site!
 
-Now the magic! Turn the simple collection of files made in [the previous tutorial](4-1-you-make-your-repo.md) into something which looks like a user friendly (and not GitHub scary!) website!
+Now the magic! Turn the simple collection of files made in [the previous tutorial](../4-1-you-make-your-repo) into something which looks like a user friendly (and not GitHub scary!) website!
 
 Go into your site settings and scroll down to the "GitHub Pages section". Change the "Source" into your "master" branch and click "save".
 
@@ -74,7 +75,7 @@ Pro-tip: Search the internet for examples where other people have used the same
 
 In the below I've edited my repo in atom. I've added a few pages, and the front matter (text at the top) to define the order I want pages to appear in, and whether they should have sub-pages ("children").
 
-Once you've made a few changes, simply [add, commit and push](2-4-git-basics.md) them to your repo!
+Once you've made a few changes, simply [add, commit and push](../2-4-git-basics) them to your repo!
 
 ![gif-add-pages](../../../img/gifs/add-pages.gif)
 

docs/gitlab/4-4-create-gitlab-pages-site.md

+---
+layout: default
+title: 4.4 Create a GitLab Pages site
+parent: Tutorials
+grand_parent: Git and GitLab
+has_children: false
+nav_order: 14
+---
+
+
+# Create and publish your GitLab Pages site
+{: .fs-8 }
+
+Use the magic of Jekyll to transform markdown pages into a website
+{: .fs-6 .fw-300 }
+
+---
+
+> **Note**
+>
+> This guide describes how to publish your project with **GitLab** Pages. If you are planning to publish a GitHub repo, see the [GitHub Pages Guide](../4-3-you-make-your-pages-site) instead!
+
+
+## 1. Turn your repo into a GitLab Pages site!
+
+Now the magic! Turn the simple collection of files made in [the previous tutorial](../4-1-you-make-your-repo) into something which looks like a user friendly website!
+
+
+**Start from a WIN template**
+
+To host your page on the WIN GitLab instance,
+
+For a basic template based on [Jekyll](https://jekyllrb.com/), fork [this repository](https://git.fmrib.ox.ac.uk/open-science/community/gitlab_pages_jekyll_template) and then edit your copy of the template.
+
+A second template using the *Beautiful Jekyll* theme can be forked [here](https://git.fmrib.ox.ac.uk/open-science/community/beautiful-jekyll).
+
+A third template based on the stylish `just-the-docs` layout (particulalry suited for documentation, guides and manuals) can be forked [here](https://git.fmrib.ox.ac.uk/open-science/community/just-the-docs).
+
+After forking one of the templates, remove the fork relationship by navigating to the forked project, then from the left panel select `Settings` > `General`. Find the panel `Advanced Settings` and click `Expand` > `Remove fork relationship`.
+
+
+**Project name**
+
+Update the project name of the forked template to something meaningful for your intended page. Go to `Settings` > `General` > `Project name`. Your project name should not contain any white spaces. Then change the path of your project to match your project name by going to `Settings` > `General` > `Advanced` > `Change path`.
+
+
+**Configuration settings**
+
+The file `_config.yml` contains the main settings to turn your project into a GitLab Pages site:
+
+    * title: This is the title for your site
+    * email: A contact email address for the page author/site operator
+    * description: A description of the content of the site
+    * baseurl: This is used to generate links to images etc, this should be set to /pages/<username>/<project name>
+    * url: "https://open.win.ox.ac.uk" (This is the host address of the GitLab instance. Don't change this!)
+    * version: If you wish to indicate that this is a new version of this site, increment this number
+
+Note that the "project name" in the baseurl must match the name and path defined in the previous step.
+
+
+
+An example `_config.yml` is shown below:
+
+```
+# Site settings
+title: "Example Pages Template" # Provide a meaningful name
+email: "myemail@ndcn.ox.ac.uk" # Set to contact email address
+description: > # this means to ignore newlines until "baseurl:"
+  Example GitLab Pages template
+baseurl: "/pages/open-science/community/gitlab_pages_jekyll_template" # Set this to /pages/<group or username>/<project name>
+url: "https://open.win.ox.ac.uk" # Leave this alone if publishing on WIN Pages site
+version: "1.0"
+
+# Build settings
+markdown: kramdown
+
+kramdown:
+  input: GFM
+  syntax_highlighter: rouge
+
+plugins:
+  - jekyll-sitemap
+```
+
+
+
+## 2. Deploying your site with CI
+
+In order for GitLab to publish your site, you need to enable a "runner". Go to `Settings` > `CI/CD` > `Runners`. Tick `Enable shared runners`.
+
+With the CI (continuous integration) runner enabled, every new commit that is pushed to your remote project directory will trigger a new build process. You can monitor the progress of the CI in `CI/CD` > `Pipelines` (rocket icon on the left navigation bar).
+
+**Configuration settings**
+
+The way CI is executed is based on a pipeline that runs a series of scripts that are grouped into "stages". Dividing the CI into different stages can help locate errors in the execution process. For example, you could set up *build*, *test* and *deploy* stages that each execute a set of shell commands and/or scripts. This is all specified in the configuration file `.gitlab-ci.yml`. However, it its simplest form, the file needs to contain only the following:
+
+```
+image: jekyll/jekyll
+pages:
+  script:
+    - bundle exec jekyll build -d public
+  tags:
+    - docker
+  artifacts:
+    paths:
+      - public
+```
+
+This tells the CI runner to use the jekyll Docker image and executes the jekyll build process. For more information, see the [gitlab docs](https://docs.gitlab.com/ee/ci/yaml/index.html#stages).
+
+
+
+## 3. Viewing your site online
+
+Assuming that the build process of the site completes without error, your GitLab Pages site will now be visable at:
+
+    https://open.win.ox.ac.uk/pages/<your-username>/<your-project>
+
+
+
+## 4. Troubleshooting
+
+Additional information and more extensive documentation can be found at the [GitLab community help pages](https://git.fmrib.ox.ac.uk/help/user/project/pages/index).
+
+
+
+## 5. Feedback
+
+To provide feedback on the WIN templates, please use GitLab issues and merge requests in the respective project repositories!

docs/gitlab/5-1-projectmanagement-issues.md

@@ -4,11 +4,11 @@ title: 5.1 GitLab issues
 parent: Tutorials
 grand_parent: Git and GitLab
 has_children: false
-nav_order: 14
+nav_order: 15
 ---
 
 
-# GitLab milestones
+# GitLab Issues
 {: .fs-8 }
 
 Use GitLab issues invite feedback and track improvements

docs/gitlab/5-2-projectmanagement-milestones.md

@@ -4,7 +4,7 @@ title: 5.2 GitLab milestones
 parent: Tutorials
 grand_parent: Git and GitLab
 has_children: false
-nav_order: 15
+nav_order: 16
 ---
 
 

docs/gitlab/gitlab-tutorials.md

@@ -39,7 +39,8 @@ Follow the below tutorials (left in the navigation panel) to set up and use GitL
 ### 4. Making and publishing your repository
 - [4.1 Make a repository](../4-1-you-make-your-repo)
 - [4.2 Create a doi](../4-2-you-doi)
-- [4.3 Making your pages site](../4-3-you-make-your-pages-site)
+- [4.3 Create a GitHub Pages site](../4-3-you-make-your-pages-site)
+- [4.4 Create a GitLab Pages site](../4-4-create-gitlab-pages-site)
 
 ### 5. Managing your project on GitLab
 - [5.1 GitLab issues](../5-1-projectmanagement-issues)

docs/gitlab/repo-doi.md

@@ -15,7 +15,7 @@ How to create a doi in zenodo for your GitLab project
 
 ---
 
-*Note this is a duplicate of [tutorial 4.2 Create a doi](4-2-you-doi)*
+*Note this is a duplicate of [tutorial 4.2 Create a DOI](../4-2-you-doi)*
 
 Zenodo is free to use tool for creating a digital object identifier (doi) for your shared resources. A doi is essential for enabling other researchers to cite and reuse your material, and for you to receive proper attribution. Your doi entry will include your [ORCID ID](https://info.orcid.org/benefits-for-researchers/), so it can be tracked against all your other research outputs.