Typically, when we set out to create a new blog, there’s a certain degree of complexity to be considered. What kind of database will you require? Will you need PHP, Node.js, mySQL? How will you manage the security of your databases and admin areas? What will your maintenance schedule for plugin and theme updates be?
If all you need is a simple blog, this kind of complexity can be overkill. With CMS.js however, you can put it all aside and have a simple, fully client-side blog without any of the aforementioned concerns. And you can set it up in minutes.
In this tutorial we’ll start with a quick look at what CMS.js is, then you’ll learn exactly how to complete its quick setup process. Once you have a site up and running we’ll go through how to add and deploy content. Let’s begin!
What is CMS.js?
CMS.js is a very lightweight site generator written in JavaScript. Out of the box it’s only 94Kb, comprising just sixteen files. By comparison, WordPress is around 24Mb and over 1,400 files.
It is designed in “the spirit of Jekyll”, which basically means you can write posts and pages as plain text Markdown files and have them automatically processed and output into a blog format.
Like Jekyll, with CMS.js you can have your site hosted (for free) on GitHub Pages. With this option CMS.js will use GitHub’s API to dynamically fetch Markdown files from your repository and serve them up as posts and pages. This is known as “GitHub Mode”, and it’s the first of two modes available in CMS.js.
By the way, if you like the sound of this mode but aren’t familiar with Github, don’t worry. We’ll be showing you how to use it in a manner such that you’ll be comfortable even if you’ve never touched git before in your life. Alternatively, if you prefer your own hosting, you can go with “Server Mode” instead.
Option 1: Server Mode
This mode is arguably the simplest, so let’s step through how to use that first.
Download and Extract CMS.js
The first thing you’ll need to do is download CMS.js. Head to https://github.com/cdmedia/cms.js and click the green Clone or download button toward the top right, then choose Download ZIP.
Note: with this process we’re going to assume you don’t want to use GitHub at all, outside of downloading CMS.js, which is why we’re just grabbing a ZIP rather than cloning the repo. However if you’d prefer to clone the repo with your own methods you can certainly do so.
Otherwise, once you have the ZIP downloaded, extract it and you should see these contents:
Edit Config Settings
Now go into the “js” folder and open up the file “config.js” for editing. Find the mode setting, (on line 52 in the current release), and change it from 'Github' to 'Server'.
You’ll also see settings for your site name, site tagline, site email address and site author name, so it’s a good time to change those too.
Edit Nav Items (Optional)
If you already know the items you’d like to have appear in your nav menu you can edit the siteNavItems setting now as well.
The value set against the name property will determine the label that appears on your menu item. The href property allows you to specify the URL you want the nav item to link to. The newWindow property determines whether the link will open in a new window when clicked.
If you want to link to an internal page leave both the href and newWindow properties out and just use the name property with its value set to the page in question’s title (more on how page titles work later). This will automatically set the nav item’s permalink with the format #page/<name>
If an internal page you want to link to uses spaces in its title, such as “About Me”, use spaces in the corresponding name property too, e.g. name: 'About Me'
Transfer to a Server
To see your site when in “server mode” you’ll need to transfer it to a server that uses either Apache or NGINX. You can upload it straight to your web hosting via your preferred FTP client if you would like, but it’s generally preferable to work on things offline first and upload them when you’re done. As such, I recommend using a program to create an offline server and working within it.
For this tutorial we’ll be using MAMP, which is available for Mac and Windows, but if you already use and prefer another option like XAMPP that’s equally suitable.
In your MAMP installation’s “htdocs” folder, create a new folder named “cms_js”, (or whatever you prefer), to house your offline CMS.js site:
Copy all your CMS.js files into this folder:
And that’s it, your site is up and running and ready to go!
To see it go to the offline URL for your site, (as provided by MAMP), e.g. http://localhost:8888/cms_js
Option 2: GitHub Mode
With “GitHub mode" you can have your CMS.js site hosted free on GitHub Pages, and you can manage your site via a GitHub repository that stores your content.
With GitHub Pages you can have an unlimited number of free sites; one “main” site per account, and then also one per project / repository. Be aware however that free GitHub accounts are typically used for open source, sharable projects so your repositories, (including those with associated sites), are not private.
Note: If you don’t yet have a GitHub account sign up at: https://github.com/join
To keep things as straight forward as possible we’ll be using GitHub Desktop for this process. If you don’t have GitHub Desktop go ahead and grab it here: https://desktop.github.com/
If you’re familiar with command line for git and you’d like to use that instead it will work just as well, but bear in mind the tutorial won’t be covering the commands to use at each stage.
Fork the CMS.js Repo
Head to the CMS.js repository and click the Fork icon towards the top right. This will create a new repository in your account with all the CMS.js files copied into it.
When you use GitHub Pages the URL of your site will draw from your repo’s name, i.e. http://<username>.github.io/<repo_name>. For this reason it’s a good idea to rename the project you just forked from its default name of “CMS.js”.
Go into the Settings tab, fill a new name into the Repository name field then click Rename.
Clone Your Repo
Go back to the Code tab and click the green Clone or download button, as we did during the Server Mode setup. But this time, choose Open in Desktop instead.
GitHub Desktop will open and you’ll be prompted to select the location you wish to clone to. This will be the folder you work in offline to manage your site, so choose an appropriate location then click Clone. All the CMS.js files will be pulled down into your specified location, ready for use.
Setup a gh-pages Branch
The next thing you’ll need is a gh-pages branch in your cloned repo, because this is the branch the GitHub API will draw content from and hence is the one you need to work on your site in. However the CMS.js repo already has a gh-pages branch that it’s using for its own project page so we’ll need to delete that first.
Switch from the master branch into the gh-pages branch.
Go to the Branch menu and select Delete 'gh-pages', then confirm by clicking Delete in the dialogue box that pops up.
Now you’re free to create your own gh-pages branch. Click the little branch icon button, type “gh-pages” into the Name field then click Create Branch.
Once this is done, click the Publish button up in the top right to get your newly created gh-pages branch online.
You now have your own gh-pages branch, inside your own clone of CMS.js, and you’re ready to go.
Edit Config Settings
In Finder, or Windows Explorer, go to the folder you cloned into.
Tip: right click on the repo name in the left column and choose Open in Finder or Open in Explorer.
From here, you’ll need to follow the same next step you would if using “Server Mode”, which is to edit your config settings. Go into the “js” folder and open up “config.js” for editing.
The “mode” will already be set to 'Github' by default so you won’t have to edit that setting. However you will need to edit githubUserSettings, (on line 55 in the current release).
Set the first value to your GitHub user name, and the second to the name of the repo you just created (forked into).
As we did with “Server Mode” you should also edit your site name, site tagline, site email address, site author name settings.
If you’d like to set your nav items now, please refer to the “Edit Nav Items (Optional)” section earlier in this tutorial.
Commit & Sync Your Changes
Now go back to GitHub Desktop and you should see a button reading 1 Uncommitted Change. This is because GitHub Desktop has detected your modifications of the “config.js” file. If you press the button in question and look at the body of code below you’ll see it highlighting in green the changes you’ve made.
Give your changes a quick look over and, once you’re happy, fill in the little form down on the bottom left with a basic description of the changes you’re committing.
Then click Commit to gh-pages. When that’s done, click the Sync button up in the top right, (where the Publish button was before), to get the changes you just committed uploaded to your repo.
You can check that the changes to your config file have been uploaded successfully by going to the webpage for your repo’s gh-pages branch and looking to see if your commit message has appeared there:
Now your site is ready to view! Your URL will take the format http://<username>.github.io/<repo_name>, e.g. for the site I created during this tutorial the URL was: https://kezzbracey.github.io/5_minute_blog/
Go to your site’s URL and check it out!
Adding Content
Now that your CMS.js site is up and running you can start adding content to it in the form of pages and posts. Both of these are added by creating Markdown (.md) files inside your site’s “pages” and “posts” folders respectively.
It’s worth being aware here that if you wish to use inline HTML, for tasks like adding video to posts, you should change a Markdown setting for your site. At the end of the “config.js” file you will find these settings:
Change sanitize from true to false to allow for inline HTML. If you don’t change this setting any inline HTML will be displayed as plain text rather than being rendered.
Add Posts
To add a post create a Markdown (.md) file in the “posts” folder and name it with a format combining the date and title like this: YYYY-MM-DD_post-title.md. Ensure the date and title are separated by an underscore.
For example, “2016-08-06_five-minute-blog-setup.md”.
At the top of the file you’ll need to add some front matter specifying the post title, then below that type out your post’s content e.g.
1 |
--- |
2 |
title: This is an Example Title |
3 |
--- |
4 |
|
5 |
And the post content begins here. |
Migrating Jekyll Posts
If you want to migrate from a Jekyll site, copy all your posts over from its “_posts” folder into your CMS.js site’s “posts” folder. If your posts have images in them be sure to bring over the folder that contains them too.
Note: ensure the file extension of your posts is “.md” not “.markdown”.
Add Pages
To add a page create a Markdown (.md) file in the “pages” folder. You don’t need a date in the name of a page file, however the file name should match the title used in the page’s front matter. There should also be dashes in the file name corresponding with any spaces in the page title.
For example a page file named “about-me.md” should have this front matter:
1 |
--- |
2 |
title: About Me |
3 |
--- |
4 |
|
5 |
And the page content begins here. |
To recap what we mentioned earlier, if you want to link to a page from your site’s nav menu, the name property used in your config file’s siteNavItems object should match said page’s title, with spaces included:
1 |
// Navigation items |
2 |
siteNavItems: [ |
3 |
{ name: 'About Me'}
|
4 |
], |
Migrating Jekyll Pages
If you are migrating from a Jekyll site you can copy all your pages over from its root folder into your CMS.js site’s “pages” folder. Give each one a quick look over to make sure the title matches the file name as described above, and that the file extension is “.md” not “.markdown”.
Deploying New Content in Server Mode
Getting your new content online in server mode is just a matter of uploading the newly added files to your host via your preferred FTP client.
Note: it seems updating existing content when in “Server Mode” can be a little tricky at present, with edits either not appearing in content or causing content to disappear all together. If you’re working in “Server Mode”, at the moment the best bet is to prepare your post files elsewhere then transfer them into your “posts” folder when you’re certain they’re finalized.
Deploying New Content in GitHub Mode
Getting new content online is actually a little easier to manage in “GitHub Mode” because you won’t have to manually keep track of the files you added or changed. Instead, you can just go to GitHub Desktop and it will automatically detect any added or changed files.
From there follow the same process you did when you edited your config file.
- Create a commit message
- Commit changes
- Sync
Note: brand new content should show up right away, but after editing existing content you might have to wait a little while before you see your changes on your live site.
Bonus: Converting a Jekyll Theme
Given CMS.js is in the flavor of Jekyll, you’ll find many Jekyll themes will fit a CMS.js site quite well. As such it’s possible to partially convert a Jekyll theme for use on your site. Jekyll has functions CMS.js does not, so you won’t be able to fully carry over all the features of some Jekyll themes, but you will be able to bring over a good amount of the look and feel.
Completing this process will take some familiarity with HTML, CSS, and JavaScript, so if you feel comfortable with these three languages give converting a theme a shot. Going through the exact steps of conversion is beyond the scope of this tutorial, but the basic process is:
- Copy the stylesheet(s) from your Jekyll theme to your CMS.js site’s “css” folder and link them in the
<head>section of the site’s “index.html” file. Be sure to link any required external stylesheets too, such as Google Fonts or Font Awesome. - Compare the templates from the Jekyll theme’s “_layouts” and “_includes” folder to the code in the CMS.js “index.html” file. Note that the post, page and error templates are housed in JavaScript snippets therein.
- Copy the appropriate markup and CSS classes from the Jekyll templates to the CMS.js “index.html” file. Note, as you do this it is important not to remove the class names you see in the existing JavaScript templates as they enable to system to inject content into the appropriate location.
- Copy any required JavaScript files from the Jekyll theme to the CMS.js site and load them in either at the bottom of the “index.html” file or in the
<head>, depending on what the script needs.
In this example I’ve converted the “Astro” theme for Jekyll and applied it to this CMS.js site:
Wrapping Up
And that’s all it takes to setup a CMS.js blog! If you don’t need bells and whistles and just want a straight-to-the-point way to get a blog online, this method gets you there fast.
Thanks very much to Chris Diana, the creator of CMS.js, for creating this great tool and sharing it freely.
Check out CMS.js for yourself and take it for a spin; you might find yourself a new favorite blogging platform!
