mongoblog v1.0.5

Mongoblog

Installation

$ npm install mongoblog -g

Mongoblog is an easy to use, developer friendly blogging system that uses a command-line interface to upload, edit, and delete blog posts. To use Mongoblog, you will need NodeJS installed on your system. I also recommend having MongoDB installed on your system for use in development and testing, but you'll need a remote database for use in production. You should also have an understanding of the following:

• Jade -- All HTML in this app is written in the Jade templating language. For information on using jade go to their website.
• MongoDB -- All database queries and inserts are taken care of in this app, but as all entries are to be stored in a MongoDB database that you initialize, it would be a good idea to have a basic understanding of how MongoDB works.
• NodeJS -- As with MongoDB, all of the Node work for a functioning app has been done already. But it wouldn't hurt to understand a little of what's going on behind the scenes.
• CSS -- If you're trying to design your own blog, it should go without saying that you know a bit of CSS.

The Mongoblog system consists of two components:

• The Mongoblog-template, which will be the starting point for your website.
• The Mongoblog-CLI, the command line interface you will use post to your blog, edit posts, delete posts, etc.

The Mongoblog-Template

The mongoblog Template is the boilerplate code for a NodeJS blogging app.

$ git clone https://github.com/nathanlisch/mongoblog-template

The index.js file contains the express server that will run your app, along with the routes that will fetch your posts from the database. Most of the time, this won't need to be messed with. The only thing you will need to do is change the dbUrl variable (this will be early in the file, and clearly commented) from "mongodb://localhost:27017/blog" to whatever the address is for the remote MongoDB instance that you set up, in the form of "mongodb://userid:password@address:port/dbname". You may also need to change the port variable (given as "app.set('port',...)") to whatever is required with your hosting service. It is currently set to process.env.PORT, and this will work with most hosts, but not all.

(NOTE: if this is your first time deploying a node app with a database, I recommend heroku.com for your app, and using mongolab as an add-on, as both services have a free plan, and heroku has the best starting guide I've seen for beginners).

In the index.js file, the two routes given are for the 'main' page, and for the 'article' page. The main page is given three variables to be used in the Jade file:

• 'titleList', which contains the list of titles ('My Blog Post')
• 'urlList', which contains the list of URLS(my_blog_post)
• dateList, which contains the list of dates

The documents containing this information are sorted by date (most recent to least recent) before being passed to these variables, so they are all in the correct order (titleList0, corresponds to urlList0 and dateList0, etc.).

The article page is given 6 variables:

• 'post', which contains the blog entry in markdown form (post shown is determined by the final parameter in the URL request -- www.example.com/article/my_blog_post would display the entry corresponding to the my_blog_post URL)
• 'title' which contains the title corresponding to the requested URL
• 'md', which contains the markdown parsing function (must be called on post within the Jade file)
• 'date', which contains the date the requested post was saved to the database. By default, this is displayed beneath the title in the Jade file
• 'titleList', which, like on the main page, contains the blog titles in order of date
• 'urlList, which contains the blog URLs in order of date. This and 'titleList' by default are used in the sidebar to display a list of links to the ten most recent posts.

Both Jade files are located in the views folder, and both contain a basic structure for a blog website. In these files, you can edit the structure of the app if you desire, but more likely, you will only need to enter these files to change the header and the 'about me' section. You should also familiarize yourself with the structure of the webpage so you know the elements to target when you edit the CSS.

In the public folder, you'll find the style.css file. This stylesheet is applied to both the main page and the article page, as both have a similar structure. This is the main file you'll want to edit to fully customize the look of your blog. The public folder also has an images folder for background images, etc. As the CLI doesn't currently support uploading pictures with blog posts, the only way to include pictures in individual posts is with direct html img links, which can be put directly in the markdown. You can use this to link to pictures hosted elsewhere, but be aware that this is considered bad practice. The best way would be to put pictures in the /public/images folder, link to those (img src='/public/images/mypic.jpg), and then re-deploy your app.

There is also a markdown folder filled with lorem ipsum (dummy text) markdown files. You can use these to experiment with the Mongoblog CLI if you don't yet have your own content for use during development.

The Mongoblog-CLI

The Mongoblog Command Line Interface is a global node module. You can install it using:

npm install -g mongoblog

If this doesn't work, try again with root access (sudo).

The Mongoblog-CLI is capable of saving posts to your blog, removing posts, renaming posts, and editing posts, all from the command line. It does this by connecting directly to the MongoDB instance that your blog data is stored in. During development, this will be the database on your local system. At production, you can change this to be your remote MongoDB instance.

Before doing anything else with the CLI, you must initialize it.

Run: mongoblog init

You will then be prompted to enter the address of your database. During development, this should be mongodb://localhost:27017/blog. You can change this later.

You will then be prompted to enter the path to your markdown folder from the home directory (/path/to/markdown). If you have already downloaded the template, you can use the lorem ipsum markdown files in the template directory, or you can use your own. It should be noted though that as these files are not a part of the app structure, but are instead loaded to the database with the CLI, and loaded to the app from the database, they should be moved out of the app directory. As long as the CLI knows where to find them, they can be located anywhere on your system. Note that this path should start with a '/' but not end with one.

Now that your app is initialized, you can run:

mongoblog save lorem_ipsum_1 'Lorem Ipsum #1'

and the text in the lorem_ispum_1.md file will be saved to the database with the title "Lorem Ipsum #1", and the URL lorem_ipsum_1.

With all mongoblog commands, the first argument will be the command, and the second argument will be the URL. The URL should always be name of the markdown file minus the '.md', and should contain no spaces or special characters besides underscores. In the case of commands requiring a title to be saved ('mongoblog save', or 'mongoblog rename'), the title you wish to give will be the third argument, in quotes.

To see other commands, run mongoblog help.

Now in your app directory, run npm test, and in your browser, navigate to localhost:5000. You should see the blog template with "Lorem Ipsum #1" listed as a blog entry. If you click on it, you will be directed to the article page with the full post.

(Note: You may notice in package.json that the 'start' script runs 'node index.js', but the 'test' script runs 'nodemon index.js'. Nodemon is a global module that does the same thing as running 'node' on a file, but it restarts every time a file in the directory is updated. This helps in the live editing process. You can install it globally with sudo npm install -g nodemon)

Now that you understand how the mongoblog system works, you can begin customizing your own blog!