zArchitect is a static website generator written in ruby. It uses extensions of markdown and erb to render pages.
History
- 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
Gem Dependencies
System dependencies
- Imagemagick (for convert and identify cli tools)
- exiv2
- Ruby
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
andcd 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.