2018-06-30

sph-cms

web publishing with command-line and filesystem interface

sph-cms currently depends on an old, outdated version of sph-dg (now sph-db) and, unless you are open to exporting and re-importing your data into a new version of sph-db in the future, shouldnt be used at this point in time

this website is a running sph-cms instance

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 path-find. example: (and emacs (or color-theme scheme))

extension

as a 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-guile

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 root 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

>= https://www.gnu.org/software/guile/ 2

web-app

sph-dg

possibly outdated documentation

installation

install the dependencies

download

alternatively see releases

alternatively run "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 web-app documentation

here are the example configurations for nginx from the web-app documentation nginx example configuration files for use with sph-web-app and scgi

it is a web-app project

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 _)

user accounts (can be implemented with _)

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


tags: guile scheme application overview start q1 computer project content-management-system wiki sph-cms publishing web cms