User Tools

Site Tools


a_simple_static_site_generator

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 bin folder, 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 ~/html folder, you can make ~/html_dest and 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.

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 &mdash; 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

a_simple_static_site_generator.txt · Last modified: 2023/02/23 20:15 by peteyboy