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