Adds RSS auto-generation for files in 'site'

This commit adds rss_generator.py which contains the main logic for
indexing the site directory and generating a feed on startup. It serves
as a sort of ad-hoc database which is accessed when /feed.xml is
requested.

Also corrects various typos, README nonsense, and expands the config
options for RSS. Instances of './templates/site' have been replaced with
the general BASE_DIR variable in the siteconfig.

1 files changed, 248 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..38cf6d6
--- /dev/null
+++ b/README.md
@@ -0,0 +1,248 @@
+# EZCMS - a minimal and simple way to manage a website
+
+## Requirements
+
+Python 3.7+
+
+
+## Huh/What/Why?
+
+EZCMS (or "Easy CMS" for those of you who call that "zed" instead) is a
+minimal and simple way of managing content and serving static files on
+a website. It was mostly made for my own website which I wanted to be
+as simple as possible, but with some ability to easily add new pages in
+a template I like.
+
+I don't really expect many people to use this, but I hope it might be
+useful for someone learning to use Flask, or someone who also likes the
+look of websites from the 90s.
+
+
+### Why not just neocities or wordpress?
+
+Neocities is awesome! You should definitely host a site there.
+
+https://neocities.org/
+
+It's easy to get a simple static site going there and it's totally
+free, but it lacks server side scripting as far as I know.
+
+I did used to have wordpress blog, but I got bored of maintaining it. I
+felt like making something from scratch might make me more invested in
+making an interesting site.
+
+## Quickstart
+
+It's recommended to run each server in it's own virtual environment. This
+program uses python 3.7, so change `python` to either `python3` or `python3.7`
+depending on your needs. First clone this repo (with git clone, or download the
+zip), change into the directory, then:
+
+```bash
+$ python -m venv env
+$ source env/bin/activate
+$ pip install -r requirements.txt
+$ python server.py
+```
+
+Your server will (by default) be hosted on http://127.0.0.1:5000
+and have the `templates/site/` directory delivered to your users when they
+access http://127.0.0.1:5000/site/
+
+You should see `home.html` render on the root directory.
+
+
+## Adding Pages
+
+To add a new page, all you need to do is add a new file (or a folder and a
+group of files) somewhere under one of the folders in `site`. This folder in
+particular is special since it contains the top-level folders which will be
+used to navigate your site, but any folders beneath will be automatically
+indexed.
+
+As an exercise, add a file to the `templates/site/thoughts/rants` folder
+called `myrant.html` and put the following content:
+
+`<p>I don't like spam!</p>`
+
+The new page will be rendered with your navbar on top and footer on the bottom
+when navigated to in the `rants folder` HTML files will by default be rendered
+in page, and all other types of files (like txt) will be returned without
+rendering.
+
+An important note, since these HTML files are being rendered by Flask,
+*you can make full use of the Jinja templating language*! So in other words,
+any template you've developed for flask is fully usable here--but remember it
+will be rendered *inside* the `templates/base.html` template. If you need to
+make tweaks to the navbar or footer, you'll want to edit that file instead.
+
+### Override base template
+
+Have a page with custom CSS, or need to get rid of the navbar entirely? No
+worries! Just add a '!' at the end of you html file and EZCMS will interpret it
+as it's own Jinja template without adding everything from the base template.
+Tip: if you're just changing the CSS, you can start with the following
+boilerplate that I provide in `base.html`:
+
+
+```code
+{% extends 'base.html' %}
+{% block css%}
+//your cool css here
+{% endblock %}
+{% block content %}
+//your cool content here
+{% endblock %}
+```
+
+
+## Configuration
+
+This program comes with a configuration file with variables to tweak
+the display of your site called `siteconfig.py`. For example, by
+default this program makes the navbar out of the directories in
+the `templates/site` directory, but you might want include other directories,
+or even external sites. Examples of how to change these options are provided
+in the comments on that file. Customization is also provided through the use of
+specific files.
+
+
+### Navbar
+
+Be default, the top navbar is populated by indexing and sorting the top-level
+`templates/site/` directory. You can override this to include any directories
+you want in any order, so long as they exist, but it's advised to still keep
+them all in the `site` directory to avoid confusion.
+
+
+### Indexing
+
+This program uses a single master index file which is used when navigating to
+any directory--instead of having to put in an 'index.html' in each folder, or
+using the default apache/nginx/httpd auto-indexer. In it's place, you can
+optionally put a `.description` file to provide a short description of what's
+in the directory or a `.links` file
+
+The `.description` file should just be a text file with no formatting. If you
+want to add formatting, you can edit the `templates\index.html` file around the
+`{{ description }}` variable (for example, you could wrap it in <i></i> for
+*italics*
+
+The `.links` file is a pseudo-csv file which should contain a comma separated
+list containing a description and a relative or absolute URL to be linked. For
+example this line:
+
+`About,/about`
+
+Produces the following HTML on your index page:
+
+`<li><a href="/about" target="_blank" rel="noopener noreferrer>About</a></li>`
+
+You can of course link to external sites, but you must specify the protocol
+(i.e. https://google.com, not google.com). Otherwise, it will be interpreted as
+a relative path like `example.net/google.com`.
+
+
+### Making Secret Directories and Files
+
+This program follows the Unix convention of placing a "." before directories
+and files to make them hidden. Aside from the special files mentioned above,
+this program will not index any file or directory with a "." prepended--and a
+user will receive a 404 error if they attempt to do so.
+
+
+### Mimetypes
+
+Default mime types are primarily sourced from
+[this page](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types)
+with some of my own additions for common source code files (like .c or .py):
+
+
+You can add your own by editing the 'mimetypes.csv' file in the following
+format:
+
+`.file_extension,type/yourcoolmimetype`
+
+Otherwise, the default mime type is `application/octet-stream`, which (for most
+browsers) triggers the browser to download the file
+
+
+### License
+
+The default license type is the same as this program's: CC0. The HTML is from
+Creative Commons, with some modifications I like to add. You can of course
+replace the HTML with your own license (or none), by editing
+`templates/site/license.html`
+
+
+### RSS and Caching
+
+This app comes packaged with an auto-RSS generator that makes a feed
+based on the files in the site directory. You can omit files by adding
+them to the omit file from the perspective of the site dir.
+
+For example:
+`thoughts/rants/dontread.txt`
+or for files run under 'site'
+`home.html`
+
+You can also make use of the Flask-Caching module to optimize your 
+site's perfomance. There are many options available and to be honest, I don't know much about them, but a simple cache of 5 minutes is provided by default. You'll want to read the
+ [Flask-Caching
+docs](https://flask-caching.readthedocs.io/en/latest/index.html)
+ before experimenting.
+
+### Other Tips
+
+There are a few special directories linked that are needed to
+customize your site. First the `static` directory, which holds your static
+files like CSS templates and images. Second the `raw` directory, which allows
+the user to access files the `templates/site` as raw files instead of HTML.
+You can disable it by deleting the code under `send_file_from_site` or
+`send_file_from_static` in `server.py`.
+
+
+## Deploying a server
+
+If you do actually use this for anything on the open Internet,
+you should NOT run this server as in the quick start, but instead
+use something like UWSGI as the Flask project recommends.
+
+Refer to https://flask.palletsprojects.com/en/2.0.x/deploying/
+for options, but an easy option I use is uwsgi since it's well
+documented. A quickstart looks like this:
+
+```bash
+$ sudo pip install uwsgi
+$ sudo mkdir /var/path/to/your-flask/
+$ sudo chown www-data -R /var/path/to/your-flask
+$ uwsgi -s /var/path/to/your-flask.sock --manage-script-name --mount /=server:app --virtualenv ./env
+```
+
+Then point your main http daemon (nginx, apache, httpd) to the socket
+you made.
+
+There are examples for a nginx configuration in the uWSGI and Flask docs:
+
+- https://uwsgi-docs.readthedocs.io/en/latest/Nginx.html
+- https://flask.palletsprojects.com/en/2.0.x/deploying/uwsgi/
+
+
+I recommend making an ini file so you can run `uwsgi --ini yourini.ini`
+without all the extra arguments. A simple ini file, which I stole from
+[here](https://github.com/mking/flask-uwsgi), looks like this (your
+socket path will be different depending on your environment):
+
+```code
+[uwsgi]
+socket = /var/www/run/flask-main/flask-main.sock
+home = env
+wsgi-file = server.py
+callable = app
+master = true
+die-on-term = true
+processes = 4
+logger = file:/var/www/logs/uwsgi.log
+```
+
+Be sure to refer to all of those links above for a full explanation.