From 749576f535a5f2eabe9214b92cc006a950b97d49 Mon Sep 17 00:00:00 2001 From: "Brian S. Stephan" Date: Mon, 17 Mar 2025 07:13:53 -0500 Subject: [PATCH] README cleanups Signed-off-by: Brian S. Stephan --- README.md | 35 ++++++++++++++++++----------------- 1 file changed, 18 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 0a1cfed..6ba4235 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ installing the Python package in a virtualenv. Something like the following shou ``` % virtualenv --python=python3.9 env-py3.9 -% source env-py3.8/bin/activate +% source env-py3.9/bin/activate % pip install -U pip % pip install incorporeal-cms % incorporealcms-build ./path/to/instance ./path/to/output/www/root @@ -17,31 +17,32 @@ installing the Python package in a virtualenv. Something like the following shou This will generate the directory suitable for serving by e.g. Nginx. -## Generating a Site +## Creating a Site -Put content, notably Markdown content, inside `./your-instance/pages/` and go. +Put content, notably Markdown content, inside `./your-instance/pages/` and when you are ready, run the build command +above. When you run `incorporealcms-build`, the following happens: -* Markdown files (ending in `.md`) are rendered via Python-Markdown as .html files, other - files generally left alone and copied to the static site. -* Directory paths (e.g. `/dir/`) can be served via a `/dir/index.md` file. -* Symlinks to files are retained and handled per the web server's configuration. -* Non-Markdown files are copied directly, so images, etc., can be referenced naturally. - -The application is further configured within `./your-instance/config.json`, and content is served +* Markdown files (ending in `.md`) are rendered via Python-Markdown as .html files and output to the static site + directory. The `.md` files are also copied there, though this behavior may be toggleable in the future. + * Directory paths (e.g. a request to `/dir/`) can be served via a `/dir/index.md` file, which will generate + `/dir/index.html`, with the appropriate web server configuration to use `index.html` for directory listings. +* Symlinks to files are retained and mirrored into the output directory, and handled per the web server's configuration, + whanever it is. +* All other files are copied directly, so images, text files, etc., can be referenced naturally as URLs. ## Configuration -I've tried to keep the software agnostic to my personal domains, logos, etc. There are some settings -you are probably interested in tweaking, by specifying new values in -`incorporealcms-instance/config.json`: +The application is further configured within `./your-instance/config.json`. See `incorporealcms/config.py` for more +information about what you can tweak. Just adding stuff to `Config.py`/`config.json` yourself is trivial if all you need +to do is to refer to it in templates. I've tried to keep the software agnostic to my personal domains, logos, etc. -* `TITLE_SUFFIX` is appended to the title of every page, separated from other title content by a - dash. +To do some basic personalization, there are some settings you are probably interested in tweaking, by specifying new +values in `incorporealcms-instance/config.json`: + +* `TITLE_SUFFIX` is appended to the title of every page, separated from other title content by a dash. * `CONTACT_EMAIL` is referred to in error templates. * `FAVICON` supplies the image used in browser tabs and that kind of thing. -If I missed anything, please let me know. - ## Development and Contributing Improvements, new plugins, and etc. are all welcome.