npm package: 1post
Description: A tiny, fast and fun static site generator
Author: Felippe Regazio
Latest version: 1.5.0

# 1POST

A tiny, fast and fun static site generator for quick blogging. 1POST is written entirely in NodeJS and has no dependencies. You can install as a global package or run directly from NPX. This is the Lighthouse results for 1POST generated pages:


<img width="566" style="margin: 0 auto; display: block" alt="Screen Shot 2022-05-02 at 03 00 52" src="https://user-images.githubusercontent.com/31618881/166191359-67e7e736-af0c-478d-a310-7434b90243b2.png">

## Installation

To install 1post, just run on a terminal:

```
npm install -g 1post
```

Now if you type `1post` on your terminal, you must see a "help" output.  
If you prefer not to install it, you can execute all the commands directly on NPX.

## Usage

Create a new folder for your blog, and from this folder root run:

```bash
1post start
```

You just created a new blog in the current folder, we will talk about its files soon.  
Now just run:

```
1post my-first-post
```

A new post has been created in the folder `/posts`. You can edit the post by editing the file `/posts/my-first-post/post.html`, this file is your post and will be automatically processed on every build. Now run:

```
1post build
```

Now your static blog has been assembled and is ready for deploy.  
If you want to test the results, just type:

```
1post serve
```

This command will serve the current blog locally with live server for tests purposes only.

## Markdown

If you prefer to write using markdown, just append the flag `--md` after your new post slug when creating a post. For example:

```
1post my-first-post --md
```

This will create a `post.md` file instead of an .html one on your post folder. Now you can write your post using markdown. You can also change a `post.html` file to a `post.md` file from any post at any moment and 1POST will start to automatically parse markdown for this post too.

## Help && Commands

1POST has 5 commands only, as mentioned on its help:

```
1POST is a CLI to create and manage a very simple static generated blogs via NPX
For more information: https://github.com/felippe-regazio/1post

Usage:
  npx 1post {command}|{postslug}

Commands:
  help: show this help
  start: start a new blog on the current folder
  build: builds the blog. adding --force will skip cache
  serve: serves the blog locally with live server

Blogging:
  To create a new post, just run "npx 1post {postslug}"
```

## Configuring the blog

To start a new blog, create a folder then run

```
1post start
```

This command must be executed only one time by folder. If you run it on a ready-existent blog, your custom files will be overwrited. After running the command, you will see 5 new files and a `posts` folder.

```
blog/
  posts/
  blog-config.json
  card.jpg
  favicon.png
  index.html
  template-index.html
  template-post.html
```

### blog-config.json

This file is responsible for your global blog configurations, its entries are available on every template file at 1post (even post files) by interpolating the key name like this {{blog_title}}. You must fill all the fields on this file as explained:

|key|description|
|---|---|
|blog_locale|A ISO locale to use as your blog locale, ex: en, fr, pt-BR|
|blog_title|Your blog title|
|blog_description|Your blog description|
|blog_theme|You can choose a blog theme or create one by yourself, see the `Theming` section of this doc to know more|
|blog_author|Probably your name|
|blog_author_url|An URL to know more about you, ex: LinkedIn, Facebook, etc|
|blog_no_posts_hint|Phrase to show when the blog list is empty|
|blog_posted_by_hint|Phrase to but before credits, ex: "Posted by"|
|blog_url|Your blog deployment URL, ex: "http://myblog.com"|
|blog_prism_theme|Your `Prism.js` code highlighting preffered theme, see the `Code Highlighting` section of this doc to know more|

You can create new entries on this file, but you must not delete or ovewrite the existing ones. Let's imagine you created an entry called `dog_name` like this:

```
{
  ...
  dog_name: "Ruffus"
}
```

Now you can use `{{dog_name}}` on every template file. If you want to show your dog name, just type on any template html (template-* file or post.html file):

```html
<h3>{{dog_name}}</h3>
```

That will be compiled to

```html
<h3>Ruffus</h3>
```

### favicon.png

This is your blog favicon, change it as you wish.

### card.jpg

This is the SEO card image. When using metatags to show a preview about your content, this image will be used as cover, you can changed it as you want. Recommended size: 1200px x 627px. 

### index.html

This is your blog index. This file is automatically generated, to edit your index you must edit the template-index.html file.

### template-index.html

This is your blog Home template. You can edit it as you want, add new assets, images, dependencies, whatever. You can also interpolate any data from `blog-config.json` as mentioned above. An important thing to keep is the special interpolation `{{posts_feed}}`, as this is where your post list will rendered. Everytime you run `1post build`, this template is used to generate a new `index.html` page.

### template-post.html

This is your post template. Every post you write will respect this "layout". You also can edit it as you want, change anything you want. Here you can also interpolate any key from the `blog-config.json`, and also from your `post configuration header` which we will talk about later. The special interpolation key `{{post}}` is used to bind your post content to this layout, dont remove it.

## Writing a Post

