Content Management System.

Content resistant in time and (cyber) space.

This document we describes our content management system (CMS). Documents are written in plain text format and media are in a free binary format, depending on media type.

Our CMS and generated documents must be resistant in time and space, to achieve this goal we use this software: Guix, Emacs Org-Mode and Git.

Guix: software dependencies must be managed so the system can generate output documents in a reproducible and long-lasting manner;
Org-mode: knowledge is code and the code should be expressed in a suitable language: the Org-mode markup is the most flexible and powerful of current lightweight markup languages (i.e. Markdown or reStructuredText); the Org-mode publishing system allow us to generate different output formats, i.e. HTML for the web, PDF for print and online delivery or Texinfo for info documentation that our contributors and users can install on their computers;
Git: tracking every change to the code is good and right, that's why we use the Git distributed version control system, to date a landmark in this field.

Introduction

We always hope to write something smart and useful not just for us and not just to have our 15 minutes of glory, that's why we'd like our contents to be available thirty or more years since today, just in case some will still be interested; that's why we take care of them since the design phases.

In Dec 2019 Jeff Huang wrote and interesting post titled ˝designed to last˝ where he noted that much too often our pages, our preferred media - audios, videos, PDF - or entire web sites disappears from the web or are moved to other URLs, making all former links unusable: this is the so called link rot problem; this happens not only after decades have passed by, but also after a few months if not days.

The reasons underlying this phenomenon - net of historical causes that determine the way of production of out digital assets - can be basically traced back to the difficulty of managing the complexity of the overall content management system.

Using a third-party web based "platform" - i.e. WordPress.com or Facebook, but there are many others - with the hope that someone else will manage that complexity forever in our place is illusory, for sooner or later the "platforms" are dismissed and the content they convey simply disappears; be it provided for free (gratis) or for a fee, be it a small company or a Big Tech is the same, unless someone will take care to migrate the content to another platform, with related costs. Many free software web based publishing systems are available, from WordPress to Wikimedia, but installing and especially maintaining that services it's not for all and… not forever, anyway.

To address this problems Huang proposes to deploy some design and implementation principles we agree with: from the content editing to the presentation on the final medium - for example using CSS styling for HTML - through software used in the build chain.

Used software

We use GNU/Guix to manage all our CMS software dependencies: it allows us to easily define and deploy a reproducible system, potentially lasting for several decades¹, and to avoid falling into the dependency hell problem, that is constantly lurking in every software project and was never really solved by other packaging or configuration management systems.

The file manifest.scm defining all needed software is tangled via the noweb system.

We publish our feeds using Emacs web-feeder, that generates one or more RSS (or ATOM) feeds from a configurable set of HTML pages.

"emacs-webfeeder"

To write HTML code we use xmlgen

"emacs-xmlgen"

For HTML code syntax highlighting we use htmlize:

"emacs-htmlize"

Design principles

The design principles for our entire CMS are:

software reproducibility: all our software dependencies are managed through Guix, so the CMS can generate documents in a reproducible and durable way, for details see Used Software section;
minimalism: in this context we refer to minimalism in software dependencies (avoid useless dependencies²) and in UI (user interface) design.

In the following sections we define the design principles to be applied to specific output formats.

HTML design principles

The HTML generated by our CMS must comply to this principles:

accessibility: user experience (UX) must be clear and functional even when sites are accessed with a textual browser;
separation of content and presentation: semantic HTML markup (HTML5) must be used only to express content meaning, not for presentation elements, that must be coded only in CSS.
no hot-linking: except in rare and circumstantial cases media files must be local to our sites;
no JavaScript: avoid JS as much as possible, if needed use it just for minimal JS scripts, see Software bloat for details;
no obfuscation of minification: source code viewed in browsers must be human readable, including CSS and (minimal) JS.

CSS design principles

The CSS used for HTML presentation must comply to these principles:

semantic: CSS depends on semantic HTML structure, it must be a mirror of HTML markup and must reflect its structure with nested CSS selectors; see Why I Don't Like Tailwind CSS for details;
avoid non semantic CSS frameworks: Bootstrap e Tailwind are two examples of non semantic CSS frameworks, see the above mentioned Why I Don't Like Tailwind CSS for details;
avoid device breakpoints: there is no point in trying to work out the size of a particular device, in order to then define a codified responsive grid, see Stop using device breakpoints for details;
avoid "BEM-like" methodologies: BEM (Block, Element, Modifier) is a CSS selectors naming methodology: despite the intentions it makes the code less readable and not very semantic, see BEM Is Terrible for details;
limit preprocessors use: always use native CSS code where available (i.e. for variables and nesting); if you really need a preprocessor the libsass implementation of SASS, even if it's deprecated, do not use the dart-sass implementation since it's not available in Guix.

Visual design

Fonts

