2023-02-27

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 categorisation
  • 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