From a26465ac4df8d4fd4f098eb32bfcc78a6780935b Mon Sep 17 00:00:00 2001
From: Henry Webel <heweb@dtu.dk>
Date: Fri, 4 Oct 2024 08:21:13 +0200
Subject: [PATCH] :memo: add some hints

- based on first workshop
---
 README.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/README.md b/README.md
index 32da005..e7d83c0 100644
--- a/README.md
+++ b/README.md
@@ -24,6 +24,10 @@ see instructions
 
 ### 3. Edit files
 
+You will need to know the Markdown to format your text. See 
+[this overview on GitHub](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) 
+or [this cheatsheet](https://www.markdownguide.org/cheat-sheet/) to get started.
+
 - update in `conf.py` at least the author, project and copyright information at the top
   - also update two urls to your repository:
    ```json
@@ -36,8 +40,17 @@ see instructions
 - use [pandoc](https://pandoc.org/try/) to convert your previous files into markdown or
   reStructuredText
 
+Troubleshooting:
+ - don't forget to add new files to the `index.md` file
+ - each document should have a title (`# title`) using a main heading and otherwise 
+   nested headlines (subheadings followed by sub-subheadings)
+
 ### 4. Build the site locally
 
+Sphinx uses the configuration file `conf.py` to set up the site. The `requirements.txt` file
+contain extensions and themes that are used additionally to sphinx to build the site.
+The layout of the website is defined in the `index.md` file.
+
 > Have look at `.github/workflows/build_website.yaml` to see how the site is built
 > if you are interested.
 
@@ -65,3 +78,4 @@ Follow
 to publish the website using GitHub Pages.
 
 - Select the `gh-pages` branch as the source for the GitHub Pages site (currently step 7)
+- add the deployed url to your "About" on the right sight of the repository