empress-blog

There are lots of powerful things you can do with the Markdown

If you've gotten pretty comfortable with all the basics of writing in Markdown, then you may enjoy some more advanced tips about the types of things you can do!

As with the last post, you'll want to be looking at the source directly on github or in your local editor as you read it so that you can see all the Markdown code we're using.

Special formatting

As well as bold and italics, you can also use some other special formatting in Markdown when the need arises, for example:

• *escaped characters*

Writing code blocks

There are two types of code elements which can be inserted in Markdown, the first is inline, and the other is block. Inline code is formatted by wrapping any word or words in back-ticks, like this. Larger snippets of code can be displayed across multiple lines using triple back ticks:

Full bleed images

One neat trick which you can use in Markdown to distinguish between different types of images is to add a #hash value to the end of the source URL, and then target images containing the hash with special styling. For example:

which is styled with…

This creates full-bleed images in the Casper theme, which stretch beyond their usual boundaries right up to the edge of the window. Every theme handles these types of things slightly differently, but it's a great trick to play with if you want to have a variety of image sizes and styles.

Reference lists

The quick brown fox, jumped over the lazy dog.

Another way to insert links in markdown is using reference lists. You might want to use this style of linking to cite reference material in a Wikipedia-style. All of the links are listed at the end of the document, so you can maintain full separation between content and its source or reference.

Full HTML

Perhaps the best part of Markdown is that you're never limited to just Markdown. You can write HTML directly in the Ghost editor and it will just work as HTML usually does. No limits! Here's a standard YouTube embed code as an example:

Ember is a powerful Javascript Framework that is designed to maximise developer productivity. Ember also has one of the best plugin experiences in the industry, which means you can get a whole lot of functionality with just a simple npm install. If you want to check out the power of Ember's addon ecosystem you can visit Ember Observer which is made by Code All Day.

The design of empress-blog is a direct result of the work done to upgrade the Ember Guides into an Ember application. This system is specifically designed to make it easy for you to get started and if you have followed the instructions on the README you will know exactly how easy it is. If you are familiar with Ember you are probably used to the Zero Config experience of setting up new applications and adding addons 🎉

empress-blog does not, and will never have the concept of user roles!

This is because it is entirely a static system. You can assign authors to posts and generate new ones using ember generate author but if you need full user permissions (outside of something like Github) and collaboration features I highly recommend that you sign up for a hosted Ghost instance.

It's a good idea to fill out the metadata on authors, including bio and social links. These will populate rich structured data for posts and generally create more opportunities for themes to fully populate their design.

empress-blog uses a language called Markdown to format text, and so does the original Ghost 🎉

The main difference between the hosted Ghost platform and empress-blog is that we just use files on disk, so you can either edit your Markdown files directly or you can use a desktop Markdown editor. It keeps things simple but it can sometimes feel like you are writing on pro-mode 😎

If you want to start a new post we recommend that you use the built in generator ember generate post "The next big thing - empress-blog". This will create a file for you and setup the start of the metadata.

