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
- A note on character sets
- Basic concepts
- Writing a post
- Creating a page
- Menubar links
Mebe does not yet have proper releases, so the installation process is the following (simplified):
- Clone the repository.
- Copy all
config/and remove the
.distextension. Set suitable configuration settings.
- 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.
- Write your content in the data directory you specified in the configuration.
MIX_ENV=prod mix compile
MIX_ENV=prod PORT=1337 mix phoenix.serverto 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 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
To write a post, create a file somewhere in
data_path with a name in the following format:
The name above has the following components:
- YYYY, MM, DD: The year, month and day of the post, respectively.
- XX: The order number of the post, optional. Should be used for ordering if there are multiple posts in one day.
- Slug: The part of the post that is appended to the URL. Should be unique per day (you can’t have two identical slugs in the same day, because that would result in identical URLs).
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:
That is to say, the name of the file is used as the URL: a page
my-page.md results in the URL path
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.