For titles and logotypes we use the Julia Mono font, licensed with the SIL OFL ver 1.1 and available on its official GitHub git remote.

For texts we use Work Sans, licensed with the SIL OFL ver 1.1 and available on its official GitHub git remote.

Colors

For each SWWS business unit we use a specific color palette.

HTML5 pages mockup

HTML5 pages layout is defined in our SWWS and MeUP homes commented mockup.

Publishing configuration

Emacs Org-mode includes a publishing system allowing us to manage different editorial projects - for example web sites but also PDF or eBook production - writing contents in the Org-mode markup language; for those who want to learn mode the Emacs documentation provides some examples.

ox-publish configuration is written in this document, divided in sections for each destination site, in turn divided in sections for each output format (to date HTML only); all this sections are assembled via the noweb system and tangled the publish.pl.

Parameters common to all sites

HTML

These are the configuration parameters for HTML export common for all sites:

:recursive yes
:base-extension "org"
:publishing-function org-html-publish-to-html
:with-archived-trees nil
:headline-levels 3
:section-numbers nil
:with-creator t
:with-toc t
:html-doctype "html5"
:html-html5-fancy t
:html-self-link-headlines t
:html-head-include-scripts nil
:html-head-include-default-style nil
:html-preamble t
:html-postamble t

doc.meup

HTML

We use these variables:

;; Title
(defvar doc.meup-title "DocMeUp!")

;; Extra head
(defvar doc.meup-html-extra-head
  (append common-html-extra-head
          (list
           `(link :rel "icon" :type "image/x-icon" :href "../logo.png")
           `(link :href "../atom.xml" :type "application/atom+xml" :rel "alternate" :title "DocMeup! Feed"))))

;; Header 1 content
(defvar doc.meup-html-preamble-en
  (list (header1)
        `(nav :class "menu" :aria-labelledby "menu-title"
              (h2 :id "menu-title" :class "a11y-offset" "Main Menu")
              (ul
               (li (a :href "/" "Home"))
               (li (a :href "/guides/sitemap.html" "User Guides"))
               (li (a :href "/colophon/" "Colophon"))
               (li (a :class "lang" :href "/it/" "IT"))))))

(defvar doc.meup-html-preamble-it
  (list (header1)
        `(nav :class "menu" :aria-labelledby "menu-title"
              (h2 :id "menu-title" :class "a11y-offset" "Main Menu")
              (ul
               (li (a :href "/it/" "Home"))
               (li (a :href "/it/guides/sitemap.html" "Guide utente"))
               (li (a :href "/it/colophon/" "Colophon"))
               (li (a :class "lang" :href "/" "EN"))))))

;; Footer 1 content
(defvar doc.meup-html-postamble-en
  `(div :class "footer1"
        (p :class "sitemap"
           (a :href "/sitemap.html" "Site map"))))

(defvar doc.meup-html-postamble-it
  `(div :class "footer1"
        (p :class "sitemap"
           (a :href "/sitemap.html" "Mappa del sito"))))

Texts and media for doc.meup.io web site must be saved in ./source/doc.meup/ folder and are published in ./public/doc.meup/, this is the configuration of the publishing sections of this site:

("doc.meup - English root pages"
 :language en
 :base-directory "./source/doc.meup/en"
 :publishing-directory "./public/doc.meup/"
 :auto-sitemap t
 :sitemap-title ,(format "%s - Site map" doc.meup-title)
 :sitemap-style list
 :recursive yes
 :base-extension "org"
 :publishing-function org-html-publish-to-html
 :with-archived-trees nil
 :headline-levels 3
 :section-numbers nil
 :with-creator t
 :with-toc t
 :html-doctype "html5"
 :html-html5-fancy t
 :html-self-link-headlines t
 :html-head-include-scripts nil
 :html-head-include-default-style nil
 :html-preamble t
 :html-postamble t
 :keywords "MeUp SoftwareWorkers"
 :html-head-extra ,(xmlgen-from-list doc.meup-html-extra-head)
 :html-preamble-format (("en"
                        ,(concat (xmlgen common-html-preamble-en) "\n"
                                 (xmlgen-from-list doc.meup-html-preamble-en)))
                       ("it"
                        ,(concat (xmlgen common-html-preamble-it) "\n"
                                 (xmlgen-from-list doc.meup-html-preamble-it))))
 :html-postamble-format (("en"
                         ,(concat (xmlgen doc.meup-html-postamble-it) "\n"
                                  (xmlgen common-html-postamble-en)))
                        ("it"
                         ,(concat (xmlgen doc.meup-html-postamble-it) "\n"
                                  (xmlgen common-html-postamble-it))))
 )

