ez-ssg

Want a minimal personal blog in 5 mins? Generate it using ez-ssg.

Check chettriyuvraj.github.io :)

Table of contents

Background

How will the the static look?

How to use ez-ssg to generate my static site?
 Install
 Organize your content
 Home Page
 Blog Listings Page
 Config
 Create a new post
 Create a new tag
 Fill up config.json
 Images and favicon
 Generate static site
 Serve static site locally

User Modes
 Command Line Mode
 GUI mode

TODOs

Acknowledgements

Background

I created my personal website using Jekyll a while back.

For a minimal website like mine, Jekyll felt like a bit of a pain to set up.

Since I already knew the theme and styling I wanted, I decided to write my own little static-site-generator.

How will the static site look?

A quick look at my static website:

Home page

Blog page

• Note how you can also see available 'tags' at the end of the listing

Blog post

Tags page

• Clicking on a particular tag at the bottom of the blog page brings us to this section.

How to use ez-ssg to generate my static website?

Install

go install github.com/chettriyuvraj/ez-ssg/v2@latest

Organize your content

Just provide the content, ez-ssg will do the rest.

ez-ssg is opinionated on how you need to structure your content directory.

Simply run the following command to give you a markdown folder organized in the correct manner:

ez-ssg init

markdown/
├── assets
│   ├── favicon.io
│   ├── images
│       ├── img1.png
│       ├── img2.png
|
└── posts
|    ├── Understanding_inferfaces.md
|    ├── Life_Lately.md
|
└── tags
|    ├── Understanding_inferfaces.md
|    ├── Life_Lately.md
|
└── blog.md
└── index.md
└── config.json

• markdown is the name of the top level directory
• assets contain images and favicon (site thumbnail)
• posts contain markdown files for blog posts
• tags contain json files for tags - e.g. your create a post and want to categorize it under the tag programming
• blog.md contains content written on top of the blog listings page
• index.md contains content written on the homepage
• config.json contains some site configs which need to be filled in by the user

Home page

The index.md page is autogenerated on running ez-ssg init and simply needs some content.

Fill in the data and metadata. The tags array is not relevant for this page.

Blog listings page

The blog.md page is autogenerated on running ez-ssg init and simply needs some content.

Fill in the data and metadata. The tags array is not relevant for this page:

Blog posts will be populated automatically when generating the site.

Config

The config.json file is filled with the following sample configs:

You can look at the screenshots of my website above and fill it up as follows:

• The title is what shows up as an h2 header on top of your homepage

• The description is used as a meta header

• The URL is used for serving the website, use http://localhost:3000 when generating it to serve it locally using ez-ssg serve and change it to your website's actual URL when generating it to serve online. (Generation using ez-ssg generate command explained ahead.)

  • Avoid trailing slash e.g. set URL as https://chettriyuvraj.github.io instead of https://chettriyuvraj.github.io/

• special_links show up alongside the Home and Blog pages as a navbar.

• paths can be left untouched

• You can add your tracking id inside google_analytics if you want to.

Create a new post

Run the following command - provide the post title and any optional tags.

ez-ssg post "Understanding interfaces via Golang" -t programming golang

This will genereate a post markdown file of the following form.

Fill in the content - you can add images to the markdown/assets/images folder and reference them in this manner:

Create a new tag

You created a post under the programming and golang tag.

However you have to create the corresponding tag for it to be displayed on the blog page as a filter.

ez-ssg tag programming golang

This creates two tag json files under the tags folder which look like:

You can create more tags if you want. Create a post under a tag and then create the tag - or vice versa.

Fill up config.json

Fill up config.json as described in this section

Images and favicon

• Double check if you have added images and favicon correctly in the assets folde.r

Generate static site

Finally, you can generate a static site using the following command:

ez-ssg generate

This will generate a folder as follows:

Serve static site locally

To see what you created, run this from outside the docs directory

ez-ssg serve <port number>

Note that you must change the URL field in config.json to http://localhost:<port_number> when serving locally

Modes

We have two modes, command-line mode and a GUI mode.

Command Line Mode

You can use ez-ssg as a regular command line program.

For reference, this is the help section for ez-ssg

ez-ssg		Create a static website like chettriyuvraj.github.io in 5 minutes.

Usage: ez-ssg <command> [argument]

Options:
	-h	Specify this flag in the command and we'll show you this help screen (e.g. ez-ssg -h)

Commands:

  init			Initializes content directories and base files for creating blog posts and adding tags. Use the absolute first time you are running this app.
  generate		Generates the static site.
  post			Creates a new post
  tag			Creates one/multiple new tag under which posts can be classified.
  serve			Serves the static site at the specified port. Port 3000 by default in GUI.
  interactive		Starts interactive command line interface

Commands Usage:

  init

  Usage: ez-ssg init


  generate

  Usage: ez-ssg generate


  post

  Usage: ez-ssg post <title> [options]

  Options:
    -t	Specify space-separated tags for the post. You must create the tag beforehand using the tag command.


  tag

  Usage: ez-ssg tag <tag 1> <tag2> ..
  

  interactive

  Usage: ez-ssg interactive


  serve

  Usage: ez-ssg serve <port-number>
  

GUI mode

There is also a GUI mode to use all the commands.

• Use up-down cursors to change commands
• Use tab to change inputs bars to enter input for a command
• Use enter to execute a command

Use the following command to start GUI mode

ez-ssg interactive

TODOs

• I want to add a bookshelf page which is a grid-like thumbnail + link of what I've been reading recently. I love reading but don't really read as much as I'd like to. I feel the act of putting out what I'm reading motivates me to read more.

Troubleshooting

The following points have been stated in the guide but are being stated again:

• You must change the URL field in config.json to http://localhost:<port_number> when serving locally and change it to your website's URL when generating static content for your site
• Avoid trailing slash e.g. set URL as https://chettriyuvraj.github.io instead of https://chettriyuvraj.github.io/ when setting URL field in config.json
• If you have created a post under a given tag, but not created a tag using ez-ssg tag tagname, the tag won't show up as a hashtag to filter in the blog listings page.

Acknowledgement

The theme is the jekyllBear theme

For the source code, I drew inspiration from:

• This blog
• Robert Nystrom's static site generator which he used to generate his e-book - Game Programming Patterns.