From c583a69362f86fcc8e1b35a45a06dd8377d6308f Mon Sep 17 00:00:00 2001 From: mjfernez Date: Thu, 14 Oct 2021 20:14:53 -0400 Subject: 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. --- README.md | 248 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 248 insertions(+) create mode 100644 README.md (limited to 'README.md') 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: + +`

I don't like spam!

` + +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 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: + +`