add writeups of the build process and how the repo works

2 files changed, 77 insertions, 0 deletions

diff --git a/BUILDING.md b/BUILDING.md
new file mode 100644
index 0000000..d39e5c5
--- /dev/null
+++ b/BUILDING.md
@@ -0,0 +1,25 @@
+# Building this Project
+
+For a quick-and-dirty build, just run `make all`.
+To specify the directory to build into, you can pass in BUILD_DIR, e.g. `make BUILD_DIR=../_build all`.
+
+Although the project is quite fast to build, we support [parallel execution](https://www.gnu.org/software/make/manual/html_node/Parallel.html).
+This means you can pass the `-j` flag followed by the number of cores to compile markdown files in parallel.
+
+## Git Build (for maintainers)
+This is my general process:
+```bash
+export BUILD_DIR=$(mktemp -d)
+make all
+
+git checkout build
+cp -r $BUILD_DIR/* .
+
+git add .
+git commit -m "build: $(date)"
+git push
+
+unset BUILD_DIR
+```
+
+_(CI/CD is scary, so I avoid it)_
diff --git a/STRUCTURE.md b/STRUCTURE.md
new file mode 100644
index 0000000..70a319e
--- /dev/null
+++ b/STRUCTURE.md
@@ -0,0 +1,52 @@
+# STRUCTURE
+This document outlines the basic structure of the repository.
+I will be outlining it in a repo-agnostic manner, so you could treat this kind of like a guide to set up a similar blog-like website.
+
+## Markdown files
+all markdown files live in `md/`.
+They all have frontmatter with at least a `title`, however I also utilize frontmatter for other features of the site
+
+Images are stored really anywhere in the `md/` directory, as long as pandoc can find them up when building.
+
+At compile time, pandoc picks up all of these markdown files and puts them in `${BUILD_DIR}/stories`.
+Some notable pandoc settings:
+- `--embed-resources`: This is because I don't want to bother with images in the final build, so I just have pandoc build them into the markdown files.
+  As a side benefit, this means that one html file can be used independently and it will contain all of the styling, images, etc for the page.
+
+- `--template template.html`: This puts the pandoc output into a little template I made.
+  In the template, I only have some css, a title line, and a link back to the homepage, but I could see this growing in the future.
+
+## Generation Scripts
+I have a few scripts living in `gen/`.
+These scripts all output valid markdown, which is then parsed by pandoc and placed in the appropriate location.
+
+It determines where the files go based on the file name.
+- `gen/gen_index.md` => `build/index.html`
+- `gen/gen_life_lessons.md` => `build/life_lessons.html`
+You get the idea.
+
+### Example
+For an example of a script, lets go through a simplified version of `gen_index.sh`.
+The index page has a link to every markdown file, so it's very important.
+
+```
+#!/usr/bin/env bash
+echo "---"
+echo "title: All Stories"
+echo "---"
+echo
+
+for i in md/*.md; do
+  title=$(grep "^title: " "$i" | sed -E 's/^title: (.*)/\1/')
+  dest="/stories/$(basename "$i" .md).html"
+  echo "- [$title]($dest)"
+done
+```
+
+First, we print some frontmatter to establish a title.
+
+Next, we iterate through the `md/` directory, finding all of the markdown files.
+We extract the title from the frontmatter using `sed`, and establish where we want the link to point.
+After printing it in the markdown link format, the script is done.
+
+When building the project, `make` runs this script, converts the output to html, and puts it in the `$BUILD_DIR`