grim/hgwebplus

The start of the readme

2020-04-10, Gary Kramlich
ee0e13f9d407
Parents b5d44784e27b
Children 354974557969
The start of the readme
2 files changed, 44 insertions(+), 0 deletions(-)
  • +44 -0
    README.md
  • +0 -0
    images/diff.png
    • --- /dev/null Thu Jan 01 00:00:00 1970 +0000
    +++ b/README.md Fri Apr 10 19:17:01 2020 -0500
    @@ -0,0 +1,44 @@
    +# hgwebplus
    +
    +hgwebplus is a [mercurial](https://mercurial-scm.org/) extension that enhances
    +the normal hgweb tooling so that theme authors can create more robust themes.
    +
    +It's built as an extension mainly to try out new things before attempting to
    +get them upstreamed. Also, due to the Bitbucket death clock, I couldn't wait
    +for an upstream release.
    +
    +That said, all of the changes that this extensions has done are completely
    +backwards compatible and older themes will work just fine.
    +
    +All screen shots are from my
    +[hgkeeper-theme](https://keep.imfreedom.org/grim/hgkeeper-theme).
    +
    +# Features
    +
    +## Readme Rendering
    +
    +The most notable feature is that a new template keyword named `readme` has been
    +added. Since this is a keyword, it can be used in any template. This keyword
    +will look for files named `README.md`, `README.txt`, and `README` in a case
    +insensitive fashion, and return their contents rendered to HTML.
    +
    +The Markdown rendering uses [cmarkgfm](https://pypi.org/project/cmarkgfm/) to
    +support GitHub Flavored Markdown. However, there is no styling associated with
    +this render. To do that, I recommend you use [sindresorhus's
    +github-markdown-css](https://github.com/sindresorhus/github-markdown-css/) in
    +your theme and addjust it accordingly.
    +
    +For plain text, the HTML rendering is just literally prefixing line endings
    +with a `<br/>`.
    +
    +## Diff Rendering
    +
    +The stock diff rendering in hgweb leaves a bit to be desired. When rendering
    +the lines of the diffs, you don't have the correct line numbers, nor the file
    +names, nor the file revisions all of which make it impossible to link to the
    +original revision for further viewing.
    +
    +Therefore, hgwebplus exposes all of these to the diffs templates and allows
    +you to create something similar to the screenshot below.
    +
    +![diff screenshot](images/diff.png)
    Binary file images/diff.png has changed