Xiao Blog uses a Markdown editor to manage blog post content. In this post an overview of the editor features is given. The steps need to create and update a post are detailed. Screen captures are marked up and shown to help you get started using Xiao Blog.
Markdown is lightweight markup language for plain text files. While it can be easily read and semantically understood in its as-is raw form, its main use is to be translated to HTML. Markdown's tags map to those of a subset of HTML. Because of the compact, intuitive nature of Markdown, its markup is easily remembered and allows one to type HTML precursor text much faster that raw HTML.
As an exmaple of Markdown syntax, compare the equivalent markup between it and HTML to embed an image:
![My alt text](/path/to/img.png)]
<img alt="My alt text" src="/path/to/img.png">
Note how Markdown syntax is more compact since it does not require a verbose matching closing img tag nor tag attributes like "alt" explicitly called out.
Overview of Markdown Editor Process
- Sign-in to your Xiao Blog account (or sign-up first).
- Click the "Add New Post" button on the sidebar.
- Start entering Markdown into the "Post Markdown Content" form field.
- Click the "Preview" button to see a fast real-time HTML preview of your Markdown text.
- Toggle the "Preview" and "Edit" button by clicking on it, to go back and both between Markdown and HTML.
- Click the "Create Post" button when you are satisfied with your content.
- Xiao Blog will save your Markdown post content into MongoDB.
- Clients request your content, Xiao Blog will retrieve your Markdown, translate it on-the-fly to HTML, and render it to your client.
Xiao Blog uses the Node.js module marked.js for its Markdown-to-HTML conversions. The module has more than 30 releases and is actively worked on by more than 30 contributors. Marked.js claims to be "built for speed". Observations of it in use with Xiao Blog validate that claim. Marked.js adheres to GitHub Flavored Markdown by default, which is also the syntax of Xiao Blog's Markdown editor.
Next the above Markdown editor steps are covered in detail, with screen captures.
Sign-up and Sign-In
Sign-up and Sign-in can both be accessed directly from links at the bottom of the right sidebar. These links are visible on every page of Xiao Blog if a user is not logged-in. If a user has been authenticated, then the two links are replaced by a Sign-out link. Signing-out will clear the authentication cookie from a user's HTTP session and result in the Sign-in, Sign-up links again being rendered on every page.
A user must sign-up to create an account and be able to administer blog posts. Clicking on the Sign-up link will render a form containing first name, last name, username, email, and password fields. The screen capture below summarizes the process.
Immediately after signing-up, the user will have the HTTP session authentication cookie set and be able to administer posts. The user's information is protected by a randomly salted Bcrypt-hashed password.
Sign-in works similarly to Sign-up: clicking on the admin sidebar link results in a sign-in form. After successfully submitting the form the user will be send to the admin home page and able to administer posts. A screen shot of sign-in is shown next.
Blog Post Creation
Once signed-in, a link in the admin area of the sidebar called "Add a New Post" will be visible on all pages. Clicking on the link takes a user to the "Create Post" form page. There are two forms present on the page: a main form for post content and meta data, and a second form for uploading images. The main form has text fields for post title, description, content, and tags. Radio buttons for yes/no "publish now" of the post are also present. The image upload form uses a file browser to select images to be uploaded and referenced in the Markdown of the post. The image upload form uses Ajax to asynchronously post the upload and return the JSON meta data back to the page. The Ajax methods allows the user to stay on the creation form page and go back and forth with content editing as the required images are posted. The next screen capture the top portion of the main post form.
The title field is not only used to render an HTML h1 heading for the post, but also an HTML meta title tag that is important for on-page SEO. The description field is used solely for the HTML meta description tag which is shown in search engine result listings.
Toggle between Markdown and Markdown-to-HTML
The featured image of this post highlights the preview button of the main create post form. The button and Markdown editor work together as follows:
- Initially, the button is labeled "Preview". Raw Markdown is shown in the text area.
- Clicking on the "Preview" button invokes a call to Marked.js. The raw Markdown is converted to HTML. JQuery replaces the contents of the text area with the resulting HTML and renames the button to "Edit".
- Clicking on the "Edit" button reverses the process. JQuery swaps the Markdown-to-HTML with the in-memory stored raw Markdown and reverts the name of the button back to "Preview".
A post author will probably toggle the "Preview/Edit" button back and forth many times while writing Markdown, after uploading images, and adjusting layout.
Images, Tags, and Category: Convention over Configuration
Xiao Blog follows some simple convention over configuration rules:
- The featured post image is the first uploaded image.
- The post category is taken from the first specified tag. The category is also a tag.
"The category is also a tag" convention is followed by some high profile websites, including Nate Silver's fivethirtyeight.com.
Blog Post Updates and Deletion
Blog post updates are done nearly identically as their creation. The difference being that the form fields are pre-populated with the data stored in MongoDB.
Both update and deletion of blog posts are accessed from the admin home page. The admin home page renders a paginated list of all the posts with buttons to update and delete them. A screen shot of post from the admin home is shown below.
- Xiao Blog uses Markdown for the rapid creation of post content. This keeps the code base lightweight while giving the user layout flexibility.
- The Markdown editor does real-time previews of the content Markdown-to-HTML that will be rendered to clients. An author can toggle between the raw Markdown and HTML quickly.
- Users must sign-up for an account before they can administer blog posts.
- Xiao Blog supports: featured post images, topic tags, categories, on-page SEO (title and description), and others to numerous to mention here.