zArchitect

zArchitect is a static website generator written in ruby. It uses extensions of markdown and erb to render pages.

History

2023-07-07 (1.7.5): Fix Debian 12 compatibility issues
2023-04-11 (1.5.0): Added command to generate an xml sitemap
2023-04-10 (1.4.0): Added support for rudimentary social media meta tags
2023-04-09 (1.3.0): Added support for semantic URLs
2023-03-29 (1.2.0): Changes default title structure to put page names first
2022-05-02 (1.1.0): Improved performance
2022-04-23 (1.0.5): Improved Katex support
2022-04-21 (1.0.4): Added Katex support.
2021-12-23 (1.0.3): Can now opt-out posts from being pushed to the RSS feed.
Fixed meta description of posts.
2020-11-12 (1.0.0): Release.

Source Code

github

Gem Dependencies

System dependencies

Imagemagick (for convert and identify cli tools)
exiv2
Ruby 3.1.2

Installation

zArchitect is available as a ruby gem: sudo gem install zarchitect or download the source and run sudo ./build.sh

Setup

Create a project directory mkdir example and cd example into it
Run zarchitect setup - This sets up various directories and a config file
Open and edit _config/_zarchitect.yaml
Create config files for your website's sections (see below)

zArchitect's sections are the building blocks used to structure websites. A section can be a blog with various categories and posts, or just a single web page. Each section requires a config file in _config/

001  # EXAMPLE 1 - Blog with various categories
002  name: My Blog # the name of the section
003  id: 2 # used for sorting sections
004  directory: blog # for collections of posts, the directory in which posts reside
005  layout: _layouts/default.html.erb # html file used for layout
006  view: _layouts/view/default.html.erb # html file that houses the content
007  collection : yes # blog has more than one posts, so it's a collection
008  categorize: yes # we use categories to put posts of similar content together
009  categories: # the section's categories require a key and real name, key is used to identify them in templates
010      category_a: Category A # key: name
011      category_b: Category B
012  tags: yes # each post can be assigned to multiple tags to divide posts even further (optional)
013  paginate: 10 # posts per index page
014  index_layout: _layouts/default.html.erb # layout used for index, that lists inidividual posts
015  index_view: _layouts/view/blog_index.html.erb
016  category_index_view: _layouts/view/blog_category_index.html.erb
017  tag_index_view: _layouts/view/blog_tag_index.html.erb
018  sort_type: date # date | alphanum (the way posts are sorted)
019  sort_order: reverse # default | reverse
020  css: # optional, used to dynamically load the respective css/jss in a single layout file
021  - /assets/styles/default/default.css
022  js: # see above
023  - /assets/default.js
024  
025  # EXAMPLE 2 - Single Web Page
026  name: About Me
027  id: 1
028  file: about/content.md # location of the markdown file to be rendered for this section
029  layout: _layouts/default.html.erb
030  view: _layouts/view/default.html.erb
031  collection: no
032  categorize: no
033  css:
034  - /assets/styles/default/default.css
035  js:
036  - /assets/default.js
037  
038  # EXAMPLE 3 - Index Page (required!)
039  # this file has to be located at "./_config/_index.yaml"
040  name: Home
041  id: 0
042  collection : yes
043  categorize: no
044  tags: no
045  paginate: 10
046  layout: _layouts/default.html.erb
047  view: _layouts/view/index.html.erb
048  index_layout: _layouts/default.html.erb
049  index_view: _layouts/view/index.html.erb
050  uses: blog,some_other_section,... # show posts from sections specified here in index (comma separated)
051  sort_type: date
052  sort_order: reverse
053  hidden: yes # allows us to skip this section when iterating the sections array in layouts
054  css:
055  - /assets/styles/default/default.css
056  js:
057  - /assets/default.js

Assets

The command zarchitect ua copies from from ./_assets/ to ./_html/assets/, converting specified .scss files into .css files. Files in ./_assets/_html/ are copied into the website root directory ./_html/.

Files

Put files into ./_files/. zArchitect automatically creates 2 thumbnails for each image (if its dimensions exceed the sizes of the thumbnails). Example:

001  #./_files/picture.jpg # assuming dimensions exceed those for both thumbnails
002  #> creates: ./_html/files/picture.jpg # symlink!
003  #> creates: ./_html/files/picture-thumbs.jpg # small thumbnail
004  #> creates: ./_html/files/picture-thumbl.jpg # large thumbnail

