Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/fletcher/multimarkdown-cms

Package to assist with publishing a web site using MMD and a few perl scripts
https://github.com/fletcher/multimarkdown-cms

Last synced: 8 months ago
JSON representation

Package to assist with publishing a web site using MMD and a few perl scripts

Awesome Lists containing this project

README 

          
Title:	MultiMarkdown-CMS  

Author:	Fletcher T. Penney  

Date:	January 31, 2010  

Tags:	MultiMarkdown, web, server  



# Introduction #



***NOTE**: MultiMarkdown CMS is now updated to work with MMD 3.0. If you need

a version that is compatible with MMD 2.0, you can choose an older version

from the [downloads] page. MMD 3.0 must be installed separately.*



*Also, please note that MMD-CMS has been modified to output HTML that should be compatible with HTML5, in ancticipation of these changes being made in MMD as well.*



[downloads]: https://github.com/fletcher/MultiMarkdown-CMS/downloads



MultiMarkdown CMS  is basically a collection  of utilities that allows  you to

run a web site without any other  software. I have tried a variety of packages

when hosting my own web site. In the end, however, I was basically using those

programs  to put  a wrapper  around my  content, which  was always  managed by

MultiMarkdown.  Additionally,  none  of  those programs  really  fit  into  my

workflow, and the performance was often not what I would like.



So, instead, I decided  to run my web site with a  minimal amount of software.

In fact,  it could be run  with MultiMarkdown alone,  but I would miss  out on

some of the interactive features.



The basic premise is:



* Create a plain text file (in MMD syntax) for each page of the site



* use `mmd2web.pl`  to convert  to HTML,  including some  markup to  format 

  the pages for the web site



* upload the HTML file (and optionally the txt file) to your web server, and

  you're off



The newly  formatted HTML file  includes SSI code  that causes Apache  to add

certain templates to  the page. This allows you to  standardize the appearance

of each page (e.g. headers, footers, sidebar, etc).



Additionally, CGI scripts  are included to manage archives,  Atom feeds, tags,

searching, OpenID authentication, comments, and more.



When  building the  system, I  started off  with a  collection of  essentially

static web  pages. I  then added cgi  scripts only where  I thought  they were

absolutely necessary  to give my site  the interactive features I  desired. If

you're someone who likes lots of widgets and gadgets on their site --- I won't

be programming  them. However,  because of the  simple philosophy  behind this

approach, the pages should be compatible  with just about anything you want to

add that doesn't require a backend database.



However,  keep in  mind that  my  goal is  simplicity.  I don't  want lots  of

plugins, extensions, modules, etc. I don't  want lots of different themes that

I can choose from. If you want these things, then another package might be for

you. But if  you want a simple method  of creating a web site  that focuses on

content, this may be for you.



This package  certainly requires more  tinkering than a prebuilt  solution. If

you're not  familiar with .htaccess  files, configuring apache,  changing file

permissions, and examining error logs then you might run into some roadblocks.

However, that could also be considered an opportunity to track down solutions!



# Where do I get it? #



You can download the package:



You can also use git to clone the source:



	git clone git://github.com/fletcher/MultiMarkdown-CMS.git



If you know  how to use git,  I recommend that approach for  reasons that will

become clear later.



# How do I install it? #



Once you download and unpack the  software, place the directory where your web

server software expects it, and rename it as desired.



*Please note: if you have trouble installing  the software, do a web search to

figure out what to do. I'm happy to help troubleshoot my software, but I don't

want to get into trying to troubleshoot everyone's web server setup....*



For example, I place mine in `/Users/fletcher/Sites/mmd-static`.



You should now be able to go to something like:



	http://127.0.0.1/~fletcher/mmd_static/index.html



And see *something* --- it will likely give you some error messages, however.



# How to configure Apache #



MultiMarkdown CMS is fairly easy to install with Apache. You are only required

to modify your Apache configuration files so that:



	AllowOverride none



becomes



	AllowOverride All



On a mac, for example, you would modify `/etc/apache2/users/username.conf`.



There are two versions of the software --- the regular, and the advanced.



The regular version  of the software is  designed to be easier  to install. It

can go in  any folder/URL in your web  host (i.e. it does *not* have  to be at

the root). You  do have to configure  the .htaccess file so  that the software

knows where it  is located so that  links are coded properly.  When using this

version, when you want  to link to your home page, for  example you would link

to "index.html", **NOT** "/index.html".



This flexibility comes at a cost --- links *within* a page, e.g. "#footnote1",

