This is a makefile based static website generator. Files are authored in the "src" subdirectory using a standard text editor to enter markdown or html as desired. A template processor is also used which enables standard page header, footers, and other common information across various web pages.
The makefile is set up to recognize and process files based on their filename extension. The following file types are currently handled:
-
.got - These are the primary content files which are translated into html. These are golang template files for processing by the pgot utility. The file types that follow are typically referred to within these .got files.
-
.igot - These are intended to be "included" in the frontmatter section of the .got files above and typically contain global variables or content to standardize across web pages.
-
.cpy - Files intended to be copied over directly into the build directory without any type of translation. The cpy file extension is removed in the process.
-
.raw - Raw files are binary files that are not stored efficiently within git. These are the only content files that are ignored by git and are handled separately using the cogit methodology described below. These are copied directly into the build directory with the raw file extension removed.
Note that folders are only created in the build directory if they contain content files. Case in point, the "inc" folder within the "src" directory is not mirrored into the "bld" folder because it only contains igot files. Since igot files are by definition only included in other got files they do not create content on their own and as such the inc folder does not need to be created in the corresponding "bld" directory.
The .got file format is described in detail on the pgot repository page. In essence it consists of JSON frontmatter bounded by triple semicolons (;;;), followed by template content. In addition you can designate sections of the template content as markdown by bounding them with '|||md+' on a line by itself followed by '|||md-' on its own line. These can encompass the whole template section or alternately can be repeated multiple times within the template for sub sections of markdown. Anything not within markdown boundary markers is considered standard html. An example .got source file can be seen here.
Once files have been authored, these are mirrored and transformed into final html in the "bld" subdirectory. The user can make a local version using the following command in order to browse and confirm content/appearance using a standard web browser. The generated files are stored in the "bld/loc" sub folder.
$ make loc
Once satisfied with the results the user can then make a public version using the following command. The files are similarly stored in the "bld/pub" sub folder.
$ make pub
The files in the "bld/pub" folder can be copied to the destination server address using scp, rsync, etc.
To install, clone the git repository and ensure you have the dependencies in the section below installed.
In addition you will need to download the latest "cogit" file set from the release folder. This is a tar archive containing any images or video etc. used by this website. See the cogit section below for more background info. There is currently only one file in the makehtml cogit archive, and it is mainly included to demonstrate the cogit method. From within the main git repository you can then extract the tar archive as follows (assuming the downloaded cogit tar archive is in your ~/Download folder) and it will populate the cogit files into the "src" directory.
$ tar -xf ~/Download/makehtml-cogit-20XX-XX-XX.tar
You should then execute the configure script which selects the appropriate Makefile version depending on which operating system you are using (linux or bsd).
$ ./configure
You should edit the following line near the top of the Makefile to match the public server address that you plan to use.
MYSERVER=my.blog.site
You can then either edit / create files directly in the "src" sub folder in the repository or alternately copy all the files in the git repository to a separate folder or repository of your choice. The src sub folder currently contains a skeleton blog site with placeholder information that you can edit as a starting point or alternately wipe it clean and start with your own format. A screen shot of the skeleton blog is shown below.
Lastly, you can then execute "make loc" to generate a local set of files that you can browse with your default web browser.
$ make loc
$ xdg-open bld/loc/index.html
- make (any posix compliant make utility) Used to identify items that have changed and convert those into final html files for a website using the tools above.
- pgot (https://git.lenzplace.org/lenzj/pgot) A template processing tool written in golang.
- chuf (https://git.lenzplace.org/lenzj/chuf) An inline chunk filtering tool written in golang (used to select sections for markdown processing).
- markdown I use discount as the markdown processor. http://www.pell.portland.or.us/~orc/Code/discount/
- unix utilities The following standard unix utilities are needed and should be available in most linux/bsd default installations: find, tar, grep, sort, sha256sum
The folder structure can be customized as desired. The example layout is as follows:
|-Makefile
|-bld
| |-loc
| |-pub
|-src
| |-css
| |-favicon.svg.cpy
| |-inc
| |-index.got
| |-post
| | |-mauris_elementum
| | | |-computer.svg.cpy
| | | |-index.got
| | |-nulla_porttitor_tellus
| | | |-elephant.svg.cpy
| | | |-index.got
| | |-pellentesque
| | | |-index.got
| | | |-rhino.svg.cpy
| |-topic
| | |-index.got
|-template
bld : All generated output is written to this folder.
loc : This folder content is created with "make loc", and can be viewed
with a standard web browser.
pub : This folder contains files which are intended for the public web
server. These files can be directly copied to the server.
src : All templates and source text files are in this folder.
css : html cascading style sheets are stored here.
inc : These are .igot templates that are included or referenced by
individual content pages in src. Global variables can be defined
here etc.
post : Place posts here. Majority of content is in this folder.
topic : A categorized index of posts.
template : You can safely ignore this folder unless you want to update the
README or LICENSE files. Further detail is in the folder.
Websites typically have a variety of raw binary data files including images, video, icons, etc. Git works exceptionally well for text files, but is not a good tool for storing these types of binary files. The git LFS system has been developed to handle this situation, however a specialized LFS server is needed. An alternate strategy is used here which I am calling "cogit" (raw binary files cohabitating with git). The .gitignore file specifies the raw files and/or folders to be ignored by git. The Makefile generates a manifest text file containing lines with a sha256sum first followed by the sub path/name for each raw binary file. The manifest is tracked in git so that the even though the raw files are not stored in git the user can determine exactly which set of raw files is associated with each commit. A tarball containing the raw files can be created and stored separately from the git respository.
If you have a bugfix, update, issue or feature enhancement the best way to reach me is by following the instructions in the link below. Thank you!
https://blog.lenzplace.org/contact
I follow the SemVer strategy for versioning. The latest version is listed in the releases section.
This project is licensed under a BSD two clause license - see the LICENSE file for details.