Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/AVGP/susi

Simplest. Static page generator. Ever.
https://github.com/AVGP/susi

Last synced: 4 months ago
JSON representation

Simplest. Static page generator. Ever.

Awesome Lists containing this project

README 

        
# SuSi2

## Because static site generation shouldn't be rocket science.



This is the **Su**​per **Si**​mple **Si**​te generator.



You give it markdown files and (if you fancy) an HTML layout to render them into - and it gives you static HTML.



That's it.

No magic, no fancy build tools - Markdown and HTML. Now go and make that website!



## How to use it



To setup, you run



```shell

    npm install -g susi

```



and then to parse markdown files into HTML you can use:



```shell

    susi directory/with/markdown_files/ output_directory/ path/to/layouts/

```



So, for example:



```shell

    susi /var/www/markdown /var/www/html  /var/www/layout.html

```



will parse all markdown files in `/var/www/markdown/` and will create corresponding HTML files in `/var/www/html/` using the `/var/www/layout.html` file.



## Using a layout



Now parsing naked Markdown files into naked HTML often isn't enough, so there's the layouts which you pass in as the third parameter.



At least create a single layout file called `page.html`.



### A basic layout

Say you have a layout with a few navigation links and some css like this:



```html

  

  

    

      

      {{title}}

    

    

      

        


      
{{title}}


      
{{date}}


      {{contents}}

    

  

```



When you pass in the path to this files directory as the third parameter, SuSi will render each markdown file into the place of ``{{contents}}``.

So if you do:



```shell

  susi input/ output/ path/to/layout/

```



A markdown file like this:

```markdown

{

  "title": "My Site",

  "date": "2014-11-27"

}



---



# Some headline



Some *text* of mine.

```



will be rendered into:



```html

  

  

    

      

      My Site

    

    

      

        


      

        
My Site


        
2014-11-27


        
Some textof mine.


      

    

  

```



which is pretty handy.



Each markdown file is expected to have a



### Using Frontmatter



Each markdown file is expected to have a a frontmatter section formatted in JSON like so:

```json

{

  "title": "new site gen",

  "date": "2014-11-27",

  "layout:" "page"

}

```



*Note:* A triple dash '---' on a new line is **required** to seperate the frontmatter from the markdown formatted text.



*Note:* You may leave out the `layout` field, which then defaults to `page`.



The layout attribute will be used to look for a file with a matching name and ".html" suffix in the directory

specified as the third parameter on the commandline to susi.



Of course additional, custom attributes can be optionally included in the frontmatter json and can then be used

in all the html layout files using the "Mustache" style syntax.



### Simple Includes



The html layout files can use the [Apache SSI style html comment "include" directive](http://httpd.apache.org/docs/2.2/mod/mod_include.html#element.include)

to pull in other layout files to provide basica support for "partials", to help keep things DRY, eg.



```html



 



 



    


      


        
{{title}}


        


          {{contents}}

        


      



    



    

```



*Note:* the "included" files can use the "Mustache" syntax as well, as they will be resolved after all the include directives

have been processed.



Now, seriously, go make static websites!



# License

SuSi is available under the [ISC License](LICENSE).



# Contributing

If you have any suggestions, found bugs or want a new feature, don't hesitate to submit a pull request or open an issue.



Pull requests are always welcome, no matter how small. But if you're about to create large, sweeping changes, I suggest opening an issue *before* making those changes to check, if they're making sense in the scope of the project and to discuss them to avoid later frustration.