~evan-hoose/SSSSS

#SSSSS

Stupid Simple Static Site Starter

IMPORTANT: SSSSS requires that a markdown renderer be installed, and be executable from a shell as 'markdown'. SSSSS assumes that the renderer will only render exactly what is in the file, and not add anything like <body> tags.

In addition to this assumption, SSSSS assumes that

$ markdown file.md

will output the generated html to stdout.

EQUALLY IF NOT MORE IMPORTANT: SSSSS assumes that there is a POSIX sh at /bin/sh. If there isn't, who knows what will happen, but probably not what you want. In addition, s5-render does pass some user defined values to sh in the form of path names. If you run it somewhere where a path includes valid commands, you're gonna have a bad time.

##About

This program will take a directory structure consisting of directories with images and markdown files and render it to an html website.

The top level directory will include templates for:

The html-header.html (<!doctype>, <html> and <head> tags.)
The document-header.html (<body> and whatever html you want to be included in the header of your website.)
The document-footer.html (Your html for the footer, followed by </body>)

When SSSSS renders a given Markdown file it will place the templates and markdown in this order:

html-header.html
document-header.html
input.md
footer.html

One final feature. If you put a document-header.html file in the top directory or one of it's sub-directories, that document-header.html file will be passed down the directory tree, in order to make things like a tabbed interface require less JS and/or drudge work. If you use this feature, be aware that if you put a document-header.html into a child directory, you need to put one in the parent as well, or else sometimes the child will leak upwards.

This is a bug, but one that I've found easy enough to work around that I haven't felt compelled to fix it yet. If at some point there is demand for this, I may fix it.

There must be exactly one markdown file in each directory of the structure that SSSSS is called on. SSSSS will take this:

DemoSite
|- html-header.html
|- document-header.html
|- footer.html
|
\-top
  |- document-header.html
  |- index.md
  |
  \-about
  | |- document-header.html
  | |- about.md
  |
  \-blog
  | |- document-header.html
  | |- blog.md
  | |
  | \-post-one
  | | |- post-one.md
  | |
  | \-post-two
  |   |- post-two.md
  |
  \-other
    |- document-header.html
    |- other.md

and turn it to:

DemoSite
|- html-header.html
|- document-header.html
|- footer.html
|
\-top
 |- document-header.html
 |- index.md
 |- index.html
 |
 \-about
 | |- document-header.html
 | |- about.md
 | |- index.html
 |
 \-blog
 | |- document-header.html
 | |- blog.md
 | |- index.html
 | |
 | \-post-one
 | | |- post-one.md
 | | |- index.html
 | |
 | \-post-two
 |   |- post-two.md
 |   |- index.html
 |
 \-other
   |- document-header.html
   |- other.md
   |- index.html

Although it seems strange that it would render every markdown file to a file called index.html, there are actually two reasons. First, it allows you to have nice looking URI's without needing to do any extra configuration in your webserver. Second, it allows for less and simpler code, which makes this easier to hack on for anyone who feels interested.

##Tutorial

So you read through all that and still want to try this out? Cool. Start by cloning this repository and installing some markdown program. After you have done this, move the programs s5-generate.sh and s5-render into your path somewhere, or just remember their fully qualified path.

Next, run

$ s5-generate.sh HelloWorld

This will create a new site called, you guessed it, HelloWorld. Move into the HelloWorld directory you just created, you should see the template files mentioned above, and a directory called top. The interior of top is where your site will start.

Go ahead and cd yourself into top, and create a markdown file with content of your choosing. I'm just going to go with a nice "Hello, World".

file: WhateverNameYouWant.md

#Hello, World!

Why does the world never say hello back?

After doing this, cd back up into the HelloWorld directory. Once there, run s5-render and go back down into top. There should now be whatever markdown file you created, along with an index.html file. Go ahead and play around with changing the template files at the top, and look at how the outputed html files change.

Presumably if you've found this, you know enough about computers to figure it out from here.

refs

clone