rrthomas / darkglass

Simple CMS that publishes a directory tree

DarkGlass

Reuben Thomas ([email protected])

DarkGlass is a simple content management system that exports a directory tree to the web. It displays different file types appropriately, uses file permissions to determine which files and directories should be exported, has a customizable navigation panel, and uses Markdown for rapid creation of simple web pages from plain text files.

DarkGlass is meant to be simple to use, simple to install and maintain, and its code should be easy to understand. It is released under the GNU General Public License version 3, or (at your option) any later version. There is no warranty.

See https://rrthomas.github.io/DarkGlass for more information.

Source code organization

The files are organised as follows:

cgi-bin

contains the main program DarkGlass.pm, some helper modules in MIME and RRT, and the front-end script and configuration file web.pl.

doc

The documentation.

darkglass's Issues

Make `$url` output page-relative URLs

Currently the URLs are server-relative, which means that a static site (all of whose links will have been rewritten via $url) does not in general work when tested locally. (A workaround is to run a development server.)

Resurrect Atom feed support

This was last working a long time ago. There was a problem because the UIDs for the feed items were generated arbitrarily each time, causing some readers to think that all articles were new each time the feed was generated; hence, should change the UIDs to depend on the article (e.g. generate from filename + timestamp).

install.sh: Install MIME converters

$INSTALL_DATA -D --target-directory "$INSTALL_DIR"/MIME Hulot/MIME/*.*
$INSTALL_DATA -D --target-directory "$INSTALL_DIR"/MIME/converters Hulot/MIME/converters/*

Pretty URLs

This isn't particularly good advice. There's no need for the Perl script to have a URL. There's a missed opportunity to sanity-check the URL path (e.g. forbid ".." and " "). And there's no need to mess around with URL rewriting.

The Apache directive I'm thinking of is ScriptAliasMatch. https://docstore.mik.ua/orelly/weblinux2/apache/ch16_05.htm

Support multi-lingual pages

See https://www.w3.org/International/questions/qa-when-lang-neg

Add:

• Support for HTTP language negotiation
• Support for multi-language pages: for each page.EXT, check for page.XX.EXT, where XX is a language code. Use LANG (already set) as the default language. Template the lang attribute on html element.
• A language switch, which appears when a page is available in multiple languages.

Offer a Docker image for easier deployment

Explain input-to-output mapping

Please add to the docs an example of an input directory tree and the corresponding output tree (or URL space). Things to cover:

• Files that get converted to HTML
• Files that have alternative conversions
• Getting the source for a file
• index.html
• style.css

Dark themed pages flash light on loading

install.sh: Missing `exit 1`s

if [ ! -d "$DOCUMENT_ROOT_DIR" ]; then
    echo "DOCUMENT-ROOT-DIR must be a directory"
    exit 1
fi
if [ ! -d "$INSTALL_DIR" ]; then
    echo "INSTALL-DIR must be a directory"
    exit 1
fi

Switch to a CommonMark implementation, with better code colouring support

This should be "more compatible" at the Markdown syntax level; it would be nice to offer better syntax colouring. Ideally something that uses Pygments, but see what there is.

Resurrect custom DarkGlass converters

Needed e.g. for #20.

This is hard to do before DarkGlass is rewritten in Python, as the code needs to run in DarkGlass context, or the converters need to be supplied with a lot of extra information somehow.

Document static site generation

The docs have been written from the point of view of using DarkGlass as a CGI script. Since it's now possible to use it as a static site generator, there are a few places in the docs where clarification is needed that you are talking about the source files.

In particular, it is confusing to use DocumentRoot to mean the source directory, since that will instead be the build directory.

I don't think it's necessary to change much. Just check every mention of a directory and make the necessary distinction.

install.sh doesn't really make sense for static sites

See Reuben for details.

DarkGlass gaily continues on its merry way when MIME-type conversion errors

E.g. web.pl: Can't exec "makepage": No such file or directory at MIME/Convert.pm line 142..

install.sh: Needs to copy *.html not *.htm

$INSTALL_DATA cgi-bin/*.htm{,l} cgi-bin/*.pm "$INSTALL_DIR"

Rename template files to end `.html`

We don't need to support 8.3 filesystems any more.

Remove macros that are specific to my personal web site

They can be written in web.pl for my web site (although currently I'm stuck on an older version of DarkGlass).

Proof-reading

web.pl.=*.md is garbled.

"macro" link is broken.

I was hoping that this "organisation" page would show me how to structure my source files and how the built files will come out, but it doesn't.

`install.sh` should install `static-site`

Then we have everything we need for a dynamic or static site installed.

Don't forget to update the docs and the update-site script for the docs site!

install.sh: Right place?

This file is no longer in the top-level directory

# Check we're being run from the right place
if [ ! -f "About DarkGlass.md" ]; then

`install.sh` should initialize `web.pl`

Already it has enough info to write the value of DocumentRoot.

Use `doc` not `doc-installed` in DarkGlass project

We don't use doc-installed.

Move config to dedicated file

Don't have the program startup in the same file as configuration.

It would also be nice if the config were in a standard format (e.g. .ini), but maybe not immediately, as we'd also like to move the per-site macros to configuration.

One simple way to achieve this would be to move the startup code to the module (i.e. allow it to run as a program), and have that source a config file (given how? probably by environment variable, so it can work from CGI mode too).

Add MP3 as an option for all audio files where Hulot offers that conversion

Offer alternate MIME types (anything that can be provided with ?convert) for all content.

Set up GitHub Action to update documentation site

On every push.

A couple of bugs in `static-site`

1. cv no longer needs to be run with perl
2. Static site fails to run web.pl if path is given as web.pl rather than ./web.pl.

`install.pl` fails if destination directory has a trailing slash

Darkglass.pm: `$download` is too magic

Ideally this would be in %Macros along with everything else.

Also $file.

Support URL rewriting for static sites

Static sites should be able to have their HTML files end .html. This is blocking #21.

Fix `$lastmodified` for static sites

Currently uses the time at which the site was generated!

Add `xdg-utils` to `.github/workflows/pages.yml`

New URLs without `?`

Problem: URLs with a ? in them don't work for statically generated sites in general. These are currently used by DarkGlass to specify (for example) the target MIME type to convert the file to. A typical URL is file:///blog/README.md?convert=text/html. Consequently, that functionality doesn't work for static sites.

Tentative idea (tires not kicked)

Redefine the URLs without ?s. Remove the query parameter, and add a path component with a file extension corresponding to the MIME type, e.g. file:///blog/README.md/index.html.

`$download` doesn't work for static site generation

$download generates URLs containing ?, which don't work on static sites.

Link rewriting doesn't work for URLs ending in '#' fragments

Make a web site that serves the documentation on GitHub

It's OK that we have it currently on rrt.sc3d.org, but it would be cleaner and more convincing to have it on GitHub Pages.

Separate into 3 main parts

• Converting/generating file types. (A thin layer on top of Hulot.)
• Rendering HTML pages with macro expansion. (A thin layer on top of Macro.pm.)
• Serving the resultant file.

Once this is done, it should be possible to start rewriting the parts in Python, for greater sanity.

Only the first two parts are needed for static sites!

Mask out some Hulot converters

As of today, Hulot supports converting e.g. text/json to text/html. DarkGlass naively uses this (and the same for application/javascript) and everything breaks. DarkGlass should not (normally) convert MIME types that are used in their own right.