SSoT audit fixes for GitLab U topics

Also improves the markdown in that section.

18 files changed, 51 insertions, 168 deletions

diff --git a/doc/university/training/topics/additional_resources.md b/doc/university/training/topics/additional_resources.md
deleted file mode 100644
index 4871372d105..00000000000
--- a/doc/university/training/topics/additional_resources.md
+++ /dev/null
@@ -1,12 +0,0 @@
----
-comments: false
----
-
-# Additional Resources
-
-1. GitLab Documentation: <http://docs.gitlab.com>.
-1. GUI Clients: <http://git-scm.com/downloads/guis>.
-1. Pro Git book: <http://git-scm.com/book>.
-1. Platzi Course: <https://courses.platzi.com/courses/git-gitlab/>.
-1. Code School tutorial: <http://try.github.io/>.
-1. Contact us at `subscribers@gitlab.com`.
diff --git a/doc/university/training/topics/agile_git.md b/doc/university/training/topics/agile_git.md
index 251af99bed7..42d91a50045 100644
--- a/doc/university/training/topics/agile_git.md
+++ b/doc/university/training/topics/agile_git.md
@@ -4,22 +4,16 @@ comments: false
 
 # Agile and Git
 
-----------
-
 ## Agile
 
 Lean software development methods focused on collaboration and interaction
 with fast and smaller deployment cycles.
 
-----------
-
 ## Where Git comes in
 
 Git is an excellent tool for an Agile team considering that it allows
 decentralized and simultaneous development.
 
-----------
-
 ### Branching And Workflows
 
 Branching in an Agile environment usually happens around user stories with one
@@ -30,8 +24,7 @@ with his/her initials, and US id.
 
 After its tested merge into master and remove the branch.
 
-----------
-
 ## What about GitLab
+
 Tools like GitLab enhance collaboration by adding dialog around code mainly
 through issues and merge requests.
diff --git a/doc/university/training/topics/bisect.md b/doc/university/training/topics/bisect.md
index 4848d0412c1..4178afa2086 100644
--- a/doc/university/training/topics/bisect.md
+++ b/doc/university/training/topics/bisect.md
@@ -4,16 +4,12 @@ comments: false
 
 # Bisect
 
-----------
-
 ## Bisect
 
 - Find a commit that introduced a bug
 - Works through a process of elimination
 - Specify a known good and bad revision to begin
 
-----------
-
 ## Bisect
 
 1. Start the bisect process
@@ -23,11 +19,9 @@ comments: false
 1. Tell bisect the result
 1. Repeat the previous 2 items until you find the offending commit
 
-----------
-
 ## Setup
 
-```
+```sh
   mkdir bisect-ex
   cd bisect-ex
   touch index.html
@@ -44,9 +38,7 @@ comments: false
   vi index.html
 ```
 
-----------
-
-```
+```sh
   # Add all good 3
   git add -A
   git commit -m "fourth commit"
@@ -64,11 +56,9 @@ comments: false
   git commit -m "seventh commit"
 ```
 
-----------
-
 ## Commands
 
-```
+```sh
   git bisect start
   # Test your code
   git bisect bad
diff --git a/doc/university/training/topics/cherry_picking.md b/doc/university/training/topics/cherry_picking.md
index df23024b6ee..fa0cb5fe6a4 100644
--- a/doc/university/training/topics/cherry_picking.md
+++ b/doc/university/training/topics/cherry_picking.md
@@ -4,16 +4,12 @@ comments: false
 
 # Cherry Pick
 
-----------
-
 ## Cherry Pick
 
 - Given an existing commit on one branch, apply the change to another branch
 - Useful for backporting bug fixes to previous release branches
 - Make the commit on the master branch and pick in to stable
 
-----------
-
 ## Cherry Pick
 
 1. Check out a new 'stable' branch from 'master'
@@ -23,8 +19,6 @@ comments: false
 1. Check out the 'stable' branch
 1. Cherry pick the commit using the SHA obtained earlier
 
