updated website

docs/custom.md

@@ -90,7 +90,7 @@ Content divided in different sections is created by multiple Markdown-files. For
 
 ???+ note "Landing page"
 
-    How to create a pretty landing page is outlined in another section. Please focus on the content in this task, only. 
+    How to create a pretty landing page is outlined in another section. Please only focus on the content of your sections in this task. 
 
 ???+ note "Curriculum Vitae"
 

docs/deploy.md

@@ -2,28 +2,124 @@ So far, we only build a local site, meaning that only you can see your website i
 
 ##### Task 1
 
+Create a new hidden folder in your website folder called ```.github```. Within this folder create again a new folder called ```workflows```. Your folder hierarchy should look like this: 
+
+```
+.
+├── docs
+│   ├── artifacts
+│   │   └── example.pdf
+│   ├── assets
+│   │   └── images
+│   │       ├── creating-your-site.png
+│   ├── index.md
+├── .github
+│   ├── workflows
+└── mkdocs.yml
+
+```
+???+ note "```.github```"
+
+    1.  You will not see this folder because folders starting with a period are hidden folders. To make hidden folders visible, you can apply a certain keyboard command. This command is different for different OS. Please google yourself what command it is for your OS.  
+
+
+Inside this folder create a new file called ```ci.yml```. Paste the following inside the ```ci.yml``` file:
+
+```yaml
+name: ci 
+on:
+  push:
+    branches:
+      - master 
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+      - uses: actions/cache@v3
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material 
+      - run: mkdocs gh-deploy --force
+```
+
+##### Task 2
+
 If you haven't done already, initialize Git in your local repository:
 ```bash
 cd my-website-folder
+```
+```bash
 git init
 ```
-##### Task 2 
+```bash
+git add . && git commit -m "commit message" 
+```
+
+???+ note "```git add . && git commit```"
+
+    This will add AND commit ALL files in your folder. If you want to exclude files from being version controlled by git, you have to add files or folders separately. 
+
+##### Task 3
 
 Go to your profile on GitHub and set up a new repository for your website:
 
 - Click on "New"
 - Give your repository a name, click "public"(1), and make sure that you **don't** add a README.md (for now)
 { .annotate }
 
-    1.  The repository has to be public, otherwise you can't use the deployment service of GitHub pages.
+    The repository has to be public, otherwise you can't use the deployment service of GitHub pages.
 
-- Follow the instructions given by GitHub on how to push your local repository to GitHub
+- Follow the instructions given by GitHub on how to push your local repository to GitHub (*"Push an existing git repository"*). Refresh the GitHub repo. 
 
-##### Task 3
+???+ note "Pushing to GitHub"
+
+    You need to have an SSH key set up to be able to push to and pull from GitHub. Otherwise you will run in unneccessary troubles. Please visit the GitHub info page for instructions on how to do that.  
+
+
+##### Task 4
+
+1. After you pushed your repository to GitHub, please go to *"Settings"* of your repository. 
+
+![settings](assets/images/settings.png)
+
+2. Go to the section *"Pages"* under the left sidebar.
+3. Under "Build and deployment", use the branch dropdown menu and select a publishing source.
+
+![branch none](assets/images/branch_none.png)
+
+4. Change "None" to "gh_pages".
+
+![branch gh pages](assets/images/branch_ghpages.png)
+
+5. ==Click "Save".==
+
+If you've done all these steps, the deployment workflow should have been triggered and your website is deployed.
+
+##### Task 5
+
+1. Go to *"Actions"* in your repository.
+2. Click on *"pages build and deployment"*. You now see the deployment workflow.
+3. Under *"deployment"* you see a link. This is the link to your website. The link will always stay the same as long as you use this repository. 
+
+#### Future development of your website
+
+You're website is now officially online. If you want to make updates on your website, you can do that either locally in your folder (like before) or directly in the GitHub repository. Either way, the important things to remember are:
+
+- Your local folder is now linked to a GitHub repository. The deployment is done over the GitHub repository. Every change you make in your local website folder needs to be **pushed to GitHub** in order to be updated on your website. Don't let yourself be confused by the changes you see when you look at your website locally via the localhost address. ==YOUR CHANGES ARE NOT ONLINE UNLESS THEY ARE DEPLOYED BY GITHUB!==
 
