Renamed phase files

bump-version.sh

@@ -41,7 +41,7 @@ if [[ -f VERSION ]]; then
     git add CHANGES VERSION
     sed -i "s/^declare -r VERSION=$/declare -r VERSION=${NEXT_VERSION}'/" bin/jqt
 	sed -i "s/\[version .*\]/[version ${NEXT_VERSION}]/" bin/jqt
-	sed -i "s/^Version *:=.*/Version := ${NEXT_VERSION}/" docs/Makefile
+	sed -i "s/^version: *.*/version: ${NEXT_VERSION}/" docs/config.yaml
     git commit -am "Version bump to ${NEXT_VERSION}"
     git tag -a -m "Tagging version ${NEXT_VERSION}" "v${NEXT_VERSION}"
     [[ $PUSH == yes ]] && git push origin --tags

docs/.gitignore

@@ -3,5 +3,3 @@
 *.swp
 /.meta/
 /_site/
-/content/xxx*
-/content/yyy*

docs/Makefile

@@ -1,136 +1,155 @@
 ########################################################################
-# Makefile for web site management
+# Makefile
 #
 # Project: jqt
 # Author: <Joan Josep Ordinas Rosa> [email protected] 
+# Description: Makefile for JQT web site management.
 # Published: https://fadado.github.io/jqt/
+#
+# Variables:
+# 	$(Metadata)
+# Rules:
+# 	$(Metadata) directory target and clobber method
+#
+########################################################################
+
+########################################################################
+# Load _Make_ configuration.
 ########################################################################
 
-# Make configuration
-include make.d/prelude.make
+include make.d/configuration.make
 
-# jqt version
-Version := 0.5.1
+# Do not try to rebuilt static makefiles.
+Makefile make.d/configuration.make: ;
 
-# Metadata directory
-Metadata := .meta
+########################################################################
+# Metadata directory for all generated make and metadata files.
+########################################################################
 
-# Do not build to clobber immediately
+Metadata ?= .meta
+
+$(Metadata):
+	$(info ==> $@)
+	mkdir --parents $@ >/dev/null 2>&1 || true
+
+# Delete all generated metadata
+clobber:: ; @rm -rf $(Metadata)
+
+########################################################################
+# Print debug info.
+########################################################################
+
+ifneq (,$(TRACE))
+ifdef MAKE_RESTARTS
+$(info Makefile phase restarted: $(MAKE_RESTARTS))
+endif
+endif
+
+########################################################################
+# Check command line sanity.
+########################################################################
+
+# Target 'clobber' must be alone.
+ifeq (clobber,$(filter clobber,$(MAKECMDGOALS)))
+ifneq (1,$(words $(MAKECMDGOALS)))
+$(error Target "clobber" must be alone)
+endif
+endif
+
+# Do not build to clobber immediately.
 ifeq (clobber,$(MAKECMDGOALS))
 ifeq (,$(wildcard $(Metadata)))
 $(error Nothing to clobber)
 endif
 endif
 
-# Do not build to clean immediately
+# Do not build to clean immediately.
 ifeq (clean,$(filter clean,$(MAKECMDGOALS)))
 ifeq (,$(wildcard $(Metadata)))
 $(error Nothing to clean)
 endif
 endif
 
-# ======================================================================
+# Check _root_ intentions.
+ifeq (,$(filter install uninstall,$(MAKECMDGOALS)))
+ifeq (0,$(shell id --user))
+$(error Root only can make "(un)install" targets)
+endif
+else
+ifneq (0,$(shell id --user))
+$(error Only root can make "(un)install" targets)
+endif
+endif
+
+########################################################################
+# Include all makefile phases.
+########################################################################
+
+# Recursive variable used in all included makefiles. This works because the
+# included files do not include other makefiles.
+
+THIS = $(lastword $(MAKEFILE_LIST))
+
+########################################################################
+# Derive metadata from `config.yaml` or `config.json`.
+
 -include $(Metadata)/phase1.make
- include make.d/config.make
-#
-# Variables defined in phase1.make:
-#	__phase_1
-#	Assets
-#	Blocks
-#	Content
-#	Data
-#	Destination
-#	Layouts
-#	Styles
-# Defined rules for:
-# 	$(Metadata)
-#	$(Metadata)/config.json
-#	$(Metadata)/phase1.make
-#	$(Metadata)/site.json
-# ======================================================================
+ include make.d/phase1.make
+
+# Do not try to rebuilt static makefiles.
+make.d/phase1.make: ;
 
-# Warning:
-#
 # If `__phase_1` is not defined because `phase1.make` does not exists, after
-# this point most of the file is ignored, but `phase1.make` is built because a
-# rule exists in the file `config.make`.  Then this `Makefile` is restarted,
-# `MAKE_RESTARTS` is be equal to 1, `phase1.make` is now loaded and
+# this point the rest of the file is ignored, but `phase1.make` is built
+# because a rule exists in the file `config.make`.  Then this `Makefile` is
+# restarted, `MAKE_RESTARTS` is be equal to 1, `phase1.make` is now loaded and
 # `__phase_1` is defined. Equivalent situation happens in all phases.
 
 ifdef __phase_1
 
-# ======================================================================
+########################################################################
+# Build metadata from filesystem introspection.
+
 -include $(Metadata)/phase2.make