-----------
-
 ## Commands
 
 ```bash
diff --git a/doc/university/training/topics/env_setup.md b/doc/university/training/topics/env_setup.md
index 78ca30e0f55..305f5ecb1fb 100644
--- a/doc/university/training/topics/env_setup.md
+++ b/doc/university/training/topics/env_setup.md
@@ -4,7 +4,6 @@ comments: false
 
 # Configure your environment
 
-----------
 ## Install
 
 - **Windows**
@@ -22,8 +21,6 @@ comments: false
   sudo apt-get install git-all
   ```
 
-----------
-
 ## Configure Git
 
 One-time configuration of the Git client
@@ -33,8 +30,6 @@ git config --global user.name "Your Name"
 git config --global user.email you@example.com
 ```
 
-----------
-
 ## Configure SSH Key
 
 ```bash
diff --git a/doc/university/training/topics/explore_gitlab.md b/doc/university/training/topics/explore_gitlab.md
index 84a1879cd92..4ca931d0e26 100644
--- a/doc/university/training/topics/explore_gitlab.md
+++ b/doc/university/training/topics/explore_gitlab.md
@@ -4,8 +4,6 @@ comments: false
 
 # Explore GitLab projects
 
-----------
-
 - Dashboard
 - User Preferences
 - Issues
diff --git a/doc/university/training/topics/feature_branching.md b/doc/university/training/topics/feature_branching.md
index 0df5f26dbea..d2efe634533 100644
--- a/doc/university/training/topics/feature_branching.md
+++ b/doc/university/training/topics/feature_branching.md
@@ -4,8 +4,6 @@ comments: false
 
 # Feature branching
 
-----------
-
 - Efficient parallel workflow for teams
 - Develop each feature in a branch
 - Keeps changes isolated
@@ -13,8 +11,6 @@ comments: false
 - Push branches to the server frequently
   - Hint: This is a cheap backup for your work-in-progress code
 
-----------
-
 ## Feature branching
 
 1. Create a new feature branch called 'squash_some_bugs'
@@ -22,11 +18,9 @@ comments: false
 1. Commit
 1. Push
 
-----------
-
 ## Commands
 
-```
+```sh
 git checkout -b squash_some_bugs
 # Edit `bugs.rb`
 git status
diff --git a/doc/university/training/topics/getting_started.md b/doc/university/training/topics/getting_started.md
index d76ff57bfa3..08027c5d15b 100644
--- a/doc/university/training/topics/getting_started.md
+++ b/doc/university/training/topics/getting_started.md
@@ -4,8 +4,6 @@ comments: false
 
 # Getting Started
 
-----------
-
 ## Instantiating Repositories
 
 - Create a new repository by instantiating it through:
@@ -19,8 +17,6 @@ comments: false
     git clone <url>
     ```
 
-----------
-
 ## Central Repos
 
 - To instantiate a central repository a `--bare` flag is required.
@@ -31,27 +27,22 @@ comments: false
     git init --bare project-name.git
     ```
 
-----------
-
 ## Instantiate workflow with clone
 
 1. Create a project in your user namespace.
-  - Choose to import from 'Any Repo by URL' and use <https://gitlab.com/gitlab-org/training-examples.git>.
+   - Choose to import from 'Any Repo by URL' and use <https://gitlab.com/gitlab-org/training-examples.git>.
 1. Create a '`Workspace`' directory in your home directory.
 1. Clone the '`training-examples`' project.
 
-----------
-
 ## Commands
 
-```
+```sh
 mkdir ~/workspace
 cd ~/workspace
 
 git clone git@gitlab.example.com:<username>/training-examples.git
 cd training-examples
 ```
-----------
 
 ## Git concepts
 
@@ -67,8 +58,6 @@ Files that have been modified but are not committed.
 
 Modified files that have been marked to go in the next commit.
 
-----------
-
 ## Committing Workflow
 
 1. Edit '`edit_this_file.rb`' in '`training-examples`'
@@ -79,11 +68,9 @@ Modified files that have been marked to go in the next commit.
 1. Push the commit to the remote
 1. View the git log
 
-----------
-
 ## Commands
 
-```
+```sh
 # Edit `edit_this_file.rb`
 git status
 git diff
@@ -93,8 +80,6 @@ git push origin master
 git log
 ```
 
