updating usage documentation and adding remaining papers

Signed-off-by: vsoch <[email protected]>

Dockerfile

@@ -1,5 +1,7 @@
 FROM jekyll/jekyll:4.1.0
 
+# docker build -t notes-jekyll .
+
 WORKDIR /srv/jekyll
 COPY Gemfile .
 COPY Gemfile.lock .

README.md

@@ -10,6 +10,8 @@ no LaTeX required here!) and render our notes on GitHub pages. The theme is base
 
  - [Add papers](#how-to-add-or-view-papers) either manually or with a citation manager
  - [Take notes](#how-to-take-notes) in Markdown, as you typically would
+ - [Develop Locally](#develop-locally) using Jekyll natively or via a container
+ - [Making changes](#how-to-make-changes) to structure or design of template.
  - [Push to GitHub](#deploy-to-github-pages) to use the GitHub action to automatically deploy the site.
 
 Since the jekyll-scholar plugin doesn't work on GitHub pages, we provide a GitHub action to do it easily.
@@ -37,21 +39,121 @@ While we could investigate solutions to run a web server and render a PDF, the s
 approach of using Markdown will likely be more comfortable for users with different
 editor preferences.
 
+## Develop Locally
+
+First, you should clone the repository (and likely fork to your own user account first).
+The command below would have "vsoch" replaced with your GitHub username.
+
+```bash
+git clone [email protected]:vsoch/notes-jekyll
+cd notes-jekyll
+```
+
+If you have jekyll installed locally, you can typically then install dependencies with
+bundle.
+
+```bash
+$ bundle install
+```
+
+And then run the development server, which will update with changes:
+
+```bash
+bundle exec jekyll serve
+```
+
+If not, then you can use a container environment to develop. First, build the container:
+
+```bash
+$ docker build -t notes-jekyll .
+```
+
+And then run it, making sure to bind the correct directory to where it is expected
+in the container, and exposing port 4000.
+
+```bash
+$ docker run --rm -v "$PWD:/srv/jekyll" -p 4000:4000 notes-jekyll
+Configuration file: /srv/jekyll/_config.yml
+            Source: /srv/jekyll
+       Destination: /srv/jekyll/_site
+ Incremental build: disabled. Enable with --incremental
+      Generating... 
+       Jekyll Feed: Generating feed for posts
+                    done in 2.825 seconds.
+ Auto-regeneration: enabled for '/srv/jekyll'
+    Server address: http://0.0.0.0:4000/notes-jekyll/
+  Server running... press ctrl-c to stop.
+```
+
+You should then be able to open your browser to [http://127.0.0.1:4000](http://127.0.0.1:4000).
+You can then edit files on your local machine, and the server will refresh with changes.
+
+### Docker to Local
+
+If you use a Docker container at any point and then run the local development server,
+you'll likely get a permissions error since the Docker user wrote the `_site` folder.
+You can easily fix this by entirely removing the site folder - it will be re-generated.
+
+```bash
+rm -rf _site
+```
+
+## How to make changes
+
+There are several easy ways to make changes, most of which are represented in the [_config.yml](_config.yml).
+For the most part, fields are self explanatory. The following sections might be of particular interest:
+
+### Jekyll scholar
+
+The `scholar` section includes information on how to generate references.
+
+```
+scholar:
+  style: _bibliography/my-ieee.cls
+  bibliography: references.bib
+  bibliography_template: bibitem-template
+  repository: papers
+  details_dir: "paper-details"
+  details_layout: "details.html"
+# details_permalink: "/notes-jekyll/:details_dir/:key:extension"
+# Ensure that details are not printed twice
+  details_link: ""
+```
+
+#### style
+The style for your citations is represented with `style`, above to be `_bibliography/my-ieee.cls`
+
+#### bibliography
+The default bibliography file is references.bib, also located in [_bibliography](_bibliography)
+
+#### bibliography_template
+The template for each reference (`bibliography_template`) is in [_layouts/bibitem-template.html](_layouts/bibitem-template.html)
+
+#### repository
+The folder with physical papers (`repository`), named according to their key, is in [papers](papers).
+
+#### details_layout
+The details page for each paper (`details_layout`) should be a template in [_layouts/details.html](_layouts/details.html)
+
+#### details_dir
+The path where the paper detail files will be rendered (`details_dir`) is `paper-details`. In practice I found that this was not rendered correctly - it was missing the base url. So I hide the default details render via `details_link` being empty, and add my own in the `bibliography_template`. For this same reason, the default `details_permalink` did not seem to work. Finally, in the documentation it noted that `details_link` should be a key, but in practice I found that it did not work.
+
+
+For all of the above, this generally means that you can change the location of papers pages, your bibliography, and
+how the citations are formatted. There are quite a few other settings, and I found it helpful to look
+at the [jekyll-scholar README](https://github.com/inukshuk/jekyll-scholar) and the [defaults.rb](https://github.com/inukshuk/jekyll-scholar/blob/master/lib/jekyll/scholar/defaults.rb) file. Everything is exposed from classes to help
+style your entries to ordering and types.
+
 ## Deploy to GitHub pages
 
 When you push to the main branch, you will trigger a build defined as a [GitHub workflow](.github/workflows/build.yml)
 that will deploy the site to GitHub pages.
 
+For more instructions on how to write references into posts, see [notes-jekyll](https://vsoch.github.io/notes-jekyll/about/)
+on GitHub pages.
+
 ## LICENSE
 
 This code has inherited the original [LICENSE](LICENSE) that must be preserved
 from the repositories where it originates from.
 
-## TODO
-
-- Need to add pdfs for each paper example
-- format bibtex
-- add fun image to 404 page
-- We want to be able to click on a reference on any page and open the PDF
-- We also want a link for each reference that shows all the places it's cited (harder)
-- create usage guide

_bibliography/my-ieee.cls

@@ -131,7 +131,7 @@
       <else>
         <choose>
           <if variable="URL">
-            <text variable="URL" prefix="&lt;a href=&quot;" suffix="&quot;&gt;"/>
+            <text variable="URL"/>
             <text variable="title" quotes="true" suffix="&lt;/a&gt;"/>
           </if>
           <else>

_bibliography/references.bib

@@ -90,7 +90,7 @@ @article{lind2019proof
 	pages = {7388},
 	publisher = {Nature Publishing Group},
 	title = {Proof of principle study of a detailed whole-body image analysis technique, ``Imiomics'', regarding adipose and lean tissue distribution},
-    url = {https://www.nature.com/articles/s41598-019-43690-w},
+        url = {https://www.nature.com/articles/s41598-019-43690-w},
 	volume = {9},
 	year = {2019}
 }
@@ -113,7 +113,7 @@ @article{sjoholm2019whole
 	pages = {6158},
 	publisher = {Nature Publishing Group},
 	title = {A whole-body FDG PET/MR atlas for multiparametric voxel-based analysis},
-    url = {https://www.nature.com/articles/s41598-019-42613-z},
+        url = {https://www.nature.com/articles/s41598-019-42613-z},
 	volume = {9},
 	year = {2019}
 }
@@ -225,15 +225,3 @@ @article{van2013mapping
 	volume = {82},
 	year = {2013}
 }
-
-@mastersthesis{pilia2018groupwise,
-	author = {Pilia, Martino},
-	institution = {Acta Universitatis Upsaliensis},
-	number = {18015},
-	pages = {111},
-	school = {Uppsala University},
-	series = {IT},
-	title = {Groupwise whole-body {MR} image registration guided by zero-average volume changes},
-    url = {http://urn.kb.se/resolve?urn=urn%3Anbn%3Ase%3Auu%3Adiva-371560},
-	year = {2018}
-}

_data/categories.yml

@@ -1,4 +1,4 @@
-- slug: notetheme
-  name: NoteTheme
-- slug: it
-  name: Information Technology
+- slug: registration
+  name: registration
+- slug: notes-jekyll
+  name: notes-jekyll

_includes/footer.html

@@ -1,6 +1,7 @@
 <footer class="page-footer teal">
   <div class="footer-copyright">
     <div class="container text-white">
+          <a class="waves-effect" href="{{ site.baseurl }}/tags">Tags</a> | <a class="waves-effect" href="{{ site.baseurl }}/categories">Categories</a> | <a class="waves-effect" href="https://github.com/{{ site.repository }}">GitHub</a>
     </div>
   </div>
 </footer>

_includes/head.html

@@ -14,7 +14,7 @@
     {% if page.title %}
       {{ page.title | escape }} | {{ site.title }}
     {% else %}
-      {{ site.title | escape }} | You cannot remember everything
+      {{ site.title | escape }} | {{ site.description }}
     {% endif %}
   </title>
 
@@ -46,8 +46,9 @@
   <link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/materialize/0.99.0/css/materialize.min.css">
   <link rel="stylesheet" href="//fonts.googleapis.com/icon?family=Material+Icons">
   <link rel="stylesheet" href="{{ site.baseurl }}/assets/css/main.css">
-
   <link rel="stylesheet" href="{{ site.baseurl }}/assets/css/thi_scss.css">
+  <link rel="preconnect" href="https://fonts.gstatic.com">
+  <link href="https://fonts.googleapis.com/css2?family=Source+Sans+Pro:wght@200;400;600&display=swap" rel="stylesheet"> 
 
   {% for css in layout.css %}
     {% if css contains "//" %}

_includes/header-toc.html

@@ -8,10 +8,10 @@
     <div class="userView thi-userView">
       <div class="background"></div>
         <a href="{{ site.baseurl }}/">
-          <img style="display:inherit;" class="circle z-depth-2" src="{{ site.baseurl }}{{ site.user.avatar }}">
+          <img style="display:inherit;" class="circle z-depth-2" src="{{ site.baseurl }}/assets/img/napkins.png">
         </a>
       <span style="font-size: larger;" class="white-text name">{{ site.repository }}</span>
-      <span class="white-text email"><a style="color: #bdbdbd;" href="{{ site.repository | prepend: 'https://github.com/'' }}">{{ repository }}</a></span>
+      <span class="white-text email"><a style="color: #bdbdbd;" href="{{ site.repository | prepend: 'https://github.com/' }}">{{ repository }}</a></span>
     </div>
   </div>
   <div style="padding: 10px;">

_includes/header.html

@@ -11,7 +11,7 @@
           <img style="display:inherit;" class="circle z-depth-2" src="{{ site.baseurl }}/assets/img/napkins.png">
         </a>
       <span style="font-size: larger;" class="white-text name">{{ site.title }}</span>
-      <span class="white-text email"><a style="color: #bdbdbd;" href="{{ site.repository | prepend: 'https://github.com/' }}">{{ site.repository }}</a></span>
+      <span class="white-text email"><a style="color: white; font-weight:400" href="{{ site.repository | prepend: 'https://github.com/' }}">{{ site.repository }}</a></span>
     </div>
   </li>
   <li style="padding: 10px;">
@@ -26,5 +26,7 @@
     <li><a class="waves-effect" href="{{ site.baseurl }}/">Home</a></li>
     <li><div class="divider"></div></li>
     <li><a class="waves-effect" href="{{ site.baseurl }}/tags">Tags</a></li>
+    <li><div class="divider"></div></li>
+    <li><a class="waves-effect" href="{{ site.baseurl }}/categories">Categories</a></li>
   </div>
 </ul>

_includes/related-posts.html

@@ -23,7 +23,7 @@
 </style>
 
 <div class="related-posts">
-  <i class="material-icons thi-icon">grade</i><span>Related Posts</span>
+  <i class="material-icons thi-icon">grade</i><span>Related Notes</span>
   {% assign RELATED_POSTS_THRESHOLD = 4 %}
   <ul>
     {% assign related_post_count = 0 %}

_includes/search.html

@@ -1,4 +1,4 @@
 <form action="{{ site.baseurl }}/search" method="get">
-	<input type="search" name="q" {% if include.add_id %}id="search-input"{% endif %} placeholder="Search something?" autofocus>
+	<input type="search" name="q" {% if include.add_id %}id="search-input"{% endif %} placeholder="Search for..." autofocus>
 	<input type="submit" value="Search" style="display: none;">
-</form>
+</form>

_includes/toc.html

@@ -6,4 +6,4 @@
   *  Auto generated table of contents
   {:toc}
   </div>
-</div>
+</div>

_layouts/details.html

@@ -11,13 +11,9 @@ <h6>{{ page.entry.author }}</h6>
 
 <div class="language-plaintext highlighter-rouge">
 <div class="highlight">
-<pre class="highlight">
-<code>
+<pre class="highlight"><code>
 {{ page.entry.bibtex }}
-</code>
-</pre>
-</div>
-</div>
+</code></pre></div></div>
 
 </body>
 </html>

_layouts/post.html

@@ -17,8 +17,7 @@
       <h3>{{page.title}}</h3>
       <span>
         Posted on
-        <span style="display: initial;" class="cat-class">{{page.date | date: "%d/%m/%Y"}}</span>,
-        in
+        <span style="display: initial;" class="cat-class">{{page.date | date: "%d/%m/%Y"}}</span>
         {% for cat in page.categories %}
           {% for catDat in site.data.categories %}
             {% if catDat.slug == cat %}

_posts/2020-11-27-registration.md

@@ -3,11 +3,9 @@ title: Registration
 categories: registration
 tags: [registration]
 maths: 1
-comment: 1
+toc: 1
 ---
 
-{% include tip.html content="These are obviously not real notes!" %}
-
 {% include toc.html %}
 
 ## Section I
@@ -37,4 +35,6 @@ Ultrices eros in cursus turpis massa tincidunt dui. Non quam lacus suspendisse f
 Commodo elit at imperdiet dui accumsan. Tellus at urna condimentum mattis pellentesque. Mi in nulla posuere sollicitudin. A pellentesque sit amet porttitor eget dolor. Metus dictum at tempor commodo ullamcorper a lacus. Tellus at urna condimentum mattis pellentesque id nibh tortor. Eu ultrices vitae auctor eu augue ut lectus arcu bibendum. Risus quis varius quam quisque id diam vel quam elementum. Sagittis eu volutpat odio facilisis mauris sit amet massa. Orci ac auctor augue mauris augue. In metus vulputate eu scelerisque. Vitae proin sagittis nisl rhoncus. Nisi vitae suscipit tellus mauris a diam maecenas sed enim. Tellus mauris a diam maecenas sed enim ut sem {% cite klein2009adaptive %}. Enim blandit volutpat maecenas volutpat blandit aliquam etiam erat. Arcu risus quis varius quam quisque id diam. Rhoncus urna neque viverra justo nec.
 
 
-{% bibliography %}
+<hr>
+
+{% bibliography --cited %}