2020-08-15-adding-about-pages-to-stagit.md (2822B) - raw


      1 <!-- title: Adding about pages to stagit -->
      2 <!-- slug: adding-about-pages-to-stagit -->
      3 <!-- categories: FOSS, Projects -->
      4 <!-- date: 2020-08-15T19:59:00Z -->
      5 
      6 I use [stagit][sg] to show the public repositories of my Git server on the web.
      7 I chose stagit because it is a very simple and lightweight tool, which makes
      8 tinkering with the source code very straightforward (which I have been doing a
      9 bit lately) and because the resulting website is static: easy to set up, faster,
     10 and there aren't any application-specific issues (there is no application).
     11 Static sites are also nice because you know exactly what is going on when a page
     12 is requested—the file is served—, whereas if it is a dynamic site, you might or
     13 might not know what operations the server is doing to answer the request.
     14 
     15 Stagit doesn't have many features. This isn't necessarily bad, as it keeps the
     16 source small and readable and it still does everything I consider necessary, it
     17 even has an Atom feed for commits! The one feature I really missed was being
     18 able to show an about page with the repository's readme file when it is
     19 opened[^nt]. For me, it is a basic feature, especially with repositories for
     20 projects without a website/wiki. When I hear about a piece of software, the
     21 first I do is go check out the repository and read a bit about it, and readme
     22 files make that easier. Since most of my repositories have readmes written in
     23 Markdown, I wanted stagit to convert them to HTML, so they could be shown nicely
     24 on the repositories' website.
     25 
     26 [^nt]: Stagit has a link on the navigation bar to the readme file, and you could
     27   easily make that the default `index.html` file, but it is just the page with
     28   the raw file (as any other file is shown), it isn't presented like an about
     29   page.
     30 
     31 If you want to try it out yourself, the change on stagit is very simple, just a
     32 couple of lines, but it will add a dependency to the program[^dep]. I use
     33 [md4c][md4c] to parse the files, and it is ridiculously fast. I haven't noticed
     34 any changes in the time it takes for stagit to run. Check out [this commit][cm]
     35 if you want to know how I did it, and feel free to suggest other approaches if
     36 you think they are better.
     37 
     38 [^dep]: The dependency is only for parsing Markdown, if you don't need that, you
     39   can just show the raw file without the line numbers and metadata, this is what
     40   [I do][nm] when the readme file isn't a Markdown file.
     41 
     42 
     43 [sg]: <https://codemadness.org/stagit.html> "Stagit blog post — codemadness.org"
     44 [md4c]: <https://github.com/mity/md4c> "md4c — GitHub"
     45 [cm]: <https://git.oscarbenedito.com/stagit/commit/1fdbc7e8ef4025e50678261ca670daca85ac298c.html> "Add about page for repos with REAMDE — git.oscarbenedito.com"
     46 [nm]: <https://git.oscarbenedito.com/stagit/commit/1fdbc7e8ef4025e50678261ca670daca85ac298c.html#h5-5-16>