Added git commands.

content/git/_index.md

@@ -21,20 +21,22 @@ This is where I keep my notes on how to do things.
 Git is project and folder-centered, and to start using git go to the root folder
 of a project you want to place under source control and initialize it:
 
-```shell
+```bash
 $ mkdir a-new-project
+$ touch README.md
 $ git init
 ```
 
 This creates a new folder, `.git`, where Git will store your commit history and
-some configuration details.
+some configuration details.  Git will usually not create a repository without
+_something_ to store in it, but see the [`git start` alias](#config) below.
 
 ## Putting files into git
 
 To put files under source control, you must add them.  To update the entire
 folder, switch to the root of the project and add _all_ of it:
 
-```shell
+```bash
 $ git add .
 $ git commit
 ```
@@ -47,7 +49,7 @@ don't have to explain too much!
 If your commit message could be a single line, you can add it directly from the
 command line:
 
-```shell
+```bash
 $ git add .
 $ git commit -m "Updated the widget to widgetize."
 ```
@@ -58,17 +60,17 @@ been modified, and will delete any files that you have deleted, from the
 repository. (Deleted files still exist in the history and can always be
 recovered.)
 
-```shell
+```bash
 $ git commit -am "Updated the widget to widgetize."
 ```
 
-## Git Configuration
+## Git Configuration {#config}
 
 You can have a global Git configuration file, `$HOME/\.gitconfig`, in which you
 keep your personal information and command aliases, which is one of three ways
 you can add your own commands to Git.
 
-```shell
+```bash
 [user]
     name = Elf M. Sternberg
     email = someguy@example.com
@@ -77,13 +79,68 @@ you can add your own commands to Git.
     unstage = reset -q HEAD --
     nevermind = !git reset --hard HEAD && git clean -d -f
 	wip = for-each-ref --sort='authordate:iso8601' --format='%(color:green)%(authordate:relative)%09%(color:white)%(refname:short)' refs/heads	
