From d079e33c049c6762e3a4faf8fdb96add2f77a033 Mon Sep 17 00:00:00 2001 From: "Elf M. Sternberg" Date: Mon, 13 Jun 2022 18:25:11 -0700 Subject: [PATCH] Added git commands. --- content/git/_index.md | 79 +++++++++++++--- content/zola/_index.md | 103 ++++++--------------- content/zola/page_arguments.json | 23 +++++ content/zola/page_fields.json | 35 +++++++ content/zola/section_arguments.json | 43 +++++++++ content/zola/section_fields.json | 22 +++++ sass/index.scss | 12 +++ templates/macros/definition_table.html | 17 ++++ templates/shortcodes/definition_table.html | 5 + 9 files changed, 253 insertions(+), 86 deletions(-) create mode 100644 content/zola/page_arguments.json create mode 100644 content/zola/page_fields.json create mode 100644 content/zola/section_arguments.json create mode 100644 content/zola/section_fields.json create mode 100644 templates/macros/definition_table.html create mode 100644 templates/shortcodes/definition_table.html diff --git a/content/git/_index.md b/content/git/_index.md index 65d983e..1f0d785 100644 --- a/content/git/_index.md +++ b/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 -your commits to be attributed to the right person, you must have the `[user]` -block, and +## Git Aliases {#aliases} + +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. + diff --git a/content/zola/_index.md b/content/zola/_index.md index c6f3b2c..23061eb 100644 --- a/content/zola/_index.md +++ b/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 -folder, every markdown document and every folder creates a corresponding page in -the constructed website. There are only *two* models you have to understand -Zola: *sections* and *pages*. +Elf, a website built with Zola originates with the `content/` folder. Inside +that folder, every markdown document and every folder creates a corresponding +page in the constructed website. There are only *two* models you have to +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 -- `description`: a string -- `draft`: `true`/`false` if this section should be included in builds -- `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 +{{ definition_list(source="zola/section_arguments.json") }} + +#### Section Object delivered to the template: 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 -- `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. +{{ definition_list(source="zola/section_fields.json") }} ### 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. -- `description`: A description of this page -- `date`: Date this page was published -- `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 +{{ definition_list(source="zola/page_arguments.json") }} + +#### Page Object delivered to templates Pages derive the following information in their context: -- `content`: The markdown content from the page's file -- `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. +{{ definition_list(source="zola/page_fields.json") }} ### Pagination diff --git a/content/zola/page_arguments.json b/content/zola/page_arguments.json new file mode 100644 index 0000000..7e09b71 --- /dev/null +++ b/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 ./templates/page.html" + }, + { "dt": "[taxonomies]", "dd": "The taxonomies for this page" }, + { "dt": "[extra]", "dd": "Your own extra data" } + ] +} diff --git a/content/zola/page_fields.json b/content/zola/page_fields.json new file mode 100644 index 0000000..d588363 --- /dev/null +++ b/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 Header 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." } + ] +} diff --git a/content/zola/section_arguments.json b/content/zola/section_arguments.json new file mode 100644 index 0000000..7a574e3 --- /dev/null +++ b/content/zola/section_arguments.json @@ -0,0 +1,43 @@ +{ + "definitions": [ + { "dt": "title", "dd": "a string" }, + { "dt": "description", "dd": "a string" }, + { + "dt": "draft", + "dd": "true/false if this section should be included in builds" + }, + { + "dt": "sort_by", + "dd": "Sorting function to use: date, title, weight, or none" + }, + { "dt": "weight", "dd": "Used to provide subsection weight to a parent section" }, + { + "dt": "template", + "dd": "The template to render this section. Defaults to ./templates/section.html" + }, + { + "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 0 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 left, right, or none. 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": "true/false, 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" } + ] +} diff --git a/content/zola/section_fields.json b/content/zola/section_fields.json new file mode 100644 index 0000000..1a94539 --- /dev/null +++ b/content/zola/section_fields.json @@ -0,0 +1,22 @@ +{ + "definitions": [ + { "dt": "content", "dd": "The content of the _index.md file" }, + { "dt": "title", "dd": "The Title found in the TOML part of _index.md" }, + { "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 [extra.*] blocks." }, + { "dt": "pages", "dd": "An array of all child pages in this same folder." }, + { "dt": "subsections", "dd": "An array of all child sections in this same folder." }, + { + "dt": "toc", + "dd": "An array of Header objects: id, title, permalink, children (Which is itself an array of Header 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." } + ] +} diff --git a/sass/index.scss b/sass/index.scss index 5f7c8e5..84af725 100644 --- a/sass/index.scss +++ b/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); + } } } diff --git a/templates/macros/definition_table.html b/templates/macros/definition_table.html new file mode 100644 index 0000000..46c09b3 --- /dev/null +++ b/templates/macros/definition_table.html @@ -0,0 +1,17 @@ +{% macro definition_table(source) %} + + + {% for entry in source -%} + + + + + {% if entry.definitions -%} + + + + {%- endif %} + {% endfor %} + +
{{ entry.dt | safe }}{{ entry.dd | safe }}
{{ self::definition_table(source=entry.definitions) }}
+{% endmacro %} diff --git a/templates/shortcodes/definition_table.html b/templates/shortcodes/definition_table.html new file mode 100644 index 0000000..1401847 --- /dev/null +++ b/templates/shortcodes/definition_table.html @@ -0,0 +1,5 @@ +{%- import 'macros/definition_table.html' as renderer -%} +
+{% set content = load_data(path=source) %} +{{ renderer::definition_table(source=content.definitions) }} +