- include make.d/data.make
-#
-# Variables defined in phase2.make:
-#	__phase_2
-#	DataCSV
-#	DataJSON
-#	DataMD
-#	DataYAML
-#	DestinationPages
-#	DestinationPaths
-#	MetadataPages 
-#	MetadataPaths
-# Defined rules for:
-#	$(Metadata)/phase2.make
-# 	$(DataFiles)
-# 	$(DestinationPaths)
-# 	$(Metadata)/pages-by-id.json
-# 	$(MetadataPages)
-# 	$(MetadataPaths)
-# Defined targets:
-# 	init
-# ======================================================================
+ include make.d/phase2.make
+
+# Do not try to rebuilt static makefiles.
+make.d/phase2.make: ;
 
 ifdef __phase_2
 
-# ======================================================================
+########################################################################
+# Define standard rules and rules for HTML pages and nodes.
+
 -include $(Metadata)/phase3.make
- include make.d/pages.make
-#
-# Load rules for pages and nodes.
-#
-# Variables defined in phase3.make:
-#	__phase_3
-# Defined rules for:
-#	$(Metadata)/phase3.make
-# Defined targets:
-#	all
-# 	build
-# 	clean
-# 	clobber
-# 	fresh
-# 	touch
-# ======================================================================
+ include make.d/phase3.make
+
+# Do not try to rebuilt static makefiles.
+make.d/phase3.make: ;
 
 ifdef __phase_3
 
-# ======================================================================
+########################################################################
+# Several complementary makefiles.
+
 include make.d/sitemap.make
 include make.d/styles.make
-include make.d/tools.make
-#
-# Several complementary files.
-#
-# Defined rules for:
-#	$(Destination)/sitemap.xml
-#	$(Destination)/sitemap.xml.gz
-#	$(Destination)/styles.css
-# Defined targets:
-# 	help
-# 	lint
-# 	valid
-# ======================================================================
+##include make.d/tools.make
+
+# Do not try to rebuilt static makefiles.
+make.d/sitemap.make: ;
+make.d/styles.make: ;
+##make.d/tools.make: ;
 
 ########################################################################
-include config.make
-#
 # Project specific makefile. All the previous modules are expected to be
 # independent, valid for any project without any change. This file must
 # exist but can be empty.
-########################################################################
+
+include config.make
+
+# Do not try to rebuilt static makefiles.
+config.make: ;
 
 endif # __phase_3
 endif # __phase_2

docs/README.md

@@ -1,27 +1,100 @@
+# Conventions
+
 ## Extension conventions for content files
 
-The files in the `content` directory must follow some conventions in the file
+The files in the `content` and `data` directories must follow some conventions in the file
 extensions:
 
 * Web site pages
-    - content.md
-    - data.md
-    - engine.md
-    - home.md
-    - structure.md
+    - `content/content.md`
+    - `content/data.md`
+    - `content/engine.md`
+    - `content/index.md`
+    - `content/structure.md`
 
 * Partial MarkDown to be included
-    - EXAMPLE.txt
-    - FLOW.txt
-    - LINKS.txt
-    - opt/\*.txt
-
-* MarkDown snippets
-    - snippets.yaml
+    - `content/EXAMPLE.text`
+    - `content/FLOW.text`
+    - `content/LINKS.text`
+    - `content/opt/\*.text`
 
 * Other unrelated MarkDown files
-    - help.markdown
-    - jqt.1.markdown
+    - `content/help.text`
+    - `content/jqt.1.text`
+
+* Extension conventions for data files
+    - `data/table.csv`
+    - `data/snippets.md`
+    - `data/document.json`
+    - `data/document.yaml`
+
+# Variables
+
+Capitalized names are for global predefined variables.
+
+## Site variables
+
+All members defined in the configuration file, except `defaults`, and the
+predefined variables:
+
+* `.site.Assets`
+* `.site.Blocks`
+* `.site.Content`
+* `.site.Data`
+* `.site.Destination`
+* `.site.Layouts`
+* `.site.Metadata`
+* `.site.Styles`
+
+In the configuration file you can assign new values to all predefined variables
+except `Metadata`, with hardcoded value in the file `Makefile`.
+
+## Page variables
+
+Front-matter members and the predefined variables.
+
+### Read only variables
+
+* `.page.Base`
+* `.page.Date`
+* `.page.Filename`
+* `.page.Id`
+* `.page.Layout`
+* `.page.Path`
+* `.page.Section`
+* `.page.Slug`
+* `.page.Source`
+* `.page.URL`
+
+### Variables merged with defaults
+
+* `.page.Datasets`
+* `.page.Dependencies`
+* `.page.Flags`
+
+### Source for pathname related variables
+
+```
+          Slug
+        |---^---| 
+content/name.html
+        |-^|
+         Id
+
+        Section  Slug
+        |--^-| |--^----|
+content/extras/name.html
+        |-------v-|
+        |--v--| Id
+          Path
+
+            Section      Slug
+        |------^-----| |---^---|
+content/extras/indexes/name.html
+        |---------------v-|
+        |-----v-------| Id
+             Path
+```
 
 <!--
 vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown

docs/blocks/body/_blog/markup.html

@@ -2,11 +2,11 @@
  # Body for blog posts
  ######################################################################>&
 <main class="#body">
-  {% pages[] | select(.section=="blog") %}<#TODO: sort?#>
+  {% pages[] | select(.Section=="blog") %}<#TODO: sort?#>
     <div class="post-excerpt">
-      <a class="post-excerpt__title" href="{{.base}}{{.url}}">{{.title}}</a>
+      <a class="post-excerpt__title" href="{{.Base}}{{.URL}}">{{.title}}</a>
       <p class="post-excerpt__test">{{.description}}
-        <span class="post-excerpt__date">{{.updated | fromdate |strftime("%B %Y") }}</span></p>
+        <span class="post-excerpt__date">{{ .updated | fromdate | strftime("%B %Y") }}</span></p>
     </div>
   {% end %}
 </main>