Furthermore, JPEG files have their Exif data stripped from them and no thumbnails are generated for image files residing in ./_files/share/.

Layouts & Views

By default zArchitect runs the layout and view files specified in the section configs through erb. Examples:

001  <% Zarchitect.sections.each do |s| %> # iterates all sections and prints their names
002      <%= s.name %> 
003  <% end %>
004  # common variables that can be used to access information relating to the current page
005  # Zarchitect.section(key) // returns section specified by key. key is the filename of the section's config without the .yaml extension
006  # Zarchitect.conf # access options from ./_config/_zarchitect.yaml
007  # e.g. Zarchitect.conf.url
008  # @section
009  # @category // nil if page doesn't belong to a category
010  # @tag // nil if page doesn't belong to a tag
011  
012  # @meta // available in layouts, holds information for html meta tags (title, description, author, keywords)
013  
014  # @section.url // url of section's index, for single page sections url of the page itself
015  # @section.name
016  # @section.posts // array of posts belonging to the sectiongt
017  
018  # @section.conf.hidden // any option in the section's config file is a method of the config object returned by .conf
019  # @category.url
020  # @category.name
021  # @category.section
022  
023  # @tag.url
024  # @tag.name
025  # @tag.category
026  
027  # @tag.category.section.url // example
028  
029  # helper functions
030  <%= link "Home", root_url %> # returns <a href="http://www.example.com">Home</a>
031  <%= link "Home", root_url, class: "link" %> # <a href="http://www.example.com" class="link">Home</a>
032  <%= img "url, options {} %> # works much like the link tag
033  # the optional hash can add any attribute with the specified key in the optional hash!
034  <%= include  "some_file.html.erb" %> # include the output from another parsed template file
035  # files included have no knowledge of the parent's state, so variables that the included template
036  # should access have to be passed
037  <%= include "file.html.erb", section: @section %> # file.html.erb has now access to @section
038  <%= include "file.html.erb", data: {} %> # hash is now accissible via @data
039  
040  <%= include_view %> # includes output of view template specified in section config
041  <%= include_content %> # includes html output of post (see below)

Posts

Posts are written into markdown files ending with .md - other file extensions are ignored when zArchitect gathers posts for a collection. Here's a basic example:

001  # config
002  ---
003  title: About Me
004  draft: false # posts marked draft are ignored when building the site
005  id: some-unique-string # required for posts of collections
006  category: x # required for posts of categorized collections - should be the key of the category in the section config
007  date: 2020-11-11 12:56:32 +0100
008  author: me
009  keywords: a, b # these are appended to the site and section keywords
010  tags: # optional array for tagged categories
011  - a
012  - b
013  script: path_to_script # optional. if set, uses the output of the specified script as content instead of the markdown section
014  katex: any_value # optional. include if content should be passed to katex renderer before rendering markdown
015  
016  # content
017  ---
018  markdown goes here
019  <?ktx this-will-be-rendered-with-katex-if-option-katex-exists ?>

Sitemaps

Run zarchitect s or zarchitect sitemap to generate an xml sitemap. Changefrequency and priority values are adjustable. Sections and posts may be excluded from the sitemap.

001  # _config/_zarchitect.yaml
002  sm_post_changefreq: monthly
003  sm_post_prio: 1.0
004  sm_index_changefreq: weekly
005  sm_index_prio: 0.5
006  
007  # _config/{my_section}.yaml
008  sm_post_changefreq: yearly
009  sm_post_prio: 0.5
010  sm_index_changefreq: monthly
011  sm_index_prio: 0.2
012  sitemap: exclude # if the section should not be included in the sitemap
013  
014  # post config
015  sm_changefreq: daily
016  sm_prio: 0.7
017  sitemap: exclude # individual posts may also be excluded

Building

zarchitect u builds the website. By default it doesn't copy assets and convert .scss to .css. It supports the following options:

flag	option
r	Rebuild. Deletes contents of ./_html/ before updating. Also copies assets and converts .scss to .css
v	Verbose. Prints status messages.
D	Drafts. Includes drafts in the update.

e.g. zarchitect u -rvD, zarchitect u -v. They can be combined in any order and any combination.

2020-11-10