To write a post, you must type `1post {postslug}`, where post slug will be the address to your post and also its folder name on `/posts` folder. Lets create a post. After start your blog (read the "Configuring the blog" section of this doc) run:

```bash
1post my-first-post
```

A new folder `/posts/my-first-post` was created with the following files

```
posts/
  my-first-post/
    index.html
    post.html
```

The `index.html` file is an automatically generated file, it binds your `post.html` file to your `template-post.html` file and parsed to build the final version of your post. Now, to write your post, just edit the file `post.html`.

When opening your `post.html` you will see a strange notation at the top of the file. You must not remove or change this notation structure, but you can add new items to it. This is your post-metadata, you must fill the post Title and Description there, it will be used to SEO and to render your post H1 heading.

```
<!--:::{
  "post_title": "Post title",
  "post_description": "Post description",
  "post_created_at": "Mon May 02 2022 01:35:03 GMT-0300 (Brasilia Standard Time)"
}:::-->
```

You can also add new entries to the post-metada if you want, for example: `"favorite_food": "garlic"`, and then retrive its value on the post by interpolating `{{favorite_food}}`. You can also bring any value from the `blog-config.json` file by interpolation. After filling the post-metadata, just write your post as a simple and usual HTML file.

## Building the blog

After writing or editing a post you must rebuild your blog,. To do it just run

```
1post build
```

This will reconstruct your index page with the new posts feed, and will also parse the new and modified posts. Remember to run this command before every deploy.

## Removing Posts

Delete the posts from your blog folder `/posts`. Now just rebuild your posts feed by running: 
:

```
1post build --force
```

## Serving locally

If you want to serve your blog for testing purposes, just run:

```
1post serve
```

## Blog Theming

You can change your blog theme on the file `blog-config.json` by editing the key `theme`. It supports the following values:

```
black-and-white
dark-blue-ocean
default-dark
default
fluorescent-green
skinny-theme
solar-theme
solid-pink
sweet-carnival
wooden-theme
```

You can preview any of this themes by visiting https://felippe-regazio.github.io/plume-css/ and clicking on the button in left bottom corner of the screen. You can also create your own theme, if you desire to create your theme, please read the Plume-CSS documentation.

1Post uses Plume-CSS for styling. Plume is a very simple, powerful and lightweight CSS-Only Microframework created by same creator of 1Post. So, anything Plume's can do, 1Post can also do. You can check Plume's documentation here: https://felippe-regazio.github.io/plume-css/.

## Code Highlighting

1Post uses Prism.js for blazing fast code highlighting of over 200 programming languages and markup.

### Usage

To activate code highligting, make sure your code is inside a `<code>` tag enclosed by a `<pre>` tag. To set the intended language, add a css class to your `<code>` tag using the following pattern: `language-xxxx`. (Eg. `language-python`, `language-rust`...)

```
<pre>
  <code class="language-python">
    print("Hello, 1Post!")
  </code>
</pre>
```

To learn more about what you can do with Prism.js and dive deep into its functionalities, please refer to the official [documentation](https://prismjs.com/).

### Code Highlight Theming

You can change your code highlighting theme on the file `blog-config.json` by editing the key `blog_prism_theme`. It supports the following values:

```
prism
prism-coy
prism-dark
prism-funky
prism-okaidia
prism-solarizedlight
prism-tomorrow
prism-twilight
```

To preview all themes and learn how to make your own, please refer to the official [documentation](https://prismjs.com/).

## Static Assets

Everything in 1POST is just simple HTML combination and interpolation, there is no complex building process, just add your assets as you would do on a normal HTML file. A tip: Try to keep header assets and script tags on the `template-*` files.

## Cache

1POST has a cache strategy to process only new and/or modified posts on a new build. If want to clean the cache and rebuild all the posts from scratch, just delete the file `/posts/cache.json`.

## Updating 1Post

To update 1Post just run `npm install -g 1post`. Now go to your blog and run `1post build --force` to rebuild your posts feed with the newer features. Obs: You dont need to add --force argument to build new posts from here.

## Deploying

Your blog is a simple collection of static files, just drop its folder on the server and go get a coffee ;)

## Contributing

PR's are welcome. 1POST has a ridiculously simple code architecture, and its built under a dumb imperative paradigm. The index.js dispatch the commands, and all the commands logics are on the `cli` folder.

## 1POST Philosophy

1POST is very small and really - i mean REALLY - simple. It's built to quick, pretty, fast and powerful blog writing, specially technical blogs. All the posts will be at the same level in a unique list at the Home page with an stupidly fast UI. Its mean to be like this. 

If you need more features, complex customizations, rich designed pages, deeper kind of control, content categorization, etc... 1POST it's not for you. There is a plenty of other options out there that can suit your needs as a breeze and infinitelly better then 1POST could do. But if just want to quick blog your posts with a cool and minimalist design and a great performance out of the box, 1POST will make you happy, for sure.