Differences

This shows you the differences between two versions of the page.

--- a_simple_static_site_generator [2021/04/09 22:22] – [Copy to your personal bid directory] fix typo peteyboy
+++ a_simple_static_site_generator [2023/02/23 20:15] (current) – added explanation peteyboy
@@ Line 1: / Line 1: @@
+====== 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.
+===== 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 [[ https://daringfireball.net/projects/markdown/syntax | 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:
+<code>
+My Title
+=======
+</code>
+or
+<code>
+# My title
+</code>
+===== 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:
+<code>
+<html><title>This is my index file &mdash; Test</title>
+<h1>This is my index file</h1>
+...
+</code>
+I use the''ssg5'' tool for my tilde pages, so I run:
+''ssg5 ~/html_source ~/public_html "Peteyboy's tilde site" <nowiki>https://freeshell.org/~peteyboy</nowiki>''
+**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