Table of Contents
SSG5: A simple static site generator
Check out https://git.sdf.org/peteyboy/ssg-for-sdf
ssg-for-sdf is an SDF-ready fork of ssg5, a static site generator written in shell, from https://www.romanzolotarev.com/ssg.html
It creates a static site from a set of markdown and/or html files, so you can start with say, an existing HTML site and migrate it over time to Markdown and ssg5.
From the author:
ssg is a static site generator written in shell. Optionally it converts Markdown files to HTML with lowdown(1) or Markdown.pl.
(note: Markdown.pl is installed on SDF cluster as of this writing, so that's what it will use)
How it Works
Unless a page has <HTML> tag ssg5 extracts its title from <H1> tag, wraps the page with _header.html, _footer.html.
Then copies everything (excluding .* or paths listed in src/.ssgignore) from src to dst directory.
Markdown and HTML files
HTML files from src have greater priority than Markdown ones. ssg5 converts Markdown files from src to HTML in dst and then copies HTML files from src to dst. In the following example src/a.html wins:
src/a.md → dst/a.html
src/a.html → dst/a.html
So simple!
So the cool thing is, you can slowly migrate your static site to ssg, because if you already have an html file in source, it just copies it straight to dest, without requiring a Markdown version to exist already. So you can have a set of files in your source folder that are some *.md files, and some *.html files, and they will all get generated into the site.
Clone Git Repo
change dirs to a folder that you keep projects in (~/projects, say), and clone the ssg-for-sdf repo:
$git clone https://git.sdf.org/peteyboy/ssg-for-sdf.git
Copy to your personal bin directory
- Make sure you have a ~/bin folder. If you don't already, make one:
mkdir ~/bin(and add it to your $PATH) - copy the ssg5 executable file to the
binfolder, and make it executable by you
$cp ssg5 ~/bin $chmod u+x ~/bin/ssg5
Set Up src and dest
- You can create a source folder, named whatever, let's say
~/html_source - If you want to make sure things look right, you can make a destination folder that is not your
~/htmlfolder, you can make~/html_destand simply delete the contents of ~/html and copy ~/html_dest into it when you are satisfied; alternately, you can just drop the results straight into your live html or public_html folder.
Set up Header and Footer
If you want consistent headers or footers, just
- If your site has or wants a favicon, put it as favicon.png in
~/html_source - Put something you want at the beginning of each file (css, <HEAD>, whatever) into
~/html_source/_header.html- At minimum, you want a HTML and title tag, the blank Title will get filled by H1 of your Markdown doc
$ echo '<html><title></title><body>' > src/_header.html
- Put something you want at the end of each file into
~/html_source/_footer.html- At minimum, you want closing /BODY and /HTML tag
$ echo '</body></html>' > ~/html_source/_footer.html
- Exclude any paths in
~/html_source/.ssgignore
Put any existing HTML files into Source folder
You can copy whatever you already have in ~/html or ~/public_html (for your tilde site), into your ~/html_source folder
Start Writing Markdown
Ah, the easy part! Just write your musings in any text editor using the Markdown Syntax. You don't need to have any HTML but either of the two optional “H1” markdown tags at the top of your markdown file if you want a title filled in using the _header.html file trick of making an empty <TITLE></TITLE> tag, as above:
My Title =======
or
# My title
Running SSG5
If you just run ssg5 with no arguments it will give you its usage:
$ ~/bin/ssg5 usage: ssg5 src dst title base_url
Assuming you've added ~/bin to your path, simply run something like:
ssg5 ~/html_source ~/html_dest 'Test' 'https://<YOUR WEBSITE URL>'
If you used the minimal _header.html and _footer.html as described above, your page Titles will be of the form Whatever the H1 is in your Markdown - The Title you fed to the ssg5 command. It will appear in the generated HTML files in html_dest folder (using the example ssg5 command above) like so:
<html><title>This is my index file — Test</title> <h1>This is my index file</h1> ...
I use thessg5 tool for my tilde pages, so I run:
ssg5 ~/html_source ~/public_html “Peteyboy's tilde site” https://freeshell.org/~peteyboy
After you generate your site, run mkhomepg -p to fix any permissions for new pages
mkhomepg -p
Fancy Stuff
roman zolotarev has a watch executable that will monitor and refresh your site on any changes, and more details. Definitely check out his page: https://www.romanzolotarev.com/ssg.html