Hindsight

What?

Hindsight is a Markdown based static website generator.
Hindsight makes creating, deploying and maintaining static websites easier.

Why?

Because I wanted to have an automated way for creating static websites.
It became hard to develop and maintain documentation websites. Using a CMS was just overkill.
So I asked myself, what changes on templates among websites? Settings and Content.
Everything is automated. Give what is needed, run Hindsight and get your website content!

What we need for generating a static website :

• a configuration file for website information (JSON)
• contents of pages (Markdown)
• a single template file (HTML) -- you can also have CSS and JS

Give these to Hindsight and get what you want as a static website!

How?

Simple. Here is a formula, if we were to think Hindsight as a math function :

Hindsight ( JSON + HTML + Markdown ) = website

Create a folder for your website project.

NOTE

Hindsight is a PHP app. It is actually a PHAR binary.
So you have to use PHP CLI to run Hindsight.

Download the 'hindsight' file in the root repository folder.
Copy 'hindsight' binary to your website project folder.

Run Hindsight in that folder from terminal.

> php hindsight <command>

Commands

• init

  Creates an empty website project in the current folder.
  This is a sample project directory structure :

  [ROOT]
  |-- README.txt
  |-- hindsight.json
  |-- hindsight.lock
  |-- composed/
    |-- index.html
    |-- <page-name>.html
  |-- pages/
    |-- index.md
    |-- <page-name>.md
  		···

• compose

  Composes your website and publishes into composed/ folder.
  You can directly upload what is inside composed/ folder, to your server.
  If you wish, you can also put some more stuff in. Like images, CSS, JS. Anything.
  It's freedom !

• status

  Tells you if something is changed and website should be composed again.
  You can see your website project's current status with this command.

• about

  Gives information about Hindsight.

• help

  Shows a simple documentation on Hindsight.

The Beginners Guide to Hindsight

So, what to do? Well, simple.

• hindsight.json

  Your website data file. It is like a monolith settings file.
  For now, you define placeholders here, which are in your HTML template file.

  • data

    You give your [placeholder] + [contents] as "key": "value" pairs.
    These placeholders will be replaced by their contents in each of your pages.

    Important !

    There is a reserved placeholder, which is {{ $markdown }}.
    You must not use this reserved placeholder in your hindsight.json.
    This points to where your Markdown contents will be injected into.
    So DO NOT FORGET to put this placeholder in your template !
    Otherwise Hindsight will assume that you won't use Markdown.

    This is a sample hindsight.json :

    {
      "data": {
        "title": "Hello!",
        "contents": "This is some text.",
        "author": "Doruk Dorkodu"
      }
    }

• hindsight.lock

  Hindsight locks the current state of the website, into this file.
  This is used for tracking changes in your contents.

• page.html

  Your single HTML template file.
  You put placeholders in this file. This is the pattern for placeholders : {{ placeholder }}
  If you set "placeholder" to a string in hindsight.json, Hindsight will replace the placeholder with its value.

  Your template file can have any CSS or JS. Hindsight DOES NOT (!) handle your assets.
  You can put them into your composed/ folder as how you wish.
  

• pages/

  This is the folder you put your pages as Markdown files.
  For each Markdown file in this folder, Hindsight will create a data-seeded HTML file with its name.
  For example you have these two ".md " files in pages/ folder :

  index.md + about.md >> index.html + about.html

  You will get two ".html" files in composed/ folder.
  Which are seeded with data you give in hindsight.json file.

Author

Doruk Dorkodu : GitHub | Twitter | doruk@dorkodu.com | dorkodu.com

See also the list of contributions that we are making at Dorkodu to the free software community.

License

Hindsight is open-sourced software licensed under the MIT license.