saait

Simple static page generator
git clone https://git.sinitax.com/codemadness/saait
Log | Files | Refs | README | LICENSE | Upstream | sfeed.txt

commit 26cef250bc4609edcc5663540f3e4055738ca06b
parent 82f2448a5181411d61e4763f45e1dfdbe6e8092b
Author: Hiltjo Posthuma <hiltjo@codemadness.org>
Date:   Sun,  5 Jan 2020 14:10:51 +0100

improve/rewrite man page and README

add a step-by-step usage example to create a site.

Diffstat:
MREADME | 238++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---------------------
Msaait.1 | 203+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--
2 files changed, 374 insertions(+), 67 deletions(-)

diff --git a/README b/README @@ -1,12 +1,12 @@ saait ----- -the most boring static page generator +The most boring static page generator. Meaning of saai (dutch): boring Pronounciation: site -Some parts are intentionally hardcoded, C knowledge is required. +Some parts are intentionally hardcoded in C for simplicity. Build and install @@ -19,102 +19,214 @@ $ make Dependencies ------------ -- C compiler (C99), tested on gcc, clang. +- C compiler (C99), tested on gcc and clang. - libc - POSIX make (optional). +- mandoc for documentation: https://mdocml.bsd.lv/ (optional). Tested and works on ------------------- - OpenBSD -- Linux (glibc) -- Windows (mingw and cygwin) +- Linux (glibc). +- Windows (mingw and cygwin). -Structure ---------- +Documentation +------------- -Directory structure for pages: +See the man page of saait(1). -- pages/file1.html -- pages/file1.cfg +Man page +-------- -Directory structure for templates: +NAME + saait the most boring static page generator -- templates/<templatename>/item.ext -- templates/<templatename>/header.ext -- templates/<templatename>/footer.ext +SYNOPSIS + saait [-c configfile] [-o outputdir] [-t templatesdir] pages... -The files are saved as output/<templatename>.ext +DESCRIPTION + saait writes HTML pages to the output directory. -the templatename "page" is special and will be used per page. + The arguments pages are page .cfg files, which are processed in the given + order. -otherwise the directory name is used as the output file, for example -templates/atom.xml/templatefiles* will be: output/atom.xml + The options are as follows: -the following filename prefixes for template blocks are detected: + -c configfile + The global configuration file, the default is "config.cfg". Each + page configuration file inherits the values from this file. The + values can be overwritten per page. -"header." - header block. -"item." - item block -"footer." - footer block. + -o outputdir + The output directory, the default is "output". -If a filename does not exist then the template block is not processed and will -have the same result as an empty file. + -t templatesdir + The templates directory, the default is "templates". +DIRECTORY AND FILE STRUCTURE + A recommended directory structure for pages, but the names can be + anything: + pages/001-page.cfg + pages/001-page.html + pages/002-page.cfg + pages/002-page.html -Cfg file and template syntax ----------------------------- + The directory and files structure for templates must be: + templates/<templatename>/header.ext + templates/<templatename>/item.ext + templates/<templatename>/footer.ext -Special variables set: -htmlfile (if not already set) path to input HTML content filename. -filename (can be overwritten) basename of output content HTML file. + The following filename prefixes are detected for template blocks and + processed in this order: -Special variables used: -index if set to 0 then don't list this page as an item for the - templates except for the "page" template. This can be used to hide - a page from the index.html and Atom feed. + "header." + Header block. -Variables: -${} escaped HTML/XML string. -#{} literal string. -%{} insert contents of file of variable value. + "item." + Item block. + "footer." + Footer block. -Usage ------ + The files are saved as output/<templatename>, for example + templates/atom.xml/* will become: output/atom.xml . If a filename does + not exist then the template block is not processed and will be the same + result as if it was an empty file. + + Hidden template directories (starting with ".") are ignored. + + The templatename "page" is special and will be used per page. + +CFG FILE + A .cfg file has a simple key=value configuration syntax, for example: + + # an example page. + filename=example.html + title=Example page + description=This is an example page + created=2009-04-12 + updated=2009-04-12 + + The following variables names are special with their respective default + values: + + filename + The relative file path of the output HTML file for this page. + The path is relative to the outputdir. + + htmlfile + Path to the input HTML content filename, by default this is the + path of the .cfg file with .cfg replaced to .html. + + index If set to 0 then this page is not processed for templates except + for the "page" template. This can be used to hide pages from + templates such as index.html or from listing in an Atom feed. + + A line starting with # is ignored and can be used as a comment. + +TEMPLATE SYNTAX + The variables set in a .cfg file can be used inside templates, but not + pages. + + The possible operators for variables are: + + $ Escapes a XML string, for example: < to the entity &lt;. + + # Literal raw string value. + + % Insert contents of file of the value of the variable. + + For example in a HTML template: + + <article> + <header> + <h1><a href="">${title}</a></h1> + <p> + <strong>Last modification on </strong> + <time datetime="${updated}">${updated}</time> + </p> + </header> + %{htmlfile} + </article> + +EXIT STATUS + The saait utility exits 0 on success, and >0 if an error occurs. + +EXAMPLES + A basic usage example: + + 1. Create a directory for a new site: + + mkdir newsite + + 2. Copy the example pages, templates, global config file and example + stylesheets to a directory: + + cp -r pages templates config.cfg style.css print.css newsite/ + + 3. Change the current directory to the created directory. + + cd newsite/ + + 4. Adjust the values in the global config.cfg file which provides + defaults for all pages. + + 5. If you want to modify parts of the header, like the navigation menu + items, you can change the following two template files: + templates/page/header.html + templates/index.html/header.html + + 6. Create any new pages in the pages directory. For each *.cfg file + there has to be a corresponding *.html file with the same basename. + They have to be placed in the same folder. Optionally they can be + overridden with the special variable "htmlfile". See the copied + example pages in this directory. + + 7. Create an output directory: + + mkdir -p output + + 8. After any modifications the following commands can be used to + generate the output and process the pages in descending order: + + find pages -type f -name '*.cfg' -print0 | sort -zr | xargs -0 saait + + 9. Copy the modified stylesheets to the output directory also: + + cp style.css print.css output/ + + 10. Open output/index.html locally in your webbrowser to review the + changes. -1. Adjust the global config.cfg file which provides defaults for all pages. -2. Call saait from a directory that is providing a config.cfg and a - templates folder. Those are included in the source, so simply call it from - the source directory. -3. For each *.cfg file there has to be a corresponding *.html file with the - same basename. They have to be placed in the same folder. - optionally they can be overridden with the special variable "htmlfile". -4. Saait is called naming an output directory and providing one or more *.cfg - files as parameters. -5. Modify the following two template files, in order to change the items - displayed in the header (Blog, Git, Github, etc...): + 11. To synchronize files, you can securely transfer them via SSH using + rsync: - templates/page/header.html - templates/index.html/header.html + rsync -av output/ user@somehost:/var/www/htdocs/ + Below is an example to use saait with Markdown. A possible method could + be to just convert the Markdown to HTML and to run saait after that as + usual. -Usage examples --------------- + In this example it uses smu for the Markdown processor, available at: + https://github.com/Gottox/smu : -this is a basic example: + cd pages + for f in *.md; do + smu -n < "$f" > "$(basename "$f" .md).html" + done - $ saait -o /path/to/www /path/to/001-example.cfg +TRIVIA + The most boring static page generator. -this is an example for how it's used in practice and for many pages: + Meaning of saai (dutch): boring, pronunciation of saait: site - $ saait -o /path/to/www /path/to/*.cfg +SEE ALSO + find(1), sort(1), xargs(1) -or: +AUTHORS + Hiltjo Posthuma <hiltjo@codemadness.org> - $ mkdir -p output - $ find pages -type f -name '*.cfg' -print0 | sort -zr | xargs -0 saait - $ cp style.css print.css output/ - $ rsync -av output/ user@somehost:/var/www/htdocs/ diff --git a/saait.1 b/saait.1 @@ -1,17 +1,212 @@ -.Dd Nov 14, 2016 +.Dd January 5, 2020 .Dt SAAIT 1 .Os .Sh NAME .Nm saait -.Nd static web page generator +.Nd the most boring static page generator .Sh SYNOPSIS .Nm .Op Fl c Ar configfile .Op Fl o Ar outputdir -.Op Fl t Ar templatedir +.Op Fl t Ar templatesdir .Ar pages... .Sh DESCRIPTION .Nm -writes static HTML pages to the output directory. +writes HTML pages to the output directory. +.Pp +The arguments +.Ar pages +are page .cfg files, which are processed in the given order. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl c Ar configfile +The global configuration file, the default is "config.cfg". +Each page configuration file inherits the values from this file. +The values can be overwritten per page. +.It Fl o Ar outputdir +The output directory, the default is "output". +.It Fl t Ar templatesdir +The templates directory, the default is "templates". +.El +.Sh DIRECTORY AND FILE STRUCTURE +A recommended directory structure for pages, but the names can be anything: +.Bl -tag -width Ds -compact +.It pages/001-page.cfg +.It pages/001-page.html +.It pages/002-page.cfg +.It pages/002-page.html +.El +.Pp +The directory and files structure for templates must be: +.Bl -tag -width Ds -compact +.It templates/<templatename>/header.ext +.It templates/<templatename>/item.ext +.It templates/<templatename>/footer.ext +.El +.Pp +The following filename prefixes are detected for template blocks and processed +in this order: +.Bl -tag -width Ds +.It Qo "header." Qc +Header block. +.It Qo "item." Qc +Item block. +.It Qo "footer." Qc +Footer block. +.El +.Pp +The files are saved as output/<templatename>, for example +templates/atom.xml/* will become: output/atom.xml . +If a filename does not exist then the template block is not processed and will +be the same result as if it was an empty file. +.Pp +Hidden template directories (starting with ".") are ignored. +.Pp +The templatename "page" is special and will be used per page. +.Sh CFG FILE +A .cfg file has a simple key=value configuration syntax, for example: +.Bd -literal +# an example page. +filename=example.html +title=Example page +description=This is an example page +created=2009-04-12 +updated=2009-04-12 +.Ed +.Pp +The following variables names are special with their respective default values: +.Bl -tag -width Ds +.It filename +The relative file path of the output HTML file for this page. +The path is relative to the +.Ar outputdir . +.It htmlfile +Path to the input HTML content filename, by default this is the path of +the .cfg file with .cfg replaced to .html. +.It index +If set to 0 then this page is not processed for templates except for the +"page" template. +This can be used to hide pages from templates such as index.html or from +listing in an Atom feed. +.El +.Pp +A line starting with # is ignored and can be used as a comment. +.Sh TEMPLATE SYNTAX +The variables set in a .cfg file can be used inside templates, but not pages. +.Pp +The possible operators for variables are: +.Bl -tag -width Ds +.It $ +Escapes a XML string, for example: < to the entity &lt;. +.It # +Literal raw string value. +.It % +Insert contents of file of the value of the variable. +.El +.Pp +For example in a HTML template: +.Bd -literal +<article> + <header> + <h1><a href="">${title}</a></h1> + <p> + <strong>Last modification on </strong> + <time datetime="${updated}">${updated}</time> + </p> + </header> + %{htmlfile} +</article> +.Ed +.Sh EXIT STATUS +.Ex -std +.Sh EXAMPLES +A basic usage example: +.Bl -enum +.It +Create a directory for a new site: +.Bd -literal +mkdir newsite +.Ed +.It +Copy the example pages, templates, global config file and example +stylesheets to a directory: +.Bd -literal +cp -r pages templates config.cfg style.css print.css newsite/ +.Ed +.It +Change the current directory to the created directory. +.Bd -literal +cd newsite/ +.Ed +.It +Adjust the values in the global config.cfg file which provides defaults for +all pages. +.It +If you want to modify parts of the header, like the navigation menu items, +you can change the following two template files: +.Bl -item -compact +.It +templates/page/header.html +.It +templates/index.html/header.html +.El +.It +Create any new pages in the pages directory. +For each *.cfg file there has to be a corresponding *.html file with the same +basename. +They have to be placed in the same folder. +Optionally they can be overridden with the special variable "htmlfile". +See the copied example pages in this directory. +.It +Create an output directory: +.Bd -literal +mkdir -p output +.Ed +.It +After any modifications the following commands can be used to generate the +output and process the pages in descending order: +.Bd -literal +find pages -type f -name '*.cfg' -print0 | sort -zr | xargs -0 saait +.Ed +.It +Copy the modified stylesheets to the output directory also: +.Bd -literal +cp style.css print.css output/ +.Ed +.It +Open output/index.html locally in your webbrowser to review the changes. +.It +To synchronize files, you can securely transfer them via SSH using rsync: +.Bd -literal +rsync -av output/ user@somehost:/var/www/htdocs/ +.Ed +.El +.Pp +Below is an example to use +.Nm +with Markdown. +A possible method could be to just convert the Markdown to HTML and to +run +.Nm +after that as usual. +.Pp +In this example it uses smu for the Markdown processor, available at: +.Lk https://github.com/Gottox/smu +: +.Bd -literal +cd pages +for f in *.md; do + smu -n < "$f" > "$(basename "$f" .md).html" +done +.Ed +.Sh TRIVIA +The most boring static page generator. +.Pp +Meaning of saai (dutch): boring, pronunciation of saait: site +.Sh SEE ALSO +.Xr find 1 , +.Xr sort 1 , +.Xr xargs 1 .Sh AUTHORS .An Hiltjo Posthuma Aq Mt hiltjo@codemadness.org