For now, though, let's run you through some of the basics of editing Markdown. You can see this post directly on github if you want to see all the Markdown we've used. (don't forget to click the Raw button to see the source).

Formatting text

The most common shortcuts are of course, bold text, italic text, and hyperlinks. These generally make up the bulk of any document. You can also make headings using # at the start of the line (multiple # symbols for h2/h3/h4/etc)

With just a couple of extra characters here and there, you're well on your way to creating a beautifully formatted story.

Inserting images

Images in Markdown look just the same as links, except they're prefixed with an exclamation mark, like this:

![Image description](/path/to/image.jpg)

If you want to add images to your empress-blog app you can just drop them in the /public folder, which you should see if you are running this locally!

Important Note: empress-blog does not currently have automatic image resizing, so it's always a good idea to make sure your images aren't gigantic files before adding them to your project.

Making lists

Lists in HTML are a formatting nightmare, but in Markdown they become an absolute breeze with just a couple of characters and a bit of smart automation. For numbered lists, just write out the numbers. For bullet lists, just use * or - or +. Like this:

1. Crack the eggs over a bowl
2. Whisk them together
3. Make an omelette

or

• Remember to buy milk
• Feed the cat
• Come up with idea for next story

Adding quotes

When you want to pull out a particularly good excerpt in the middle of a piece, you can use > at the beginning of a paragraph to turn it into a Blockquote. You might've seen this formatting before in email clients.

A well placed quote guides a reader through a story, helping them to understand the most important points being made

All themes handles blockquotes slightly differently. Sometimes they'll look better kept shorter, while other times you can quote fairly hefty amounts of text and get away with it. Generally, the safest option is to use blockquotes sparingly.

Dividing things up

If you're writing a piece in parts and you just feel like you need to divide a couple of sections distinctly from each other, a horizontal rule might be just what you need. Dropping --- on a new line will create a sleek divider, anywhere you want it.

This should get you going with the vast majority of what you need to do in the editor, but if you're still curious about more advanced tips then check out the Advanced Markdown Guide - or if you'd rather learn about how tags work, we've got a overview of how to use tags.

empress-blog currently only supports 2 themes, the default Casper template and the Attila template. If you want to swap between templates it is as simple as installing a different npm dependency 🎉

The empress-blog documentation recommends that you use the default theme called Casper, which is designed to be a clean, readable publication layout and can be easily adapted for most purposes. The empress-blog-casper-template is a direct fork of Ghost's official Casper repository so it aims to be as close as possible to the original.

If you are interested in writing your own theme for empress-blog you can get started using

and it will create a brand new template addon in the folder empress-blog-template-name-template! You can check out the documentation for create-empress-blog-template here. As Ghost uses handlebars it is not too difficult to port an existing Ghost template to use Ember templates, so if you have any requests for an existing open source Ghost template please let us know 👍

If you do end up writing an empress-blog template please let me know on Twitter so I can include your template in a list of existing templates.

empress-blog has a single, powerful organisational taxonomy, called tags.

It doesn't matter whether you want to call them categories, tags, boxes, or anything else. You can think of tags a lot like Gmail labels. By tagging posts with one or more keyword, you can organise articles into buckets of related content.

Basic tagging

When you write a post, you can assign tags to help differentiate between categories of content. For example, you might tag some posts with News and other posts with Cycling, which would create two distinct categories of content listed on /tag/news/ and /tag/cycling/, respectively.

If you tag a post with both News and Cycling - then it appears in both sections.

Tag archives are like dedicated home-pages for each category of content that you have. They have their own pages and hopefully soon will support their own cover images and meta data.

The primary tag

At the top of every post there is a tiny bit of YAML, and the tags key is an array of tags. The first tag in the list is always given the most importance, and some themes will only display the primary tag (the first tag in the list) by default. So you can add the most important tag which you want to show up in your theme, but also add a bunch of related tags which are less important.

tags:
  - news
  - cycling
  - bart-stevens
  - extreme-sports

In this example, News is the primary tag which will be displayed by the theme, but the post will also still receive all the other tags, and show up in their respective archives.

Hey! Welcome to empress-blog, it's great to have you :)

We know that first impressions are important, so we've populated your new site with some initial Getting Started posts that will help you get familiar with everything in no time. This is the first one!

There are a few things that you should know up-front:

1. empress-blog is designed to be a static site version of the amazing Ghost blogging platform

2. empress-blog is designed for developers who know how to deploy a static site (folder of html files and assets) using something like S3 or even just on NGINX.

3. If you are slightly less tech savvy or if you want to manage your blog outside of just a set of files in a git repo we highly recommend signing up for Ghost

Quick Start

It will ask you if you want to update the index.html file and you should say yes 👍

If you want to see the blog system running on your local machine just run npm start and you will be able to navigate to http://localhost:4200 to see the blog in action.

The main thing you'll want to read about next is probably: editing files with empress-blog.

Once you're done reading, you can simply delete the default Ghost user from your team to remove all of these introductory posts!