aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorPaul Duncan <pabs@pablotron.org>2021-11-18 10:40:11 -0500
committerPaul Duncan <pabs@pablotron.org>2021-11-18 10:40:11 -0500
commit3d2e1624ce0abc3f9c8148140ec2be3428001dc7 (patch)
tree6ea9d9e280a7ab86b3d00e84430d37c0de830226
parentb9a28ab1c8408967bb273cc1c19436a2c0563b48 (diff)
downloadpablotron.org-3d2e1624ce0abc3f9c8148140ec2be3428001dc7.tar.bz2
pablotron.org-3d2e1624ce0abc3f9c8148140ec2be3428001dc7.zip
README.md: update documentation
-rw-r--r--README.md41
1 files changed, 31 insertions, 10 deletions
diff --git a/README.md b/README.md
index 3e43060..6a2c53a 100644
--- a/README.md
+++ b/README.md
@@ -21,6 +21,14 @@ on the [archive][] page in reverse chronological order.
`projects` have a repository link and a brief description. Eventually I
may add more information (release history, signatures, etc).
+Put assets (images, files, etc) for articles and posts in
+`static/files/{articles|posts}/$SLUG`. Use the built-in `figure`
+shortcode to reference images in content, because it supports more
+attributes and is responsive (grep existing content for examples).
+
+Use [mathyd][] to generate [SVGs][svg] for math posts and articles,
+rather than pulling in [MathJax][].
+
## Usage
The `bin/new` script allows you (me) to quickly create new content by:
@@ -51,13 +59,7 @@ To add a new article:
## Add Project
-To add a new project:
-
- # easy version
- bin/new project great-project
-
- # longer version
- hugo new --editor $EDITOR projects/great-project.md
+Update `data/projects.yaml` and then run `bin/gen-projects.rb`.
## Edit Navbar Menu
@@ -71,9 +73,10 @@ To add or edit navbar menu entries:
To serve this site locally:
# serve hugo locally on port 1313
- hugo serve --minify --disableFastRender
+ hugo serve -D --minify --disableFastRender
**Notes:**
+* `-D` shows draft content,
* `--minify` generates minified HTML, and
[`html/template`][html-template] is aware of `<pre>` and `<code>` so
inline code blocks work correctly.
@@ -96,17 +99,27 @@ Then:
* push to upstream repo
The push will trigger a hook which runs
-`/data/www/pablotron.org/data/bin/deploy.sh`, which will:
+`/data/www/pablotron.org/data/bin/hook/deploy.rb`, which will:
1. Pull the latest changes from the git repository
2. Run [Hugo][] to rebuild the site.
-3. Update the `htdocs` symlink
+3. Update the `htdocs` symlink for the live site.
+4. Remove stale site builds.
+5. Log the time taken for each step.
+
+See `bin/hook/` for additional information.
# Theme
The current theme is `hugo-pt2021` and is stored in this repository as
`themes/hugo-pt2021`.
+Includes the following shortcodes:
+
+* `table`: Enhanced [CSS][]-only table shortcode. See
+ [hugo-shortcode-table][].
+* `sup`: Superscript.
+
`hugo-pt2021` is depends on the following:
* [Bulma 0.9.3][bulma]: CSS framework.
@@ -143,3 +156,11 @@ The [Bulma][] [SASS][] is:
"Go programming language"
[html-template]: https://pkg.go.dev/html/template
"Go's built-in HTML template renderer"
+[mathyd]: https://github.com/pablotron/mathyd
+ "TeX to SVG rendering daemon and docker image."
+[mathjax]: https://mathjax.org/
+ "JavaScript LaTeX renderer."
+[svg]: https://en.wikipedia.org/wiki/Scalable_Vector_Graphics
+ "Scalable Vector Graphics"
+[hugo-shortcode-table]: https://github.com/pablotron/hugo-shortcode-table
+ "CSS-only table shortcode for Hugo."