Brian S. Stephan
27d4d16572
I think arguments that "Such new versions will be similar in spirit to the present version", in my own reading and readings such as in https://www.draketo.de/software/gpl-or-later, convince me for now that it is acceptable to allow the "or later" for compatibility and future problem's sake Signed-off-by: Brian S. Stephan <bss@incorporeal.org>
74 lines
3.5 KiB
Markdown
74 lines
3.5 KiB
Markdown
# incorporeal-cms
|
|
|
|
A lightweight static site generator for Markdown-based sites.
|
|
|
|
## Installation and Usage
|
|
|
|
Something like the following should suffice:
|
|
|
|
```
|
|
% virtualenv --python=python3.9 env-py3.9
|
|
% source env-py3.9/bin/activate
|
|
% pip install -U pip
|
|
% pip install incorporeal-cms
|
|
% incorporealcms-build ./path/to/instance ./path/to/output/www/root
|
|
```
|
|
|
|
This will generate the directory suitable for serving by e.g. nginx.
|
|
|
|
## Creating a Site
|
|
|
|
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 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,
|
|
whatever it is.
|
|
* All other files are copied directly, so images, text files, etc., can be referenced naturally as URLs.
|
|
|
|
## Configuration
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
## Development and Contributing
|
|
|
|
Improvements, new plugins, and etc. are all welcome.
|
|
|
|
I'm reachable on the fediverse, over email, or on Discord, but if you're looking for an option I prefer, I maintain an
|
|
IRC channel, `#incorporeal-cms`, on [my IRC network, Randomus](https://randomus.net/) if you would like a place to hang
|
|
out and discuss issues and features and whatnot.
|
|
|
|
## Author and Licensing
|
|
|
|
Written by and copyright (C) 2025 Brian S. Stephan (bss@incorporeal.org).
|
|
|
|
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General
|
|
Public License as published by the Free Software Foundation, either version 3 of the License, or (at your
|
|
option) any later version.
|
|
|
|
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the
|
|
implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
|
|
more details.
|
|
|
|
You should have received a copy of the GNU General Public License along with this program. If not, see
|
|
<https://www.gnu.org/licenses/>.
|
|
|
|
### Content Output
|
|
|
|
As per [the GPL FAQ entry](https://www.gnu.org/licenses/gpl-faq.en.html#CanIUseGPLToolsForNF), the generated output
|
|
(HTML, Atom/RSS feeds, etc.) of this program is *not* subject to the GPLv3 license, aside from cases where e.g.
|
|
JavaScript source code, CSS files, and the like are copied into the output directory verbatim, in which case their
|
|
license applies, naturally, to only those files.
|