82a536bb0e9c08c000f76a80598e036b2c96858c — Frank Doepper 11 years ago de8e84e
1 files changed, 183 insertions(+), 0 deletions(-)

A README.md => README.md +183 -0
@@ 0,0 1,183 @@
# WofFS
## WofFS' Content Machine


> *CMS verpiss dich,  
  keiner vermisst dich!*


*WofFS' Content Machine* is a tiny perl CGI which takes a
directory tree of Markdown files or shell scripts (or whatever) and
turns it into a browsable website.

### Features

- Pages are (optionally) written in
- One page — one file.
- Page titles and menu entries are taken from the file names.
- The menu tree is built from the directory structure.
  Choose how many levels are uncollapsed by default.
- It is very extensible: use shell or perl scripts
  for simplest creation of dynamic pages or to introduce other source
  formats than Markdown. 
- Builtin smart redirection in case of moved pages.
- No configuration needed! Plug and play! The CGI tries hard to find
  the URL of itself automatically.
- You can have hidden pages (which do not appear in the menu).
- Redirects can be created by placing symlinks.
- It supports Apache or lighttpd mod_rewrite for friendly URLs.
- It is secure by design: only the configured directory is
  scanned for source files. Nothing else. The request URL is
  not getting converted into some file path. This takes away
  many opportunities for exploits.
  Note: shell, perl or php files in the source tree get
  executed. You have been warned. .-)
- There is no need for write permission for the script on the
  web server.
- It is very small and fast. Any file which must be opened
  gets read only once. Only information that is really needed
  for computing the result is taken from the filesystem.
  There is no DB connection.
- It is tested under Debian and Ubuntu with
  [thttpd](http://www.acme.com/software/thttpd/) and
  [lighttpd](http://www.lighttpd.net/). It should work with
  any Linux distributon and other unix-like systems. Anyone
  want to try Windows or Mac?

### What it is *not*

- There is no embedded editor. (Well, you could install one.)
  Just upload your files.
- There are not many variables. Only content, navigation,
  page title and URL prefix are substituted in the HTML template.
- There is no HTTP header management, no cookies.
  Only *Last-Modified* is set.

### <a name="HOWTO"></a>HOWTO

-    Setup your web server (apache or lighttpd are recommended),
     and install perl and markdown, too.
     On a Debian system:

        apt-get install apache2 perl markdown

-    Download wcm and unpack it in your document root
     (or whereever you want):

        cd /var/www
        wget http://woffs.de/downloads/wcm-20120410.tar.gz
        tar xvzf wcm-20120410.tar.gz

-    Point your browser at `http://localhost/wcm-20120410/index.pl`.
     If you just see the source code of the perl script, you have to
     include something like

        <Directory /var/www/wcm-20120410/>
          AllowOverride All

     in your `/etc/apache2/sites-available/default` or
     whereever your apache config is. Reload config:

        /etc/init.d/apache2 reload

-    Now your browser should display the WCM page. Please
     [drop me a line](http://woffs.de/Kontakt) if this is not the case,
     so I can update the HOWTO accordingly.

-    If rewriting works,
     you can try `http://localhost/wcm-20120410/`, and the links
     will be nicer ("/WCM" instead of "/index.pl?page=WCM").

-    Look at the files under `/var/www/wcm-20120410/src/`,
     menu and content come from there.

-    File extensions are
     - _sh_: shell script (gets executed!) with Markdown output
     - _bash_: bash script (gets executed!) with Markdown output
     - _php_: php script (gets executed!) with raw HTML output
     - _mphp_: php script (gets executed!) with Markdown output
     - _pl_: perl script (gets executed!) with taint checks enabled,
       with Markdown output
     - _cgi_: executable (gets executed!) with Markdown output
     - _html_: raw HTML text
     - _any other extension (or no extension)_: Markdown text

-    Everything before the first "_" in the filename is ignored.
     You can use that for menu sorting. If the Filename begins with "0",
     the File does not show up in the menu (a hidden entry).

-    You can have subdirectories for submenus. Edit the $menulevel
     value in index.pl to decide how many levels of submenus are shown
     for not-selected items. (The submenu of the selected item will
     always be shown.)

-    You can use the special filename "index" (or better "0\_index" or
     "00\_index", or "00\_index.sh" if it is a shell script, etc) to have
     a directory index.

-    Within the text and the html template you can use special strings:
     - \_<span/>\_prefix__ will be replaced by the starting part
       of the URL leading to the doc root (`http://woffs.de/` in this case)
     - \_<span/>\_pprefix__ will be replaced by the starting part
       of the URL leading to the page (`http://woffs.de/` in this case)

-    Only within the html template you can additionally use:
     - \_<span/>\_navi__ will be replaced by the menu
       (constructed by "src" directory tree)
     - \_<span/>\_title__ will be replaced by the page title
       (derived from file name)
     - \_<span/>\_content__ will be replaced by the page content
       (file content or script output)

-    You can (ab)use symlinks to point to another page.
     A redirection will then be created.

### Download

You are invited to have a look at the
[source code](http://woffs.de/Software/WCM/source) of the main
script and to download
including some examples for easy setup.

The Software is Licensed under
[GNU AGPL](http://www.gnu.org/licenses/agpl-3.0.html). 

You can browse the
[Git repository](http://woffs.de/git/fd/wcm.git)
or get your copy with

>     git clone git://woffs.de/git/fd/wcm.git

or use [GitHub](https://github.com/woffs/wcm).

Feel free to [contact](http://woffs.de/Kontakt) me.

### History

After discovering that I don't need embedded HTML editors,
although I want to enter the content in a
readable and writable way;
and that I don't need a CMS, although I want automatic menus,
I decided to write my own *Content Machine*.

One weekend in late August 2010 I spent some hours with this,
and finally it ended up in ~130 lines of a perl CGI
which serves the whole thing. All in one script!

With a little bit of shell magic and
I moved my own Webpage from
(which is a really light CMS, but still much more than I need)
to my new *Content Machine* within some hours.

### Similar projects by others'

- [werc](http://werc.cat-v.org/) is "a minimalist web anti-framework"
- [Commonplace](http://helloform.com/projects/commonplace/) is "a wiki-like way to store and browse Markdown writings"