75 lines
3.5 KiB
Markdown
75 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,
|
|
whanever 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, version 3 of the License.
|
|
|
|
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.
|