-----------
-
 ## Note
 
 - git fetch vs pull
diff --git a/doc/university/training/topics/git_add.md b/doc/university/training/topics/git_add.md
index e02a7deab91..4c61d5eb175 100644
--- a/doc/university/training/topics/git_add.md
+++ b/doc/university/training/topics/git_add.md
@@ -4,8 +4,6 @@ comments: false
 
 # Git Add
 
-----------
-
 ## Git Add
 
 Adds content to the index or staging area.
@@ -22,8 +20,6 @@ Adds content to the index or staging area.
     git add -A
     ```
 
-----------
-
 ## Git add continued
 
 - Add all text files in current dir:
diff --git a/doc/university/training/topics/git_intro.md b/doc/university/training/topics/git_intro.md
index 127323c292c..845bb7f0a81 100644
--- a/doc/university/training/topics/git_intro.md
+++ b/doc/university/training/topics/git_intro.md
@@ -4,8 +4,6 @@ comments: false
 
 # Git introduction
 
-----------
-
 ## Intro
 
 <https://git-scm.com/about>
@@ -17,8 +15,6 @@ comments: false
 - Adapts to nearly any workflow
 - Fast, reliable and stable file format
 
-----------
-
 ## Help!
 
 Use the tools at your disposal when you get stuck.
diff --git a/doc/university/training/topics/git_log.md b/doc/university/training/topics/git_log.md
index 763ef802a04..11addcd3ee1 100644
--- a/doc/university/training/topics/git_log.md
+++ b/doc/university/training/topics/git_log.md
@@ -4,44 +4,38 @@ comments: false
 
 # Git Log
 
-----------
-
 Git log lists commit history. It allows searching and filtering.
 
 - Initiate log:
 
-    ```
+    ```sh
     git log
     ```
 
 - Retrieve set number of records:
 
-    ```
+    ```sh
     git log -n 2
     ```
 
 - Search commits by author. Allows user name or a regular expression.
 
-    ```
+    ```sh
     git log --author="user_name"
     ```
 
-----------
-
 - Search by comment message:
 
-    ```
+    ```sh
     git log --grep="<pattern>"
     ```
 
 - Search by date:
 
-    ```
+    ```sh
     git log --since=1.month.ago --until=3.weeks.ago
     ```
 
-----------
-
 ## Git Log Workflow
 
 1. Change to workspace directory
@@ -51,11 +45,9 @@ Git log lists commit history. It allows searching and filtering.
 1. Search by date
 1. Combine
 
-----------
-
 ## Commands
 
-```
+```sh
 cd ~/workspace
 git clone git@gitlab.com:gitlab-org/gitlab-runner.git
 cd gitlab-runner
diff --git a/doc/university/training/topics/merge_conflicts.md b/doc/university/training/topics/merge_conflicts.md
index a7d42904229..dd235fe3a81 100644
--- a/doc/university/training/topics/merge_conflicts.md
+++ b/doc/university/training/topics/merge_conflicts.md
@@ -4,15 +4,11 @@ comments: false
 
 # Merge conflicts
 
-----------
-
 - Happen often
 - Learning to fix conflicts is hard
 - Practice makes perfect
 - Force push after fixing conflicts. Be careful!
 
-----------
-
 ## Merge conflicts
 
 1. Checkout a new branch and edit `conflicts.rb`. Add 'Line4' and 'Line5'.
@@ -26,11 +22,9 @@ comments: false
 1. Force push the changes.
 1. Finally continue with the Merge Request.
 
-----------
-
 ## Commands
 
-```
+```sh
 git checkout -b conflicts_branch
 
 # vi conflicts.rb
@@ -49,7 +43,7 @@ git push origin master
 
 Create a merge request on the GitLab web UI. You'll see a conflict warning.
 
-```
+```sh
 git checkout conflicts_branch
 git fetch
 git rebase master
