Random Notes

Mebe User's Guide

This is a user’s guide to the Mebe Minimalistic Elixir Blog Engine. If you notice any omissions or errors, please comment below or file an issue in the Bitbucket project.

Table of Contents

  1. Installation
  2. A note on character sets
  3. Basic concepts
  4. Writing a post
  5. Creating a page
  6. Menubar links

1. Installation

Mebe does not yet have proper releases, so the installation process is the following (simplified):

  1. Clone the repository.
  2. Copy all *.exs.dist files in config/ and remove the .dist extension. Set suitable configuration settings.
  3. To build the frontend, install npm and then run npm install && mix frontend.build. To build in production mode, run MIX_ENV=prod mix frontend.build. To digest the files, run MIX_ENV=prod mix phoenix.digest.
  4. Write your content in the data directory you specified in the configuration.
  5. MIX_ENV=prod mix compile
  6. MIX_ENV=prod PORT=1337 mix phoenix.server to start the server. Replace the port with a suitable one. You can either serve the blog publicly or proxy it through something like Nginx.

2. A note on character sets

Mebe is built to use Unicode via UTF-8. No other character encoding is supported. All content and filenames should be valid UTF-8. For filenames, it is suggested to stick with ASCII characters for compatibility.

3. Basic concepts

Mebe does not have an administration interface. To write a blog, content is placed in Markdown formatted files in a certain path (configured by the user as data_path). data_path is searched recursively for all matching files, so feel free to create as many subdirectories as you want.

Pages and posts are distinguished by their filenames: posts have their posting date in the filename. But more on that in the next sections. After startup, post and page data is stored in memory, so it is very quick to access.

4. Writing a post

Filename

To write a post, create a file somewhere in data_path with a name in the following format:

YYYY-MM-DD[-XX]-slug.md

The name above has the following components:

To clarify the above, here are examples of filenames and the URLs they will result in:

2016-05-16-best-post.md            -> /2016/05/16/best-post
1999-12-31-new-years-party.md      -> /1999/12/31/new-years-party
2010-01-01-01-prolific-day.md      -> /2010/01/01/prolific-day
2010-01-01-02-second-post-today.md -> /2010/01/01/second-post-today

As you can see, the slug is appended to the URL as is. It is not sanitized so it’s suggested to only use URL-safe ASCII there.

Anatomy of a post

Now that you have your file, you can start writing your post. Here is the basic format of a post:

My First Post!
first, meta, woo-here-i-go
author: Nicd
time: 15:02

This is my first post on my new awesome blog!
I will talk about _stuff_ and _things_ and **rockets**!!!

<!-- SPLIT -->

Isn't this blog great? I'm gonna write every day!

A post file starts with a title on the first line. The title will be shown in post lists, the post page, in feeds, and in the HTML title, so don’t use HTML there. There is no length limit for the title.

The next line has a list of the post’s tags. Tags are separated by commas and can contain any character, but they are used in URLs so again it is suggested to use URL safe characters. The post above has the tags “first”, “meta”, and “woo-here-i-go”. The tags are not sanitized so if you insert the wrong kind of characters, the tags won’t work.

After tags come custom headers. They are a list of key-value pairs, each on their own line. They are used for things like multi author mode or for marking the time of the post. If you make custom templates (which are talked about later in this guide), you can render any custom headers as you like. For example, you could have a custom header np: Foo - Bar, which could render that you were listening to the song Bar by Foo when you were writing the post.

Next we have an empty line and then the post content can start. From here on, all content is Markdown (parsed with Earmark, so for example Github Flavored Markdown tables are supported), with one exception: adding <!-- SPLIT --> anywhere will split the post into short and long content. Short content will be displayed in post lists and feeds (if so configured), along with an optional “Read more…” link. Note that when viewing the post itself, both the short content and the long content will be shown.

5. Creating a page

Writing a page is very similar to writing a post. A page is a Markdown file in the same way as a post, but it does not have any date information or headers. Here’s an example of a page filename:

slug.md

That is to say, the name of the file is used as the URL: a page my-page.md results in the URL path /my-page.

Example of the format of a page file:

My best page

This is my page content…

As you can see, a page file contains the title of the page, an empty file and then the content. Unlike with posts, there is no splitting of content because pages are not shown in lists.

6. Menubar links

By default a page is not linked to anywhere. If you want to add a page to the blog’s menu bar, use the menu file. The menu file is a file called menu in the root of data_path. Here is an example of a menu file:

/my-page My page
/about About
/terms-of-service Terms

The first part of a line is the path or URL of the link and the rest of the line is the name of the link to insert in the menu. The first part can be a path to a page or a blog post or even a URL to an external website.