Linux Tutorials, Guides & Latest Tech Stuffs

MDWIKI Local and Remote Setup complete Guide

MDWiki is a markdown based content management system ( CMS )  or Wiki. The most amazing thing about MDWiki is, it is built completely on client side and uses client-side technologies like Javascript, HTML5 and Markdown. Setting MDWiki is quite easy, it require just a single file named mdwiki.html in the same folder from where you want to serve files.

MDWiki Features

  • No server side dependency
  • Use Markdown as its markup language
  • Responsive in mobile, tablet and range of devices as it is built on top of Bootstrap
  • Ability to add Google Maps, Gist and highlighting syntax with the help of Gimmicks

Requirements

  • Web server or web space
  • Any modern web browser like Google Chrome, Firefox etc.
  • mdwiki.html file
  • For local setup you should require to have nodejs

MDwiki Local Setup

1. Clone Github repository or download zip file

      https://github.com/Dynalon/mdwiki

2. Go to mdwiki folder  and run these commands

    cd mdwiki && npm install

3. Install grunt globally if not installed earlier

     npm install -g grunt

4. Run grunt command to build mdwiki.html file

grunt build devel
Running "jshint:js" (jshint) task
>> 28 files lint free.

Running "concat:dev" (concat) task
File "dist/MDwiki.js" created.

Running "index_debug" task
Building single index.html of type: debug
Generated 'dist/mdwiki-debug.html' from 'index.tmpl'

Running "reload" task
Attempting reload at http://localhost:35729/triggerReload
Reload server running at http://localhost:35729

Running "watch" task
Waiting...

5. As you can see server is started to run at localhost://35729, Go to this address in browser

http://localhost:35729/dist/mdwiki.html#!index.md

If you are using Github branch 0.6.x, we will see page not found, else you will find error in browser console showing navigation.md not found, config.js not found

6. Now Create index.md for home page, navigation.md for navigation and config.json for configuration. You can create other md files like contact.md  etc and put that in the same file where mdwiki.html is present. Example files are given below.

index.md example

About
=====

Welcome to our newly created wiki, which is built by open source markdown wiki platform "MDwiki".

Note: MDwiki is built with contribution of Timo Dorr and contributors

## Our Site Features

* Built completely on markdown
* Fully Responsive
* Easy to build

contact.md example

Contact
====

Find Us on facebook, Google+, Linkedin, Twitter

download.md example

Download
====

Download our source code from our official repository hosted on Github

navigation.md example

[Home](index.md)
[contact](contact.md)
[Download](download.md)

[gimmick:theme](spacelab)

example config.json

{
 "useSideMenu": true,
 "lineBreaks": "gfm",
 "additionalFooterText": "",
 "anchorCharacter": "⚓",
 "title": "MDwiki - Markdown based wiki done 100% on the client via javascript"
}

Start server with command grunt devel

See your MDwiki site hosted locally

http://localhost:35729/dist/mdwiki.html#!index.md

MDwiki-installation

You can rename mdwiki.html to index.html to host site beautifully at

http://localhost:35729/dist/#!index.md

MDwiki Hosting

As per official site of MDwiki, there are three options for hosting MDWiki, these are listed below

  1. Google Drive
  2. Dropbox
  3. Github
  4. IIS Server

I tried some of these options and found Google Drive hosting option is deprecated a year ago , so obviously top option Google Drive can not be used for hosting MDWiki. Second option is DropBox but as per official website of MDwiki, Dropbox allow hosting for old, pro or business dropbox accounts only. I tried this option and sign up for a Dropbox-account but i was unable to find hosting option. Third option Github is perfect for hosting MDwiki because it also allows editing of your markdown content.

How to setup MDwiki with Github

If you have created your page on Github like your githubusername.github.io  or your project is hosted in Github then it is quite easy to setup MDwiki. If not then you can create a Github page following this guide  . If you don’t have Github account then you create a new one from here

I am assuming you have already created your Github account and your Github page as like mine kumarpranav.github.io. So if you have done this then just do these simple steps to start serving your markdown file with MDwiki.

  1. Clone your repository locally using git clone command
  2. Create a folder with whatever name you want but in my case it’s name is mdwiki
  3. Clone MDwiki locally
       git clone https://github.com/Dynalon/mdwiki.git

Following output will appear

Cloning into 'mdwiki'...
remote: Counting objects: 3000, done.
remote: Total 3000 (delta 0), reused 0 (delta 0), pack-reused 3000
Receiving objects: 100% (3000/3000), 1.79 MiB | 212.00 KiB/s, done.
Resolving deltas: 100% (1934/1934), done.
Checking connectivity... done.

4. Go to mdwiki directory using and run git branch

     cd mdwiki  && git branch

you will see *master branch, as there are some issues with master branch like side navigation does not appear correctly, you should change your branch to 0.6.x

    git checkout 0.6.x
Branch 0.6.x set up to track remote branch 0.6.x from origin.
 Switched to a new branch '0.6.x'

MD-wiki-installation

Again run  git branch command and you will find branch is successfully changed to 0.6.x, now run these commands to install required files to generate mdwiki.html file.

npm install

grunt

If you have issue running grunt command, you would require to install grunt globally using

npm install -g grunt

After running grunt, there may output similar to this

Running "jshint:js" (jshint) task
>> 28 files lint free.

Running "concat:dev" (concat) task
File "dist/MDwiki.js" created.

Running "uglify:dist" (uglify) task
File "dist/MDwiki.min.js" created.

Running "index_slim" task
Building single index.html of type: slim
Generated 'dist/mdwiki-slim.html' from 'index.tmpl'

Running "jshint:js" (jshint) task
>> 28 files lint free.

Running "concat:dev" (concat) task
File "dist/MDwiki.js" created.

Running "uglify:dist" (uglify) task
File "dist/MDwiki.min.js" created.

Running "index_fat" task
Building single index.html of type: fat
Generated 'dist/mdwiki.html' from 'index.tmpl'

Running "jshint:js" (jshint) task
>> 28 files lint free.

Running "concat:dev" (concat) task
File "dist/MDwiki.js" created.

Running "index_debug" task
Building single index.html of type: debug
Generated 'dist/mdwiki-debug.html' from 'index.tmpl'

check your directories then you will find there is directory called dist, just go to this folder using cd dist command and enter

ls
mdwiki-debug.html mdwiki.html MDwiki.js MDwiki.min.js mdwiki-slim.html

Now you can see your MDwiki.html is successfully generated, just copy this file in you Github repository folder, In my case it is mdwiki folder. I have added following files to run example site mdwiki.html or rename it to index.html, index.md, contact.md, download.md. Commit and push these files to Github remote

Now access your newly created MDwiki site at

yourgithubusername.github.io/mdwiki/#!index.md

Conclusion

MDwiki is brilliant as it serve markdown files directly no need to installation. You just have to dump your markdown file along with mdwiki.html file and you can access easily these files using MDwiki. Your project can have multiple folder with different markdown document for serving each file you need to copy mdwiki.html file too in each folder

Pranav K

Pranav K is a software engineer and all-round computer geek. His interests include AWS, Ubuntu and Wordpress

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.