@@ -65,7 +59,6 @@ git rebase --continue
 # need to force push so that our remote branch is restructured
 git push origin conflicts_branch -f
 ```
-----------
 
 ## Note
 
diff --git a/doc/university/training/topics/merge_requests.md b/doc/university/training/topics/merge_requests.md
index d7b771cd87b..b5bbe7b2e1e 100644
--- a/doc/university/training/topics/merge_requests.md
+++ b/doc/university/training/topics/merge_requests.md
@@ -4,8 +4,6 @@ comments: false
 
 # Code review and collaboration with Merge Requests
 
-----------
-
 - When you want feedback create a merge request
 - Target is the default branch (usually master)
 - Assign or mention the person you would like to review
@@ -14,8 +12,6 @@ comments: false
 - Anyone can comment, not just the assignee
 - Push corrections to the same branch
 
-----------
-
 ## Merge requests
 
 **Create your first merge request**
@@ -25,8 +21,6 @@ comments: false
 1. Push a new commit to the same branch
 1. Review the changes again and notice the update
 
-----------
-
 ## Feedback and Collaboration
 
 - Merge requests are a time for feedback and collaboration
@@ -36,8 +30,6 @@ comments: false
 - Be as receptive as possible
 - Feedback is about the best code, not the person. You are not your code
 
-----------
-
 ## Feedback and Collaboration
 
 Review the Thoughtbot code-review guide for suggestions to follow when reviewing merge requests:
diff --git a/doc/university/training/topics/rollback_commits.md b/doc/university/training/topics/rollback_commits.md
index 96b89e3319a..1e6602deef2 100644
--- a/doc/university/training/topics/rollback_commits.md
+++ b/doc/university/training/topics/rollback_commits.md
@@ -4,40 +4,34 @@ comments: false
 
 # Rollback Commits
 
-----------
-
 ## Undo Commits
 
 - Undo last commit putting everything back into the staging area:
 
-    ```
+    ```sh
     git reset --soft HEAD^
     ```
 
 - Add files and change message with:
 
-    ```
+    ```sh
     git commit --amend -m "New Message"
     ```
 
-----------
-
 - Undo last and remove changes:
 
-    ```
+    ```sh
     git reset --hard HEAD^
     ```
 
 - Same as last one but for two commits back:
 
-    ```
+    ```sh
     git reset --hard HEAD^^
     ```
 
 ** Don't reset after pushing **
 
-----------
-
 ## Reset Workflow
 
 1. Edit file again 'edit_this_file.rb'
@@ -51,11 +45,9 @@ comments: false
 1. Pull for updates
 1. Push changes
 
-----------
-
 ## Commands
 
-```
+```sh
 # Change file edit_this_file.rb
 git status
 git commit -am "kjkfjkg"
@@ -68,15 +60,13 @@ git pull origin master
 git push origin master
 ```
 
-----------
-
 ## Note
 
 - git revert vs git reset
 - Reset removes the commit while revert removes the changes but leaves the commit
 - Revert is safer considering we can revert a revert
 
-```
+```sh
 # Changed file
 git commit -am "bug introduced"
 git revert HEAD
diff --git a/doc/university/training/topics/stash.md b/doc/university/training/topics/stash.md
index dfd28fbcbc9..02b2f610266 100644
--- a/doc/university/training/topics/stash.md
+++ b/doc/university/training/topics/stash.md
@@ -4,14 +4,12 @@ comments: false
 
 # Git Stash
 
-----------
-
 We use git stash to store our changes when they are not ready to be committed
 and we need to change to a different branch.
 
 - Stash:
 
-    ```
+    ```sh
     git stash save
     # or
     git stash
@@ -21,18 +19,16 @@ and we need to change to a different branch.
 
 - Apply stash to keep working on it:
 
-    ```
+    ```sh
     git stash apply
     # or apply a specific one from out stack
     git stash apply stash@{3}
     ```
 
-----------
-
 - Every time we save a stash it gets stacked so by using list we can see all our
   stashes.
 
-    ```
+    ```sh
     git stash list
     # or for more information (log methods)
     git stash list --stat
@@ -40,7 +36,7 @@ and we need to change to a different branch.
 
 - To clean our stack we need to manually remove them:
 
-    ```
+    ```sh
     # drop top stash
     git stash drop
     # or
@@ -49,19 +45,15 @@ and we need to change to a different branch.
     git stash clear
     ```
 