("doc.meup - English guides"
 :language en
 :base-directory "./source/doc.meup/en/guides"
 :publishing-directory "./public/doc.meup/guides/"
 :auto-sitemap t
 :sitemap-title ,(format "%s - User guides" doc.meup-title)
 :sitemap-style list
 ;; :sitemap-date-format FIXME
 :sitemap-format-entry doc-meup/org-publish-sitemap-entry
 :recursive yes
 :base-extension "org"
 :publishing-function org-html-publish-to-html
 :with-archived-trees nil
 :headline-levels 3
 :section-numbers nil
 :with-creator t
 :with-toc t
 :html-doctype "html5"
 :html-html5-fancy t
 :html-self-link-headlines t
 :html-head-include-scripts nil
 :html-head-include-default-style nil
 :html-preamble t
 :html-postamble t
 :keywords "MeUp SoftwareWorkers"
 :html-head-extra ,(xmlgen-from-list doc.meup-html-extra-head)
 :html-preamble-format (("en"
                        ,(concat (xmlgen common-html-preamble-en) "\n"
                                 (xmlgen-from-list doc.meup-html-preamble-en)))
                       ("it"
                        ,(concat (xmlgen common-html-preamble-it) "\n"
                                 (xmlgen-from-list doc.meup-html-preamble-it))))
 :html-postamble-format (("en"
                         ,(concat (xmlgen doc.meup-html-postamble-it) "\n"
                                  (xmlgen common-html-postamble-en)))
                        ("it"
                         ,(concat (xmlgen doc.meup-html-postamble-it) "\n"
                                  (xmlgen common-html-postamble-it))))
 )

("doc.meup - Italian root pages"
 :language it
 :base-directory "./source/doc.meup/it"
 :publishing-directory "./public/doc.meup/it/"
 :auto-sitemap t
 :sitemap-title ,(format "%s - Mappa del sito" doc.meup-title)
 :sitemap-style list
 :recursive yes
 :base-extension "org"
 :publishing-function org-html-publish-to-html
 :with-archived-trees nil
 :headline-levels 3
 :section-numbers nil
 :with-creator t
 :with-toc t
 :html-doctype "html5"
 :html-html5-fancy t
 :html-self-link-headlines t
 :html-head-include-scripts nil
 :html-head-include-default-style nil
 :html-preamble t
 :html-postamble t
 :keywords "MeUp SoftwareWorkers"
 :html-head-extra ,(xmlgen-from-list doc.meup-html-extra-head)
 :html-preamble-format (("en"
                        ,(concat (xmlgen common-html-preamble-en) "\n"
                                 (xmlgen-from-list doc.meup-html-preamble-en)))
                       ("it"
                        ,(concat (xmlgen common-html-preamble-it) "\n"
                                 (xmlgen-from-list doc.meup-html-preamble-it))))
 :html-postamble-format (("en"
                         ,(concat (xmlgen doc.meup-html-postamble-it) "\n"
                                  (xmlgen common-html-postamble-en)))
                        ("it"
                         ,(concat (xmlgen doc.meup-html-postamble-it) "\n"
                                  (xmlgen common-html-postamble-it))))
 )

("doc.meup - Italian guides"
 :language it
 :base-directory "./source/doc.meup/it/guides"
 :publishing-directory "./public/doc.meup/it/guides" 
 :auto-sitemap t
 :sitemap-title ,(format "%s - Guide utente" doc.meup-title)
 :sitemap-style list
 :sitemap-format-entry doc-meup/org-publish-sitemap-entry
 :recursive yes
 :base-extension "org"
 :publishing-function org-html-publish-to-html
 :with-archived-trees nil
 :headline-levels 3
 :section-numbers nil
 :with-creator t
 :with-toc t
 :html-doctype "html5"
 :html-html5-fancy t
 :html-self-link-headlines t
 :html-head-include-scripts nil
 :html-head-include-default-style nil
 :html-preamble t
 :html-postamble t
 :keywords "MeUp SoftwareWorkers"
 :html-head-extra ,(xmlgen-from-list doc.meup-html-extra-head)
 :html-preamble-format (("en"
                        ,(concat (xmlgen common-html-preamble-en) "\n"
                                 (xmlgen-from-list doc.meup-html-preamble-en)))
                       ("it"
                        ,(concat (xmlgen common-html-preamble-it) "\n"
                                 (xmlgen-from-list doc.meup-html-preamble-it))))
 :html-postamble-format (("en"
                         ,(concat (xmlgen doc.meup-html-postamble-it) "\n"
                                  (xmlgen common-html-postamble-en)))
                        ("it"
                         ,(concat (xmlgen doc.meup-html-postamble-it) "\n"
                                  (xmlgen common-html-postamble-it))))
 )

("doc.meup - Media"
 :recursive yes
 :base-directory "./source/doc.meup/media"
 :base-extension "jpg\\|gif\\|png\\|svg\\|webm\\|mp4\\|ogg\\|.htaccess"
 :publishing-directory "./public/doc.meup/media"
 :publishing-function org-publish-attachment)