-    stem = "!f() { git checkout -b $1 master; }; f"
+    stem = "!f() { git checkout -b $1 develop; }; f"
     start = !git init && git commit --allow-empty -m \"Initial commit\"
 ```
 
-I'll explain each of these eventually, but for now, just know that if you want
+## Git Aliases {#aliases}
-your commits to be attributed to the right person, you must have the `[user]`
+
-block, and 
+Aliases are commands that you can run *in git* as if they were part of the git
+toolset, but their functionality is defined by you.  The five aliases shown
+above are my "must haves."  They represent the way I work.
+
+- `unstage` is something I do a lot.  Maybe it's my ADHD, but I often add
+  something to the git staging area, then realize that the work was incomplete
+  and have to go back.  This command does that, and I hated memorizing it.
+- `nevermind` is for when your work has gone off the rails; your stab at solving
+  the problem has taken you places you didn't want to be.  This command resets
+  you to exactly where you were before you started hacking.
+- `wip` stands for "works in progress"; it shows you a list of branches
+  currently live in your local project, in the order from oldest to newest, with
+  a text that tells you your last commit was "yesterday" or "3 months ago".
+- `stem` creates a new branch off the develop branch (you can change that to
+  main or canon or whatever). This is the most common workflow I have at home,
+  and this command allows me to get to it quickly. The syntax tells git to use
+  the bash to populate the new branch name, as the default alias format can
+  only take arguments at the end, and the new branch name must be injected
+  before the source branch.
+- `start` creates a git repository out of a completely empty folder.  This might
+  seem odd, but it's actually a very useful way of introducing a new project and
+  ensuring git is ready to go.
+
+## Git Extensions
+
+Just like aliases, you can add whole unique commands to git, as long as the
+extension name doesn't conflict with one of git's internal commands.  The
+syntax for doing so is to create a script (in any language!) and name it
+`git-your-extension-name`, and you call it by invoking git and giving it the
+extension name. 
+
+For example, if you write documentation and you want to know how many words
+you've written since your last commit, you can create a Bash script named
+`git-wc` (word count):
+
+``` bash
+#!/bin/bash
+REM=`git diff --word-diff=porcelain -U $* | grep '^-' | sed 's/^-//' | wc -w`
+ADD=`git diff --word-diff=porcelain -U $* | grep '^+' | sed 's/^+//' | wc -w`
+DIF=`expr $ADD - $REM`
+echo "Word count: $DIF"
+```
+
+## Add vs Commit
+
+You may have noticed that there's a two-step to committing your work; you `add`
+it, then `commit` it.  `add`ing it puts it into the `staging area`.  The primary
+goal of this design is to allow you to commit only parts of your project, rather
+than committing everything at once.  By creating an index of what-to-commit, and
+then allowing you to write your commit message afterward, you have more control
+over the development process.
+
+If you're completely reassured of your skillz as a _leet koder dood_, you could
+always create an alias that stages, commits, and pushes to your remote
+repository all at once.  I don't recommend that.
+
 
     
 

content/zola/_index.md

@@ -17,18 +17,20 @@ categories=["Web Development", "Static Site Generation", "Zola"]
 collection of markdown documents in a folder-structured hierarchy, using a
 corresponding collection of HTML templates, which in turn use a corresponding
 collection of SASS collection and a collection of HTML templates. The templating
-language is called [Tera](https://tera.netlify.app).
+language is called [Tera](https://tera.netlify.app). For convenience, all the
+functions defined for both Tera and Zola have been compiled into lists in this
+document.
 
 If you need anything else (Typescript built into Javascript, templates other
-than Zola's internal, static file conversion, etc.), you'll need separate
+than Zola's internal, static file conversion, etc.), you'll need separate build
 toolchains for those.
 
 ## Mental Model for Zola
 
-A website built with Zola originates with the `content/` folder.  Inside that
+Elf, a website built with Zola originates with the `content/` folder. Inside
-folder, every markdown document and every folder creates a corresponding page in
+that folder, every markdown document and every folder creates a corresponding
-the constructed website.  There are only *two* models you have to understand
+page in the constructed website. There are only *two* models you have to
-Zola: *sections* and *pages*.
+understand Zola: *sections* and *pages*.
 
 A *section* is a folder with a file named `_index.md` in it; note the
 underscore, which signifies the section definition file. For these documents, a
@@ -53,7 +55,7 @@ by which every template has access to the metadata (and even the content!) of
 every other markdown document, arranged in the hierarchy described in the
 `content` folder.
 
-### Recommendation
+### Proces Recommendation
 
 1. Design your document hierarchy first.
 2. Construct your content folder to support that hierarchy.
@@ -62,6 +64,13 @@ every other markdown document, arranged in the hierarchy described in the
 5. Build the corresponding `Page` templates.
 6. Worry about Sass afterward
 
+### Construction Recommendation
+
+Use the `include` block more than the `extends` block.  Build your websites by
+composition, not inheritance with override.  Ignore the way Django and everyone
+else does it.  Composition may result in some small amount of repetition, but
+the legibility and coherency of your project will more than compensate.
+
 ## Running Zola
 
 Zola has only a few commands:
@@ -314,42 +323,18 @@ some optional content. The TOML header _may_ specify which template to use to
 render the section info, otherwise Zola falls back to the default at
 `./templates/section.html`.
 
+#### Section Header in every `_index.md` file
+
 The arguments that con be placed into the TOML header of a the `_index.md` file are:
 
-- `title`: a string
+{{ definition_list(source="zola/section_arguments.json") }}
-- `description`: a string
+
-- `draft`: `true`/`false` if this section should be included in builds
+#### Section Object delivered to the template:
-- `sort_by`: Sorting function to use: `date`, `title`, `weight`, or `none`
-- `weight`: Used to provide subsection weight to a parent section
-- `template`: The template to render this section. Defaults to `./templates/section.html`
-- `page_template`: The default template to render pages in this section. Pages with this field specified overide this setting
-- `paginate_by`: Number of pages to paginate by. Set to `0` for no pagination
-- `paginate_path`: The prefix for paginations. Default to "page"
-- `paginate_reversed`: boolean
-- `insert_anchor_links`: One of `left`, `right`, or `none`. Specifies whether an anchor-link should be provided for every header item.  Probably overridable by the template.
-- `in_search_index`: Include this section in the search index. Only matters if search is enabled
-- `transparent`: `true`/`false`, specifies if this section should be inherited by the parent
-- `aliases`: An array of paths to redirect to this folder
-- `[extra]`: Your extra data block
 
 The context for a section page contains the following fields, which will be
 available to the template:
 
-- `content`: The content of the `_index.md` file
+{{ definition_list(source="zola/section_fields.json") }}
-- `title`: The Title found in the TOML part of `_index.md`
-- `description`: (optional): The description
-- `path`: As provided by Zola
-- `components`: The path, split into atoms
-- `permalink`: The URL for this page
-- `extra`: The contents of the TOML's `[extra.*]` blocks.
-- `pages`: An array of all child pages _in this same folder_.
-- `subsections`: An array of all child sections _in this same folder_.
-- `toc`: An array of `Header` objects: id, title, permalink, children (Which is itself
-  an array of `Header` objects)
-- `word_count`: Unicode-smart.
-- `reading_time`: Number;
-- `assets`: An array of assets available in this section.
-- `ancestors`: An array of parent paths, with the root being the last one.
 
 ### Pages {#page}
 
@@ -359,49 +344,17 @@ underscore!). The latter syntax is preferred if the file has associated assets,
 such as JavaScript or images, that you want to load alongside the content within
 the markdown page.
 
+#### Page Header in every page file
+
 The following items can appear in the TOML header of a page:
 
-- `title`: The title of this page.
+{{ definition_list(source="zola/page_arguments.json") }}
-- `description`: A description of this page
+
-- `date`: Date this page was published
+#### Page Object delivered to templates
-- `updated`: Date this page was updated
-- `weight`: A number, used for sorting
-- `draft`: Boolean. Specifies if this page should be rendered at build time
-- `slug`: String. The slug Zola should use when generating the URL
-- `path`: A manually specified absolute path to this content
-- `aliases`: An array of former urls that lead here, to redirect people here
-- `in_search_index`: If set to false and search is enabled, this page will not be included
-- `template`: The template used to render this page. Defaults to `./templates/page.html`
-- `[taxonomies]`: The taxonomies for this page
-- `[extra]`: Your own extra data
 
 Pages derive the following information in their context:
 
-- `content`: The markdown content from the page's file
+{{ definition_list(source="zola/page_fields.json") }}
-- `title`: The title, if present in the TOML block
-- `description`: The description
-- `date`: The date this file was added
-- `updated`: The date this file was last updated
-- `slug`: The slug name of this file
-- `path`: The path to this file
-- `draft`: true/false, will tell Zola not to include this file during builds
-- `components`: The path, split by '/'
-- `permalink`: The URL Zola generates for this file
-- `summary`: A provided string
-- `taxonomies`: The taxonomies list, if any
-- `extra`: The extras block
-- `toc`: An array of `Header` objects as derived from the Markdown
-- `word_count`: A naive word count
-- `reading_time`: A primitive reading time, in minutes
-- `earlier`: The content of the previous page, if the section header entry 'sort_by' is set to 'date.'
-- `later`: The content of the next page
-- `heavier`: The content of the previous page, if the section header entry 'sort_by' is set to 'weight'
-- `lighter`: The content of the next page
-- `year`: Year as a number. 
-- `month`: Month as a number.
-- `day`: Day as a number.
-- `assets`: An array of assets available to this page.
-- `ancestors`: An array of parent paths, with the root being the last one.
 
 ### Pagination
 

content/zola/page_arguments.json

@@ -0,0 +1,23 @@
+{
+    "definitions": [
+        { "dt": "title", "dd": "The title of this page." },
+        { "dt": "description", "dd": "A description of this page" },
+        { "dt": "date", "dd": "Date this page was published" },
+        { "dt": "updated", "dd": "Date this page was updated" },
+        { "dt": "weight", "dd": "A number, used for sorting" },
+        { "dt": "draft", "dd": "Boolean. Specifies if this page should be rendered at build time" },
+        { "dt": "slug", "dd": "String. The slug Zola should use when generating the URL" },
+        { "dt": "path", "dd": "A manually specified absolute path to this content" },
+        { "dt": "aliases", "dd": "An array of former urls that lead here, to redirect people here" },
+        {
+            "dt": "in_search_index",
+            "dd": "If set to false and search is enabled, this page will not be included"
+        },
+        {
+            "dt": "template",
+            "dd": "The template used to render this page. Defaults to <kbd>./templates/page.html</kbd>"
+        },
+        { "dt": "[taxonomies]", "dd": "The taxonomies for this page" },
+        { "dt": "[extra]", "dd": "Your own extra data" }
+    ]
+}

content/zola/page_fields.json

@@ -0,0 +1,35 @@
+{
+    "definitions": [
+        { "dt": "content", "dd": "The markdown content from the page's file" },
+        { "dt": "title", "dd": "The title, if present in the TOML block" },
+        { "dt": "description", "dd": "The description" },
+        { "dt": "date", "dd": "The date this file was added" },
+        { "dt": "updated", "dd": "The date this file was last updated" },
+        { "dt": "slug", "dd": "The slug name of this file" },
+        { "dt": "path", "dd": "The path to this file" },
+        { "dt": "draft", "dd": "true/false, will tell Zola not to include this file during builds" },
+        { "dt": "components", "dd": "The path, split by '/'" },
+        { "dt": "permalink", "dd": "The URL Zola generates for this file" },
+        { "dt": "summary", "dd": "A provided string" },
+        { "dt": "taxonomies", "dd": "The taxonomies list, if any" },
+        { "dt": "extra", "dd": "The extras block" },
+        { "dt": "toc", "dd": "An array of <kbd>Header</kbd> objects as derived from the Markdown" },
+        { "dt": "word_count", "dd": "A naive word count" },
+        { "dt": "reading_time", "dd": "A primitive reading time, in minutes" },
+        {
+            "dt": "earlier",
+            "dd": "The content of the previous page, if the section header entry 'sort_by' is set to 'date.'"
+        },
+        { "dt": "later", "dd": "The content of the next page" },
+        {
+            "dt": "heavier",
+            "dd": "The content of the previous page, if the section header entry 'sort_by' is set to 'weight'"
+        },
+        { "dt": "lighter", "dd": "The content of the next page" },
+        { "dt": "year", "dd": "Year as a number. " },
+        { "dt": "month", "dd": "Month as a number." },
+        { "dt": "day", "dd": "Day as a number." },
+        { "dt": "assets", "dd": "An array of assets available to this page." },
+        { "dt": "ancestors", "dd": "An array of parent paths, with the root being the last one." }
+    ]
+}

content/zola/section_arguments.json

@@ -0,0 +1,43 @@
+{
+    "definitions": [
+        { "dt": "title", "dd": "a string" },
+        { "dt": "description", "dd": "a string" },
+        {
+            "dt": "draft",
+            "dd": "<kbd>true</kbd>/<kbd>false</kbd> if this section should be included in builds"
+        },
+        {
+            "dt": "sort_by",
+            "dd": "Sorting function to use: <kbd>date</kbd>, <kbd>title</kbd>, <kbd>weight</kbd>, or <kbd>none</kbd>"
+        },
+        { "dt": "weight", "dd": "Used to provide subsection weight to a parent section" },
+        {
+            "dt": "template",
+            "dd": "The template to render this section. Defaults to <kbd>./templates/section.html</kbd>"
+        },
+        {
+            "dt": "page_template",
+            "dd": "The default template to render pages in this section. Pages with this field specified overide this setting"
+        },
+        {
+            "dt": "paginate_by",
+            "dd": "Number of pages to paginate by. Set to <kbd>0</kbd> for no pagination"
+        },
+        { "dt": "paginate_path", "dd": "The prefix for paginations. Defaults to \"page\"" },
+        { "dt": "paginate_reversed", "dd": "boolean" },
+        {
+            "dt": "insert_anchor_links",
+            "dd": "One of <kbd>left</kbd>, <kbd>right</kbd>, or <kbd>none</kbd>. Specifies whether an anchor-link should be provided for every header item.  Probably overridable by the template."
+        },
+        {
+            "dt": "in_search_index",
+            "dd": "Include this section in the search index. Only matters if search is enabled"
+        },
+        {
+            "dt": "transparent",
+            "dd": "<kbd>true</kbd>/<kbd>false</kbd>, specifies if this section should be inherited by the parent"
+        },
+        { "dt": "aliases", "dd": "An array of paths to redirect to this folder" },
+        { "dt": "[extra]", "dd": "Your extra data block" }
+    ]
+}

content/zola/section_fields.json

@@ -0,0 +1,22 @@
+{
+    "definitions": [
+        { "dt": "content", "dd": "The content of the <kbd>_index.md</kbd> file" },
+        { "dt": "title", "dd": "The Title found in the TOML part of <kbd>_index.md</kbd>" },
+        { "dt": "description", "dd": "(optional): The description" },
+        { "dt": "path", "dd": "As provided by Zola" },
+        { "dt": "components", "dd": "The path, split into atoms" },
+        { "dt": "permalink", "dd": "The URL for this page" },
+        { "dt": "extra", "dd": "The contents of the TOML's <kbd>[extra.*]</kbd> blocks." },
+        { "dt": "pages", "dd": "An array of all child pages <em>in this same folder</em>." },
+        { "dt": "subsections", "dd": "An array of all child sections <em>in this same folder</em>." },
+        {
+            "dt": "toc",
+            "dd": "An array of <kbd>Header</kbd> objects: id, title, permalink, children (Which is itself an array of <kbd>Header</kbd> objects)"
+        },
+
+        { "dt": "word_count", "dd": "Unicode-smart." },
+        { "dt": "reading_time", "dd": "Number;" },
+        { "dt": "assets", "dd": "An array of assets available in this section." },
+        { "dt": "ancestors", "dd": "An array of parent paths, with the root being the last one." }
+    ]
+}

sass/index.scss

@@ -232,5 +232,17 @@ body {
         padding: var(--space-m) var(--space-s) var(--space-m-l) var(--space-s);
         flex: 0 0 auto;
         width: 56.25%;
+
+        dd {
+            padding-left: var(--space-s);
+        }
+
+        ul {
+            padding-left: var(--step-0);
+        }
+
+        pre {
+            padding: var(--space-2xs);
+        }
     }
 }

templates/macros/definition_table.html

@@ -0,0 +1,17 @@
+{% macro definition_table(source) %}
+<table>
+  <tbody>
+  {% for entry in source -%}
+  <tr>
+    <td><code>{{ entry.dt | safe }}</code></td>
+    <td>{{ entry.dd | safe }}</td>
+  </tr>
+  {% if entry.definitions -%}
+  <tr>
+    <td colspan="2" class="sub-definition">{{ self::definition_table(source=entry.definitions) }}</td>
+  </tr>
+  {%- endif %}
+  {% endfor %}
+  </tbody>
+</table>
+{% endmacro %}

templates/shortcodes/definition_table.html

@@ -0,0 +1,5 @@
+{%- import 'macros/definition_table.html' as renderer -%}
+<div>
+{% set content = load_data(path=source) %}
+{{ renderer::definition_table(source=content.definitions) }}
+</div>