-----------
-
 - Apply and drop on one command:
 
-    ```
+    ```sh
       git stash pop
     ```
 
 - If we meet conflicts we need to either reset or commit our changes.
 - Conflicts through `pop` will not drop a stash afterwards.
 
-----------
-
 ## Git Stash
 
 1. Modify a file
@@ -72,11 +64,9 @@ and we need to change to a different branch.
 1. Apply with pop
 1. View list to confirm changes
 
-----------
-
 ## Commands
 
-```
+```sh
 # Modify edit_this_file.rb file
 git add .
 
diff --git a/doc/university/training/topics/subtree.md b/doc/university/training/topics/subtree.md
index ba7c3394938..981918d4758 100644
--- a/doc/university/training/topics/subtree.md
+++ b/doc/university/training/topics/subtree.md
@@ -9,19 +9,15 @@ comments: false
 - For these cases we need a dependency control system.
 - Command are painfully long so aliases are necessary.
 
-----------
-
 ## Subtree Aliases
 
-- Add: git subtree add --prefix <target-folder> <url> <branch> --squash.
-- Pull: git subtree add --prefix <target-folder> <url> <branch> --squash.
-- Push: git subtree add --prefix <target-folder> <url> <branch>.
-- Ex: git config alias.sbp 'subtree pull --prefix st /
-  git@gitlab.com:balameb/subtree-nested-example.git master --squash'.
-
-----------
+- Add: `git subtree add --prefix <target-folder> <url> <branch> --squash`.
+- Pull: `git subtree add --prefix <target-folder> <url> <branch> --squash`.
+- Push: `git subtree add --prefix <target-folder> <url> <branch>`.
+- Ex: `git config alias.sbp 'subtree pull --prefix st /
+  git@gitlab.com:balameb/subtree-nested-example.git master --squash'`.
 
-```
+```sh
   # Add an alias
   # Add
   git config alias.sba 'subtree add --prefix st /
@@ -41,9 +37,7 @@ comments: false
 
 ```
 
-----------
-
-```
+```sh
   # Adding, or committing won't change the sub repo at remote
   # even if we push
   git add -A
diff --git a/doc/university/training/topics/tags.md b/doc/university/training/topics/tags.md
index 14c39457838..cdbb8a2da7c 100644
--- a/doc/university/training/topics/tags.md
+++ b/doc/university/training/topics/tags.md
@@ -1,19 +1,16 @@
 ---
 comments: false
+type: reference
 ---
 
 # Tags
 
-----------
-
 - Useful for marking deployments and releases
 - Annotated tags are an unchangeable part of Git history
 - Soft/lightweight tags can be set and removed at will
 - Many projects combine an annotated release tag with a stable branch
 - Consider setting deployment/release tags automatically
 
-----------
-
 # Tags
 
 - Create a lightweight tag
@@ -24,11 +21,9 @@ comments: false
 
 <https://git-scm.com/book/en/Git-Basics-Tagging>
 
-----------
-
 # Commands
 
-```
+```sh
 git checkout master
 
 # Lightweight tag
@@ -40,3 +35,15 @@ git tag
 
 git push origin --tags
 ```
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/university/training/topics/unstage.md b/doc/university/training/topics/unstage.md
index c926f0b4888..af16afdc5d1 100644
--- a/doc/university/training/topics/unstage.md
+++ b/doc/university/training/topics/unstage.md
@@ -4,8 +4,6 @@ comments: false
 
 # Unstage
 
-----------
-
 ## Unstage
 
 - To remove files from stage use reset HEAD where HEAD is the last commit of the current branch. This will unstage the file but maintain the modifications. 
@@ -20,17 +18,15 @@ comments: false
     git checkout -- <file>
     ```
 
-----------
-
 - To remove a file from disk and repo use 'git rm' and to rm a dir use the '-r' flag:
 
-    ```
+    ```sh
     git rm '*.txt'
     git rm -r <dirname>
     ```
 
 - If we want to remove a file from the repository but keep it on disk, say we forgot to add it to our `.gitignore` file then use `--cache`:
 
-    ```
+    ```sh
     git rm <filename> --cache
     ```