("doc.meup - Themes"
 :recursive yes
 :base-directory "./source/themes/"
 :base-extension "jpg\\|gif\\|png\\|svg\\|css\\|ttf\\|woff\\|woff2\\|js"
 :publishing-directory "./public/doc.meup/themes"
 :publishing-function org-publish-attachment)

("doc.meup" :components ("doc.meup - English guides"
                         "doc.meup - Italian guides"
                         "doc.meup - Media"
                         "doc.meup - Themes"
                         "doc.meup - English root pages"
                         "doc.meup - Italian root pages"))

This is the HTML template of this site:

:keywords "MeUp SoftwareWorkers"
:html-head-extra ,(xmlgen-from-list doc.meup-html-extra-head)
:html-preamble-format (("en"
                        ,(concat (xmlgen common-html-preamble-en) "\n"
                                 (xmlgen-from-list doc.meup-html-preamble-en)))
                       ("it"
                        ,(concat (xmlgen common-html-preamble-it) "\n"
                                 (xmlgen-from-list doc.meup-html-preamble-it))))
:html-postamble-format (("en"
                         ,(concat (xmlgen doc.meup-html-postamble-it) "\n"
                                  (xmlgen common-html-postamble-en)))
                        ("it"
                         ,(concat (xmlgen doc.meup-html-postamble-it) "\n"
                                  (xmlgen common-html-postamble-it))))

beta.swws

HTML

This is the beta testing site beta.softwareworkers.it.

Site variables:

;; test.softwareworkers - website variables
(defvar beta.swws-title "SWWS")

;; Extra head
(defvar beta.swws-html-extra-head
  (append common-html-extra-head
          (list
           `(link :rel "icon" :type "image/x-icon" :href "../logo.png")
           `(link :href "../atom.xml" :type "application/atom+xml" :rel "alternate" :title "SWWS Feed"))))

;; Header 1 content
(defvar beta.swws-html-preamble-en
  (list (header1)
        `(nav :class "menu" :aria-labelledby "menu-title"
              (h2 :id "menu-title" :class "a11y-offset" "Main Menu")
              (ul
               (li (a :href "/en/" "Home"))
               (li (a :href "/en/private-cloud" "Private cloud"))
               (li (a :href "/en/application-hosting" "Application hosting"))
               (li (a :href "/en/about/" "About"))
               (li (a :href "/en/impressum" "Impressum"))
               (li (a :class "lang" :href "/" "IT"))))))

(defvar beta.swws-html-preamble-it
  (list (header1)
        `(nav :class "menu" :aria-labelledby "menu-title"
              (h2 :id "menu-title" :class "a11y-offset" "Main Menu")
              (ul
               (li (a :href "/" "Home"))
               (li (a :href "/private-cloud" "Cloud privati"))
               (li (a :href "/application-hosting" "Hosting applicativo"))
               (li (a :href "/about/" "Chi siamo"))
               (li (a :href "/impressum" "Impressum"))
               (li (a :class "lang" :href "/en/" "EN"))))))

;; Footer 1 content
(defvar beta.swws-html-postamble-en
  `(div :class "footer1"
        (p :class "sitemap"
           (a :href "/sitemap.html" "Site map"))))

(defvar beta.swws-html-postamble-it
  `(div :class "footer1"
        (p :class "sitemap"
           (a :href "/sitemap.html" "Mappa del sito"))))

Sitemap generation code³:

;;
;; code adapted from Pierre Neidhardt's blog
;; https://gitlab.com/ambrevar/ambrevar.gitlab.io/-/blob/master/publish.el
;;

(defun beta-swws/org-publish-sitemap (title list)
  "beta-swws sitemap, as a string 
See `org-publish-sitemap-default'. "
  ;; Remove index and non articles.
  (setcdr list (seq-filter
                (lambda (file)
                  (string-match "file:[^ ]*/index.org" (car file)))
                (cdr list)))
  (org-list-to-org list))

(defun beta-swws/org-publish-sitemap-entry (entry style project)
  "Custom format for site map ENTRY, as a string.
See `org-publish-sitemap-default-entry'."
  (cond ((not (directory-name-p entry))
         (format "[[file:%s][%s]]^{ (%s)}"
                 entry
                 (org-publish-find-title entry project)
                 (format-time-string "%Y-%m-%d" (org-publish-find-date entry project))))))

Texts and media for beta.softwareworkers.it web site must be saved in ./source/beta.swws/ folder and are published in ./public/beta.swws/, this is the configuration of the publishing sections of this site:

