Skip to content

Home

Jump to bottom
Mathieu Dombrock edited this page Aug 5, 2021 · 2 revisions

SteelSky

SteelSky is a"no BS" static site generator that takes your valid Markdown and HTML (or a hybrid of the two) files and turns them into a static site.

The directory structure used for generating a site with this tool is pretty simple.

  • layout/ - This directory contains the site layout and theme files.
  • out/ - By default this directory contains the generated static files.
  • source/ - This directory contains the page content either as HTML or Markdown.
  • config.js - This is the configuration file which is required to run SteelSky.

Site Style & Layout

Simply create a layout directory that looks something like this:

layout/
--footer.html
--header.html
--theme.css

The layout directory includes all of your site's global styles and layout.

NOTE: Markdown in this directory will NOT be processed.

Header

header.html will be placed at the top of every generated page. This file is standard HTML that contains your <head> meta data as well as anything else you might want to include at the top of every page.

This can contain any JS that needs to called or any navigation elements you want to include.

Here is an example of a simple header that contains some static navigation links:

<head>
  <title>SteelSky</title>
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <meta charset="utf-8"/>
</head>
<h1><a href="/testx/out/">STEEL SKY</a></h1>
<small>A very lightweight, no BS static site generator written in NodeJS.</small>
<hr>
<h3>
  <a href="/testx/out/listing-advanced.html">listing</a> |
  <a href="/testx/out/test.html">test</a> |
  <a href="/testx/out/x/y.html">x/y</a>
</h3>
<hr>

NOTE: Do not place any <body> tags here.

Footer

footer.html will be placed at the bottom of every generated page. It works in the same way as the header.html file so anything said about that applies to the footer as well.

Here is an example of a simple footer.html file:

<hr>
<div>Footer | <a href="https://github.com/matdombrock/SteelSky" target="_blank">Github</a></div>

NOTE: Do not place any <body> tags here.

Theme (CSS)

theme.html will be placed near the top of every generated page. If you need to load styles later, they should be imported in the footer.

This file can contain any valid CSS. Any CSS rules specified here will be available on any page generated by SteelSky.

NOTE: If you need to apply page-specific styles, they should be written into or imported by the page itself using HTML.

Here is an example of a valid theme.css file:

body{
  background:rgb(33, 33, 33);
  color:rgb(233, 233, 233);
  padding:1em;
}
a{
  color:rgb(233, 233, 233);
}
img{
  max-width:100%;
}

Creating Pages

Now that you understand how the site style and layout are setup we can discuss how to create pages and add content.

By default, anything inside of the source/ directory will be converted or copied to your static file output directory. More specifically, only Markdown files will be converted. Everything else is just copied (Including .html files).

The logic for generating a page is something like this:

  1. Header
  2. Showdown CSS
  3. User Theme CSS
  4. Converted Markdown
  5. Footer

HTML Only (.html)

So if you create a file with an .html extension in your layout/ directory it will not be converted at all. It will not get the header or footer content and the global CSS rules from theme.css will not work. This can be useful if you want to host a stand-alone HTML based project on your site.

Markdown & HTML (.md)

SteelSky has out of the box support for using both Markdown and HTML in the same file (you can even include CSS and JS). So if you want to use some HTML/JS/CSS but still take advantage of all the features of SteelSky just make a Markdown (.md) file and go for it.

Here is an example of using Markdown and HTML in the same file

## Current Projects:

### [Github](https://github.com/matdombrock/)
> Some cool quote.

<hr>

<img src="/max.png" width="256px">

Syntax Highlighting

Syntax highlighting is handled automatically in Markdown files. The highlighting is preformed by Showdown. You can find more info at that link but in general it works a lot like you might expect if you have done markdown editing on Github ect.

Page Meta Data

Any Markdown page can contain meta data at the top of the page. To take advantage of this simply include the <steelsky> open and closing tags to the top of the file.

For example:

<steelsky>
{
  "title":"AARL (American Radio  Relay League)",
  "description":"Info about the AARL.",
  "tags":"#radio"
}
</steelsky>

Inside the tags you can put any (single) valid JSON object.

When the page is processed, it will convert the <steelsky> tags to <script> tags and assign the value of the JSON object inside of the tags to a globally (in relation to that page) accessible object named ssmeta.

**NOTE: The `ssmeta` object will only only be available to scripts that are in the body (content) of the page and in the footer.**

## Configuration

The `config.js` file can be generated simply by running SteelSky in an empty directory. 

Here is an example config file in case you want (or need) to write it yourself:

```js
module.exports = {
  "sourcePath": __dirname + "/source",
  "layoutPath": __dirname +"/layout",
  "highlightStyle": "a11y-dark",
  "outPath": __dirname +"/out"
};

NOTE: __dirname is a NodeJS global.

Source Path

This is the directory location of your source files.

Layout Path

This is the directory of your layout files.

Highlight Style

Sets the Showdown highlight style CSS. (This section needs more info).

Out Path

This is the directory of your static site output files.

Deleting Pages & Static Content

Deleting a file from the source/ directory and running steelsky will remove this file from the generated listing.json. However the old file will NOT be deleted from the out/ directory. In order to remove the file from your static output it will either need to be manually deleted or you will need to manually purge the entire output directory before generating a new set of static files.

Directory Listing

Every file that is processed or copied by SteelSky will be included in a file called listing.json in the root of the output path.

It might look something like this:

[
  {
    "path": {
      "root": "",
      "dir": "",
      "base": "bss-ss.jpg",
      "ext": ".jpg",
      "name": "bss-ss"
    },
    "location": "bss-ss.jpg",
    "meta": {}
  },
  {
    "path": {
      "root": "",
      "dir": "img_test",
      "base": "img_test.md",
      "ext": ".html",
      "name": "img_test"
    },
    "location": "img_test/img_test.html",
    "meta": {}
  },
  {
    "path": {
      "root": "",
      "dir": "",
      "base": "test.md",
      "ext": ".html",
      "name": "test"
    },
    "location": "test.html",
    "meta": {
      "test": "somename"
    }
  },
  {...}
]

This file can be imported into any other page or script and can be used to create directory listings among other things.

NOTE: This data also contains the meta data for each page.

There are examples of how this can be done in the SteelSky Example Repo

Here is one simple example (Markdown):

# Simple Listing Example

<div id="listing-area"></div>


<script>

let listing;

const xhttp = new XMLHttpRequest();
xhttp.onreadystatechange = function() {
    if (this.readyState == 4 && this.status == 200) {
      listing = JSON.parse(xhttp.responseText);
      processListing();
    }
};
xhttp.open("GET", "/testx/out/listing.json", true);
xhttp.send();

function processListing(){
  let html = "";
  let hasResults = false;
  for(let item of listing){
    const location = item.location;
    html += `<a href="${location}">${location}</a></br>`;
    hasResults = true;
  }
  if(!hasResults){
    html += "<strong>No results.</string>";
  }
  document.getElementById('listing-area').innerHTML = html;
}

</script>

Well

That's pretty much it.

Clone this wiki locally