~grtcdr/liaison

Go-to-source functionality for static websites published via Org
954c9da3 — grtcdr 10 months ago
Update contact information
4b7899eb — grtcdr 10 months ago
Refactor internal functions
41216b2f — grtcdr 10 months ago
Require vc-git

clone

read-only
https://git.sr.ht/~grtcdr/liaison
read/write
git@git.sr.ht:~grtcdr/liaison

You can also use your local clone with git send-email.

#Introduction

Liaison generates URLs that point to a specific page in a Git web interface, e.g. the tree, blob, blame, edit pages and more.

It aims to provide your readers with complete transparency about the history of changes (so long as you don't rewrite it) and the origin of web pages without hindering the reading experience.

It currently supports Sourcehut, Github, Gitlab, Gitea, cgit, including custom instances of the aforementioned services.

Documentation is available in a number of formats:

#Intended users

Liaison can be used in a number of situations, for example in a blog or documentation website built on top of the ox-publish library or high-level static site generators such as ox-hugo.

The following websites are currently making use of this library:

  • grtcdr.tn, in the postamble of blog posts and documentation files.
  • ushin.org, in the postamble of every page.

If you are using Liaison in your project and would like to be included in the list, feel free to contact me or submit a patch directly.

#Installation

Find and navigate to your desired project, and run the following in a shell prompt:

git clone https://github.com/grtcdr/liaison.git

Likewise, you may choose to add it as a submodule:

git submodule add https://github.com/grtcdr/liaison.git

It is assumed that you have a publishing script, named hereafter publish.el; in this file, you should define the project specification as well as any other configuration variables or special functions that affect the output of the published website.

It is best that you initiate the publishing process using a Makefile.

In your publishing script, add the package to the load-path and then require it like so:

(add-to-list 'load-path "liaison")
(require 'liaison)

If you’re interested in a more elaborate but less tedious method for installing this package, you should read my article on Implementing per-project package management for ox-publish projects.

#Support

If you wish to contribute a patch, inquire about something or share your feedback, you are welcome to send an email to ~grtcdr/pub@lists.sr.ht. If you encounter issues of any kind, please file them in the project's ticket tracker.