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:
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.
Create a new folder for your blog, and from this folder root run:
1post startYou 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.
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.
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}"
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
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):
<h3>{{dog_name}}</h3>That will be compiled to
<h3>Ruffus</h3>This is your blog favicon, change it as you wish.
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.
This is your blog index. This file is automatically generated, to edit your index you must edit the template-index.html file.
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.
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.
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-postA 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.
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.
Delete the posts from your blog folder /posts. Now just rebuild your posts feed by running:
:
1post build --force
If you want to serve your blog for testing purposes, just run:
1post serve
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/.
1Post uses Prism.js for blazing fast code highlighting of over 200 programming languages and markup.
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.
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.
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.
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.
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.
Your blog is a simple collection of static files, just drop its folder on the server and go get a coffee ;)
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 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.