("beta.swws - English root pages"
 :language en
 :base-directory "./source/beta.swws/en"
 :publishing-directory "./public/beta.swws/en"
 :auto-sitemap t
 :sitemap-title ,(format "%s - Site map" beta.swws-title)
 :sitemap-style list
 :recursive yes
 :base-extension "org"
 :publishing-function org-html-publish-to-html
 :with-archived-trees nil
 :headline-levels 3
 :section-numbers nil
 :with-creator t
 :with-toc t
 :html-doctype "html5"
 :html-html5-fancy t
 :html-self-link-headlines t
 :html-head-include-scripts nil
 :html-head-include-default-style nil
 :html-preamble t
 :html-postamble t
 :keywords "SWWS SoftwareWorkers Software Workers"
 :html-head-extra ,(xmlgen-from-list beta.swws-html-extra-head)
 :html-preamble-format (("it"
                        ,(concat (xmlgen common-html-preamble-it) "\n"
                                 (xmlgen-from-list beta.swws-html-preamble-it)))
                       ("en"
                        ,(concat (xmlgen common-html-preamble-en) "\n"
                                 (xmlgen-from-list beta.swws-html-preamble-en))))
 :html-postamble-format (("en"
                         ,(concat (xmlgen beta.swws-html-postamble-it) "\n"
                                  (xmlgen common-html-postamble-en)))
                        ("it"
                         ,(concat (xmlgen beta.swws-html-postamble-it) "\n"
                                  (xmlgen common-html-postamble-it)))))

("beta.swws - English jobs"
 :language en
 :base-directory "./source/beta.swws/en/jobs"
 :publishing-directory "./public/beta.swws/en/jobs/"
 :auto-sitemap t
 :sitemap-title ,(format "%s - Jobs" beta.swws-title)
 :sitemap-style list
 ;; :sitemap-date-format FIXME
 :sitemap-format-entry beta-swws/org-publish-sitemap-entry
 :recursive yes
 :base-extension "org"
 :publishing-function org-html-publish-to-html
 :with-archived-trees nil
 :headline-levels 3
 :section-numbers nil
 :with-creator t
 :with-toc t
 :html-doctype "html5"
 :html-html5-fancy t
 :html-self-link-headlines t
 :html-head-include-scripts nil
 :html-head-include-default-style nil
 :html-preamble t
 :html-postamble t
 :keywords "MeUp SoftwareWorkers"
 :html-head-extra ,(xmlgen-from-list doc.meup-html-extra-head)
 :html-preamble-format (("en"
                        ,(concat (xmlgen common-html-preamble-en) "\n"
                                 (xmlgen-from-list doc.meup-html-preamble-en)))
                       ("it"
                        ,(concat (xmlgen common-html-preamble-it) "\n"
                                 (xmlgen-from-list doc.meup-html-preamble-it))))
 :html-postamble-format (("en"
                         ,(concat (xmlgen doc.meup-html-postamble-it) "\n"
                                  (xmlgen common-html-postamble-en)))
                        ("it"
                         ,(concat (xmlgen doc.meup-html-postamble-it) "\n"
                                  (xmlgen common-html-postamble-it))))
 )

("beta.swws - Italian root pages"
 :language it
 :base-directory "./source/beta.swws/it"
 :publishing-directory "./public/beta.swws/"
 :auto-sitemap t
 :sitemap-title ,(format "%s - Mappa del sito" beta.swws-title)
 :sitemap-style list
 :recursive yes
 :base-extension "org"
 :publishing-function org-html-publish-to-html
 :with-archived-trees nil
 :headline-levels 3
 :section-numbers nil
 :with-creator t
 :with-toc t
 :html-doctype "html5"
 :html-html5-fancy t
 :html-self-link-headlines t
 :html-head-include-scripts nil
 :html-head-include-default-style nil
 :html-preamble t
 :html-postamble t
 :keywords "SWWS SoftwareWorkers Software Workers"
 :html-head-extra ,(xmlgen-from-list beta.swws-html-extra-head)
 :html-preamble-format (("it"
                        ,(concat (xmlgen common-html-preamble-it) "\n"
                                 (xmlgen-from-list beta.swws-html-preamble-it)))
                       ("en"
                        ,(concat (xmlgen common-html-preamble-en) "\n"
                                 (xmlgen-from-list beta.swws-html-preamble-en))))
 :html-postamble-format (("en"
                         ,(concat (xmlgen beta.swws-html-postamble-it) "\n"
                                  (xmlgen common-html-postamble-en)))
                        ("it"
                         ,(concat (xmlgen beta.swws-html-postamble-it) "\n"
                                  (xmlgen common-html-postamble-it)))))