-Deploy your website with GitHub Pages.
+- If you make changes in GitHub and later decide to continue working locally, you need to do a **```git pull```** first to integrate the changes you made in GitHub into your local git repository. 
 
-The developers of Material for Mkdocs wrote a very good documentation about how to deploy your website on GitHub. Thus, I won't add anything to this but redirect you to the section [Publishing your site] on their website. 
 
 [Publishing your site]: https://squidfunk.github.io/mkdocs-material/publishing-your-site/
 [Google Slides]: https://docs.google.com/presentation/d/16Rgdn_-uqjZVwmeyDhGL41vKMRCFA0dSom2IpreZ59I/edit?usp=sharing

docs/landing.md

@@ -8,6 +8,8 @@ The landing page is the first page people see when they visit your website. As y
 
 ### Using Markdown only
 
+##### Task 1
+
 Surely, you can just apply your newly acquired Markdown-skills to create a landing page. For example, the landing page of this website was created using only Markdown. 
 
 You can use [images] and [buttons] combined with a text. See my `index.md` file as template. How to insert contact information in form of buttons will be shown in the next section "Pretty and useful extras".
@@ -21,7 +23,7 @@ With the following tasks, you can create a landing page looking similar to this:
 
 ![landing](assets/images/example_landing.png)
 
-##### Task 
+##### Optional task 
 
 Try to use [html styles] to format and align your text (e.g., put a big text in the middle of the page). **Please see this [HTML info page] for formatting in html language.**
 
@@ -73,7 +75,19 @@ body {
 
 If you want to customize even more in html language (like blocking out the header and footer on the landing page), it makes sense to override the whole theme of Material for MkDocs and use your own html configurations for EVERYTHING. With this you have more freedom but also more work. See below an example setup for a `home.html` and `main.html` file. 
 
-**1.**
+**1.** 
+
+Create a ```overrides``` directory inside your website folder (**not** inside the ```docs``` folder!).
+
+**2.**
+
+Open your ```mkdocs.yml``` file and put the following:
+```yml
+theme:
+  custom_dir: overrides
+```
+
+**3.**
 
 Create a `home.html` in your `overrides` directory and put the following content:
 ```html
@@ -148,7 +162,7 @@ Create another file in the same directory called `main.html` with the following
 {% extends "base.html" %}
 ```
 
-**3.**
+**4.**
 
 Open your `index.md` file and put the following content:
 ```md

docs/troubleshoot.md

@@ -0,0 +1,34 @@
+**What if...**
+
+##### Preview server
+
+**... I get an error message in the terminal?**
+
+This can happen sometimes. Try those things in the given order:
+
+- kill the current process in your terminal and start ```mkdocs serve``` again.
+- check your ```mkdocs.yml``` file for indentation errors. 
+- check your ```mkdocs.yml``` file for any other errors such as misspelling, invalid variable names, missing parameters etc. 
+
+##### YAML-file
+
+**... my website doesn't update?**
+
+- Make sure you ==saved== the updates on your ```mkdocs.yml```. 
+- Make sure that you considered the indentation rules in your ```mkdocs.yml``` file.
+
+##### Images and PDFs
+
+**... my pdfs and images are not shown?**
+
+- Make sure you used the correct code for inserting an image. 
+- Is the path to your image correct?
+- Make sure that the folders where you store your pdfs and images are inside the ```docs``` folder. This is important because in your ```mkdocs.yml``` file you configured that the directory for your content (=```docs_dir```) is called ```docs```. So MkDocs expects ==everything you want to have on your website to be somewhere inside ```docs```.==
+
+**... my image shows in the local website but not after I deployed it with GitHub?**
+
+The deployment server is a bit more sensitive than the preview server. 
+
+- Make sure you used the correct code for inserting an image. 
+- Is the path to your image correct?
+- Check the ==extension of your file==. If you changed the extension at some point, the image will not be recognized. E.g., if your image was originally a JPEG (.jpg) and you converted it to a PNG (.png) the image will not be recognized.     

mkdocs.yml

@@ -56,6 +56,7 @@ nav:
 - Creating a Landing Page: landing.md
 - Pretty and useful extras: extras.md
 - Deployment on GitHub: deploy.md
+- Troubleshooting: troubleshoot.md
 - Further resources: resources.md