1post v1.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:

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:

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:

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):

<h3>{{dog_name}}</h3>

That will be compiled to

<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:

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.

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.

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.