Introduction
Maren is a simple theme based static site generator.
Let's look first at these words, what they mean.
Simple (There are only 4 simple commands to know, you don't even have to remember them. Maren also doesn't force you to learn any conventions or rules, therefore, you're freer to focus on what's important, the writing.)
Theme based (Maren converts your blog, which is a basically set of Markdown files, to HTML, by using a Theme - this is an essential concept of Maren which we'll get back to later. It is nothing complicated or something to be worried about. Actually, it is an exciting playground!)
Static site generator (It means Maren can take care of creating your blog. You write the blog, but the final product, called the build, which you then upload to the Internet, can be created for you.)
Examples
First, let's see what we can achieve:
Maren
Maren as a name has 2 origins. Maren, at its core, is a theme based markdown renderer (might sound complicated, but isn't).
In those words you can see markdown renderer and therefore, a memorable Maren was born.
Maren also means "star of the sea" and comes from the Latin name Mary.
I considered that as a very nice name, also easy to remember, and type.
Creating our first blog
Get ready. Make yourself comfortable. Grab your favorite tea or coffee. I will now guide you throw the whole process of creating the blog!
The steps we will cover, are:
1) Starting a new blog
2) Writing the content of the blog (the most important part)
3) Previewing the blog (checking it looks and feels as we expected)
4) Uploading the blog so the whole Internet can see it!
5) Using your own theme!
Excited? Let's get started!
Step 1: Starting a new blog
It all starts by creating a new folder for our blog.
mkdir myblog
cd myblog
It's time to install Maren! (run the commands in our myblog directory)
npm init -y
npm install maren
npx maren init
Step 1 is almost done. And it couldn't be faster!
We have now myblog folder, installed Maren, and the blog is initiated by maren init we run. But, what does maren init do, you might ask?
It will simply prepare our blog to have the folder structure, that will guide us to organize our files nicely!
The content of our myblog should look like this:
~/myblog/documents
~/myblog/draft
~/myblog/static
~/myblog/themes
~/myblog/maren.json
What are those folders? Let's think about that in step 2!
Step 2: Writing the content
/documents => place to write our Markdown files!
/draft => place to put our unfinished work (Markdown files, text files, whatever!)
/static => place to put our images, music files, videos, simply any static content that is supposed to, stay static!
/themes => this folder is initially empty, but a whole thing can be going on once we dig into it. It is the place for our themes! Remember? Themes used to render Markdown files to HTML? Here they are.
/maren.json => A configuration file that can set the current theme, or plugins to use. It is an optional file (doesn't have to exist).
Let's write our first Markdown files, shall we?
To write Markdown files, you might use any editor you like! In our scenario, we simply put a few commands to get ready fast! And to make it even more interesting, there are two strategies to do so! Pick the one you like most! You can even combine them and use them simultaneously!
Strategy 1
echo "# My blog" > documents/index.md
echo "# 404" > documents/404.md
mkdir documents/article-1
mkdir documents/article-2
echo "# My first article" > documents/article-1/index.md
echo "# My second article" > documents/article-2/index.md
mkdir draft/not-yet
echo "# My draft" > draft/not-yet/index.md
Strategy 1 might work perfectly, it fully mirrors what you might expect to see at your website, as html file of course.
Strategy 2
echo "# My blog" > documents/index.md
echo "# 404" > documents/404.md
echo "# My first article" > documents/article-1.md
echo "# My second article" > documents/article-2.md
echo "# My draft" > draft/not-yet.md
Strategy 2 is more natural and helps to get around more easily once you have many files opened. As being said, you're free to use both strategies simultaneously to achieve your best!
Step 3: Previewing the blog
We are almost done! To preview the blog, we need to build it first.
To do so, run:
~/myblog $ npx maren build
This step will create a special folder named _build. It is a place where you'll find all html files, themes files, static files. But not drafts. Still though, you can preview the drafts using the local server!
To preview the blog, run:
~/myblog $ npx maren serve
# Serving at http://localhost:8080
That's it! Open the browser and try to visit:
http://localhost:8080
http://localhost:8080/any-random-url/
http://localhost:8080/article-1/
http://localhost:8080/article-2/
http://localhost:8080/not-yet/
Bonus: If you'd like to preview your blog and see your edits without restarting the server, simply, instead of maren serve, use:
npx maren watch
Step 4: Uploading the blog
Uploading the blog is unfortunately behind the scope of this article, but I will explain to you all the necessary steps.
To upload the blog, you probably wouldn't like to do it manually!
This is where plugins comes to play. One of these plugins is maren-s3 which provides an easy upload capability to AWS S3.
First, we need to install the plugin inside myblog:
npm install maren-s3
To enable the plugin, we might need to update maren.json, to make it look like:
{
"theme": "",
"plugins": [
"maren-s3"
]
}
Then, we simply upload the blog by running:
npx maren upload myblog # name of our S3 bucket.
Step 5: Using your own theme
By default, a built-in theme is used, to get quicky running.
It is also a perfect fallback.
Now, it's time to boost things a bit and use some custom theme.
To do so, simply run inside your myblog directory:
git clone https://github.com/penge/maren-theme-default.git themes/default
(cd themes/default && npm install)
To use the theme, or to change the theme, we update maren.json, and make in this case, like this:
{
"theme": "default",
"plugins": [
"maren-s3"
]
}
Then, run the build and server again!
npx maren build
npx maren serve
And whoala! You should see the blog in a fresh new look!
The best part of it is, the Theme can be developed by any set of tools, and customized to any level of imagination.
Final notes
I hope you've enjoyed reading this article as I've enjoyed writing it.
Probably, at this time, the coffee (or tea) is already finished, time for another one!
Also, I have mentioned, there is no need to remember maren commands. To get a reminder, simply run:
npx maren
The output you might see (especially if you have maren-s3 installed) might look like this:
maren <command>
Commands:
maren init init current folder
maren build build blog to _build directory
maren watch watch markdown files for changes and
create html
maren serve [--port] serve files for local preview
maren upload <bucket> [--themes] upload to S3
[--static] [--html] [--dryrun]
Options:
--version Show version number [boolean]
--help Show help [boolean]
That's all for now!
In case you'd like to know more, please, visit https://maren.io.
Top comments (1)
Hi guys!
Here's an example, how this article can look in Maren.
pavelbucka.com/how-to-write-a-blog...
I hope you'll like it! :)
PS: Notice the generated TOC (Table of contents) in the top.
And also the % progress updated while reading :)))