diff --git a/README.md b/README.md index 8ee28af..9fa08cf 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,39 @@ Software that makes simple Markdown content go. +## Installation and Usage + +I recommend getting a release from and +installing the Python package in a virtualenv. Something like the following should suffice: + +``` +% cd ~/site +% virtualenv --python=python3.8 env-py3.8 +% source env-py3.8/bin/activate +% pip install -U pip +% pip install ~/incorporeal_cms-1.3.0-py3-none-any.whl +% pip install -U gunicorn +% gunicorn -w 5 -t 60 -b 127.0.0.1:10000 --reload 'incorporealcms:create_app()' +``` + +This will get the CMS up and running, and listening on the specified port. The application is +further configured within `env-py3.8/var/incorporealcms-instance/config.py`, and content is served +out of `env-py3.8/var/incorporealcms-instance/pages/`. + +## Serving a Site + +Put content inside `env-py3.8/var/incorporealcms-instance/pages/` and go. + +* Markdown files (ending in `.md`) are rendered via Python-Markdown if they are accessed without the + suffix (i.e., `post.md` should be referred to as `/post` to get it to render as Markdown. +* Directory paths (e.g. `/dir/`) can be rendered with a `/dir/index.md` file. +* Symlinks to files are treated as redirects to the destination content. +* Request paths with file suffixes are not rendered and served directly, so images, etc., can be + referenced naturally, and even the unrendered Markdown can be served as a text file via e.g. + `/post.md`. + +Care is taken to not serve content above the `pages/` dir, even via symlink. + ## Author and Licensing Written by and copyright Brian S. Stephan (bss@incorporeal.org).