("beta.swws - Italian jobs"
 :language it
 :base-directory "./source/beta.swws/it/jobs"
 :publishing-directory "./public/beta.swws/jobs/"
 :auto-sitemap t
 :sitemap-title ,(format "%s - Offerte di lavoro" beta.swws-title)
 :sitemap-style list
 ;; :sitemap-date-format FIXME
 :sitemap-format-entry beta-swws/org-publish-sitemap-entry
 :recursive yes
 :base-extension "org"
 :publishing-function org-html-publish-to-html
 :with-archived-trees nil
 :headline-levels 3
 :section-numbers nil
 :with-creator t
 :with-toc t
 :html-doctype "html5"
 :html-html5-fancy t
 :html-self-link-headlines t
 :html-head-include-scripts nil
 :html-head-include-default-style nil
 :html-preamble t
 :html-postamble t
 :keywords "MeUp SoftwareWorkers"
 :html-head-extra ,(xmlgen-from-list doc.meup-html-extra-head)
 :html-preamble-format (("en"
                        ,(concat (xmlgen common-html-preamble-en) "\n"
                                 (xmlgen-from-list doc.meup-html-preamble-en)))
                       ("it"
                        ,(concat (xmlgen common-html-preamble-it) "\n"
                                 (xmlgen-from-list doc.meup-html-preamble-it))))
 :html-postamble-format (("en"
                         ,(concat (xmlgen doc.meup-html-postamble-it) "\n"
                                  (xmlgen common-html-postamble-en)))
                        ("it"
                         ,(concat (xmlgen doc.meup-html-postamble-it) "\n"
                                  (xmlgen common-html-postamble-it))))
 )

("beta.swws - Media"
 :recursive yes
 :base-directory "./source/beta.swws/media"
 :base-extension "jpg\\|gif\\|png\\|svg\\|webm\\|mp4\\|ogg\\|.htaccess"
 :publishing-directory "./public/beta.swws/media"
 :publishing-function org-publish-attachment)

("beta.swws - Themes"
 :recursive yes
 :base-directory "./source/themes/"
 :base-extension "jpg\\|gif\\|png\\|svg\\|css\\|ttf\\|woff\\|woff2\\|js"
 :publishing-directory "./public/beta.swws/themes"
 :publishing-function org-publish-attachment)

("beta.swws" :components ("beta.swws - Media"
                          "beta.swws - Themes"
                          "beta.swws - English root pages"
                          "beta.swws - English jobs"
                          "beta.swws - Italian root pages"
                          "beta.swws - Italian jobs"))

This is the HTML template of this site:

:keywords "SWWS SoftwareWorkers Software Workers"
:html-head-extra ,(xmlgen-from-list beta.swws-html-extra-head)
:html-preamble-format (("it"
                        ,(concat (xmlgen common-html-preamble-it) "\n"
                                 (xmlgen-from-list beta.swws-html-preamble-it)))
                       ("en"
                        ,(concat (xmlgen common-html-preamble-en) "\n"
                                 (xmlgen-from-list beta.swws-html-preamble-en))))
:html-postamble-format (("en"
                         ,(concat (xmlgen beta.swws-html-postamble-it) "\n"
                                  (xmlgen common-html-postamble-en)))
                        ("it"
                         ,(concat (xmlgen beta.swws-html-postamble-it) "\n"
                                  (xmlgen common-html-postamble-it))))

beta.meup

HTML

This is the beta testing site beta.meup.io.

Site variables:

;; beta.meup - website variables
(defvar beta.meup-title "MEUP")

;; Extra head
(defvar beta.meup-html-extra-head
  (append common-html-extra-head
          (list
           `(link :rel "icon" :type "image/x-icon" :href "../logo.png")
           `(link :href "../atom.xml" :type "application/atom+xml" :rel "alternate" :title "Meup! Feed"))))

;; Header 1 content
(defvar beta.meup-html-preamble-en
  (list (header1)
        `(nav :class "menu" :aria-labelledby "menu-title"
              (h2 :id "menu-title" :class "a11y-offset" "Main Menu")
              (ul
               (li (a :href "https://softwareworkers.it" "by SWWS"))
               (li (a :href "/pricing/" "Pricing"))
               (li (a :href "/community/" "Community"))
               (li (a :class "lang" :href "/it/" "IT"))))))

(defvar beta.meup-html-preamble-it
  (list (header1)
        `(nav :class "menu" :aria-labelledby "menu-title"
              (h2 :id "menu-title" :class "a11y-offset" "Main Menu")
              (ul
               (li (a :href "https://softwareworkers.it" "by SWWS"))
               (li (a :href "/pricing/it/" "Prezzi"))
               (li (a :href "/community/it/" "Community"))
               (li (a :class "lang" :href "/" "EN"))))))

;; Footer 1 content
(defvar beta.meup-html-postamble-en
  `(div :class "footer1"
        (p :class "sitemap"
           (a :href "/sitemap.html" "Site map"))))

(defvar beta.meup-html-postamble-it
  `(div :class "footer1"
        (p :class "sitemap"
           (a :href "/sitemap.html" "Mappa del sito"))))