will not work with the regular version of MMD CMS. This is a limitation of the

`` feature.



If you want to allow internal links, then you need to use the advanced version

of MMD  CMS. This version *does*  need to be installed  so that it lives  at a

top-level URL.  This can be accomplished  by putting it at  the webserver root

folder (wherever  that is for your  particular server), or by  using a virtual

host. I  can't support everyone  in figuring  out how to  do that, but  I have

included what I did to get it working on my particular machine.



For Apache  2 on a Mac,  do the following (all  others will need to  seek help

elsewhere):



* as an admin, go to `/etc/apache2/extra`

* `sudo pico httpd-vhosts.conf` (or similar)

* comment out the existing virtualhost sections (add a "#" at the beginning of 

  the line)

* then, add something like the following at the end of the file:



		

		    DocumentRoot "/Users/fletcher/Sites/mmd_static"

		    ServerName mmd.local

		



* then add the following to `/etc/hosts`:



		127.0.0.1       mmd.local



* finally, `sudo pico /etc/apache2/httpd.conf` and uncomment the following

  line:



		Include /private/etc/apache2/extra/httpd-vhosts.conf



If you  restart Web Sharing in  the control panel,  you should now be  able to

access your  site by pointing  your browser to `http://mmd.local/`.  It should

look much better than  the first time, but the default CSS  is ugly. There are

two sample articles, and one sample tag, to get you started.



You can then modify the `.htaccess` file just like the regular version.



# How do I add content to my site? #



You can add  content anywhere within the MultiMarkdown CMS  directory. You can

create folders,  and bury your  content away. Keep  in mind that  the archives

feature only locates  pages in a `/YYYY/MM/` folder, e.g.  the sample posts in

`/2010/01/`. Other  folders are  not treated  as "blog posts".  My site  is an

example of this structure.



To process  the files into  HTML, you need to  have a working  installation of

