Differences between revisions 3 and 4
Revision 3 as of 2019-09-19 08:41:35
Size: 2785
Comment: add hint that repo and page is down, but there is still a download available
Revision 4 as of 2019-10-27 12:44:59
Size: 3079
Editor: rblank
Comment: Add a comment about the extension being broken.
Deletions are marked like this. Additions are marked like this.
Line 9: Line 9:
''Author: '' ''Remy Blank <remy.blank@pobox.com>'' ''Author:'' ''Remy Blank <remy.blank@pobox.com>''
Line 11: Line 11:
  Repository and web page: http://rc.c-space.org/hg/HgSite/ (site down 2019-09-19, there still seems to be a version downloadable at http://c-space.org/download/HgSite/)   Repository and web page: (site down as of 2019-09-19; last release still downloadable at http://c-space.org/download/HgSite/)
Line 13: Line 13:
  Browse the repository: http://rc.c-space.org/hg/HgSite/shortlog ''This extension was a neat idea, but it stopped working some time around Mercurial 3.2 due to a [[https://www.mercurial-scm.org/repo/hg/rev/6e1fbcb18a75|minor change]] in `hgweb`. This highlighted the brittleness of patching into `hgweb`, and made it not worth fixing. A better approach would be to handle rendering in a real WSGI application, and delegate to `hgweb` for paths that it should handle.''

HgSite

Serve a web site straight out of a Mercurial repository


This extension is not distributed with Mercurial.

Author: Remy Blank <remy.blank@pobox.com>

This extension was a neat idea, but it stopped working some time around Mercurial 3.2 due to a minor change in hgweb. This highlighted the brittleness of patching into hgweb, and made it not worth fixing. A better approach would be to handle rendering in a real WSGI application, and delegate to hgweb for paths that it should handle.

Overview

HgSite is a Mercurial extension that allows serving a dynamic, read-only website using a Mercurial repository as the backend storage. Pages are served by hgweb, the same component that serves the Mercurial repository, and no additional configuration is necessary in the web server.

Current features include:

  • A subset of the files in the repository are rendered through a number of renderers, based on their path. Built-in renderers include support for Genshi templates, static files and in-repository renderers, and you can also add your own.

  • It is possible to view a site as it was at any revision, thanks to the consistent versioning of the rendering configuration and all the files composing a site. Have your own Wayback Machine for your site!

  • Rendered pages have full access to the repository. This allows linking to specific files in the repository browser, including snippets of code in a page (with syntax highlighting), or even implementing a fully custom repository browser.

These features allow a number of interesting use cases, for example:

  • Serve a README file at the top-level of your repository, GitHub-style.

  • Serve the web site for a small project directly out of the project's repository. Using a templating engine like Genshi allows writing HTML pages relatively comfortably, as it allows factoring out common parts to avoid duplication. Editing and testing is very easy thanks to the immediate feedback provided by hg serve. And pushing changes to production is as easy as hg push.

  • Keep the documentation of a project together with the project's code in a single repository, and serve it directly out of the repository. As both are versioned together, it's easy to get the documentation for a specific version of the code. Moreover, the templates have access to all the files in the repository, so the documentation can link to files in the repository browser or inline snippets directly. You could even create a fully custom repository browser.

  • Run a small blog. The site structure can be done with a few HTML templates, and the articles could be stored as individual files, which could be listed and rendered in the templates.


CategoryExtensionsByOthers

HgSiteExtension (last edited 2019-10-27 12:44:59 by rblank)