Sitemap generation code³:

;;
;; code adapted from Pierre Neidhardt's blog
;; https://gitlab.com/ambrevar/ambrevar.gitlab.io/-/blob/master/publish.el
;;

(defun beta-meup/org-publish-sitemap (title list)
  "beta-meup sitemap, as a string 
See `org-publish-sitemap-default'. "
  ;; Remove index and non articles.
  (setcdr list (seq-filter
                (lambda (file)
                  (string-match "file:[^ ]*/index.org" (car file)))
                (cdr list)))
  (org-list-to-org list))

(defun beta-meup/org-publish-sitemap-entry (entry style project)
  "Custom format for site map ENTRY, as a string.
See `org-publish-sitemap-default-entry'."
  (cond ((not (directory-name-p entry))
         (format "[[file:%s][%s]]^{ (%s)}"
                 entry
                 (org-publish-find-title entry project)
                 (format-time-string "%Y-%m-%d" (org-publish-find-date entry project))))))

Texts and media for beta.meup.io web site must be saved in ./source/beta.meup/ folder and are published in ./public/beta.meup/, this is the configuration of the publishing sections of this site:

("beta.meup - English root pages"
 :language en
 :base-directory "./source/beta.meup/en"
 :publishing-directory "./public/beta.meup/"
 :auto-sitemap t
 :sitemap-title ,(format "%s - Site map" beta.meup-title)
 :sitemap-style list
 :recursive yes
 :base-extension "org"
 :publishing-function org-html-publish-to-html
 :with-archived-trees nil
 :headline-levels 3
 :section-numbers nil
 :with-creator t
 :with-toc t
 :html-doctype "html5"
 :html-html5-fancy t
 :html-self-link-headlines t
 :html-head-include-scripts nil
 :html-head-include-default-style nil
 :html-preamble t
 :html-postamble t
 :keywords "MEUP SoftwareWorkers Software Workers"
 :html-head-extra ,(xmlgen-from-list beta.meup-html-extra-head)
 :html-preamble-format (("en"
                        ,(concat (xmlgen common-html-preamble-en) "\n"
                                 (xmlgen-from-list beta.meup-html-preamble-en)))
                       ("it"
                        ,(concat (xmlgen common-html-preamble-it) "\n"
                                 (xmlgen-from-list beta.meup-html-preamble-it))))
 :html-postamble-format (("en"
                         ,(concat (xmlgen beta.meup-html-postamble-it) "\n"
                                  (xmlgen common-html-postamble-en)))
                        ("it"
                         ,(concat (xmlgen beta.meup-html-postamble-it) "\n"
                                  (xmlgen common-html-postamble-it)))))

("beta.meup - Italian root pages"
 :language en
 :base-directory "./source/beta.meup/it"
 :publishing-directory "./public/beta.meup/it"
 :auto-sitemap t
 :sitemap-title ,(format "%s - Site map" beta.meup-title)
 :sitemap-style list
 :recursive yes
 :base-extension "org"
 :publishing-function org-html-publish-to-html
 :with-archived-trees nil
 :headline-levels 3
 :section-numbers nil
 :with-creator t
 :with-toc t
 :html-doctype "html5"
 :html-html5-fancy t
 :html-self-link-headlines t
 :html-head-include-scripts nil
 :html-head-include-default-style nil
 :html-preamble t
 :html-postamble t
 :keywords "MEUP SoftwareWorkers Software Workers"
 :html-head-extra ,(xmlgen-from-list beta.meup-html-extra-head)
 :html-preamble-format (("en"
                        ,(concat (xmlgen common-html-preamble-en) "\n"
                                 (xmlgen-from-list beta.meup-html-preamble-en)))
                       ("it"
                        ,(concat (xmlgen common-html-preamble-it) "\n"
                                 (xmlgen-from-list beta.meup-html-preamble-it))))
 :html-postamble-format (("en"
                         ,(concat (xmlgen beta.meup-html-postamble-it) "\n"
                                  (xmlgen common-html-postamble-en)))
                        ("it"
                         ,(concat (xmlgen beta.meup-html-postamble-it) "\n"
                                  (xmlgen common-html-postamble-it)))))

("beta.meup - Media"
 :recursive yes
 :base-directory "./source/beta.meup/media"
 :base-extension "jpg\\|gif\\|png\\|svg\\|webm\\|mp4\\|ogg\\|.htaccess"
 :publishing-directory "./public/beta.meup/media"
 :publishing-function org-publish-attachment)

("beta.meup - Themes"
 :recursive yes
 :base-directory "./source/themes/"
 :base-extension "jpg\\|gif\\|png\\|svg\\|css\\|ttf\\|woff\\|woff2\\|js"
 :publishing-directory "./public/beta.meup/themes"
 :publishing-function org-publish-attachment)