[MultiMarkdown](http://fletcherpenney.net/multimarkdown/).



Once you add  the text files, you  need to run `mmd2web.pl` to  create an html

file.  This uses  the  `xhtml-static-site.xslt` file  to  add the  appropriate

templates to your  documents. You will also need to  change the permissions on

your  `.html` files  so  that the  execute  bit is  enabled  (required by  the

[XBitHack](http://httpd.apache.org/docs/1.3/mod/mod_include.html#xbithack)

feature in order to enable SSI without screwing everything else up).



Now you just need to customize your templates and CSS files to make everything

look pretty....



# Features #



Included with  MultiMarkdown-CMS are several  cgi scripts that  add additional

features:



* pages in the `/YYYY/MM/` hierarchy are treated as "blog posts"- organized by

  date



* an archive  of blog posts is  available at `/archives/`, you can  also go to

  any year or year/month and see a list of posts in that month



* visitors can  leave comments on any  blog post (by default  comments are not

  accepted on other pages)



* visitors are authenticated via OpenID for leaving comments



* two Atom feeds are generated automatically - one for blog posts, and one for

  comments



* `/sitemap.xml` generates a Google compatible  sitemap of the content of your

  site



* by default, the home page lists the last 15 blog posts



* by default, `index.html` pages include a list of the other pages within that

  folder



* a built-in search function is available (though setting up a 

  [Custom Search Engine](http://www.google.com/cse/) isn't a bad idea either)



* a list of similar pages can be added to each page in the site



* several  tag related  features are  available automatically  --- `/tags/foo`

  searches for posts tagged `foo` and `/tagmap/` shows a list  of current tags

  with links to those pages



* default CSS allows you to switch from a right-sided sidebar, to a left-sided

  sidebar with a  simple keyword  switch in `header.html`  --- `rightmenu`  vs

  `leftmenu` (thanks to [Matthew James Taylor][MJT])



* valid HTML 5 & valid CSS, with the exception of unsupported `` elements if you have metadata



These features are  all demonstrated by the default configuration  - feel free

to modify the scripts as needed for your own requirements.



[MJT]: http://matthewjamestaylor.com/blog/ultimate-multi-column-liquid-layouts-em-and-pixel-widths



# Metadata #



The primary metadata used to for this software consists of three tags:



* Title --- Self-explanatory

* Date --- either `01/31/2010 15:59:56`, or `01/31/2010`

* Tags --- comma separated list of tags (case sensitive)



# Settings #



There are a  couple of configuration changes that should  be done before going

live with this software:



* the root `.htaccess` file should be changed to reflect your desired time

  zone



* four files in `/cgi/` contain the phrase "enter your password here" --- this

  should be changed to a private passphrase for better security when handling

  OpenID authentication



Obviously,  I recommend  improving the  CSS design,  and tweaking  the various

templates to construct the look of your site.



# Advanced use of git #



One of the things I really wanted to be able to do was to manage my site on my

laptop, experiment with it to be sure it works after any changes are made, and

only then to upload my changes to the  live server. I have tried to design the

cgi scripts so that they configure themselves as much as possible, so that the

same code can be run locally, or from a production server.



My workflow is  that I make changes  in `/Users/fletcher/Sites/mmd_static/` as

described  above.  That   directory  was  created  as  a  git   clone  of  the

MultiMarkdown-CMS software(as above).



I then add a remote repository to the git repo:



	git remote add live ssh://user@my.live.host/path/to/public



where the username and  host are what I would normally use to  ssh into my web

provider. `/path/to/public`  is the path  to the  directory that holds  my web

site.



This allows me  to use git to  upload a copy of  my local site to  my web host

when I am satisfied with the changes.  Additionally, by storing my web site in

a git repository, I can undo changes when  I make a mistake, and I can also go

back to any previous version of my site.



One trick, though, is that you have to configure the remote repository to

update the remote copies of all files after every `git push`. To do this, ssh

into your account, and go to the public directory. (You may want to back

everything up at this point....) Then do the following to create the remote

git repository:



	git init

	cd .git/hooks

	pico post-update



and then put the following in the file:



	#!/bin/sh

	#

	cd /path/to/public

	/usr/bin/env -i /usr/local/bin/git reset --hard

	chmod g+s cgi/accept_comment.cgi



What this does is force git on the remote server to reset the remote directory

to match the state of the repository  itself. Then I change the permissions on

accept_comment.cgi so that it is permission to write to the comments files.



You can, of course, add your own commands to this file as well.



If you use the same approach, whenever you want to upload your changes, simply

type:



	git push live master



Your changes  will be uploaded,  then the remote  repository will be  reset so

it's up to date, and the permissions will be fixed on accept_comment.cgi.



Remember, since you have a read-only  connection to my github repository, your

changes and  private files  cannot be  uploaded. You can  still use  `git pull

origin master`  to update to the  latest version of software  I have released.

This should not overwrite any changes you  have made, since git is pretty good

at  avoiding  "collisions". I've  only  been  using this  "triple  repository"

approach for a little while, but so far it's been convenient in allowing me to

keep private and public files separate.



**NOTE**: This set-up works  for me. I don't promise it will  work for you, or

that it won't mess something up. I am  not a git expert. I simply patched this

together with a lot  of help from Google. I can't really  offer any support if

it's not working for you.



# Included Software #



This software  would not  be possible  without work  previously done  for many

other projects:



## Net-OpenID-Consumer ##



* by Brad Fitzpatrick

* 



Used for OpenID authentication.



## Crypt-DH ##



* by Benjamin Trott

* 



Crypt-DH is used to enable the OpenID authentication.



## XML-Atom-Simplefeed ##



* by Aristotle Pagaltzis

* 



Used to generate the atom feeds.



## VectorMap.pm ##



* by Fletcher T. Penney

* 



Used to find similar pages, and perform searches of site content.



## Lingua-Stem ##



* by Benjamin Franz and Jim Richardson

* 



Used by my VectorMap searching software to improve results



## MultiMarkdown 3.0 ##



* by Fletcher T. Penney

* 



MultiMarkdown is my update to John Gruber's

[Markdown](http://daringfireball.net/projects/markdown/) syntax, and built

using modifications to [peg-markdown](https://github.com/jgm/peg-markdown) by

John MacFarlane.



# Known Issues #



* Email is "de-obfuscated" when run through an XSLT, and it appears there is

  no (straightforward) way around this. Not that this does *not* affect email

  addresses that are placed in your HTML include statements --- in a sidebar,

  for example.



# License #



	Copyright (C) 2010-2011  Fletcher T. Penney 



	This program is free software; you can redistribute it and/or modify

	it under the terms of the GNU General Public License as published by

	the Free Software Foundation; either version 2 of the License, or

	(at your option) any later version.



	This program is distributed in the hope that it will be useful,

	but WITHOUT ANY WARRANTY; without even the implied warranty of

	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

	GNU General Public License for more details.



	You should have received a copy of the GNU General Public License

	along with this program; if not, write to the

	   Free Software Foundation, Inc.

	   59 Temple Place, Suite 330

	   Boston, MA 02111-1307 USA