2024-09-04

discontinued: sph-cms

web publishing with command-line and filesystem interface

discontinued

motivation

to publish lots of content on the web easily (text, pictures, audio and any other files)

features

content

direct file editing in the filesystem
command-line interface for metadata listing, content addition, mass tag editing and more
include other pages or links to them filtered by tags on a page
parameterised include with placeholders and conditionals
any file type is supported for inclusion. there are several default content types with special rendering: itml, plain, preformatted, url and csv. media is included using the html <object> tag: png, jpg, svg, gif. other types are by default hyperlinked when included
itml is an indent based markup language with extendable custom dynamic expression support. for the syntax see itml
csv file inclusion rendered as one or multiple grouped tables based on a csv column
separate instances with the same codebase but different data sets possible. for example for multiple different sites on the same sph-cms version
bonus: inclusion of automatically extracted guile scheme code documentation for guile modules

interface

read-only html/http interface
html5 output using <section> and <object> tags to embed content
browse by tags
browse with pagination, optional content inlining while browsing, optionally sorted by title or modification time
atom feed for recently modified files with custom tag queries
view markup source for a page
thumbnails of customisable size for images

organisation

content tagging
tag filter queries with and/or/not, ##### fully supporting

extension

as a sph-web-app project, other projects can derive from it, import it, use and extend its routes and other features

server

pages are text and any other type of files
metadata is stored in an automatically managed database, sph-dg
derivative configuration files

example use cases

online database

have overview pages with hyperlinks to sub-pages filtered by tags to create mind map like websites, or pages that include content matching certain tags

weblog

browse a list of content ordered by modification time like a super minimal weblog

custom site or webservice

extend it with new url paths that call scheme procedures for custom responses

terminal interface

$ sph-cms --help

parameters
  options ... command argument ...
options
  --about | -a
  --dg-root
  --help | -h
  --interface
options shared by all commands
  --dg-root[=string]
commands
  content add :: tag ...
  content add-edit :: tag ...
  content delete :: content-id
  content display :: content-id
  content edit :: content-id
  content import :: format sources ...
  content list :: tag ...
  content path :: content-id
  start :: [environment project-name]
  statistics
  tag add :: tags content-id ...
  tag delete :: tag ...
  tag list :: content-id
  tag remove :: tags content-id ...
  tag replace :: tags tags-replacements content-id ...
  type list :: content-id
  type set :: type-name content-id ...
  type set-guess :: content-id ...

the filesystem path of the database to use, the directory that contains a file named "metadata", can be specified as an option or in a environment variable named DG_ROOT

default paths

/browse

lists all tags split into two groups based on how many elements they are used for

/browse/link [/tag-or-tag-query...]

lists all content with all selected tags
supports a nestable expression syntax with and/or/not, for example "/essays/(not topic-a)"
when filtering content, two rows are displayed: one for adding non-ubiquitous tags to the query, and one for removing tags/expressions from the current query

/browse/link.nonav [/tag-or-tag-query...]

like /browse/link but without rendering the browse navigation, only a list of matching content

/browse/content [/tag...]

like browse/link but directly includes text content if it is below a certain file size. by default sorted by modification time

/c/view/{base32-number}

every content element has a database-unique base32 id

/c/data/{hex-number}

direct access to content files

dependencies

guile
sph-web-app
sph-dg

installation

install the dependencies
get the source code "git clone git://sph.mn/sph-cms"
unpack the archive and change to the unpacked/source directory

setup

"./exe/sph-cms start" starts the application ("C-c" exits) with an scgi interface. if there are no errors, that likely means that the install of the sph-cms code is working
then to access it via http, an http server that supports scgi like nginx has to be configured like in the sph-web-app documentation
here are the example configurations for nginx from the web-app documentation nginx configuration example

remote content editing

for files: mount the "data/files/" directory with sshfs or use rsync or git to synchronise the directory. because files are registered in the database, content can only be edited, not deleted or added this way
for metadata: load-balance two started instances of the same installation. pack the database with tar (the database is a sparse file), stop one instance, replace the database, start. repeat for the other instance. since the database stores little data, this usually takes only a few seconds

possible enhancements

versioning of edits (can be implemented with (sph filesystem versioning))
access control (can be implemented with sph-lib-dg (sph storage permission))
user accounts (can be implemented with sph-lib-dg (sph storage user))
search (an extension could search through the content files)
use of record data structures for content elements (classes)
create one default configuration file stored with the project and a script to start nginx using that local configuration file so that no separate web server configuration is required
display links to pages that link to the currently visited content
check for broken links in the markup
management of remote instances with the sph-cms command
permalinks, content urls that do not change when content is moved between databases
template and style extensions

license

gpl3+

alternatives

haunt static site generator
tekuti weblog application that uses git for versioning and tags for categorization
gollum wiki that uses git for versioning and has markdown support. used by github. see also omnigollum because gollum does not include access control
dokuwiki wiki with filesystem-based content storage
sph-web-publish