("beta.meup" :components ("beta.meup - Media"
                          "beta.meup - Themes"
                          "beta.meup - English root pages"
                          "beta.meup - Italian root pages"))

This is the HTML template of this site:

:keywords "MEUP SoftwareWorkers Software Workers"
:html-head-extra ,(xmlgen-from-list beta.meup-html-extra-head)
:html-preamble-format (("en"
                        ,(concat (xmlgen common-html-preamble-en) "\n"
                                 (xmlgen-from-list beta.meup-html-preamble-en)))
                       ("it"
                        ,(concat (xmlgen common-html-preamble-it) "\n"
                                 (xmlgen-from-list beta.meup-html-preamble-it))))
:html-postamble-format (("en"
                         ,(concat (xmlgen beta.meup-html-postamble-it) "\n"
                                  (xmlgen common-html-postamble-en)))
                        ("it"
                         ,(concat (xmlgen beta.meup-html-postamble-it) "\n"
                                  (xmlgen common-html-postamble-it))))

TODO testevent.meup

HTML

Delete this site?

TODO Deployment

TODO Content authoring

Riteniamo che sia fondamentale utilizzare formati accessibili e duraturi e per questo evitiamo formati binari per i testi e ove possibile utilizziamo linguaggi di markup specifici per ciacun dominio, come ad esempio ditaa per i diagrammi liberi, PlantUML per diagrammi strutturati o gnuplot per rappresentare graficamente i dati tabellari. Laddove è necessario inludere media, utilizziamo solo formati binari liberi.

TODO Org-mode

Per scrivere il contenuto abbiamo scelto il formato Org-mode perché tra i Light Markup Languages è quello che consente un elevato grado di espressività pur rimanendo sufficientemente intuitivo. Org-mode include anche il sistema Babel che consente di inserire nei documenti il codice sorgente e di pubblicare il risultato della sua esecuzione: questo sistema è perfetto per includere nel testo anche pezzi di codice che poi vengono compilati e inseriti nelle pagine pubblicate, per esempio immagini di diagrammi in formato ditaa.

Per inserire o conneggere i testi ciascun autore può scegliere di utilizzare l'editor che preferisce; chi usa l'interprete Lisp Emacs, nel quale è programmato Org-mode, dovrebbe già conoscere il markup e il suo avanzato sistema di gestione.

Per vim sappiamo esiste il plugin Org.vim che fornisce il supporto alla sintassi Org-mode; se utilizzate altri editor di testo potete cercare se sono disponibili plugins analoghi. Ad ogni modo sonsigliamo vivamente di adottare sistemi alternativi e Emacs Org-mode che tentino di andare oltre il semplice supporto alla visalizzazione facilitata della sintassi Org-mode.

Detto questo, ciascun utente deve occuparsi di configurare il proprio ambiente di editing in modo tale da fornirgli uno strumento di lavoro che lo soddisfi e che gli permetta di essere produttivo.

TODO File media

Questi sono i formati di file media ammessi:

PDF per documenti da stampare,
PNG per le immagini,
OGG o MP3 per l'audio,
WebM per il video.

TODO Estensioni.

Se siete nel gruppo dei redattori di questo progetto ed avete necessità di utilizzare testo formattato in altri linguaggi di markup leggeri o di generare assets (es. immagini, audio, video) attraverso software che interpreta un domain spacific language non incluso nell'attuale sistema di pubblicazione, potete contattare il supporto tecnico e descrivere i vostri requisiti e le vostre proposte in merito: se valuteremo che l'estensione richiesta è necessaria e il software è disponibile in Guix allora c'è la possibilità che la vostra proposta venga accettata.

TODO Come contribuire

Il progetto è pubblico, ogni persona può copiare e redistribuire i contenuti secondo quanto stabilito nella licenza.

Se sei interessato a contribuire con nuovi contenuti, integrare quelli già presenti, tradurli in altre lingue, commentare o segnalare possibili correzioni siete benvenuti; questo progetto:

usa git per la gestione delle revisioni e l'inclusione delle patch, il remote ufficiale è su GitLab;
usa una mailing list pubblica, moderata, per l'invio e la discussione di patch (FIXME)
usa una mailing list pubblica, moderata, per l'invio e la pubblicazione dei commenti sui contenuti. (FIXME)

TODO Invio patch tramite email

Prendere ispirazione da https://orgmode.org/contribute.html

Per invio patch fare riferimento a: https://git-send-email.io/

Footnotes:

at least on currently Guix supported hardware architectures, assuming that such architectures will still exist decades from now.

for example see the post My Minimalist Approach to Software Engineering by Benjamin Tanone

thanks Brett Gilio who shared his code that we took as example.