hosting papers in private repo and adding first paper notes

Signed-off-by: vsoch <vsochat@stanford.edu>

README.md

@@ -1,15 +1,16 @@
-# Notes-jekyll
+# Build Notes
 
-This is a Jekyll template that is optimized to serve as a note-taking organizational tool.
-Specifically, we can easily insert citations into Markdown (you heard that right, 
-no LaTeX required here!) and render our notes on GitHub pages. The theme is based on 
-[notetheme](https://github.com/dinhanhthi/notetheme) and has added 
-[jekyll-scholar](https://github.com/inukshuk/jekyll-scholar) for citation management.
+This is a Jekyll template for taking and sharing notes for the BUILD SC project.
+It is a modified version of [notes-jekyll](https://github.com/vsoch/notes-jekyll) 
+that is optimized to serve as a note-taking organizational tool. We have changed the following
 
-![assets/img/home.png](assets/img/home.png)
+ - the overall design
+ - papers are stored in a private repository, [build-bib](https://github.com/llnl/build-bib).
+ - the front page is optimized to share information about the BUILD project.
 
 ## Getting started
 
+ - [Updating References](#how-to-update-references) from the private repository with papers
  - [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
@@ -18,36 +19,72 @@ no LaTeX required here!) and render our notes on GitHub pages. The theme is base
 
 Since the jekyll-scholar plugin doesn't work on GitHub pages, we provide a GitHub action to do it easily.
 
-## How to add or view papers
-
-If you want to interact with your bibliography via a citation manager, you can
-easily use something like [BibDesk](https://bibdesk.sourceforge.io/) to keep track of papers.
-For example, the references file under [_bibliography](_bibliography) is also 
-linked in the root directory, and it could include links to papers in [papers](papers).
-By default, we expect the name of the paper pdf to match the name of the citation 
-(and BibDesk will do this automatically for you, this is called "AutoFile") and it's
-suggested to do a format like `papers/%f{Cite Key}-%u%e`.
-
-## How to take notes
-
-Once you have your papers, you of course want to take notes!
-So how can we turn a simple setup of a folder and bibtex file into a nice organizational
-structure to take notes and easily cite references? The answer is to take advantage
-of Jekyll, and provide a base container and suggested organization to take notes.
-You can add references to [build.bib](build.bib), which is linked to the same file
-in the [_bibliography](_bibliography) folder. These rederences will render on the front page,
-and be available to cite anywhere in the site where you can write markdown.
-While we could investigate solutions to run a web server and render a PDF, the simpler
-approach of using Markdown will likely be more comfortable for users with different
-editor preferences.
+## How to Update References
+
+If you want to physically add papers, this needs to be done in the [build-bib](https://github.com/llnl/build-bib)
+repository, which is private and you should have access to if you are part of the project.
+The format of the paper PDFs in the "papers" folder of this repository is expected to match
+`papers/%f{Cite Key}-%u%e`.
+
+To then update [references](_bibliography/references.bib) here, you'll need access to the [builb-bib](https://github.com/llnl/build-bib)
+repository. Specifically, you should be able to clone it with git. Then you can simply run:
+
+```bash
+./pull_references.sh
+```
+And the references file in [_bibliography](_bibliography) will be updated.
+
+## How to make changes
+
+This is a GitHub repository, so as you would imagine, we can use the general git workflow
+to collaborate on notes. This means forking the repository and then cloning your fork:
+
+```bash
+git clone git@github.com/<username>/build-notes
+cd build-notes
+```
+And then checkout out a new branch, ideally with a meaningful name:
+
+```bash
+git checkout -b notes/myusername-papername
+```
+And then making changes and pushing to your remote, and opening a pull request.
+For more instructions on this process, see the [getting started](https://vsoch.github.io/build-notes/getting-started/) page.
+
+## How to write content
+
+Writing content comes down to editing or creating a Markdown file in the right place.
+Yes, you are most definitely free to update pages and notes created by others! If you think something
+is fundamentally wrong or warrants discussion, it's probably best to open an [issue first](https://github.com/vsoch/build-notes/issues).
+
+### Papers
+
+Notes on specific papers can be added to the the [_papers](_papers) folder. Specifically, you should name the markdown file to match the paper key in the BibTex, but *remove `:` characters*.
+
+### Thrusts
+
+Each thrust has it's own file in the [thrusts](_notes/thrusts) notes folder. These files already exist so you should not need to add anything.
+
+### Topics
+
+A topic is a general theme that you might want to extract from many papers, and write consolidated notes for (e.g., solvers).
+To create a new topic, create a markdown file in the [notes](_notes). You can organize your files in subfolders however you like.
+
+### Writeups
+
+[Posts](_posts) are intended for any kind of more structured writeup that warrants a timestamp. For example, we have a <a href="https://vsoch.github.io/build-notes/how-to-write-notes">writeup</a> that demonstrates all the different kind of formatting you can do.
+
+### Pages
+
+Any higher level page (e.g., this one, or about) generally can be found in the [pages](pages) folder. These pages aren't automatically linked so you would need to manually add them somewhere on the side (e.g., the table of contents on the sidebar).
 
 ## 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 git@github.com:vsoch/notes-jekyll
+git clone git@github.com:vsoch/build-notes
 cd notes-jekyll
 ```
 
@@ -67,7 +104,7 @@ 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 .
+$ docker build -t build-notes .
 ```
 
 And then run it, making sure to bind the correct directory to where it is expected
@@ -158,4 +195,3 @@ on GitHub pages.
 
 This code has inherited the original [LICENSE](LICENSE) that must be preserved
 from the repositories where it originates from.
-