updated README with best practice jekyll notes for our site

Author: orbeckst

README.md

@@ -25,21 +25,44 @@ For further notes see [Web development](#web-development) below.
 Check out the repository, edit the pages under `_posts`, and push
 commits. The published pages are on the *master* branch.
 
+### File name 
+
 Blog posts should be placed under `_posts`. These should have names
 according to:
 
     YEAR-MONTH-DAY-title.md
 
 where `YEAR` is a four-digit number, and `MONTH` and `DAY` are both two-digit
-numbers. Each post should have a header with:
+numbers. 
+
+### Meta data header of markdown files
+
+Each post should have a header with:
 
     ---
     layout: post
-    title: The title of this post
+    title: "The title of this post"
     ---
 
-in order for it to be picked up by the paginator. The `blog` directory should
-not be touched, as this is only here to set the paginator.
+in order for it to be picked up by the paginator. You *must* put the title in
+quotation marks if it contains special characters.
+
+Other keys can be in the header (such as *date* (overrides file name date) or
+*order* (for [static pages](#static-pages))).
+
+
+### Section headers
+
+* Do not put a title at the start of the post. The title from the metadata will
+  create the level 1 header.
+* Do not use level 1 (`# ... #`) headers, level 1 is reserved for the overall
+  title.
+* Use level 2 (`## ... ##`) or higher level headers.
+
+
+### Good to know
+
+The `blog` directory should not be touched, as this is only here to set the paginator.
 
 * The `_site` directory is generated by Jekyll on the GitHub server side and
   should not be included in commits.
@@ -100,34 +123,57 @@ including MathJax.
 Drop images into the `public/images` directory and include them like
 
 ```html
-  <img src="{{site.images}}/imagename.png"
+  <img src="{{ site.images }}/imagename.png"
    style="float: right" alt="alternative text" width="30%"/>
    ```
 
 or use Markdown
 ```markdown
-![alternative text]({{site.images}}/imagename.png)
+![alternative text]({{ site.images }}/imagename.png)
 ```
 
 
 ### Notes on using Jekyll ###
 
+#### Absolute site links
+
 For links between pages to work, generate absolute links with `site.baseurl`
 liquid tag:
 
 ```
-[see citations]({{ site.baseurl }}/pages/citations
+[see citations]({{ site.baseurl }}/pages/citations)
 ```
 
-The example will link to the file `/pages/citations`. Also note that one does
-not need spaces between the configuration variable and the curly braces (i.e.
-`{{ site.baseurl }}/` as typical seen), so I avoid them to prevent the editor
-breaking the line inside the curly braces (which upsets Jekyll greatly).
+The example will link to the file `/pages/citations`.
+
+**Note**: Always put a slash `/` *after* `{{ site.baseurl }}`.
 
 We define additional variables in `_config.yml` and use them with liquid tags.
 In particular, the sidebar `_includes/sidebar.html` is configured with
 additional links that are all stored in the config file.
 
+#### Links to blog posts
+Use the
+[post_url](https://jekyllrb.com/docs/liquid/tags/#linking-to-posts)
+liquid tag `{% post_url FILENAME_NO_SUFFIX %}`. *FILENAME_NO_SUFFIX*
+is something like "2025-02-11-GSOC2024-final-blog" to reference the
+file `_posts/2025-02-11-GSOC2024-final-blog.md`. Note that the `.md`
+suffix is *not* included.
+
+Prefix with the baseurl so you use it something like
+```markdown
+See the [GSOC 2024 blog post]({{ site.baseurl }}/{% post_url 2025-02-11-GSOC2024-final-blog %}) 
+for more details.
+```
+
+#### Liquid tags
+
+One does not need spaces between the configuration variable and the
+curly braces (i.e.  `{{ site.baseurl }}/` as typical seen). If you
+find that your editor breaks the line inside the curly braces
+(which upsets Jekyll greatly) then omit the space.
+
+
 
 ### Local testing ###